@heihei0299/matt-skills 2.1.9 → 2.1.13

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

@@ -1,171 +1,54 @@
-# 多 issue 编排（按依赖分层串行）
+# 多 issue 编排
 
-本文件仅在 `.scratch/<feature>/issues/` 下存在多个 `Type: task` issue 时生效。单 `spec` / 单 `task` 直接按 [stages.md](stages.md) 的三个交付阶段执行，并在 Verify 后 Finalize。A0-A5 是编排控制活动，不是额外的产品交付阶段。
+仅在存在多个 `Type: task` issue 时生效。每个 issue 仍按 `Red-Green → Verify → Finalize` 独立完成；本文件只负责依赖顺序与状态推进。
 
-主代理按依赖分层、层内按编号串行执行；每个 issue 由同一个主代理完成 Contract → Red-Green → Verify，再执行非阶段 Finalize 并创建一个独立 commit。实现细节以 [stages.md](stages.md) 为准，TDD 语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为准。
+## 1. 构建依赖图
 
-## 目录
+读取每个 issue 的 `Blocked by`：
 
-- [A0：依赖图与编排 Preflight](#a0依赖图与编排-preflight)
-- [A1：Kahn 拓扑分层](#a1kahn-拓扑分层)
-- [A2：分层串行调度](#a2分层串行调度)
-- [A3：层收敛](#a3层收敛)
-- [A4：最终收敛](#a4最终收敛)
-- [A5：回退与冲突处理](#a5回退与冲突处理)
+- 无依赖时视为可直接调度；
+- 引用了其它 issue 时建立依赖边；
+- 字段无法解析、依赖节点不存在或出现环时，对受影响 issue 停止调度并报告实际原因，不降级为无依赖。
 
----
+使用 Kahn 算法按依赖关系分层；层间串行，每层内按 issue 编号串行。
 
-## A0：依赖图与编排 Preflight
-
-1. 扫描 `.scratch/<feature>/issues/` 下全部 `NN-<slug>.md`，逐文件解析 `Blocked by`：
-   - `Blocked by: None`、`Blocked by: （无）` 或无此行：无依赖；
-   - `Blocked by: 01, 02` 或 `Blocked by: 01（…）`：依赖对应编号 issue；
-   - `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`：
-
-   ```markdown
-   ## DAG
-   ## Layers (Kahn L1..Ln)
-   ## Progress
-   | NN | Status | Commit | Review | Tests |
-   |---|---|---|---|---|
-   ```
-
-   `progress.md` 是派生视图，真相源仍是 `spec.md` 与 `issues/*.md`。
-
-### A0 出口
-
-- 所有 `Blocked by` 字段均可解析且依赖节点存在；否则相关 issue 保持 `blocked`，A1 不开始；
-- DAG 已构建且无环；
-- 编排 Preflight 和 `BASE_HEAD` 已记录；
-- `progress.md` 已存在并可回写；
-- 依赖解析或缺失节点问题已明确报告，而不是降级成无依赖。
-
-## A1：Kahn 拓扑分层
-
-对 DAG 做 Kahn 分层：
+## 2. 串行执行
 
 ```text
-L1 = 全部入度为 0 的节点
-L2 = 移除 L1 后入度为 0 的节点
-...
-Ln = 最后一层
+for each layer:
+  for each issue:
+    Red-Green
+    Verify
+    Finalize
+    更新 issue 与 progress
 ```
 
-每层内节点互无依赖，但仍由主代理按编号串行执行。层间必须串行。编排开始前一次性向用户展示 DAG 和 `L1..Ln`，得到确认后进入 A2；这是合规交互点，不把每个 seam 或每个 issue 的正常切换变成确认点。
-
-### A1 出口
-
-- Kahn 分层结果已展示并确认；
-- 每个可调度 issue 都属于一个层；
-- 不存在因无法解析依赖而被误放入 L1 的 issue；
-- 同文件预期冲突已记录，必要时已通过依赖顺序隔离。
-
-## A2：分层串行调度
-
-```text
-for each layer Li in L1..Ln:
-  for each issue in Li（按编号顺序）:
-    主代理执行三个阶段：
-      ① Contract
-      ② Red-Green
-      ③ Verify（当前 issue 影响范围 + 当前 issue review）
-    执行 Finalize（非阶段：独立 commit + Tracker 收尾）
-    产出回执卡片并回写 issue
-    强制更新 progress.md 的 Status/Commit/Review/Tests
-  通过 A3 层收敛后进入下一层
-全部层完成后进入 A4
-```
-
-每个 issue 的 Verify 只运行当前 issue 影响范围内的测试；编排层不额外扩大测试范围。当前 issue 的最终 diff 稳定后只调用一次 `code-review`；review 的内部方法完全由 `code-review` 定义。修复 blocking finding 后执行受影响验证和 finding delta recheck，不重复调用完整 `code-review`。
-
-主代理在层内和层间连续调度：一个 issue 的 Finalize 出口满足后，立即取下一个 issue，直到全部层完成或发生明确外部阻塞。进度输出并入执行序列，不在正常切换点等待用户“继续”。
-
-进入 A2 前记录的 `BASE_HEAD` 必须在每个 issue 的三个阶段出口和 Finalize commit 前校验：
-
-```bash
-git merge-base --is-ancestor $BASE_HEAD HEAD
-```
-
-为达到工作区干净只删除本次产生的 `[DEBUG-...]` 和一次性临时产物；未经用户确认不使用 `git reset --hard`、`git checkout .`、`git clean -fd`、`git stash push --include-untracked` 或其他改写/丢弃历史的命令。
-
-### Issue 回执卡片
-
-每个 issue 完成后记录并回写：
-
-```text
-Issue: NN
-Status: resolved
-Commit: <hash> — <message>
-Behaviors: <completed list>
-Acceptance Criteria: <checkbox result>
-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>
-```
-
-### A2 出口
-
-- 当前层每个 issue 均完成三个阶段与 Finalize 并有独立 commit；
-- issue、回执卡片和 `progress.md` 一致；
-- 相关测试通过，工作区卫生和历史校验通过；
-- 没有未记录的跨 issue 改动。
-
-## A3：层收敛
-
-A3 只做编排收敛，不再次调用 `code-review`；正式 review 已在每个 issue 的 Verify 中完成。
-
-每层全部 issue 串行完成后检查以下项目，全部通过才进入下一层：
-
-1. 所有 issue `Status: resolved`，实施总结已落盘，`progress.md` 对应行已为 `done`；
-2. 该层 issue 的相关测试通过；
-3. `git status` 只显示预期改动或干净；
-4. `git merge-base --is-ancestor $BASE_HEAD HEAD` 通过；
-5. 不存在未分类的 scope 扩张、review blocking finding 或未清理临时产物。
-
-任一项失败，定位到该层失败 issue，按 A5 回退并重做该 issue 的受影响阶段或 Behavior，然后重新收敛本层。
-
-## A4：最终收敛
-
-全部层完成且各层收敛通过后：
+一个 issue Finalize 完成后立即进入下一个可调度 issue。前置 issue 未完成时，其依赖项保持 `blocked`。
 
-1. 汇总并确认各 issue 的相关测试、typecheck/build、真实运行和 review 证据仍对应最终状态；若后续改动使证据失效，只重新验证受影响范围；
-2. 执行 `git merge-base --is-ancestor $BASE_HEAD HEAD`；失败时按 A5 恢复后重验；
-3. 执行 `git status`，确认无 `[DEBUG-...]`、一次性脚本或未跟踪临时文件；
-4. 汇总各 issue 回执卡片的 commit、Behaviors、Acceptance Criteria、测试、真实运行和文档对齐结果；汇总只在对话输出，不另写汇总文件。
+每个 issue 的 TDD、验证、Review 与 Finalize 规则分别以 `SKILL.md`、`red-green.md`、`verify.md`、`finalize.md` 为准，本文件不重复定义。
 
-### A4 出口
+## 3. 状态收敛
 
-- 全部 issue 已有独立 commit、实施总结和 `progress.md` 派生记录；
-- 各 issue 的受影响验证证据仍对应最终状态；
-- 工作区卫生、历史校验和真实运行要求均满足；
-- `progress.md` 与 `issues/*.md` 一致，不一致时以 issue 真相源为准并修复派生视图。
+每个 issue 完成后同步：
 
-## A5：回退与冲突处理
+- `Status`；
+- commit；
+- Review 状态；
+- 验证结果；
+- 已解除的 blockers。
 
-A5 负责所有编排级失败，不把失败静默吞掉，也不把不相关问题塞入当前 issue：
+当前层所有 issue 完成后进入下一层。全部层完成后，确认 issue 与 progress 状态一致即可结束；不额外扩大验证范围，也不再次执行完整 Review。
 
-| 失败类别 | 处理 |
-|---|---|
-| `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 |
-| Finalize 的必要 docs、commit 或 Tracker 失败 | 保持 issue 未 resolved，修复 Finalize 问题后重新验证 |
-| A4 收敛发现验证证据失效 | 定位到受影响 issue，按上述路径修复；只重新验证受影响范围 |
-| `Blocked by` 依赖未完成 | 后续 issue 保持 `blocked`，前置 issue resolved 后自动解阻 |
-| 多 issue 预期修改同一文件 | 记录冲突，按编号串行；无法安全归属时暂停并请求用户决定 |
-| Git 历史祖先校验失败 | 立即停止写入，使用 `git reflog` 找回 `BASE_HEAD` 之后的提交，校验通过后继续 |
+## 冲突与失败
 
-主代理不跨 issue 无记录改动；不通过第二次完整 `code-review` 来掩盖定向修复。外部权限、model、browser 或 tool 不可用时遵循 [stages.md](stages.md) 的 Tool Failure Budget，最多一次有依据的 fallback，仍失败则标记 `blocked/unavailable` 并报告实际状态。
+- `Blocked by` 无法解析、依赖缺失或存在环：停止受影响调度并报告。
+- issue 执行失败：保持未完成，按失败所在 Step 处理；其依赖项继续保持 `blocked`。
+- 多个 issue 修改同一位置且无法安全串行归属：暂停相关 issue，请求用户决定。
+- 外部权限、工具或环境阻塞：记录实际状态，不把失败静默当作完成。
 
-### A5 出口
+## 出口
 
-- 失败原因已分类并记录；
-- 回退目标明确，受影响证据已重新验证；
-- 冲突已按依赖顺序解决或已明确请求用户决策；
-- DAG 顺序、issue 状态、commit 和 `progress.md` 保持一致。
+- 所有可执行 issue 均按依赖顺序完成；
+- 每个完成的 issue 均有独立 commit；
+- issue、依赖状态与 progress 一致；
+- 不存在被误当作已完成的 blocked issue。

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

@@ -1,24 +1,15 @@
 # Verify
 
-仅在 `tdd-implement` Step ③ 读取。验证必须对应当前最终 diff；产品代码或测试再次变化时，测试/typecheck/build 等受影响证据失效。
-
-## 固定顺序
-
-`影响范围测试 → 必要 build → 必要真实运行验证 → code-review 一次 → blocking 修复后的定向复核`
+验证必须对应当前最终 diff；实现或测试变化后，只重新验证受影响证据。
 
 ## 规则
 
-- 单 issue / 单 spec 与多 issue 均按 Contract 验证矩阵运行当前 issue 影响范围测试；不因进入 Verify 自动扩大测试范围。
-- ticket 要求真实运行时，优先专用 browser，其次项目已有 Playwright；HTTP/CLI 不能替代 WebUI 可见验证。
-- 临时进程必须使用隔离配置/端口，记录 PID 与实际结果，结束后清理。
-- 当前 issue 的最终 diff 稳定后，调用一次 [code-review](.agents/skills/code-review/SKILL.md)。`tdd-implement` 只规定调用时机；审查维度、reviewer 数量、提示词、上下文与输出格式以 `code-review` 为唯一事实源。
-- `code-review` 未完成或返回 blocking finding 时，issue 保持未完成；只修当前 issue 的 blocking finding，其余按 review 结果记录。
-- 修复 blocking finding 后，只重跑受影响测试/typecheck 并对该 finding 做 delta recheck；不再次调用完整 `code-review`。若修复引入新的 Behavior、改变 Scope 或使原 Review 对象不再成立，则回到 Contract/Red-Green，重新形成稳定最终 diff 后再进入 Verify。
+- 只验证当前 issue 的必要范围，不因进入 Verify 自动扩大验证范围。
+- ticket 要求真实运行验证时，执行与验收目标匹配的实际验证。
+- 验证通过后不机械重复等价验证。
+- 若修改产生新的 Behavior，返回 Red-Green 对该 Behavior 执行 TDD，完成后再验证受影响范围。
 
 ## 出口
 
-- 最终 diff 的相关测试/typecheck/build 通过；
-- 要求的真实运行验证有实际证据；
-- 当前稳定 diff 已完成一次 `code-review`；
-- 无 blocking finding；
-- post-review 修复（如有）的受影响验证与 finding delta recheck 已完成。
+- 当前 issue 的必要验证通过；
+- 要求的真实运行验证完成。

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

@@ -1,21 +0,0 @@
-# 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/red-green.md

@@ -1,25 +0,0 @@
-# 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

@@ -1,254 +0,0 @@
-# 三阶段详细定义 + Finalize
-
-单 `spec` / 单 `task` 与多 `task` 共用下列三个交付阶段；Verify 通过后执行 Finalize 收尾，Finalize 不计入阶段。多 issue 的依赖图、Kahn 分层、层收敛、最终收敛和回退/冲突处理见 [orchestration.md](orchestration.md)。TDD 语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，不在此重写。
-
-## 目录
-
-- [① Contract：明确交付契约](#阶段-①-contract明确交付契约)
-- [② Red-Green：行为级 TDD](#阶段-②-red-green行为级-tdd)
-- [③ Verify：最终验证与审查](#阶段-③-verify最终验证与审查)
-- [Finalize：非阶段交付收尾](#finalize非阶段交付收尾)
-- [跨阶段运行纪律](#跨阶段运行纪律)
-- [状态统一](#状态统一)
-- [回退路由](#回退路由)
-
----
-## 不可省略的质量门禁
-
-无论单 issue 还是多 issue，以下门禁都必须形成证据：
-
-1. 当前 issue 的范围、Acceptance Criteria 和 Out of Scope 明确；
-2. 产品实现之前存在有效 Red；
-3. 最终 diff 对应的相关测试和 typecheck 通过；
-4. ticket 要求真实运行时，真实运行验证已完成；
-5. 当前稳定 diff 已完成一次 `code-review` 且无 blocking finding；
-6. README/docs 与实现一致；
-7. 每个 issue 形成独立、可追溯的 commit；
-8. Tracker 状态与真实完成度一致。
-
-Seam 或专项测试绿色不等于 issue 完成；只有三个阶段与 Finalize 全部通过，issue 才能标记为 `resolved`。
-
-
-## 阶段 ① Contract：明确交付契约
-
-### 入口条件
-
-- 用户提供单个 `spec`、等价 spec 或 `Type: task` issue。
-- `research`、`prototype`、`grilling` 等非实现入口已分流。
-
-### 操作
-
-1. 完整读取入口；按需读取 `CONTEXT.md` 的相关术语和与本次 spec、触及符号或失败证据有关的 ADR。
-2. 使用仓库规定的代码探索入口。探索结果含完整源码时视为已读，不再次 `read` 同一文件，除非文件发生漂移或只返回调用路径。
-3. 逐条提取 Acceptance Criteria，并写出本 issue 的 **Scope Ledger**：
-
-   ```text
-   必须实现：当前 issue 要求的行为
-   明确不做：后续 tickets 和 Out of Scope
-   允许触及：预计受影响的模块、组件、接口
-   ```
-
-4. 实现或 Review 中发现的新问题必须归类为：
-   - 当前 Behavior 必须修复；
-   - 当前 issue 需要新增 Behavior；
-   - 后续 ticket；
-   - 与当前 feature 无关。
-
-   只有前两类进入当前实现；第 2 类必须补回 Contract 和验证矩阵，第 3、4 类保留记录，不无记录地扩大范围。
-5. 完成一次 **Preflight** 并记录真实结果：
-   - 当前 `HEAD`、工作区状态和 `BASE_HEAD=$(git rev-parse HEAD)`；
-   - 可用的 test、typecheck、build 命令；
-   - `code-review` 可用性；
-   - 可用的 browser 或 Playwright 路径；
-   - ticket 要求的真实运行验证方式。
-6. 建立一次验证矩阵，列出 targeted tests、typecheck、必要 build、smoke/package check 和真实运行验证，并记录各项的触发条件，后续只复用这份矩阵。
-7. 识别公共测试边界和 Behaviors。一个 Seam 是一个公共可观察边界；一个 Behavior 是一个红-绿 cycle；一个 Seam 可以包含多个 Behaviors。每个 Behavior 明确输入、可观察输出、对应 Acceptance Criterion 和验证层级。
-8. spec 已确认且未变化的 Seam 直接复用；只有出现需求歧义、验收缺口、范围变化、破坏性操作或互斥方案时才请求用户确认。
-
-### 出口条件
-
-- 能用自己的话复述需求和每条 Acceptance Criterion；
-- Scope Ledger 已记录，且明确什么不做；
-- 无未澄清歧义；
-- 验证矩阵已建立；
-- 工具、命令和真实运行路径已确认可用，或已记录为 `blocked/unavailable` 及替代路径；
-- `BASE_HEAD` 已记录。
-
----
-
-## 阶段 ② Red-Green：行为级 TDD
-
-### 入口条件
-
-- Contract 出口条件全部满足。
-
-### 操作
-
-1. 在本阶段入口加载 [tdd 技能](.agents/skills/tdd/SKILL.md) 的相关规则一次；每个 Behavior 只按需读取对应的 `tdd/tests.md` 和 `tdd/mocking.md` reference，不重复阅读全文。
-2. 按 Behavior 建立 Todo，而不是按 Seam 建立 Todo。推荐层级：
-   - 大任务：整个 issue；
-   - 中任务：Seam；
-   - Todo：一个 Behavior cycle；
-   - Subtodo：`B1-R` 红 → `B1-G` 绿 → `B1-T` typecheck。
-3. 每个 Behavior 连续执行：
-
-   ```text
-   写一个失败测试
-   → 从公共接口确认目标 Behavior 失败
-   → 最小实现
-   → formatter
-   → typecheck
-   → 最小相关测试
-   → 标记该 Behavior completed
-   ```
-
-4. 只有通过公共接口观察到“目标行为尚未实现”的断言失败才是有效 Red。语法错误、缺失 helper/fixture、测试环境启动失败、工具参数错误、timeout 或命令中断都记录为失败类别或 `UNKNOWN`，不能当作有效 Red。
-5. 根据语言做即时验证：Go 修改后立即 `gofmt` 和最小 package test；TS/TSX 修改后立即 parser/typecheck 和最小 component test。批量编辑拆成小批，每批恢复绿色后再继续。
-6. 每个 Behavior 完成后更新实际 Todo 状态，再进入下一个 Behavior；全部 Behaviors completed 后才离开本阶段。
-
-### 回合连续性与 Chunking
-
-- 每个 Behavior 的 Red → Green → formatter → typecheck → 最小相关测试在一个回合内串行完成；确认全绿后立即进入下一个 Behavior。
-- 一个 Seam 全绿只是内部进度，不是阶段出口；阶段出口是所有 Behaviors 红-绿完成且 typecheck 通过。预告下一步后立即执行，直到阶段出口、合规交互点或外部阻塞。
-- 进度输出并入工具调用序列，输出后继续执行；不要把“准备下一步”当作回合终点。
-- 单次 `write` 超过约 150 行时先写骨架再分批补全；批量 `replace` 超过 5 处时拆批，每批后立即验证。
-- `done`、`completed` 等状态只按当前实际推进更新，已完成项永不回退。
-
-### 出口条件
-
-- 所有 Behaviors 都有有效 Red；
-- 所有 Behaviors 的最小实现已 Green；
-- formatter、typecheck 和最小相关测试通过；
-- Todo 清单反映真实状态，全部 Behavior Todo 为 `completed`；
-- `BASE_HEAD` 祖先校验通过。
-
----
-
-## 阶段 ③ Verify：最终验证与审查
-
-### 入口条件
-
-- Red-Green 出口条件满足，当前 diff 稳定。
-
-### 固定顺序
-
-```text
-当前 issue 影响范围测试
-→ 必要 build
-→ 必要真实运行验证
-→ 当前稳定 diff 调用一次 code-review
-→ 修复 blocking finding 后的定向复核
-```
-
-### 测试与真实运行验证
-
-- 单 issue / 单 spec 与多 issue 均只运行当前 issue 影响范围内的测试，按照 Contract 的验证矩阵执行，不同时运行等价命令；不因进入 Verify 自动扩大测试范围。
-- ticket 要求真实运行时，优先使用专用 browser 工具，其次使用项目已有 Playwright；HTTP/CLI 只能补充 API 验证，不能替代 WebUI 验证。
-- 真实进程验证使用隔离配置和临时端口，保存 PID，记录实际请求结果或页面可见结果，结束时清理进程和临时目录。
-
-### Review
-
-1. 当前 issue 的最终 diff 稳定后，调用一次 [code-review](.agents/skills/code-review/SKILL.md)。
-2. `tdd-implement` 只负责 **何时调用 review**；审查维度、reviewer 数量、提示词、上下文与输出格式全部以 `code-review` 为唯一事实源，不在这里复制或弱化。
-3. `code-review` 未完成或存在 blocking finding 时，issue 保持未完成。只修当前 issue blocking finding；其余 findings 按 `code-review` 的分类与输出处理，不无记录地扩大范围。
-4. 修复 blocking finding 后，只运行受影响测试/typecheck 与 finding delta recheck，不再次调用完整 `code-review`。若修复引入新的 Behavior、改变 Scope 或使原 Review 对象不再成立，则回到 Contract/Red-Green，重新形成稳定最终 diff 后再进入 Verify。
-5. Review 结果只在对话/运行记录中消费，不由 `tdd-implement` 额外生成自己的 review 报告格式。
-
-### 出口条件
-
-- 最终 diff 对应的相关测试通过；
-- 必要 typecheck/build 通过；
-- ticket 要求的真实运行验证已完成并记录实际结果；
-- 当前稳定 diff 已完成一次 `code-review`；
-- 无 blocking finding；
-- 受影响范围的最后一次证据对应当前 diff。
-
----
-
-## Finalize：非阶段交付收尾
-
-### 入口条件
-
-- Verify 出口条件满足。
-
-### 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、最终测试命令/数量/结果和真实运行结果；
-- 确认下一 issue 的 blockers 已解除。
-
-Finalize 开始后不新增产品 Behavior。若实现、测试或文档不完整，回到对应阶段；只有三个阶段与 Finalize 全部通过，才可把 issue 标记为 `resolved`。
-
-### 出口条件
-
-- commit 已创建且为当前 issue 的独立提交；
-- Acceptance Criteria 全部通过；
-- issue 状态为 `resolved`（无关联 issue 的直接 spec 则在会话中输出总结）；
-- 实施总结和 `progress.md` 已同步。
-
----
-
-## 跨阶段运行纪律
-
-### Tool Failure Budget
-
-```text
-首次失败
-→ 判断失败类别
-→ 最多一次有依据的 fallback
-→ 仍失败则记录 blocked/unavailable 并停止该路径
-```
-
-相同命令或工具参数不原样连续重试；timeout 或中断后缩小到 package、文件或具体 test；model、browser 或 tool 不可用时最多一次 fallback。用户要求停止或 handoff 时立即停止。
-
-### 验证证据失效
-
-任何产品代码或测试文件再次变化，旧的测试、typecheck、build 等受影响证据立即失效，必须重新验证受影响范围。正式 `code-review` 调用本身不因 finding 修复而重复；post-review 修复必须完成受影响验证和 finding delta recheck。若修改引入新的 Behavior、改变 Scope 或使原 Review 对象不再成立，则回到 Contract/Red-Green，重新形成稳定最终 diff 后再进入 Verify。
-
-### Git History Preservation
-
-进入 Contract 时记录 `BASE_HEAD=$(git rev-parse HEAD)`；每个阶段出口和 commit 前都执行：
-
-```bash
-git merge-base --is-ancestor $BASE_HEAD HEAD
-```
-
-失败时先经 `git reflog` 找回被改写的历史，再继续。为达到工作区干净只删除本次产生的 `[DEBUG-...]`、一次性脚本和临时文件；未经用户确认不使用 `git reset --hard`、`git checkout .`、`git clean -fd`、`git stash push --include-untracked`、`git push --force`、`git rebase -i` 或任何让 `HEAD` 后退的命令。需要 stash 时使用 `--keep-index`，pop 后重新校验。
-
----
-
-## 状态统一
-
-```text
-Todo:     pending | in_progress | completed | blocked
-Issue:    ready-for-agent | in_progress | resolved | blocked
-Progress: pending | in_progress | done | blocked
-```
-
-状态转换：Contract 完成后 Issue/Progress 为 `in_progress`；Red-Green 完成后 Behaviors 为 `completed`，Issue 仍为 `in_progress`；Verify 完成后 Issue 仍为 `in_progress`；Finalize 完成后 Issue 为 `resolved`、Progress 为 `done`。外部阻塞记录为 `blocked`，恢复后回到 `in_progress`。
-
----
-
-## 回退路由
-
-| 当前阶段 | 回退条件 | 回退目标 |
-|---|---|---|
-| ① Contract | 需求歧义、验收缺口、范围变化 | → ① 补充契约和验证矩阵 |
-| ② Red-Green | 有效 Red、实现、formatter、typecheck 或相关测试失败 | → ② 修复当前 Behavior |
-| ③ Verify | 测试、build、真实运行或 review finding 失败 | → ② 修复 Behavior；需求偏差 → ① |
-| Finalize | 必要 docs 未同步、commit 失败或 Tracker 信息不完整 | → ①/③ 修复对应问题；仍在 Finalize 完成前解决 |
-
-多 issue 的层收敛、最终收敛、依赖冲突和跨 issue 修改冲突按 [orchestration.md](orchestration.md) A5 回退，不跨 issue 无记录改动。

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

@@ -1,21 +0,0 @@
-# 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/template/.agents/skills/tdd-implement/references/red-green.md

@@ -1,25 +0,0 @@
-# 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` 祖先校验通过。