SOP 位置: 本 skill 是 sop-definitions/development.yaml stage quality_gate 的执行细节。 SOP definition: sop-definitions/development.yaml stage quality_gate。 这是按需自检车道，不绑定固定上一步 / 下一步；完成后把证据交给实际选择的独立验证源或交付载体。

Quality Gate

完成声明前做两件事：对照真实需求自检，并用与风险面匹配的真实命令输出证明声明。

先理解本次答应交付的结果，再选择验证。需求仍是含糊愿望或不可承诺结果时，先澄清，不自行编 AC；已有清楚约定则沿用。原问题到交付的判断方法帮助核对实际使用场景，程序只检验可确定的行为，不能代替猫判断是否解决原问题。

核心知识

两条铁律合一：

1. Spec alignment（来自 spec-compliance-check）：AC 可能写偏，先回读原始需求，再逐项验收
2. Evidence before claims（来自 verification-before-completion）：没有运行命令、没看到输出，就不能说"通过了"

铁律：NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

自问："我是这次真的运行了命令并看到输出，还是我只是相信它能工作？"

为什么 AC 可能不够：AC 是人写的，可能遗漏 UX 要求或场景覆盖。F041 教训：AC 全打勾，但operator的原始需求（能力显示描述、多项目管理）根本没进 AC——spec compliance check 检查了 AC，但 AC 本身就是错的。

流程

BEFORE 声称完成 / 提 review:

Step 0: VISION CHECK（愿景核对）
  ① 找原始 Discussion/Interview 文档（operator experience在里面）
  ② 读核心痛点："我要..."、"我不想..."
  ③ 问自己：operator坐在 Hub 前用这个功能，体验是什么样的？
  ④ AC 是否完整覆盖了operator的原始需求？
     → 如有遗漏，先补 AC 再继续

Step 0.5: DELIVERY COMPLETENESS CHECK
  ① 这次交付的是完整 feat 还是 feat 的一部分？
     → 完整 feat：继续
     → 部分：有operator明确同意分批交付的记录吗？没有就继续做完
  ② 本次产出后续需要"重写"还是"扩展"？
     → 扩展：通过
     → 重写：如果是已标注 Spike 且有结论，通过；否则不通过，回去重做

Step 1: FIND — 找 spec/plan 文档
  - the active feature spec or implementation plan
  - 同时找 Discussion/Interview（operator experience所在）

Step 2: CREATE — 先确定完整旅程，再组织检查
  - 从原始需求写清本次约定的完整路径：从哪进、做什么、拿到什么结果，以及需要时怎样回到原处或再次打开
  - 将 AC / 功能点 / 关键边界挂在这条旅程下面；检查组合操作与真实接线，不把各按钮分别点通当作旅程走通
  - 按风险将计算、组件事件等局部分支交给单测或集成测试；浏览器检查真实入口、导航、渲染和跨步骤状态，不为每个内部切片重复验整套按钮
  - 非交互交付按其真实使用场景写输入、处理与最终结果；不为纯文档或内部计算虚构页面旅程

