@heihei0299/matt-skills 2.0.1 → 2.1.0

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

@@ -20,19 +20,20 @@ disable-model-invocation: true
 
 ## 四阶段 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、要求的真实运行验证；并行执行两个独立 reviewer（Standards-only + Spec-only） | 最终 diff 的相关证据通过，真实运行验证完成（如要求），两个 reviewer 结果齐全且无 blocking finding |
+| ④ **Deliver** | [deliver.md](references/deliver.md) | 对齐 docs/README，执行敏感信息扫描，检查 staged diff、commit message 和必要的 Git history，创建独立 commit，更新 issue/progress.md | commit 已创建，Acceptance Criteria 全部通过，Tracker 与工作区反映真实完成状态 |
 
 ## 运行时纪律
 
 - 四个阶段都从入口连续执行到自身出口：预告下一步后立即执行；进度输出并入工具调用序列，输出后继续执行。只有合规交互点、明确的外部阻塞或阶段出口条件结束当前回合。
-- 一个 seam 是公共可观察边界；一个 Behavior 是一个红-绿 cycle；一个 seam 可以包含多个 Behaviors。Seam/Behavior 的细节和 Todo 粒度见 [stages.md](references/stages.md)。
+- 一个 seam 是公共可观察边界；一个 Behavior 是一个红-绿 cycle；一个 seam 可以包含多个 Behaviors。Seam/Behavior 的细节和 Todo 粒度只在进入 Step ② 时读取 [red-green.md](references/red-green.md)。
+- Verify 的正式 review round 必须并行启动两个独立 reviewer：一个只执行 Standards，一个只执行 Spec；同一个 reviewer invocation 不能同时计入两个轴。两份结果齐全前，review 不得标记完成；任一 reviewer 不可用时记录 `blocked/unavailable` 并保持 issue 未解决。
 - 当前 issue 的范围、Acceptance Criteria、Out of Scope、测试/typecheck/build/真实运行证据和最终 commit 必须可追溯。Seam 或专项测试绿色不代表 issue 完成；四阶段出口全部满足后才可标记 `resolved`。
 - 多 issue 模式中，每个 issue 只提交一个独立 commit；issue 影响范围测试在 Step ③ 执行，全仓测试由 orchestration 的 A4 在全部 issue 完成后执行一次。
 
