@heihei0299/matt-skills 2.0.2 → 2.1.2

package/.agents/skills/ci-guard/SKILL.md

@@ -1,11 +1,14 @@
 ---
 name: ci-guard
-description: "保护本仓库 GitHub Actions CI/release pipeline：按发布、workflow 维护或发布后故障场景执行必要门禁。Use when CI is flaky/failing, when setting up or editing .github/workflows/ci.yml, or before tagging a release to npm."
+description: "matt-skills 仓库专用 GitHub Actions / npm release gate。仅在用户显式调用并且当前仓库身份确认是 @heihei0299/matt-skills 时执行。"
+disable-model-invocation: true
 ---
 
 # CI Guard
 
-本 skill 只编排当前仓库的 CI 与 npm 发布门禁。先读取 `.github/workflows/ci.yml`，以实际 workflow 的 job、input、condition 和权限为事实源；不要假设不存在的 job、input 或自动回滚行为。产品代码 bug 的诊断和修复交给 `diagnose-fix`，不在此重复通用诊断。
+这是 **matt-skills 仓库专用** skill，不是通用 CI skill。用户显式调用后，第一步先读取当前 `package.json`；只有 `name` 精确等于 `@heihei0299/matt-skills` 时才继续。身份不匹配立即停止并报告 `repo mismatch`，不得把本仓库的 workflow、tag 或 npm 发布假设套到其它项目。
+
+身份确认后，读取 `.github/workflows/ci.yml`，以实际 workflow 的 job、input、condition 和权限为事实源；不要假设不存在的 job、input 或自动回滚行为。产品代码 bug 的诊断和修复交给 `diagnose-fix`，不在此重复通用诊断。
 
 ## 场景选择
 
@@ -44,6 +47,7 @@ description: "保护本仓库 GitHub Actions CI/release pipeline：按发布、w
 
 ## 不做什么
 
+- 不在非 `@heihei0299/matt-skills` 仓库执行；
 - 不把每次发布都扩展为完整 CI 工具链演练；
 - 不引用不存在的 `build` job、`dry_run` input 或 `rollback_version` input；
 - 不把历史事故描述当成当前仓库事实；

package/.agents/skills/commit-check/scripts/scan-sensitive.sh

@@ -1,5 +1,7 @@
 #!/usr/bin/env bash
 # Deterministic staged-diff secret scan for commit-check.
+# Only ADDED lines are inspected: removing a leaked secret must never be blocked.
+# Match contents are never echoed, so detected credentials do not leak into agent/log output.
 # FAIL: structured assignments and private-key blocks.
 # WARN: bare keywords that may legitimately appear in documentation.
 set -euo pipefail
@@ -12,18 +14,24 @@ fi
 fail_patterns='(api[_-]?key|secret|token|passwd|password)[[:space:]]*[=:][[:space:]]*[^[:space:]]{8,}|BEGIN (RSA|OPENSSH|EC|DSA) PRIVATE KEY'
 warn_patterns='(api[_-]?key|secret|token|passwd|password|\.env)'
 
-staged_diff=$(git diff --cached -U0)
+# Strip diff metadata and deletions. The scanner cares only about content that the
+# commit would introduce, not secrets that the commit is removing.
+added_lines=$(
+  git diff --cached --unified=0 --no-color \
+    | awk '/^\+\+\+ / { next } /^\+/ { print substr($0, 2) }'
+)
+
 fail=0
 
-if grep -inE "$fail_patterns" <<< "$staged_diff"; then
-  echo "❌ Structured secrets found in STAGED diff — remove them before committing." >&2
+if grep -qiE "$fail_patterns" <<< "$added_lines"; then
+  echo "❌ Possible structured secret found in ADDED staged content — remove or redact it before committing." >&2
   fail=1
 else
-  echo "✅ No structured secrets in staged diff."
+  echo "✅ No structured secrets in added staged content."
 fi
 
-if grep -inE "$warn_patterns" <<< "$staged_diff"; then
-  echo "⚠  Keyword matches in STAGED diff — eyeball whether they are real secrets." >&2
+if grep -qiE "$warn_patterns" <<< "$added_lines"; then
+  echo "⚠  Sensitive keyword found in ADDED staged content — inspect the staged diff manually." >&2
 fi
 
 exit "$fail"

package/.agents/skills/diagnose-fix/SKILL.md

@@ -1,42 +1,43 @@
 ---
 name: diagnose-fix
-description: "Complete diagnosis→fix→regression channel for bugs: diagnose, then fix via a TDD red-green loop with a hard gate (no fix code before a failing regression test). Use when the user says diagnose/debug/fix this, or reports something broken/throwing/failing/slow — prefer this over diagnosing-bugs when a fix is wanted, not just a diagnosis."
+description: "Complete diagnosis→fix→regression channel for bugs and performance regressions: diagnose, then fix behind observed red regression evidence. Functional bugs require a failing regression test; performance regressions may use a benchmark/perf harness with an explicit failing threshold. Use when the user says diagnose/debug/fix this, or reports something broken/throwing/failing/slow — prefer this over diagnosing-bugs when a fix is wanted, not just a diagnosis."
 ---
 
 # Diagnose Fix
 
-本 skill 只连接诊断、TDD 修复和回归三个阶段。诊断细节以 [`diagnosing-bugs`](.agents/skills/diagnosing-bugs/SKILL.md) 为事实源，红绿语义以 [`tdd`](.agents/skills/tdd/SKILL.md) 为事实源；不复制两个上游的完整步骤。
+本 skill 只连接诊断、受保护的最小修复和回归三个阶段。诊断细节以 [`diagnosing-bugs`](.agents/skills/diagnosing-bugs/SKILL.md) 为事实源，普通功能 bug 的红绿语义以 [`tdd`](.agents/skills/tdd/SKILL.md) 为事实源；不复制两个上游的完整步骤。
 
 ## 流程
 
 ### ① 诊断
 