Step 2.5: CLOSE GATE MATRIX + FOLLOW-UP TAIL SCAN（F177 Phase A）🔴
  - **下面 CloseGateReport / unmet AC 处置 / tail scan / cvo_signoff 四项仅在本次交付声称关闭 Feature（feat close）时执行；普通 PR / Phase 内交付跳过这四项、不生成 CloseGateReport。本步其余按作者触发的检查（包装未做作者的 close 复核）不受此门线影响，仍按各自条件执行**
  - 检查 CloseGateReport 是否已生成（schema: `../.cat-cafe-shared-refs/close-gate.md`）
  - 每个 unmet AC 是否三选一处置（immediate / delete / cvo_signoff）
  - **Follow-up tail scan**：扫以下文本来源，命中关键词 = **线索（进入语义判定），不是自动 BLOCKED**——判定标准只有一条：该词是否在把 **unmet AC 包装成已完成 / 偷偷延期**（close 借口）。正常阶段描述（"X 属 next phase 的 scope"）、风险讨论、路线图引用不触发（2026-07-15 修订：raw keyword 自动 BLOCK 误杀正常文本）：
    - 来源：close report、PR body、commit messages、spec 中 AC 注释、review 反馈回复
    - 线索关键词（不区分大小写；仅用于定位待语义检查处）：
      `follow-up` `followup` `deferred` `next phase` `next PR` `P2` `stub` `TD`
      `后续` `留个尾巴` `先这样` `下次一定` `回头` `以后再` `will address later`
      `out of scope`（作为 close 借口时）`MVP 先上`（作为 close 借口时）
    - 豁免：spec 的 Why/Risk/History 章节中引用历史上下文时使用这些词不触发
  - cvo_signoff 四件套完整性验证（proposal + cvo message + quote + scope）
  - 🔴 **包装未做作者的 close 复核**（F177 Phase B，原为针对单只已退役猫的规则）：仅当 PR 作者的 dossier「翻车熔断信号」写有「包装未做 / 过早收口」类失败模式时，其 feat close PR 的 quality-gate 由非作者猫重跑，按风险默认只选一只，同族也行；审核者由 reviewer/系统按当前 roster 指定，作者无选择权。其他作者照常自检。通用底线不变：作者自评不能替代已选择的独立 review（reviewer ≠ author）
  - **hotfix**（F177 Phase E）：执行 `node scripts/check-hotfix-pattern.mjs` 识别 hotfix 模式；其"自我说服"风险由跨个体 review 铁律承接（reviewer ≠ author，merge-gate 校验），作者照常自检，不再额外安排另一只猫重跑 quality-gate

Step 2.6: FALLBACK LAYER CHECK（F177 Phase D）🔴
  - 执行：`node scripts/check-fallback-layers.mjs` 扫描 PR diff
  - 同一文件新增 ≥3 层 fallback 或累计 ≥5 层 → 触发坐标系自检
  - 自检三问：①修坐标系还是补错误坐标系？②坐标变换能否消除？③每层为什么不能去掉？
  - 层数合理时在报告中说明理由；不合理时重构后再过 gate

Step 2.7: ARCHITECTURE OWNERSHIP REPORT（F191，warning-only）🔴
  - 执行：`pnpm check:architecture-ownership`
  - 从 spec / plan 抄入：
    `Architecture cell` / `Map delta` / `Why`
  - 若缺失，报告 `⚠️ missing` 并列为 review focus；不在 quality-gate 做 semantic hard block
  - 若 `Map delta: none` 但 diff 明显新增 `Store|Queue|Router|Adapter|Dispatcher|Binding` 等架构名词，报告 mismatch 给 reviewer
  - 若 `Map delta: update required|new cell required`，报告对应 ownership cell / new cell 文件是否随 PR 更新
  - 注意：quality-gate 只报告机械可见事实；架构语义正确性由 Design Gate + reviewer 判断

Step 3: VERIFY — 逐项检查
  - 代码在哪？有测试覆盖？边界处理了？
  - 🔴 F244 Tips Contribution：若本 PR 新增/修改 user-visible feature / capability / guide / harness behavior，
    必须满足其一：
    ① `packages/web/src/lib/capability-tips.seed.json` 有对应 `sourceRef` tip
    ② 相关 feature/guide/skill 文件写明 `tips_exempt: {reason}`
    并执行 `pnpm check:capability-tips`。
    注意：CI 只证明结构/anchor/action；reviewer 仍要退回只复述标题、没有动作或时机的废话 tip。
  - 🔴 交付物必须核实 commit/PR 状态（git log --grep + gh pr list）
    spec checkbox 是记录工具，不是真相源（LL-029）
  - 🔴 新增 MCP 工具 → 认知入口更新了吗？优先级：MCP tool description → 相关 skill refs → capability wakeup / L0 quick index；只有 legacy/fallback surface 仍依赖时才补 `MCP_TOOLS_SECTION`（F086 教训：造了工具猫不知道；F203 后不再默认塞 SystemPromptBuilder）
  - 🔴 新增行为规则 → governance digest / shared-rules 注入更新了吗？
  - 🔴 产出了 SKILL.md 或改了 MCP tool description → 加载 `writing-skills`，用 T0 六要素审查质量（软硬同检）