@@ -41,5 +42,9 @@ 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)
+- Deliver：[deliver.md](references/deliver.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/deliver.md

@@ -0,0 +1,33 @@
+# Deliver
+
+仅在 `tdd-implement` Step ④ 读取。阶段开始后不新增产品 Behavior；发现实现/测试/文档遗漏时回到对应阶段。
+
+## Commit 前门禁
+
+1. 逐条复核 Acceptance Criteria、Scope Ledger 与 Out of Scope。
+2. 确认 README/docs/config/package 与实现一致，且证据对应最后一次修改。
+3. 清理本次临时文件和进程；工作区只保留预期改动。
+4. 对 staged diff 执行敏感信息扫描。
+5. 执行 `git merge-base --is-ancestor $BASE_HEAD HEAD`。
+6. 确认 commit message 与暂存区都只覆盖当前 issue，并检查 `git diff --cached`。
+7. 创建当前 issue 的独立 commit。
+
+## Tracker 收尾
+
+- 勾选 Acceptance Criteria；
+- issue 标记 `resolved`；
+- 写实施总结并同步 `.scratch/<feature>/progress.md` 的 Status/Commit/Review/Tests；
+- 记录 commit hash/message、最终测试和真实运行结果；
+- 清理一次性资源，确认后续 blockers 是否解除。
+
+## Git 安全
+
+历史只能在 `BASE_HEAD` 之后追加；未经用户明确确认不使用 `git reset --hard`、`git checkout .`、`git clean -fd`、`git stash push --include-untracked`、force push 或交互式 rebase 来“清理”目录。
+
+## 出口
+
+- 独立 commit 已创建；
+- Acceptance Criteria 全部通过；
+- Tracker/progress 与真实完成度一致；
+- 工作区无本次临时残留；
+- 文档与实现一致，Git history 校验通过。

package/.agents/skills/tdd-implement/references/orchestration.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：分层串行调度
@@ -78,7 +80,7 @@ for each layer Li in L1..Ln:
 全部层完成后进入 A4
 ```
 
-每个 issue 的 Verify 只运行当前 issue 影响范围内的完整测试；全仓测试不在每个 issue 中重复执行。每个 issue 只做一次正式 Standards + Spec Review；修复 blocking finding 后执行定向复核，不重新启动完整 review。
+每个 issue 的 Verify 只运行当前 issue 影响范围内的完整测试；全仓测试不在每个 issue 中重复执行。每个 issue 只做一次正式 Review round；该 round 并行启动两个独立 reviewer：Standards-only 与 Spec-only。两份结果齐全前不得收敛 review；修复 blocking finding 后执行定向复核，不重新启动完整双轴 review。
 
 主代理在层内和层间连续调度：一个 issue 的 Deliver 出口满足后，立即取下一个 issue，直到全部层完成或发生明确外部阻塞。进度输出并入执行序列，不在正常切换点等待用户“继续”。
 
@@ -100,7 +102,7 @@ Status: resolved
 Commit: <hash> — <message>
 Behaviors: <completed list>
 Acceptance Criteria: <checkbox result>
-Review: Standards + Spec, no blocking finding
+Review: Standards-only reviewer + Spec-only reviewer, both completed, 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>
@@ -147,6 +149,7 @@ 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 |

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` 祖先校验通过。

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

@@ -137,7 +137,7 @@ Seam 或专项测试绿色不等于 issue 完成；只有四个阶段全部通
 当前 issue 影响范围测试
 → 必要 build
 → 必要真实运行验证
-→ 一次 Standards + Spec Review
+→ 一个正式 Review round：并行启动两个独立 reviewer（Standards-only + Spec-only）
 → 修复 blocking finding 后的定向复核
 ```
 
@@ -150,19 +150,21 @@ Seam 或专项测试绿色不等于 issue 完成；只有四个阶段全部通
 
 ### Review
 
-1. 每个 issue 恰好执行一次正式双轴 review：
-   - **Standards**：是否符合仓库规则和代码质量要求；
-   - **Spec**：是否逐条满足当前 issue 的 Acceptance Criteria。
-2. 两个轴独立输出、互不掩盖；每个轴明确限制输出，例如 `≤ 400 words / ≤ 40 行`。
-3. findings 分类为：当前 issue blocking、后续 ticket、advisory、out of scope。只处理当前 issue blocking finding；其余记录而不扩大范围。
-4. 修复 blocking finding 后只运行受影响测试、typecheck 和 finding 的 delta recheck，不重新启动完整双轴 review。审查结果只在对话输出，不生成 `review-*.md` 等书面报告文件。
+1. 每个 issue 恰好执行一次正式双轴 review round：该 round 必须并行启动两个独立 reviewer invocation/process：
+   - **Standards-only reviewer**：只判断是否符合仓库规则和代码质量要求；
+   - **Spec-only reviewer**：只判断是否逐条满足当前 issue 的 Acceptance Criteria。
+   同一个 reviewer invocation 不能同时承担两个轴；“一个 reviewer 输出两个章节”不算独立双轴 review。
+2. 两个 reviewer 都必须返回结果后，才能记录 `review_axes: standards=completed; spec=completed` 并推进 review state；任一 reviewer/tool/model 不可用时记录 `blocked/unavailable`，保持 issue 未解决，不用人工 diff 检查替代正式轴结果。
+3. 两个轴独立输出、互不掩盖；每个轴明确限制输出，例如 `≤ 400 words / ≤ 40 行`。
+4. findings 分类为：当前 issue blocking、后续 ticket、advisory、out of scope。只处理当前 issue blocking finding；其余记录而不扩大范围。
+5. 修复 blocking finding 后只运行受影响测试、typecheck 和 finding 的 delta recheck，不重新启动完整双轴 review。审查结果只在对话输出，不生成 `review-*.md` 等书面报告文件。
 
 ### 出口条件
 
 - 最终 diff 对应的相关测试通过；
 - 必要 typecheck/build 通过；
 - ticket 要求的真实运行验证已完成并记录实际结果；
-- 一次 Standards + Spec Review 已完成；
+- 一个正式 Review round 已完成；Standards-only 与 Spec-only 两个独立结果均已记录；
 - 无 blocking finding；
 - 受影响范围的最后一次证据对应当前 diff。
 
@@ -189,7 +191,7 @@ Seam 或专项测试绿色不等于 issue 完成；只有四个阶段全部通
 9. 确认暂存区只包含当前 issue；
 10. 执行 `git diff --cached`，再创建当前 issue 的独立 commit。
 
-执行敏感信息扫描脚本（`bash .agents/skills/commit-check/scripts/scan-sensitive.sh --staged-only`），检查 staged diff、commit message 和 Git history preservation，全部通过后创建当前 issue 的独立 commit。
+执行敏感信息扫描脚本（`bash .agents/skills/tdd-implement/scripts/scan-sensitive.sh --staged-only`），检查 staged diff、commit message 和 Git history preservation，全部通过后创建当前 issue 的独立 commit。
 
 ### Tracker 收尾
 

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

@@ -0,0 +1,24 @@
+# Verify
+
+仅在 `tdd-implement` Step ③ 读取。验证必须对应当前最终 diff；产品代码或测试再次变化时，旧证据失效。
+
+## 固定顺序
+
+`影响范围测试 → 必要 build → 必要真实运行验证 → 一次 Standards + Spec Review → blocking 修复后的定向复核`
+
+## 规则
+
+- 单 issue / 单 spec：按 Contract 验证矩阵运行完整相关测试；多 issue：只跑当前 issue 影响范围，全仓测试留给 orchestration A4。
+- ticket 要求真实运行时，优先专用 browser，其次项目已有 Playwright；HTTP/CLI 不能替代 WebUI 可见验证。
+- 临时进程必须使用隔离配置/端口，记录 PID 与实际结果，结束后清理。
+- 每个 issue 恰好一次正式 Review round：并行启动两个独立 reviewer invocation/process，一个只执行 Standards-only，一个只执行 Spec-only；同一 invocation 不得覆盖两个轴。两份结果齐全前保持 `blocked/unavailable` 或未完成状态。
+- findings 只分为当前 blocking、后续 ticket、advisory、out of scope；仅修当前 blocking。
+- 修复 blocking 后只重跑受影响测试/typecheck 与 delta recheck，不重复完整双轴 review；修复不会重置已完成的两个 review axes。
+
+## 出口
+
+- 最终 diff 的相关测试/typecheck/build 通过；
+- 要求的真实运行验证有实际证据；
+- 一次 Standards + Spec Review 已完成；
+- 无 blocking finding；
+- 最后一次证据产生在最后一次相关修改之后。