-委托 `diagnosing-bugs` 完成 Phase 1–4：建立能捕捉用户症状的 tight feedback loop，实际复现并最小化，再形成可证伪的假设并按单变量探针验证。
+委托 `diagnosing-bugs` 完成修复前的诊断活动：建立能捕捉用户症状的 tight feedback loop，实际复现并最小化，再形成可证伪的假设并按单变量探针验证。不要依赖固定 Phase 编号；以上游当前“进入修复前必须完成的诊断出口”为事实源。
 
-出口：反馈回路已实际变红，且最小复现已确认；此阶段不写修复代码。
+出口：反馈回路已实际变红，最小复现已确认，且导致症状的假设已有证据；此阶段不写修复代码。
 
-### ② TDD 修复
+### ② 受保护的最小修复
 
-1. 在正确的公共 seam 上提出回归测试边界，并遵循 `tdd` 要求获得用户确认；只确认本次 seam，不建立重型 seam ledger。
-2. 加载 `tdd`，先把最小复现转成失败回归测试并实际看到 Red。
-3. 只写让该测试 Green 的最小修复，并遵循 `tdd` 的红绿循环。
+先判断 Red 证据类型：
 
-**硬门槛：**不存在已实际观察到的失败回归测试时，不得写任何修复代码。不存在正确 seam 时，本身就是 finding；记录架构阻塞，不绕过测试直接修改。
+- **功能 bug**：在正确的公共 seam 上提出回归测试边界，遵循 `tdd` 要求获得用户确认；把最小复现转成失败回归测试并实际看到 Red，再写最小修复直到 Green。
+- **性能回归**：复用 `diagnosing-bugs` 的 performance branch，建立可重复的 benchmark、timing harness、query-count 或 profiler-derived threshold；必须先实际观察到该阈值失败，再做最小修复，并用同一测量方式确认转绿。不为满足形式强造一个无法代表真实性能症状的普通单元测试。
 
-出口：回归测试先 Red，最小修复后 Green；不进入 `tdd-implement` 的长流程。
+**硬门槛：**不存在已实际观察到的 **red-capable regression evidence** 时，不得写修复代码。功能 bug 的证据必须是正确 seam 上的失败回归测试；性能回归可使用带明确阈值且可重复的 benchmark/perf harness。不存在正确 seam 或可靠性能测量边界时，本身就是 finding；记录阻塞，不绕过证据直接修改。
+
+出口：功能 bug 为 regression test Red → 最小修复 → Green；性能回归为 benchmark/perf threshold Red → 最小修复 → Green。两者都不进入 `tdd-implement` 的长流程。
 
 ### ③ 回归收尾
 
-按 `diagnosing-bugs` 的收尾要求重跑阶段 ① 的原始、未最小化反馈回路，确认用户症状消失；清理 `[DEBUG-...]` 探针和一次性 harness，并记录最终验证的假设。
+按 `diagnosing-bugs` 的收尾要求重跑阶段 ① 的原始、未最小化反馈回路，确认用户症状消失；功能 bug 重跑回归测试，性能回归重跑原始基准/测量；清理 `[DEBUG-...]` 探针和一次性 harness，并记录最终验证的假设。
 
-出口：原始症状消失、回归测试 Green、临时诊断产物已清理。
+出口：原始症状消失、对应 regression evidence 为 Green、临时诊断产物已清理。
 
 ## 回合连续性
 
-诊断 → seam 确认 → Red → 修复 → Green → 原始回路 → 清理在一个回合内连续推进。只在用户必须确认 seam、发现无 seam finding、外部环境阻塞或整个阶段出口时暂停；预告下一步后立即执行。
+诊断 → Red 证据 → 修复 → Green → 原始回路 → 清理在一个回合内连续推进。只有功能 bug 的 seam 确认、发现无正确 seam/测量边界、外部环境阻塞或整个阶段出口可以暂停；预告下一步后立即执行。
 
 ## 引用
 
-- 诊断：[`diagnosing-bugs`](.agents/skills/diagnosing-bugs/SKILL.md)
-- 修复：[`tdd`](.agents/skills/tdd/SKILL.md)
+- 诊断与性能分支：[`diagnosing-bugs`](.agents/skills/diagnosing-bugs/SKILL.md)
+- 功能 bug 修复：[`tdd`](.agents/skills/tdd/SKILL.md)
 - 负向边界：[`references/anti-patterns.md`](references/anti-patterns.md)

package/.agents/skills/diagnose-fix/references/anti-patterns.md

@@ -5,14 +5,15 @@ SKILL.md 正文各阶段规则是正面约束；本文件是负向边界（不
 ## 诊断阶段
 
 - 不跳过反馈回路直接猜根因：回路未红之前不进入假设、不写修复代码
-- 不把最小复现留在 harness 里：必须转写为正确 seam 上的回归测试，harness 只作诊断工具
+- 功能 bug 不把最小复现永久留在 harness 里：必须转写为正确 seam 上的回归测试；性能回归可保留最小、可重复且有明确阈值的 benchmark/perf harness 作为回归证据
 - 不一次改多个变量：探针一次只改一个，`[DEBUG-...]` 前缀标记
 
 ## 修复阶段
 