Step 4: RUNTIME GUARD — 前端证据采集前先做运行态保护
  - 若会话在 `cat-cafe-runtime`，先探活：`curl -sf http://localhost:3004/health`
  - 服务已在线时直接复用，禁止在该会话执行 `pnpm start` / `pnpm runtime:start` / `pnpm runtime:restart` / `pnpm runtime:stop` / `./scripts/start-dev.sh`
  - `localhost:3003/3004` 默认按 runtime 处理；如果你要验证未合入改动，不能把这两个端口的页面/接口响应当成当前分支的证据
  - 证明“这是我当前 worktree 的验证证据”时，必须同时说清：`worktree/cwd` + 目标 URL。两者对不上 = 证据无效
  - 确需重启时，先获operator明确授权，再执行 `pnpm runtime:restart`；shell 参数与环境变量都不是授权证明
  - **Alpha 优先**：验证已合入 main 的改动时，优先用 `pnpm alpha:start`（3011/3012/4111/6397）取证，而非 runtime。Alpha 环境每次启动自动同步 origin/main

Step 4.5: DOGFOOD — 实际走通本次约定的完整旅程（F209 / F314）🔴
  对 user-visible / runtime feature，author 必须在请求 review 前：
    ① 实际走 Step 2 的完整旅程，从真实入口与输入到最终结果，覆盖需要的返回、保存与重进；不能用当前 slice 的局部成功代替原约定
      旅程的输入用需求方原话里的真实例子和真实数据（原话说"打开 backlog"，就打开那份 backlog），不用作者自己挑的样例。原话里的核心动作用真实数据做不到，记"没走通"，不记成小缺口或下一阶段。给猫用的功能，由一只猫在真实任务里实际调用一次；人和猫都用的能力，两边各走一遍，确认调用的是同一个底层操作。
    ② 把命令 + 输出 / 截图证据写进 Quality Gate Report 的 "Dogfood" 块
    ③ 抓到的任何 dogfood bug 必须当轮修，不允许"post-merge 再说"
    ④ **结构性例外**（2026-07-15）：验证路径只在合入后才存在（需 main/alpha 环境或真实外部案例，AC-F7 型）→ pre-merge 验证到能验的边界即可，剩余由**带 owner + 触发条件的持久 post-merge task** 接走，**不阻塞 pre-merge review / merge**；若它是 required AC，则 task 在 terminal PASS（或 `delete` / `cvo_signoff`）前仍阻塞 **feature close**。例外理由写进 review packet

  Scope（必做 vs 可豁免）：
    - **必做**：任何对最终用户 / 猫体感有变化的 feature 或 bugfix。包括但不限于：
      search / recall / UI / routing / drillDown / typed reader / 任何新 MCP tool / 任何新 REST 端点 /
      **任何修复用户或猫可感知路径的 bugfix（即使已有回归测试覆盖）**
      → 反例 PR #1854 dogfood hotfix：file-slice drillDown 路径口径不一致，已有回归测试也不够——
        必须 author 自己跑一遍 `search_evidence → drillDown → read_file_slice` 才能抓到
    - **可豁免**：docs-only / 纯重构 / 纯测试 / 内部基础设施 / **纯内部 bugfix（非 user/cat 可感知路径，如内部 DB 一致性、log format、纯算法常量调整等）**
      → 豁免必须**显式在 review packet 里写出理由**（"docs-only" / "纯重构 + 既有测试覆盖" / "纯内部 bugfix，不影响 user/cat 可感知路径"等），不能省略

  Why（F209 反思 2026-05-23）:
    "AC pass 但用户感受不到" + "dogfood bug post-merge 才暴露" 是同型走偏。
    - Phase B alias registry: AC-B1~B5 全 ✅、跨族 review APPROVE、merge 闭环 — 但生产 `entity_registry` 是空的，真实用户搜 `operator` 找不到 `operator`。
    - Phase C drillDown: 测试 / cloud review / merge 都过 — 但 author 自己 post-merge 用一次刚发现 file-slice 路径口径不一致。
    根因是没人 pre-review 真用一次自己刚做的东西。pre-merge dogfood 把这一类 bug 提前到 author 自检阶段。

  报告写法（在 Quality Gate Report 里加 "### Dogfood" 块）：
    ```markdown
    ### 完整旅程（Dogfood）
    完整旅程：走通 / 没走通（断点：...）/ 不适用（本次交付与验证方式：...）
    Scope verdict: ✅ 必做 / 🆗 可豁免（理由：xxx）

    （必做时）
    实际使用路径: search_evidence("operator") → drillDown → cat_cafe_get_thread_context → 读到能回答原问题的原文
    实际命令 / 输出（粘贴）: ...
    发现的 bug: 无 / 列表（含修复 commit SHA）
    ```

