| name | quality-gate |
| description | 开发完成后的自检门禁：愿景对照 + spec 合规 + 验证。 Use when: 开发完了准备提 review、声称完成了、准备交付。 Not for: 收到 review 反馈（用 receive-review）、merge（用 merge-gate）。 Output: Spec 合规报告（含愿景覆盖度）。
|
| triggers | ["开发完了","准备 review","自检","声称完成"] |
SOP 位置: 本 skill 是 sop-definitions/development.yaml stage quality_gate 的执行细节。
SOP definition: sop-definitions/development.yaml stage quality_gate。
上一步: impl stage | 下一步: request-review（review stage）
Quality Gate
开发完成到提 review 之间的双重关卡：对照 spec 自检 + 用真实命令输出证明你的声明。
核心知识
两条铁律合一：
- Spec alignment（来自
spec-compliance-check）：AC 可能写偏，先回读原始需求，再逐项验收
- 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 / 功能点 / 边界条件
- 列出 Discussion 里的 UX 描述和场景
Step 2.5: CLOSE GATE MATRIX + FOLLOW-UP TAIL SCAN（F177 Phase A）🔴
- 检查 CloseGateReport 是否已生成（schema: `cat-cafe-skills/refs/close-gate.md`）
- 每个 unmet AC 是否三选一处置（immediate / delete / cvo_signoff）
- **Follow-up tail scan**：扫以下文本来源，命中阻塞关键词 = BLOCKED：
- 来源：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）
- 🔴 **47 盲审规则**（F177 Phase B）：若 PR 作者是 opus-47，quality-gate 必须由对家猫执行（Maine Coon优先，46 兜底）。审核者由 reviewer/系统指定，47 无选择权，47 的自评不计入放行判据
- 🔴 **hotfix 自检禁止**（F177 Phase E）：执行 `node scripts/check-hotfix-pattern.mjs`，若检测到 hotfix 模式，作者不得自行通过 quality-gate——必须由另一只猫执行 quality-gate。原因：hotfix 心态容易自我说服"够用了"，跨猫审视打破惯性
- 🔴 **Ragdoll search→Read 检查**（F177 Phase F）：若执行者是Ragdoll家族（46 / 47 / 4.5 / Sonnet），检查本次 session 的 search 行为：
1. 有 `search_evidence` 调用命中 doc anchor（高/中置信度）吗？
2. 命中后有对应的 `Read` 调用去读源文件吗？
3. 输出中包含精确数字/版本号/日期但没有 Read 证据吗？
→ 三条件同时满足 = **BLOCKED**："这个精确结论你 Read 源文件了吗？摘要是索引不是答案。"
→ 豁免：架构方案/假设性讨论（不含精确数字的推理不触发）；通过 Grep/LSP 获取的精确信息不触发
- 🔴 **Siamese edit scope 检查**（F177 Phase C）：若 PR 作者是Siamese，检查改动文件是否超出白名单（designs/ docs/ assets/ 根目录.md）。碰 packages/ src/ 的改动必须有对应 handoff 记录或 Dry Run Gate 通过证据（build + test pass）
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` / `./scripts/start-dev.sh`
- `localhost:3003/3004` 默认按 runtime 处理；如果你要验证未合入改动，不能把这两个端口的页面/接口响应当成当前分支的证据
- 证明“这是我当前 worktree 的验证证据”时，必须同时说清：`worktree/cwd` + 目标 URL。两者对不上 = 证据无效
- 确需重启时，先获operator明确授权，再用 `CAT_CAFE_RUNTIME_RESTART_OK=1` 执行
- **Alpha 优先**：验证已合入 main 的改动时，优先用 `pnpm alpha:start`（3011/3012/4111/6398）取证，而非 runtime。Alpha 环境每次启动自动同步 origin/main
Step 4.5: DOGFOOD-YOUR-SLICE — 用一次自己刚做的功能（F209 教训 2026-05-23）🔴
对 user-visible / runtime feature，author 必须在请求 review 前：
① 跑一条**真实端到端 query / 路径**，涵盖该 slice 的核心交付能力
② 把命令 + 输出 / 截图证据写进 Quality Gate Report 的 "Dogfood" 块
③ 抓到的任何 dogfood bug 必须当轮修，不允许"post-merge 再说"
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-Your-Slice
Scope verdict: ✅ 必做 / 🆗 可豁免（理由：xxx）
（必做时）
端到端路径: search_evidence("operator") → drillDown → cat_cafe_get_thread_context
实际命令 / 输出（粘贴）: ...
发现的 bug: 无 / 列表（含修复 commit SHA）
```
Step 5: PEN CHECK — 自动化设计稿对照（不可跳过！）
① glob designs/**/*.pen，匹配当前 feat 编号或关键词
② 若匹配到 .pen 文件 → 强制进入设计稿对照流程（见下方"有 .pen 设计稿的功能额外要求"）
③ 若无匹配 → 检查 feat 是否有前端 UI 改动（改了 packages/web/src/components/）
→ 有 UI 改动但无 .pen → 在报告中标注"⚠️ 无设计稿，跳过对照"
④ 此步骤不依赖猫猫"记得"——必须执行 glob 命令，用输出决定是否进入对照
Step 6: RUN — 运行验证命令（必须这次真实运行）
pnpm test # 必须全部通过
pnpm lint # 0 errors
pnpm check # 0 errors（biome 格式 + lint）
pnpm -r --if-present run build # exit 0
# Redis 相关改动额外跑：
pnpm --filter @cat-cafe/api test:redis
# ⚠️ pnpm check 包含 biome format + lint 规则。
# 如果有 format 问题，先跑 pnpm check:fix 自动修复。
# 不能带着 biome errors 提 review！（2026-03-12 operator定调）
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-skills/refs/evidence-output-contract.md`
Step 8: REPORT — 输出合规报告 + 证据
前端功能额外要求：≤3 张截图 + 1 段 15s 录屏，附"需求 → 截图"映射表。
执行细则：cat-cafe-skills/refs/vision-evidence-workflow.md。
有 .pen 设计稿的功能额外要求 🔴（Step 5 匹配到 .pen 时强制执行）：
- 打开 .pen 文件 →
get_screenshot 截取设计稿
- Playwright/Chrome 打开实际页面 → 截取实现截图
- 逐区域对比：布局、颜色、间距、交互状态
- 不一致处必须标注并修复（或记录为"有意偏差 + 原因"）
- 报告附 设计稿截图 vs 实现截图 对照表
- 🔴 此流程由 Step 5 自动触发，不依赖猫猫主动想起来
教训（2026-03-11）：三只Ragdoll同时跳过了 .pen 对照，根因是没有自动化检查点。
Step 5 的 glob 就是解决这个问题——用命令输出驱动，不靠记忆。
Quick Reference
| Claim | 需要 | 不够用 |
|---|
| 测试通过 | 这次运行输出：0 failures | "上次跑过"、"应该通过" |
| lint 干净 | lint 输出：0 errors | 部分检查、推断 |
| biome 干净 | pnpm check：0 errors | "先跑通再说"、"回头再改格式" |
| 构建成功 | build 命令：exit 0 | lint 通过不代表编译通过 |
| Bug 修了 | 原症状测试：通过 | 代码改了，以为修了 |
| 需求满足 | spec + Discussion 逐项打勾 | 测试通过就完事 |
| Feature 完成/未完成 | git log + PR 状态 + spec 逐项 | 只看 spec checkbox 就下结论 |
合规报告模板：
## 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 | ✅ |
### 功能验收
| # | 要求 | 状态 | 代码位置 | 测试覆盖 |
|---|------|------|----------|----------|
| 1 | XXX | ✅ | file.ts:L10 | test.spec.ts |
### 设计稿对照（Step 5）
glob designs/**/*.pen 匹配结果: [列出匹配文件或"无匹配"]
对照状态: ✅ 已对照 / ⚠️ 无设计稿（有 UI 改动）/ ➖ 无 UI 改动
### 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 ✅
### Dogfood-Your-Slice（Step 4.5）
Scope verdict: ✅ 必做 / 🆗 可豁免（理由）
（必做时）端到端路径: search_evidence("...") → drillDown → reader(...)
实际命令 / 输出 / 截图: ...
发现的 bug: 无 / 列表（含修复 commit SHA）
### 验证命令输出（必须是这次真实运行）
pnpm test → 34/34 pass ✅
pnpm lint → 0 errors ✅
pnpm check → 0 errors ✅ (biome format + lint)
pnpm -r --if-present run build → exit 0 ✅
Common Mistakes
| 错误 | 正确做法 |
|---|
| 只检查 AC，没回读 Discussion | Step 0 先读原始需求，AC 可能不完整 |
| "上次跑测试是通过的" | 这次重新跑，看输出，再声明 |
| "应该没问题" / "probably works" | Run the command. Read the output. |
| 测试通过就声称 phase 完成 | 还要对照 spec 逐项检查 |
| 部分实现就提 review | P1/P2 遗漏必须当轮补完再提 review |
| 交付半成品让operator"先看看" | 交付完整 feat，步骤是内部节奏不是交付批次 |
| 产出后续要重写而非扩展 | 如果要重写，说明绕路了（Spike 除外） |
| 前端功能没有截图证据 | ≤3 张截图 + 15s 录屏 + 映射表 |
| 有 .pen 设计稿但没对照实现 | Step 5 自动 glob 检测，匹配到就强制对照，不靠记忆 |
为了截图在 runtime 会话里重跑 pnpm start | 先探活复用现有 runtime；确需重启必须显式授权 |
拿 runtime 的 3003/3004 页面当成当前 worktree 的验证结果 | 报告里同时写明 pwd/worktree 和目标 URL；如果 URL 是 3003/3004，默认这是 runtime 证据，不是未合入改动证据 |
| 截图/录屏/设计稿顺手掉进仓库根目录 | Step 7.5 必查；先移到 ${TMPDIR}/cat-cafe-evidence/... 或正式归档目录，再继续 |
| Redis 改动用默认测试命令 | 必须跑 test:redis，禁止直连 6399 |
| 产出了 skill/MCP 但没审查质量 | 加载 writing-skills，用 T0 六要素审查（软硬同检） |
| 只看 spec checkbox 就声称完成/未完成 | 核实 git log --grep + gh pr list + 实际 commit（LL-029） |
| AC 全 ✅ 就声明 phase close（机制 ship 但用户感受不到） | Step 4.5 Dogfood-Your-Slice：必做 feature 跑一条真实端到端 query 写进报告；豁免必须显式写理由（F209 反思 2026-05-23） |
Red flags — 立刻 STOP：
- 用 "should"、"probably"、"seems to"
- 表达满足感（"好了！"、"完成！"）时还没运行命令
- 信任 subagent 的 "success" 报告而没独立验证
和其他 skill 的区别
| Skill | 关注点 | 时机 |
|---|
| quality-gate（本 skill） | spec 对照 + 证据验证 | 提 review 之前 |
merge-gate | reviewer 是否放行、P1/P2 是否全修 | 合入 main 之前 |
receive-review | 如何处理 reviewer 的反馈 | 收到 review 之后 |
一句话：quality-gate 是"你自己检查自己"，merge-gate 是"reviewer 放行你"，receive-review 是"你处理 reviewer 的意见"。
下一步
Quality Gate 通过后 → 直接加载 request-review skill 请求 review（SOP stage review）。不要停下来问operator"要不要继续"（§17）。
Gate 未通过时：
- P1 遗漏 → 补完再过 gate
- P2 遗漏 → 必须当轮补完再提 review
- 测试 / lint / build 失败 → 修到绿灯再提