-- 不绕过测试直接改代码（见 SKILL.md ②无逃生舱）——没有 seam 是 finding，不是豁免
-- 不套用 tdd-implement 重流程：见 SKILL.md ②轻量声明——单 seam 修复直走红-绿，不引入重流程编排
-- 不重写 tdd 技能的红-绿语义：seam 定义、好测试标准、mocking 边界一律查上游技能
+- 不绕过 red-capable regression evidence 直接改代码——功能 bug 没有正确 seam 是 finding；性能回归没有可靠测量边界同样是 finding，不是豁免
+- 不为性能问题强造一个不能代表真实慢路径的普通单元测试；优先复用 diagnosis 中已经验证过的 benchmark、timing、query-count 或 profiler-derived threshold
+- 不套用 tdd-implement 重流程：单个 bug/perf regression 的修复保持轻量，不引入完整 delivery orchestration
+- 不重写 tdd 技能的红-绿语义：功能 bug 的 seam 定义、好测试标准、mocking 边界一律查上游技能
 
 ## 回归阶段
 

package/.agents/skills/grill-to-spec/SKILL.md

@@ -30,6 +30,10 @@ disable-model-invocation: true
 
 出口：spec 已发布，路径、状态和未纳入范围已报告。
 
+## 回合连续性
+
+本 skill 是 Long-Horizon Skill。阶段 ① 达到出口后立即进入阶段 ②；正常的阶段切换、进度汇报或“接下来生成 spec”不是回合终点。仅在必须获得用户确认的 ADR/spec 草稿、明确外部阻塞、用户主动停止或整个 skill 出口时暂停。确认完成后在同一任务链继续推进到下一可验证出口，不要求用户额外回复“继续”。
+
 ## 本 skill 独有门禁
 
 - ADR：草稿 → 用户确认 → 落盘，任何情况不例外；

package/.agents/skills/grill-to-spec/references/rules.md

@@ -1,33 +1,28 @@
-# 守则：Grill-to-Spec 产出物格式细则
+# 守则：Grill-to-Spec 本地增量规则
 
-三类产出物（Glossary / ADR / Spec）格式的**唯一细节出处**，由 SKILL.md 直链引用。SKILL.md 只保留流程、导航与不可协商规则，本文件不重复流程内容。
+本文件只保存 `grill-to-spec` 相对上游 `grill-with-docs` / `to-spec` 的**增量约束**。Spec 的章节、User Story 形状、Implementation Decisions 等格式全部以 `to-spec` 为唯一事实源，本文件不复制上游模板。
 
-## Glossary 守则
+## Glossary 增量规则
 
-- 懒创建：首个术语解析时才建 `CONTEXT.md`；多上下文时先确认归属，归属不清则询问
-- 只是 glossary：零实现细节，不当 spec/scratch pad
-- 只收本上下文特有术语，通用编程概念不收
-- 定义 WHAT 非 HOW，1-2 句；opinionated，同义词列 `_Avoid_`；术语解析即 inline 更新，不批量
+- 懒创建：首个术语解析时才建 `CONTEXT.md`；多上下文时先确认归属，归属不清则询问。
+- 只收本上下文特有术语；定义 WHAT 非 HOW，避免把 glossary 变成实现草稿。
+- glossary 可按上游流程 inline 更新，不额外增加确认轮次。
 
-## ADR 守则
+## ADR 增量规则
 
-- 三条件全满足才提议（难逆转 / 无上下文费解 / 真实权衡）；`docs/adr/` 懒创建
-- 格式：标题 + 1-3 句正文；可选节（Status/Considered Options/Consequences）按需，大多数不需要
-- 编号：`0001-slug.md` 顺序递增，扫描最高号 +1
-- 草稿经用户显式确认后落盘，任何情况无例外（见 SKILL.md 流程① 与不可协商规则）
+- 只有同时满足“难逆转 / 无上下文费解 / 存在真实权衡”时才提议 ADR。
+- ADR 草稿必须完整展示并获得用户明确确认后才落盘；这是本 skill 的独有硬门禁。
+- 不把 ADR 当 glossary 一样静默 inline 更新。
 
-## Spec 守则
+## Spec 增量规则
 
-- 完整七节模板逐节不缺：Problem Statement / Solution / User Stories / Implementation Decisions / Testing Decisions / Out of Scope / Further Notes
-- User Stories：长编号列表，`As an <actor>, I want a <feature>, so that <benefit>` 格式
-- Implementation Decisions：不含文件路径/代码片段；例外——原型产出的决策密集片段可 inline，注明来源并裁剪至决策部分
-- 全文贯穿 glossary 词汇；尊重所触区域既有 ADR
-- seams：既有优先于新建、取最高、理想数量 1，与用户确认
-- 发布后标 `ready-for-agent`，triage 状态以 issue 文件顶部 `Status:` 行记录
+- Spec 的结构与字段全部委托 `to-spec`，本文件不维护第二份模板。
+- seam 提案并入最终 spec 草稿，不再制造独立的一次确认。
+- 发布前只做一次最终 spec 明确确认；确认后写入并标记 `ready-for-agent`。
+- 全文沿用已经确认的 glossary 词汇，并尊重所触区域既有 ADR。
 
-## 反模式（不做什么）
+## 反模式
 
-- 不把守则当逐条朗读的检查清单——守则约束产出物格式，不约束对话节奏
-- 不把 ADR 当 glossary 一样 inline 更新（见 SKILL.md 不可协商规则）
-- 不产出守则之外的文件：产出物只有三种（Glossary / ADR / Spec）
-- 不在本文件之外重复守则细节——SKILL.md 与 references 之间信息只在一处存在
+- 不复制 `to-spec` 的章节清单、User Story 模板或 Implementation Decisions 细则。
+- 不产出 Glossary / ADR / Spec 之外的额外设计文件。
+- 不把本文件当逐条朗读的对话脚本；它只约束本地增量行为。

package/.agents/skills/scaffold-functional-test/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: scaffold-functional-test
 disable-model-invocation: false