Step 5: 参考与实物对照 — 有产品/体验要求时
  先在 designs/ 中用 glob designs/**/*.pen 查设计稿，再沿 feature doc / 原讨论 / docs/evidence 查已接受的参考。
  命令帮助发现材料，猫判断哪些与本次任务相关；找到适用参考后，用同一任务核对本次实物。
  关注对象、操作位置、状态变化和结果；没有 .pen 不等于没有参考，更不等于可以跳过产品判断。
  比较方法按问题选择，不用文件后缀、截图数量或勾选代替判断。

Step 6: RUN — 运行风险匹配的验证命令（必须这次真实运行）
  ① 先列五轴风险与受影响面；命令逐条对应 claim，不按“写了代码”机械全跑
     测试增量先按 docs/ops/testing-standard.md 核真实失败、最低足够层级、已有覆盖缺口与成本；pass 数不代替判断
  ② 默认：受影响 package / schema / generator / docs checker + git diff --check
  ③ 新行为 / bug：相关行为或回归测试；现有精确检查红可以直接作 RED
  ④ targeted 无法覆盖实际风险时才跑 pnpm gate；作者可按 merge-gate「Gate 选择」带依据调整机器默认 full，保留按风险要求的独立审查和硬边界
  ⑤ Redis 相关改动额外跑：pnpm --filter @cat-cafe/api test:redis（租用隔离端口；保护 6397/6398/6399/6401）
  ⑥ 相关或尚未排除关联的红灯先修；已证实无关的失败保留并交原 owner，不阻塞自己的充分验证；不得隐去失败
     批量清理先收齐并完成成批修改，再集中验证；之后只为实质变化、新失败或未解决疑点补跑相关项

Step 7: READ — 完整读输出，看 exit code，数失败数

Step 7.5: ARTIFACT HYGIENE CHECK — 根目录媒体垃圾闸门
  - 执行（工作树）：
    `git status --short | rg '^.. [^/]+\.(png|jpe?g|webp|gif|webm|mp4|mov|wav|pdf|pen)$'`
  - 执行（已提交差异）：
    `git diff --name-only origin/main...HEAD | rg '^[^/]+\.(png|jpe?g|webp|gif|webm|mp4|mov|wav|pdf|pen)$'`
  - 任一命中 → BLOCK：说明仓库根目录出现了媒体/设计工件（含已跟踪和未跟踪）
  - 处理方式：移到 `${TMPDIR}/cat-cafe-evidence/...` 或显式归档到正式目录后再继续
  - 规则真相源：`../.cat-cafe-shared-refs/evidence-output-contract.md`

Step 8: REPORT — 输出合规报告 + 证据

前端功能额外要求：author 必须在正确 worktree / preview 的真实入口走关键交互，并记录 URL、操作与结果。SOP 产品快车道先在第一小时争取交付实物、贴作者自采截图并对照原约定，不等 review/full 后才看；其余场景按判断需要选择截图、录屏、DOM assertion 或 Playwright 证据，不把缺截图转成 operator 的劳动。人工预览不以前置跑整套浏览器测试代替；合入后作者在 Alpha 核对。执行细则：../.cat-cafe-shared-refs/vision-evidence-workflow.md。