-description: "Scaffold a repo-specific functional-test skill from spec — use when the user wants to generate a customized functional-test suite/skill from a spec/README/help; not for regular instance execution (use the generated instance-test skill) nor for TDD (use tdd-implement)"
+description: "Scaffold a repo-specific functional-test skill from spec — use when the user wants to generate a customized functional-test suite/skill from a spec/README/help; supports CLI, HTTP, browser, and file-oriented behaviors; not for regular instance execution nor for TDD"
 ---
 
 # Scaffold Functional Test
@@ -22,9 +22,11 @@ spec 不存在时可从 README 与 `--help` 建立候选清单，但必须把它
 
 ### ② 推导并确认实例
 
-按 [`references/schema.md`](references/schema.md) 为每个行为生成实例草案：每个实例必须有溯源，不能用无来源的隐含行为扩张范围。向用户展示实例清单并等待一次确认；确认前不落盘。
+按 [`references/schema.md`](references/schema.md) 为每个行为选择最接近真实用户路径的实例类型：`cli`、`http`、`browser` 或 `file`。每个实例必须有溯源，不能用无来源的隐含行为扩张范围，也不能为了统一格式给 browser/http 行为强塞无意义的 stdout/exit-code 字段。
 
-出口：实例清单已确认，每个实例字段完整且可追溯。
+向用户展示实例清单并等待一次确认；确认前不落盘。
+
+出口：实例清单已确认，每个实例类型、字段和断言完整且可追溯。
 
 ### ③ 生成或更新
 
@@ -39,19 +41,20 @@ spec 不存在时可从 README 与 `--help` 建立候选清单，但必须把它
 
 ### ④ 结构验证
 
-生成后立即做快速、确定性的结构验证：文件存在、schema 字段、实例溯源、spec hash、`generatedAt`、manual 段保护和内部链接均通过后再报告成功。不默认执行完整实例集，不启动服务，不产生功能测试副作用。
+生成后立即做快速、确定性的结构验证：文件存在、schema 字段、实例类型、实例溯源、spec hash、`generatedAt`、manual 段保护和内部链接均通过后再报告成功。不默认执行完整实例集，不启动服务，不产生功能测试副作用。
 
 出口：结构验证结果为 `PASS`，失败则报告具体 gap，不回滚生成物。
 
 ## 可选行为验证
 
-仅当用户明确要求运行实例集时，才调用生成的功能测试 skill 执行隔离、串行的实例验证；届时按实例捕获 stdout/stderr、exit code 和 expected-vs-actual evidence，并由执行 skill 报告 `PASS m/n`。这不是 scaffold 的默认步骤。
+仅当用户明确要求运行实例集时，才调用生成的功能测试 skill 执行隔离、串行的实例验证；执行器按实例 `type` 捕获对应 evidence：CLI 的 stdout/stderr/exit code，HTTP 的 status/body/headers，browser 的页面/DOM/network/console 证据，file 的文件与内容 diff，并报告 expected-vs-actual 与 `PASS m/n`。这不是 scaffold 的默认步骤。
 
 ## 不做什么
 
 - 不替代生成后的功能测试 skill；
 - 不替代 `tdd`、`tdd-implement` 或 `commit-check`；
-- 不覆盖 `<!-- manual -->` 段，不静默重生成，不把 README/`--help` 推断写成无溯源实例。
+- 不覆盖 `<!-- manual -->` 段，不静默重生成，不把 README/`--help` 推断写成无溯源实例；
+- 不把所有行为强制降格成 CLI 测试。
 
 ## 引用
 

package/.agents/skills/scaffold-functional-test/references/schema.md

@@ -2,24 +2,69 @@
 
 `scaffold-functional-test` 生成的实例清单以本文件为唯一字段契约。实例是声明式输入，不把执行逻辑散落在生成器正文中。
 
-## Required fields
+## Common required fields
 
-每个实例必须包含：
+每个实例都必须包含：
 
 - `prompt`：实例要覆盖的用户行为；
-- `command`：实际执行的命令或入口；
-- `expected files/content`：预期文件、副作用或内容；无文件副作用时明确写 `none`；
-- `expected stdout phrases`：预期 stdout/stderr 短语；无要求时明确写 `none`；
-- `expected exit code`：预期退出码；
+- `type`：实例类型，必须是 `cli`、`http`、`browser` 或 `file` 之一；
 - `source`：spec 章节/行号，或 README / `--help` 的明确来源。
 
-## Optional fields
+`setup`、`env`、`timeout`、`teardown` 为跨类型可选字段。不要为了凑字段写 `none`；某个断言维度不适用时直接省略。
 
-可按实例需要增加：
+## Type-specific contract
 
-- `setup`、`env`、`timeout`、`type`、`teardown`；
-- `type` 缺省为 `cli`；
-- 需要展示多个文件或短语时使用列表，不把不可验证的自然语言目标当作断言。
+### `type: cli`
+
+必须包含：
+
+- `command`：实际执行命令；
+- `expected exit code`：预期退出码。
+
+按需包含：
+
+- `expected stdout phrases`；
+- `expected stderr phrases`；
+- `expected files/content`。
+
+### `type: http`
+
+必须包含：
+
+- `request`：method + URL/path + 必要 headers/body；
+- `expected status`：预期 HTTP status。
+
+按需包含：
+
+- `expected body`；
+- `expected headers`；
+- `expected side effects`。
+
+### `type: browser`
+
+必须包含：
+
+- `entrypoint`：已有页面、dev server 或浏览器入口；
+- `steps`：最小用户操作序列；
+- `assertions`：DOM、可见文本、URL、网络或控制台等用户可观察断言。
+
+browser 实例不要求伪造 `stdout` 或 `exit code` 字段；执行器负责记录浏览器证据和必要截图/trace 路径。
+
+### `type: file`
+
+必须包含：
+
+- `command` 或已有生成入口；
+- `expected files/content`：应出现、变化或保持不变的文件与内容断言。
+
+按需包含 `expected exit code`、stdout/stderr 断言。
+
+## Assertion rules
+
+- 只写可机器验证或可明确观察的断言，不把“应该正常”“体验良好”这类自然语言目标当作 assertion；
+- 一个实例可以有多个断言，但每个断言必须能回溯到 `source`；
+- 优先验证用户可观察行为，不把内部实现细节当作功能结果；
+- 同一行为存在多种入口时，选择最接近真实使用路径的类型和入口，不强行统一成 CLI。
 
 ## Fingerprint
 

package/.agents/skills/tdd-implement/SKILL.md

@@ -6,34 +6,40 @@ disable-model-invocation: true
 
 # TDD Implement
 
-`seam` + `red-green` 是本技能的领衔词。它把一个 spec 或 task issue 编排成四个交付阶段；TDD 的红-绿语义、测试质量和 mock 边界以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，本技能只定义交付编排。
+`seam` + `red-green` 是本技能的领衔词。它把一个 spec 或 task issue 编排成三个交付阶段，并在 Verify 后执行一次非阶段的 Finalize 收尾；TDD 的红-绿语义、测试质量和 mock 边界以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，本技能只定义交付编排。
 
 本技能是 **Long-Horizon Skill**：阶段按顺序连续执行，并自带 **Turn Continuity** 与 **Chunking**。术语见 `CONTEXT.md`，技能设计规则见 `docs/agents/skill-design.md`。
 
 ## 入口与分支
 
-- **单 issue**：单个 `.scratch/<feature>/spec.md`、等价 spec 或 `Type: task` issue，按下方四个 Steps 完成一个交付闭环。
+- **单 issue**：单个 `.scratch/<feature>/spec.md`、等价 spec 或 `Type: task` issue，按下方三个 Steps 完成验证，再执行 Finalize 收尾。
 - **多 issue**：`.scratch/<feature>/issues/` 下存在多个 `Type: task` 文件时，先读取 [orchestration.md](references/orchestration.md)，按 `Blocked by` 构建 DAG、Kahn 分层，再由主代理按层串行完成各 issue。
 - `Type: research`、`prototype`、`grilling` 分流到对应技能，不进入本技能。
 
 多 issue 的 A0-A5 是编排控制活动，不是额外的产品交付阶段：依赖图、分层、串行调度、层收敛、全量收敛和回退/冲突处理的详规只在 [orchestration.md](references/orchestration.md) 中维护。
 
-## 四阶段 Steps
+## 三阶段 Steps
 
-按序执行；每步达到可验证出口条件后立即进入下一步。每步开始前读取 [stages.md](references/stages.md) 中对应定义。
+按序执行；每步达到可验证出口条件后立即进入下一步。每步只读取自己的轻量 reference，避免在每个阶段重复注入完整 `stages.md`。
 
-| Step | 做什么 | 出口条件 |
-|---|---|---|
-| ① **Contract** | 读取入口，提取 Acceptance Criteria，建立 Scope Ledger、Preflight、验证矩阵和 Behavior/Seam 边界 | 需求无待决歧义，验证命令已确定；知道做什么、从哪里验证、什么不做 |
-| ② **Red-Green** | 以 Behavior 为粒度执行有效 Red → 最小 Green → formatter/typecheck → 最小相关测试 | 所有 Behaviors 均有有效 Red、实现全绿，formatter/typecheck 和最小相关测试通过 |
-| ③ **Verify** | 运行当前 issue 影响范围测试、必要 build、要求的真实运行验证；执行一次 Standards + Spec Review | 最终 diff 的相关证据通过，真实运行验证完成（如要求），无 blocking finding |
-| ④ **Deliver** | 对齐 docs/README，执行敏感信息扫描，检查 staged diff、commit message 和必要的 Git history，创建独立 commit，更新 issue/progress.md | commit 已创建，Acceptance Criteria 全部通过，Tracker 与工作区反映真实完成状态 |
+| Step | Reference | 做什么 | 出口条件 |
+|---|---|---|---|
+| ① **Contract** | [contract.md](references/contract.md) | 读取入口，提取 Acceptance Criteria，建立 Scope Ledger、Preflight、验证矩阵和 Behavior/Seam 边界 | 需求无待决歧义，验证命令已确定；知道做什么、从哪里验证、什么不做 |
+| ② **Red-Green** | [red-green.md](references/red-green.md) | 以 Behavior 为粒度执行有效 Red → 最小 Green → formatter/typecheck → 最小相关测试 | 所有 Behaviors 均有有效 Red、实现全绿，formatter/typecheck 和最小相关测试通过 |
+| ③ **Verify** | [verify.md](references/verify.md) | 运行当前 issue 影响范围测试、必要 build、要求的真实运行验证；在最终 diff 稳定后调用一次 [code-review](.agents/skills/code-review/SKILL.md) | 最终 diff 的相关证据通过，真实运行验证完成（如要求），code-review 已完成且无 blocking finding |
+
+## Finalize（非阶段）
+
+Verify 出口满足后读取 [finalize.md](references/finalize.md) 并立即收尾。Finalize 不计入交付阶段，只负责必要的 docs/README 对齐、直接创建当前 issue 的独立 commit 与 Tracker/progress 更新；不执行额外安全扫描、staged diff 复核或 commit message 门禁。若发现实现、测试或文档证据不完整，回到对应阶段修复后再 Finalize。
+
+Finalize 出口：commit 已创建、Acceptance Criteria 全部通过，Tracker 与工作区反映真实完成状态。
 
 ## 运行时纪律
 