视觉对照的用法：需要判断布局和操作关系时，把已接受的参考与实际页面放在一起看，并实际操作关键状态。截图适合说明外观，不能单独证明保存、返回或恢复；已有证据仍覆盖的部分可以复用。有意偏离参考要说明真实原因，涉及新价值取舍时再找 operator，不要求用户重复批准同一方向。

2026-03-11 教训：三只Ragdoll同时跳过了已有 .pen 对照，所以保留命令驱动的参考发现。发现步骤不替猫判断设计，也不能用“没有 .pen”排除图片或实页等其他已接受参考。

Quick Reference

合规报告模板：

## Quality Gate Report

完整旅程：走通 / 没走通（断点：...）/ 不适用（本次交付与验证方式：...）
Spec: feature spec or implementation note
原始需求: feature-discussions/YYYY-MM-DD-xxx/README.md
检查时间: YYYY-MM-DD HH:MM

### 愿景覆盖（Step 0）
| # | operator原始需求 | AC 覆盖？ | 实现？ |
|---|---------------|-----------|--------|
| 1 | "我要 XXX"    | AC#3      | ✅     |

### 旅程与支撑检查
约定路径：<真实入口、组合操作、最终结果；需要时包含返回与重进>
| 旅程环节 | 要求 / 关键边界 | 状态 | 代码位置 | 验证证据 |
|----------|-----------------|------|----------|----------|
| XXX      | XXX             | ✅   | file.ts:L10 | test.spec.ts / 实际操作 |

### 参考与实物对照（适用时）
已接受参考与实际路径：<来源 / 本次观察>
判断：<是否保留了约定的操作与结果；差异及理由>

### Artifact Hygiene（Step 7.5）
仓库根目录媒体/设计工件（工作树 + 已提交差异）: 无 ✅

### Architecture Ownership（Step 2.7）
Architecture cell: dispatch
Map delta: none
Why: 只扩展现有 InvocationQueue 行为，不改变 dispatch cell 边界
Diff mismatch scan: 无新增并行 Store/Queue/Router/Adapter ✅

### 完整旅程（Step 4.5 Dogfood）
Scope verdict: ✅ 必做 / 🆗 可豁免（理由）
（必做时）实际路径与结果: <Step 2 的完整旅程，哪一步走通或断开>
实际命令 / 输出 / 截图: ...
发现的 bug: 无 / 列表（含修复 commit SHA）

### 五轴风险与验证命令（必须是这次真实运行）
风险: behavior=<...> data=<...> security=<...> contract=<...> irreversible=<...>
<targeted command 1> → exit 0 ✅（覆盖 claim: ...）
<targeted command 2> → exit 0 ✅（覆盖 claim: ...）
pnpm gate → exit 0 ✅（仅影响范围要求 full 时填写）

Common Mistakes

Red flags — 立刻 STOP：

• 用 "should"、"probably"、"seems to"
• 表达满足感（"好了！"、"完成！"）时还没运行命令
• 信任 subagent 的 "success" 报告而没独立验证

和其他 skill 的区别

quality-gate 负责作者自检，merge-gate 消费风险匹配的交付证据，receive-review 处理已收到的审查意见。

下一步

Quality Gate 通过后，符合 docs/SOP.md 产品快车道且未选 review 的改动由作者直接进入 merge-gate；其余把证据交给风险路由已选择的独立验证源：治理 / stateful 语义通常走 request-review；安全 / 契约的 context-blind 扫描可走 cloud；fresh-context-review 仅在 author 判断认知盲点收益足够时作为 finding generator，不是固定前置。

Gate 未通过时：

• P1 遗漏 → 补完再过 gate
• P2 遗漏 → 必须当轮补完再提 review
• 检查失败 → 修复相关失败；已证实无关的失败交原 owner，作者按 merge-gate 的验证裁量完成自身覆盖后继续交付