-- 四个阶段都从入口连续执行到自身出口：预告下一步后立即执行；进度输出并入工具调用序列，输出后继续执行。只有合规交互点、明确的外部阻塞或阶段出口条件结束当前回合。
-- 一个 seam 是公共可观察边界；一个 Behavior 是一个红-绿 cycle；一个 seam 可以包含多个 Behaviors。Seam/Behavior 的细节和 Todo 粒度见 [stages.md](references/stages.md)。
-- 当前 issue 的范围、Acceptance Criteria、Out of Scope、测试/typecheck/build/真实运行证据和最终 commit 必须可追溯。Seam 或专项测试绿色不代表 issue 完成；四阶段出口全部满足后才可标记 `resolved`。
+- 三个阶段都从入口连续执行到自身出口；Verify 出口满足后立即进入 Finalize：预告下一步后立即执行；进度输出并入工具调用序列，输出后继续执行。只有合规交互点、明确的外部阻塞或阶段出口条件结束当前回合。
+- 一个 seam 是公共可观察边界；一个 Behavior 是一个红-绿 cycle；一个 seam 可以包含多个 Behaviors。Seam/Behavior 的细节和 Todo 粒度只在进入 Step ② 时读取 [red-green.md](references/red-green.md)。
+- 每个 issue 只在 Verify 的最终 diff 稳定后调用一次 `code-review`；审查维度、reviewer 数量、提示词和输出格式全部由 `code-review` 自己定义，`tdd-implement` 不复制这些规则。`code-review` 未完成或存在 blocking finding 时 issue 不得收敛；A3 层收敛不再次调用 review。
+- 当前 issue 的范围、Acceptance Criteria、Out of Scope、测试/typecheck/build/真实运行证据和最终 commit 必须可追溯。Seam 或专项测试绿色不代表 issue 完成；三个阶段出口与 Finalize 全部满足后才可标记 `resolved`。
 - 多 issue 模式中，每个 issue 只提交一个独立 commit；issue 影响范围测试在 Step ③ 执行，全仓测试由 orchestration 的 A4 在全部 issue 完成后执行一次。
 
 ## 引用
@@ -41,5 +47,10 @@ disable-model-invocation: true
 - TDD 核心规则：[tdd 技能](.agents/skills/tdd/SKILL.md)
 - 测试标准：[tdd/tests.md](.agents/skills/tdd/tests.md)
 - Mock 指南：[tdd/mocking.md](.agents/skills/tdd/mocking.md)
-- 四阶段详规：[stages.md](references/stages.md)
+- Contract：[contract.md](references/contract.md)
+- Red-Green：[red-green.md](references/red-green.md)
+- Verify：[verify.md](references/verify.md)
+- Review 方法：[code-review](.agents/skills/code-review/SKILL.md)
+- Finalize：[finalize.md](references/finalize.md)
+- 完整兼容规范：[stages.md](references/stages.md)
 - 多 issue 编排：[orchestration.md](references/orchestration.md)

package/.agents/skills/tdd-implement/references/contract.md

@@ -0,0 +1,21 @@
+# Contract
+
+仅在 `tdd-implement` Step ① 读取。完整跨阶段规则仍以 `stages.md` 为兼容事实源；本文件只提供 Contract 阶段运行所需内容，避免加载其它阶段。
+
+## 操作
+
+1. 读取 spec/task、相关 `CONTEXT.md` 与必要 ADR，并使用仓库规定的代码探索入口理解当前实现。
+2. 提取每条 Acceptance Criterion，建立 Scope Ledger：`必须实现 / 明确不做 / 允许触及`。
+3. 将新发现分类为：当前 Behavior 必须修复、当前 issue 新增 Behavior、后续 ticket、无关项；只有前两类进入本次实现。
+4. 做一次 Preflight：记录 `HEAD`、工作区、`BASE_HEAD=$(git rev-parse HEAD)`、test/typecheck/build、可用 subagent/browser、敏感扫描、真实运行验证路径。
+5. 建立一次验证矩阵，后续复用，不重复探测等价命令。
+6. 定义公共 Seam 与 Behaviors：Behavior 必须映射到 Acceptance Criterion，并明确输入、可观察输出和验证层级。
+7. 已确认且未变化的 seam 直接复用；只有歧义、验收缺口、范围变化、破坏性操作或互斥方案才请求用户确认。
+
+## 出口
+
+- Acceptance Criteria、Scope Ledger 与 Out of Scope 明确；
+- 无待决需求歧义；
+- 验证矩阵和真实运行路径已确定，或明确标为 `blocked/unavailable`；
+- Behaviors/Seams 可追溯；
+- `BASE_HEAD` 已记录。

package/.agents/skills/tdd-implement/references/finalize.md

@@ -0,0 +1,27 @@
+# Finalize（非阶段）
+
+仅在 `tdd-implement` Step ③ Verify 通过后读取。Finalize 不计入交付阶段；开始后不新增产品 Behavior，发现实现、测试或文档遗漏时回到对应阶段。
+
+## Commit
+
+1. 如本次实现要求 README/docs/config/package 同步，完成必要更新。
+2. 按当前 issue 范围直接创建一个独立 commit。
+3. 不执行额外敏感信息/安全扫描，不做 `git diff --cached` 复核，也不设置额外 commit message 门禁。
+
+仓库级 Git 安全与历史保护规则仍然适用；Finalize 不重复定义或扩展这些规则。
+
+## Tracker 收尾
+
+Commit 成功后：
+
+- 勾选 Acceptance Criteria；
+- issue 标记 `resolved`；
+- 写实施总结并同步 `.scratch/<feature>/progress.md` 的 Status/Commit/Review/Tests；
+- 记录 commit hash/message、最终测试和真实运行结果；
+- 确认后续 blockers 是否解除。
+
+## 出口
+
+- 当前 issue 的独立 commit 已创建；
+- Acceptance Criteria 全部通过；
+- Tracker/progress 与真实完成度一致。

package/.agents/skills/tdd-implement/references/orchestration.md

@@ -1,8 +1,8 @@
 # 多 issue 编排（按依赖分层串行）
 
-本文件仅在 `.scratch/<feature>/issues/` 下存在多个 `Type: task` issue 时生效。单 `spec` / 单 `task` 直接按 [stages.md](stages.md) 的四阶段闭环执行。A0-A5 是编排控制活动，不是额外的产品交付阶段。
+本文件仅在 `.scratch/<feature>/issues/` 下存在多个 `Type: task` issue 时生效。单 `spec` / 单 `task` 直接按 [stages.md](stages.md) 的三个交付阶段执行，并在 Verify 后 Finalize。A0-A5 是编排控制活动，不是额外的产品交付阶段。
 
-主代理按依赖分层、层内按编号串行执行；每个 issue 由同一个主代理完成 Contract → Red-Green → Verify → Deliver，并创建一个独立 commit。实现细节以 [stages.md](stages.md) 为准，TDD 语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为准。
+主代理按依赖分层、层内按编号串行执行；每个 issue 由同一个主代理完成 Contract → Red-Green → Verify，再执行非阶段 Finalize 并创建一个独立 commit。实现细节以 [stages.md](stages.md) 为准，TDD 语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为准。
 
 ## 目录
 
@@ -20,8 +20,8 @@
 1. 扫描 `.scratch/<feature>/issues/` 下全部 `NN-<slug>.md`，逐文件解析 `Blocked by`：
    - `Blocked by: None`、`Blocked by: （无）` 或无此行：无依赖；
    - `Blocked by: 01, 02` 或 `Blocked by: 01（…）`：依赖对应编号 issue；
-   - 无法解析：按无依赖处理，并在编排总结中记录告警。
-2. 以 issue 编号为节点、`Blocked by` 为有向边构建 DAG；检测到环时列出环上节点并停止调度。
+   - `Blocked by` 行存在但无法解析：**fail closed**。将该 issue 标记为 `blocked`，记录原始字段和值，不把它加入可调度 DAG，也不得按“无依赖”继续。只有字段修正或用户明确确认依赖后才能继续编排。
+2. 以 issue 编号为节点、`Blocked by` 为有向边构建 DAG；检测到环时列出环上节点并停止调度。依赖引用了不存在的 issue 时同样 fail closed：对应 issue 保持 `blocked`，报告缺失节点，不静默忽略该依赖。
 3. 读取共享 `spec.md`（若存在）、`CONTEXT.md` 和与本次改动有关的 ADR。
 4. 完成编排级 Preflight：记录当前 `HEAD`、工作区状态、`BASE_HEAD=$(git rev-parse HEAD)`、测试/typecheck/build 命令、真实运行路径和敏感信息扫描脚本可用性。后续只使用已经确认的命令和路径。
 5. 强制初始化 `.scratch/<feature>/progress.md`：
@@ -38,10 +38,11 @@
 
 ### A0 出口
 
+- 所有 `Blocked by` 字段均可解析且依赖节点存在；否则相关 issue 保持 `blocked`，A1 不开始；
 - DAG 已构建且无环；
 - 编排 Preflight 和 `BASE_HEAD` 已记录；
 - `progress.md` 已存在并可回写；
-- 依赖解析告警已记录。
+- 依赖解析或缺失节点问题已明确报告，而不是降级成无依赖。
 
 ## A1：Kahn 拓扑分层
 
@@ -59,7 +60,8 @@ Ln = 最后一层
 ### A1 出口
 
 - Kahn 分层结果已展示并确认；
-- 每个 issue 都属于一个层；
+- 每个可调度 issue 都属于一个层；
+- 不存在因无法解析依赖而被误放入 L1 的 issue；
 - 同文件预期冲突已记录，必要时已通过依赖顺序隔离。
 
 ## A2：分层串行调度
@@ -67,22 +69,22 @@ Ln = 最后一层
 ```text
 for each layer Li in L1..Ln:
   for each issue in Li（按编号顺序）:
-    主代理执行四阶段：
+    主代理执行三个阶段：
       ① Contract
       ② Red-Green
-      ③ Verify（当前 issue 影响范围）
-      ④ Deliver（独立 commit + Tracker 收尾）
+      ③ Verify（当前 issue 影响范围 + 当前 issue review）
+    执行 Finalize（非阶段：独立 commit + Tracker 收尾）
     产出回执卡片并回写 issue
     强制更新 progress.md 的 Status/Commit/Review/Tests
   通过 A3 层收敛后进入下一层
 全部层完成后进入 A4
 ```
 
-每个 issue 的 Verify 只运行当前 issue 影响范围内的完整测试；全仓测试不在每个 issue 中重复执行。每个 issue 只做一次正式 Standards + Spec Review；修复 blocking finding 后执行定向复核，不重新启动完整 review。
+每个 issue 的 Verify 只运行当前 issue 影响范围内的完整测试；全仓测试不在每个 issue 中重复执行。当前 issue 的最终 diff 稳定后只调用一次 `code-review`；review 的内部方法完全由 `code-review` 定义。修复 blocking finding 后执行受影响验证和 finding delta recheck，不重复调用完整 `code-review`。
 
-主代理在层内和层间连续调度：一个 issue 的 Deliver 出口满足后，立即取下一个 issue，直到全部层完成或发生明确外部阻塞。进度输出并入执行序列，不在正常切换点等待用户“继续”。
+主代理在层内和层间连续调度：一个 issue 的 Finalize 出口满足后，立即取下一个 issue，直到全部层完成或发生明确外部阻塞。进度输出并入执行序列，不在正常切换点等待用户“继续”。
 
-进入 A2 前记录的 `BASE_HEAD` 必须在每个 issue 的阶段出口和 commit 前校验：
+进入 A2 前记录的 `BASE_HEAD` 必须在每个 issue 的三个阶段出口和 Finalize commit 前校验：
 
 ```bash
 git merge-base --is-ancestor $BASE_HEAD HEAD
@@ -100,7 +102,7 @@ Status: resolved
 Commit: <hash> — <message>
 Behaviors: <completed list>
 Acceptance Criteria: <checkbox result>
-Review: Standards + Spec, no blocking finding
+Review: code-review completed once, no blocking finding
 Tests: <targeted command and actual result>
 Runtime: <actual request/page-visible result or not required>
 Docs: <updated files or no update required>
@@ -108,13 +110,15 @@ Docs: <updated files or no update required>
 
 ### A2 出口
 
-- 当前层每个 issue 均完成四阶段并有独立 commit；
+- 当前层每个 issue 均完成三个阶段与 Finalize 并有独立 commit；
 - issue、回执卡片和 `progress.md` 一致；
 - 相关测试通过，工作区卫生和历史校验通过；
 - 没有未记录的跨 issue 改动。
 
 ## A3：层收敛
 
+A3 只做编排收敛，不再次调用 `code-review`；正式 review 已在每个 issue 的 Verify 中完成。
+
 每层全部 issue 串行完成后检查以下项目，全部通过才进入下一层：
 
 1. 所有 issue `Status: resolved`，实施总结已落盘，`progress.md` 对应行已为 `done`；
@@ -147,16 +151,17 @@ A5 负责所有编排级失败，不把失败静默吞掉，也不把不相关
 
 | 失败类别 | 处理 |
 |---|---|
+| `Blocked by` 存在但无法解析，或依赖节点不存在 | fail closed：该 issue 保持 `blocked`，保留原始依赖值并停止其调度；字段修正或用户明确确认依赖后才重新构建 DAG |
 | Contract 歧义、验收缺口、范围变化 | 回到该 issue 的 Contract，补 Scope Ledger、Behavior 和验证矩阵 |
 | Red-Green 的有效 Red、实现、typecheck 或 targeted test 失败 | 回到该 issue 的 Red-Green，修复当前 Behavior 并重新验证 |
 | Verify 的测试、build、真实运行或 review blocking finding 失败 | 回到受影响 issue 的对应阶段；修复后只做受影响检查和 delta review |
-| Deliver 的 docs、敏感扫描、commit 或 Tracker 失败 | 保持 issue 未 resolved，修复 Deliver 门禁后重新验证 |
+| Finalize 的必要 docs、commit 或 Tracker 失败 | 保持 issue 未 resolved，修复 Finalize 问题后重新验证 |
 | 全量测试失败 | 定位到引入失败的 issue，按上述路径修复；只在修复后重跑必要范围和全量测试 |
 | `Blocked by` 依赖未完成 | 后续 issue 保持 `blocked`，前置 issue resolved 后自动解阻 |
 | 多 issue 预期修改同一文件 | 记录冲突，按编号串行；无法安全归属时暂停并请求用户决定 |
 | Git 历史祖先校验失败 | 立即停止写入，使用 `git reflog` 找回 `BASE_HEAD` 之后的提交，校验通过后继续 |
 
-主代理不跨 issue 无记录改动；不通过第二次完整双轴 review 来掩盖定向修复。外部权限、model、browser 或 tool 不可用时遵循 [stages.md](stages.md) 的 Tool Failure Budget，最多一次有依据的 fallback，仍失败则标记 `blocked/unavailable` 并报告实际状态。
+主代理不跨 issue 无记录改动；不通过第二次完整 `code-review` 来掩盖定向修复。外部权限、model、browser 或 tool 不可用时遵循 [stages.md](stages.md) 的 Tool Failure Budget，最多一次有依据的 fallback，仍失败则标记 `blocked/unavailable` 并报告实际状态。
 
 ### A5 出口
 

package/.agents/skills/tdd-implement/references/red-green.md

@@ -0,0 +1,25 @@
+# Red-Green
+
+仅在 `tdd-implement` Step ② 读取。TDD 语义以 `.agents/skills/tdd/SKILL.md` 为唯一事实源；本文件只描述交付阶段编排。
+
+## 操作
+
+1. 加载 `tdd` 核心规则；每个 Behavior 只按需读取 `tdd/tests.md` / `tdd/mocking.md`。
+2. Todo 以 Behavior 为粒度；一个 Behavior 是一个 `Red → Green → formatter/typecheck → 最小相关测试` cycle。
+3. 有效 Red 必须从公共接口观察到“目标行为尚未实现”的断言失败；语法错误、fixture/helper 缺失、环境启动失败、timeout 或工具错误都不是有效 Red。
+4. 只写让当前 Behavior Green 的最小实现；每次修改后即时 formatter/typecheck 和最小相关测试。
+5. 每个 Behavior 完成后更新 Todo，然后立即进入下一个 Behavior；一个 Seam 全绿不是阶段出口。
+
+## Turn Continuity / Chunking
+
+- 每个 Behavior 的 Red → Green → 验证在一个回合内连续完成；预告下一步后立即执行。
+- 所有 Behaviors 完成前持续推进，除非遇到合规交互点或明确外部阻塞。
+- 单次 write 超过约 150 行时先骨架后分批；超过约 5 处 replace 时拆批验证。
+
+## 出口
+
+- 所有 Behaviors 都有有效 Red；
+- 最小实现全部 Green；
+- formatter/typecheck 与最小相关测试通过；
+- Todo 全部反映真实完成状态；
+- `BASE_HEAD` 祖先校验通过。