@heihei0299/matt-skills 1.2.1 → 1.3.1

package/.agents/skills/commit-check/SKILL.md

@@ -21,11 +21,13 @@ description: "Run the pre-commit gate before any commit: verify docs match the i
 - 改动涉及项目结构、分发文件、技能/命令清单时，检查 README 中对应的结构说明、映射表、清单是否同步
 - 改动涉及用法/CLI/配置/示例时，检查 README 对应描述与实际一致
 - 存在模板镜像/分发副本时，确认源文件与副本同步（如有守护测试，跑一遍确认）
+- **特例：skill 与 AGENTS.md 的模板同步增量**：若 `git diff HEAD` 仅涉及 `AGENTS.md` 的 `tdd-implement ↔ implement` 路由行 + `.agents/skills/`/`.pi/skills/`/`.opencode/skills/` 的技能文件 + `.gitignore` 的 `.pi/` 忽略，且同目录存在 `AGENTS.md.bak`（模板同步 `sync`/`init --force` 的备份），视为模板同步的预期增量，禁止自动 `checkout -- AGENTS.md` 回滚；存在性按文件系统判（`ls .agents/skills/<name> .pi/skills/<name> .opencode/skills/<name>` 任一存在即算存在，不以 `git ls-files` 为准）；缺技能则正向补齐而非回滚文档
 
 ### ③ 保持目录卫生
 
 - `git status` 确认工作区只含预期改动：无残留未跟踪文件、无临时产物（调试脚本、日志、备份文件、`[DEBUG-...]` 残留）
-- 清理本次改动产生的临时文件（一次性脚本、转储、探针）——删除或移入明确的非提交位置
+- 清理本次改动产生的临时文件（一次性脚本、转储、探针）——仅删本次产生的未跟踪临时产物，禁止为达干净而执行 `git reset --hard`、`git checkout .`、`git clean -fd`、`git stash push --include-untracked`、`git push --force`、`git rebase -i` 等（需显式用户确认；`stash` 如需使用改用 `--keep-index` 并在 `pop` 后校验 `git merge-base --is-ancestor $BASE_HEAD HEAD`）。详见 `CONTEXT.md` Git History Preservation 与 `docs/agents/skill-design.md` Rule 4
+- 若本次会话记录了 `BASE_HEAD`，commit 前校验 `git merge-base --is-ancestor $BASE_HEAD HEAD`，失败即经 `git reflog` 恢复后才提交
 - 确认没有敏感信息进入改动（密钥、token、`.env`、私钥）——跑 `scripts/scan-sensitive.sh`，不用手写扫描
 - 提交后工作区应为干净状态（`git status` 无输出）
 

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

@@ -1,143 +1,48 @@
 ---
 name: tdd-implement
-description: "Implement from a spec or ticket via strict TDD red-green loop, then typecheck, review, commit, update the issue status, and write an implementation summary. Use this skill whenever the user asks to implement from a spec/ticket/issue, mentions TDD/red-green/test-first, or wants test-first work carried through review, commit and issue close-out in one pass — even if they don't name the process. For implementation without the test-first pipeline use implement; for test technique alone use tdd — this skill is the complete orchestration."
+description: "TDD seam red-green loop: use when the user provides a spec/ticket to implement test-first, or mentions TDD/red-green/test-first and wants the full loop through typecheck, review, commit and closeout. For implementation without TDD use implement; for TDD technique alone use tdd."
 ---
 
 # TDD Implement
 
-整合 **implement** + **tdd** 的完整实现流程：每个 seam 一个红-绿循环，直到 commit。TDD 语义（红-绿循环、seam 定义、好测试标准）以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源——测试标准详见 [tdd/tests.md](.agents/skills/tdd/tests.md)，Mock 边界见 [tdd/mocking.md](.agents/skills/tdd/mocking.md)；本技能只编排阶段与运行时规则。
+`seam` + `red-green` 为领衔词的完整实现编排：每个 seam 一个红-绿循环，直到 commit。TDD 语义（红-绿循环、seam 定义、好测试标准）以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源——测试标准见 [tdd/tests.md](.agents/skills/tdd/tests.md)，Mock 边界见 [tdd/mocking.md](.agents/skills/tdd/mocking.md)；本技能只编排阶段与运行时规则。
 
-本技能是**长程任务**（Long-Horizon Skill）：多阶段串行执行，自带**回合连续性**（Turn Continuity）与**任务分解**（Chunking）规则（见 [stages.md](references/stages.md) 阶段③ 3e/3f）。术语定义见 `CONTEXT.md`，技能设计规则见 `docs/agents/skill-design.md`。
+本技能是**长程任务**（Long-Horizon Skill）：多阶段串行执行，自带**回合连续性**（Turn Continuity）与**任务分解**（Chunking）规则。术语定义见 `CONTEXT.md`，技能设计规则见 `docs/agents/skill-design.md`。
 
-## 流程速览
+## 分支
 
-```
-① 理解需求 → ② 确认 Seams → ③ TDD 开发循环 → ④ 完整测试套件 → ⑤ Code Review → ⑥ Commit → ⑦ 收尾（文档对齐 + issue 状态 + 实施总结）
-```
+- **单线**：单 spec / 单 issue，走下节 Steps ①→⑦（详规见 [stages.md](references/stages.md)）。
+- **多 issue 编排**：`.scratch/<feature>/issues/` 下多文件且含 `Blocked by` 时走编排模式——编排器按依赖分层并行调度，子代理各自治完成 ①→⑦。详见 [orchestration.md](references/orchestration.md)。
 
-每阶段的入口条件、操作与边界规则见 [`stages.md`](references/stages.md)——进入任一阶段前先读取该阶段的定义。③ TDD 开发循环的红-绿规则见 [tdd 技能](.agents/skills/tdd/SKILL.md)，不在本文件重写。多 issue 编排见下节与 [`stages.md` 附录：多 issue 编排](references/stages.md#附录-多-issue-编排按依赖分层并行)。
+## Steps
 
-阶段要点：
-- ⑤ Code Review：按 [code-review](.agents/skills/code-review/SKILL.md) **双轴审查**——Standards 轴（编码标准符合度）与 Spec 轴（spec/issue 实现忠实度），两轴独立报告互不掩盖；审查结果只在对话输出，不生成书面审查报告（不落盘 `review-*.md` 类文件）。**派发纪律：两轴必须用 subagent single 模式或 `subagent_consult` 逐个派发，禁止 parallel `tasks` 数组**（parallel 结果仅保留 160 字节摘要，中文报告必截断；详见 stages.md 阶段⑤）
-- ⑥ Commit：commit 前运行 [commit-check](.agents/skills/commit-check/SKILL.md) 门禁（①审查文档 ②对齐 README ③目录卫生 ④commit message），四项全过才提交
-- ⑦ 收尾：先对齐文档——检查 README 与 docs/ 中涉及本次实现的描述与实现是否一致，不一致则更新并 commit；再更新 issue 状态（有关联 issue 时，其验收标准逐条转写为 checkbox 清单并打勾——全部 `- [x]` 才允许标 `resolved`）；最后保持目录卫生（清理 `[DEBUG-...]` 调试残留与临时产物，`git status` 确认工作区干净）
+按序执行，每步达到完成条件才进入下一步；进入任一步前先读取其在 [stages.md](references/stages.md) 的定义。
 
-## 多 issue 编排（按依赖分层并行）
+| Step | 做什么 | 完成条件（可验证） | 详规 |
+|------|--------|-------------------|------|
+| ① 理解需求 | 读取 spec/ticket + `CONTEXT.md`/`docs/adr/`，澄清歧义 | 能复述需求且无未澄清歧义 | [stages.md#阶段-①](references/stages.md#阶段-①理解需求) |
+| ② 确认 Seams | 列出待测公共接口 seams（名称+输入+预期输出），向用户确认并生成 Todo | 用户明确同意 seams 清单；Todo 已生成 | [stages.md#阶段-②](references/stages.md#阶段-②确认-seams测试接缝) |
+| ③ TDD 开发循环 | 逐 seam 红-绿循环，串行推进至全绿 | 所有 seams 红-绿完成 + typecheck 通过 | [stages.md#阶段-③](references/stages.md#阶段-③tdd-开发循环) |
+| ④ 完整测试套件 | 跑全量测试 | 全部测试通过（失败回 ③） | [stages.md#阶段-④](references/stages.md#阶段-④完整测试套件) |
+| ⑤ Code Review | 按 [code-review](.agents/skills/code-review/SKILL.md) 双轴审查（Standards + Spec） | 双轴均通过 | [stages.md#阶段-⑤](references/stages.md#阶段-⑤code-review) |
+| ⑥ Commit | 跑 [commit-check](.agents/skills/commit-check/SKILL.md) 门禁四项后提交 | commit 完成且历史校验通过 | [stages.md#阶段-⑥](references/stages.md#阶段-⑥commit) |
+| ⑦ 收尾 | 文档对齐 → issue 状态与实施总结 → 目录卫生 | 文档已对齐、issue 已 `resolved`+总结落盘、工作区干净 | [stages.md#阶段-⑦](references/stages.md#阶段-⑦收尾文档对齐--issue-状态--实施总结) |
 
-当 `.scratch/<feature>/issues/` 下存在多个 issue 且彼此有 `Blocked by` 依赖时走本模式；单 issue / 单 spec 仍走上节单线流程。触发后主代理为**编排器**，子代理按**单 issue 单代理**各自治完成完整 tdd-implement 流程（①→⑦）。详规见 [`stages.md` 附录](references/stages.md#附录-多-issue-编排按依赖分层并行)，本节只定契约：
+编排模式流转见 [orchestration.md](references/orchestration.md)；子代理内部仍走上表 ①→⑦（其中 ④ 为相关测试口径，全量由编排器收敛）。
 
-- **触发**：扫描 `.scratch/<feature>/issues/` 多文件且含 `Blocked by` 时进入编排模式；否则单线执行——不为单 issue 引入编排开销。
-- **编排器职责**：解析 `Blocked by` 依赖图 → 拓扑分层 → 按层调度子代理 → 逐 issue 验收（见下）→ 层间收敛验证（全量测试 + `git status` 干净）→ 汇总实施总结。
-- **子代理契约（单 issue 单代理）**：输入 `spec.md + 单个 issue.md + CONTEXT.md/ADRs`，严格走 tdd-implement ①→⑦（含 seams 确认、红-绿循环、typecheck、双轴 review、commit-check 门禁、issue `resolved` + 实施总结）；产出独立 commit；禁止跨 issue 改动。
-- **子代理输出约束**：只返回**回执卡片**（结构化关键信息），不透传全量过程日志。回执字段：issue 编号与标题 / commit hash / seams 清单 / 测试结果（数量与是否全绿）/ typecheck 结论 / 双轴 review 结论 / 验收 checkbox 结果 / 文档对齐清单 / 遗留与风险。红-绿细节、typecheck 原始输出、review 全文等过程日志留在子代理内部，不向主代理透传。
-- **主代理验收**：编排器不盲信回执，逐 issue 验收后才算该 issue 完成。验收项：① commit 存在且 message 含 issue 编号 ② issue 文件 `Status: resolved` + `## 实施总结` 已落盘 ③ 抽检验证（抽跑相关测试或 `tsc --noEmit` 抽检，不重跑全量）④ 无跨 issue 改动（`git diff --name-only` 核对）⑤ 工作区干净。任一项不通过则打回重派该子代理，层内其他已通过不受影响；验收通过才计入层收敛。
-- **分层并行**：同层无依赖的 issue 并行派发子代理，层内全部验收通过后才进入下一层；层间串行，层内并行。
-- **冲突处理**：同层子代理若触及同一文件，后完成者 rebase 解决冲突后重跑 typecheck + 相关测试；跨层天然串行无冲突。
-- **收敛**：全部层验收通过后编排器跑全量测试套件 + 目录卫生检查，任一失败按回退路由回到对应层重派。
+### 阶段间流转
 
-## 回合连续性规则
-
-flash 类模型在长程任务上容易在"预告下一步"处提前收尾——本规则源自一次真实事故（一次会话停四次，见 docs/agents/skill-design.md），是长程技能能否跑完的决定性规则。每个逻辑单元（一次红-绿循环、一次 typecheck、一次测试失败修复）必须**在一个回合内连续执行完毕后才输出**：测试 → 分析失败 → 修正 → 重跑 → 全绿 整条链一气呵成，中间不停顿、不等用户说"继续"。
-
-回合终点仅为三类之一：
-- **合规交互点**：技能要求的用户确认（如阶段② seams 清单确认）——此时提问并等待
-- **外部阻塞**：权限拒绝、缺失授权、依赖不可用——此时明确说明需要什么授权或替代路径，不静默停止
-- **阶段完成**：整个阶段的出口条件满足（如阶段③的所有 seams 红-绿完成 + typecheck 通过、commit 完成）——单个 seam 全绿只是阶段③的内部步骤，不是回合终点
-
-输出进度/预告本身不结束回合——输出后继续执行，直到三类终点之一达成；预告下一步后立即执行该步骤。逐 seam 的执行细则见 [stages.md 3e](references/stages.md#阶段-③tdd-开发循环)。
-
-编排模式下回合连续性延伸至**层**：一层内全部子代理派发后，编排器等待该层全 `resolved` 再进入下一层，不在层间停顿等待用户"继续"；子代理内部仍遵守单 issue 的回合连续性。
-
-## 不做什么
-
-- 不重写 TDD 语义：红-绿循环、seam 定义、好测试标准、mocking 边界一律查 [tdd 技能](.agents/skills/tdd/SKILL.md)，本技能只编排阶段与运行时规则
-- 不把重构塞进红-绿循环：重构归阶段⑤ Code Review
-- 不在阶段间停顿：单 seam 全绿、单次 typecheck 通过都不是回合终点（见回合连续性规则）
-- 不生成书面审查报告：阶段⑤审查结果只在对话输出，不落盘 `review-*.md` 类文件
-- 不手写超大改动：巨型 write/批量 replace 会撞输出上限、中途截断，因此单次 `write` 超 ~150 行先写骨架再分批补全；批量 `replace` 超 ~5 处先拆分再分批执行（见 [stages.md](references/stages.md) 3f）
-- 不跳步：阶段出口未达成不进入下一阶段（见路由规则）
-- 不为单 issue 引入编排：单 issue / 单 spec 不走多 issue 编排分支
-
-## 任务拆分与 Todo 规定
-
-### 拆分层级（大小任务层次）
-
-1. **大任务**：Goal/Ticket——整个实现单元，对应一次完整的 tdd-implement 流程
-2. **中任务**：Seam（阶段②确认）——一个红-绿循环单元，每 seam 一个 Todo
-3. **小任务**：Todo——seam 内可独立验证、可勾选的执行单元（T1/T2/T3…）
-4. **执行步**：Subtodo——Todo 内的串行步骤（红 → 绿 → typecheck），回合内逐步勾选推进
-
-编排模式下新增一层：
-
-5. **编排层**：Feature——`.scratch/<feature>/` 下全部 issues，按 `Blocked by` 分层；每层一组并行子代理，每子代理一个 issue 的完整 ①→⑦。
-
-### Todo 清单格式
-阶段② seams 确认后立即生成 todo 清单，每个 seam 一个 todo：
-- 编号：`T1`、`T2`、`T3`…
-- 描述：seam 名称 + 输入 + 预期输出
-- 状态：`pending` / `in-progress` / `done` / `blocked`
-- 完成标准（DoD）：该 seam 测试全绿 + typecheck 通过 + 既有测试不受影响
-- 执行步（Subtodo）：`T1-R` 红（写失败测试）→ `T1-G` 绿（最小实现）→ `T1-T` typecheck
-
-编排模式下 Todo 清单为**分层清单**：`L1: [01, 02] → L2: [03, 04] → L3: [05]`，每层内 issue 并行，层间串行；每 issue 的 DoD 为 `Status: resolved` + 独立 commit + 实施总结已落盘。
-
-### Todo 状态机
-```
-pending → in-progress → done
-                ↘ blocked（外部阻塞）→（授权/替代路径）→ in-progress
-```
-- Subtodo 不单独设 `blocked`——阻塞状态归父 Todo，Subtodo 跟随父状态
-
-编排模式下 issue 粒度状态机：`pending → in-progress(子代理已派发) → done(Status: resolved)`；`blocked` 表示 `Blocked by` 依赖未满足，待前层全 `resolved` 后自动解阻。
-
-### 粒度与回合归属
-- 一个 todo = 一个 seam 的红-绿 cycle + typecheck，不可再拆
-- 一个 todo 必须在一个回合内完成（红→绿→typecheck→全绿）
-- Subtodo 是 todo 内的执行步：每完成一步立即进入下一步（`T1-R` → `T1-G` → `T1-T`），禁止停在步间预告
-- 每完成一个 todo 立即更新其状态，再进入下一个
-- todo 状态只按实际推进更新（pending → in-progress → done），不基于旧快照重写整个清单；已完成项（done）永不回退
-- 全部 todo 为 done 才进入阶段④
-
-编排模式下：每层全部 issue `done` 才进入下一层；全部层 `done` 后编排器做全量收敛验证。
-
-### 阻塞处理
-- 外部阻塞（权限拒绝、缺失授权、依赖不可用）→ 标记 `blocked`，记录所需授权或替代路径
-- 不静默停止；恢复后回到 `in-progress` 继续
-
-编排模式下：`Blocked by` 依赖阻塞由编排器自动管理——前层未全 `resolved` 时后层 `blocked`，前层收敛后自动解阻派发；不需人工确认依赖满足。
-
-## 路由规则
-
-### 正常流转
-
-| 当前阶段 | 出口条件 | 下一阶段 |
-|----------|----------|----------|
-| ① 理解需求 | 需求已澄清，无歧义 | → ② 确认 Seams |
-| ② 确认 Seams | 用户确认 seams 清单 | → ③ TDD 开发 |
-| ③ TDD 开发 | 所有 seams 红-绿完成，typecheck 通过 | → ④ 完整测试套件 |
-| ④ 完整测试套件 | 全部测试通过 | → ⑤ Code Review |
-| ⑤ Code Review | 审查通过 | → ⑥ Commit |
-| ⑥ Commit | commit 完成 | → ⑦ 收尾 |
-| ⑦ 收尾 | issue 状态已更新 + 实施总结已写 | ✅ 结束 |
-
-编排模式流转：`编排器：依赖图 → 分层 → [层内并行子代理(①→⑦) → 层收敛]×N → 全量收敛 → 汇总总结 ✅`；子代理内部仍走上表单 issue 流转。
-
-### 回退路由
-
-| 当前阶段 | 回退条件 | 回退目标 |
-|----------|----------|----------|
-| ③ TDD 开发 | typecheck 失败 | → ③ 修复类型错误 |
-| ④ 完整测试套件 | 测试失败 | → ③ 修复失败测试 |
-| ⑤ Code Review | 实现错误 | → ③ 修复实现 |
-| ⑤ Code Review | seams 遗漏 | → ② 补充 seams |
-| ⑤ Code Review | 需求偏差 | → ① 澄清需求 |
-
-编排模式回退：子代理内回退按上表在子代理内闭环；编排器层收敛失败（全量测试失败 / 目录不干净）→ 定位到失败 issue 所在层重派对应子代理。
+- 正常流转：出口条件满足即进入下一阶段，不在阶段间停顿。
+- 回退路由：见 [stages.md#回退路由](references/stages.md#回退路由)；编排模式回退见 [orchestration.md#A5](references/orchestration.md#a5-回退与冲突)。
+- 回合连续性：阶段内连续动作（红→绿→typecheck→下一 seam）在**一个回合内串行完成**，直至阶段出口；预告下一步后立即执行。详规见 [stages.md ③-3e](references/stages.md#3e-回合连续性) 与 [orchestration.md#A2](references/orchestration.md#a2-分层调度)。
+- 任务分解：巨型写入拆小步——`write` 超 ~150 行先写骨架再分批补全，`replace` 超 ~5 处分批执行并验证。详见 [stages.md ③-3f](references/stages.md#3f-任务分解chunking)。
 
 ## 引用
 
 - TDD 核心规则：[tdd 技能](.agents/skills/tdd/SKILL.md)
 - 测试标准：[tdd/tests.md](.agents/skills/tdd/tests.md)
 - Mock 指南：[tdd/mocking.md](.agents/skills/tdd/mocking.md)
-- Commit 门禁：[commit-check 技能](.agents/skills/commit-check/SKILL.md)
+- Commit 门禁：[commit-check](.agents/skills/commit-check/SKILL.md)
+- 单线详规：[stages.md](references/stages.md)
+- 多 issue 编排：[orchestration.md](references/orchestration.md)
 - Issue tracker 约定：[issue-tracker.md](../../docs/agents/issue-tracker.md)

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

@@ -0,0 +1,136 @@
+# 多 issue 编排（按依赖分层并行）
+
+本文件仅在多 issue 编排模式下生效；单 issue / 单 spec 走 [stages.md](stages.md) 单线流程，不经过本文件。
+
+多 issue 触发条件：`.scratch/<feature>/issues/` 下存在多个 issue 文件且至少部分含 `Blocked by` 依赖声明。
+
+## 目录
+
+- [A0. 依赖图构建](#a0-依赖图构建)
+- [A1. 拓扑分层](#a1-拓扑分层)
+- [A2. 分层调度](#a2-分层调度)
+- [A3. 子代理契约（单 issue 单代理）](#a3-子代理契约单-issue-单代理)
+- [A4. 全量收敛](#a4-全量收敛)
+- [A5. 回退与冲突](#a5-回退与冲突)
+- [出口条件](#出口条件)
+- [边界](#边界)
+
+---
+
+### A0. 依赖图构建
+
+1. 扫描 `.scratch/<feature>/issues/` 下全部 `NN-<slug>.md`，逐文件解析 `Blocked by` 行：
+   - `Blocked by: None` / `Blocked by: （无` / 无此行 → 无依赖（frontier）
+   - `Blocked by: 01, 02` / `Blocked by: 01（…）` → 依赖 `01`、`02` 对应的 issue 文件（按编号前缀匹配）
+   - 无法解析的行 → 视为无依赖，并在编排总结中注明告警
+2. 以 issue 编号为节点、`Blocked by` 为有向边构建 DAG；若检测到环，立即报错并列出环上节点，不进入调度。
+3. 读取 `spec.md`（若存在）作为各子代理的共享上下文；同时读取 `CONTEXT.md` 与 `docs/adr/` 供一致性校验。
+
+### A1. 拓扑分层
+
+对 DAG 做 Kahn 分层（BFS 拓扑）：
+
+```
+L1 = 全部入度为 0 的节点（可立即开始）
+L2 = 移除 L1 后入度为 0 的节点
+…
+Ln = 最后一层
+```
+
+每层内节点互无依赖，可并行；层间有依赖，必须串行。分层结果在编排开始前一次性展示给用户确认（合规交互点），确认后才派发。
+
+### A2. 分层调度
+
+```
+for each 层 Li in L1..Ln:
+  并行派发：为 Li 中每个 issue 启动一个子代理（single 模式，禁止 parallel tasks 数组）
+  等待：阻塞直到 Li 全部子代理返回回执卡片
+  验收：编排器按 A3 验收清单逐 issue 验收（只认回执卡片的关键信息 + 抽检验证，不消费全量日志）
+  层收敛验证：验收全通过进入全量验证（完成条件 4 项，全部通过才进下一层，任一失败按 A5 回退）：①该层全部 issue 验收通过 ②全量测试套件通过 ③`git status` 卫生（仅删本次临时产物，正向；护栏：禁止 `git reset --hard`/`git checkout .`/`git clean -fd`/`git stash push --include-untracked`）④历史校验 `git merge-base --is-ancestor $BASE_HEAD HEAD` 通过；验收不通过或全量/卫生/历史任一失败按 A5 回退重派该 issue
+全部层层收敛通过后进入 A4 全量收敛
+```
+
+- **派发纪律**：与阶段⑤双轴审查一致——逐个 `subagent` 派发，禁止 `parallel tasks` 数组（同因：中文报告截断）。
+- **等待语义**：层内任一子代理失败不取消同层其他子代理；待层内全部返回后统一按 A5 处理。
+- **回合连续性**：编排器在层间不结束回合——一层收敛后立即派发下一层，直到全部层完成或外部阻塞；预告下一层后立即执行。
+- **Git 历史保护（正向：仅追加；护栏：禁改写）**：编排器在分层调度前记录 `BASE_HEAD=$(git rev-parse HEAD)`，每层收敛后校验 `git merge-base --is-ancestor $BASE_HEAD HEAD`，失败即经 `git reflog` 恢复；为达 `git status` 干净仅删本次产生的 `[DEBUG-...]`临时产物（正向），护栏：禁止 `git reset --hard`/`git checkout .`/`git clean -fd`/`git stash push --include-untracked`/`git push --force` 等（需显式确认）。
+
+### A3. 子代理契约（单 issue 单代理）
+
+每个子代理是一个**完整的 tdd-implement 单 issue 执行单元**，输入与产出严格界定：
+
+> 编排层为 Feature 层，按 `Blocked by` 分层；每子代理各自治完成完整 tdd-implement 流程，产出独立 commit；禁止跨 issue 改动；输出约束为回执卡片，不透传全量过程日志；主代理验收保证无跨 issue 改动与逐 issue 验收，打回重派直至验收通过才计入层收敛。
+
+- **输入**：
+  - `spec.md`（feature 级共享 spec，若无则以该 issue 正文为准）
+  - 分配的单个 `NN-<slug>.md`（唯一 issue 输入）
+  - `CONTEXT.md` + `docs/adr/`（术语与决策一致性）
+- **执行**：严格走 tdd-implement ①→⑦全流程——①理解需求（读 spec + issue）→ ②确认 seams（该 issue 范围内）→ ③红-绿循环（每 cycle 后 typecheck + 相关测试）→ ④相关测试套件（仅该 issue 相关 + typecheck，不跑全量；全量由编排器在 A2 层收敛/A4 统一执行，单 issue 单线模式仍跑全量）→ ⑤双轴 review → ⑥commit-check 门禁 + commit → ⑦文档对齐（仅该 issue 相关描述）+ `Status: resolved` + `## 实施总结` 落盘 + 目录卫生。TDD 语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，不在子代理内重写。
+- **产出**：
+  - 独立 commit（message 含 issue 编号，如 `feat(<feature>): <issue title> (#NN)`）
+  - 该 issue 文件 `Status: resolved` + 底部 `## 实施总结`
+  - 该 issue 范围内的测试全绿 + typecheck 通过
+- **禁止**：跨 issue 改动；修改其他 issue 文件；跳过 ⑤/⑥ 直接 commit。
+
+#### 输出约束（子代理只返回回执卡片）
+
+子代理不向编排器透传全量过程日志（各 seam 的红-绿细节、typecheck 原始输出、双轴 review 全文、完整测试日志）。只返回一张**回执卡片**（结构化关键信息，中文，≤ 30 行）：
+
+```
+[回执] #NN <issue 标题>
+- 提交：<commit hash> — <message>
+- seams：<清单>
+- 测试：相关测试 <数量> 项全绿 / 失败清单（全量由编排器层收敛/A4 验证）
+- typecheck：通过 / 失败原因
+- review：Standards <通过/问题> / Spec <通过/问题>
+- 验收：checkbox <m/n 全绿，缺口说明>
+- 文档：<更新文件 / 无需更新>
+- 遗留：<如有>
+```
+
+卡片字段缺一不可；缺失字段视为验收不通过。详细过程与证据留在子代理的 commit 与 issue 文件中，编排器按需抽检而非全量消费。
+
+#### 主代理验收（编排器逐 issue 验收）
+
+编排器收到回执后逐 issue 验收，不盲信子代理自检：
+
+1. **落盘校验**：`git log --oneline` 含该 commit 且 message 含 `#NN`；issue 文件 `Status: resolved` 且底部 `## 实施总结` 已落盘。**完成条件：5 项检查表，全部通过才计入层收敛，任一不过即打回重派**（详见 `SKILL.md` 主代理验收）。
+2. **抽检验证**：抽跑该 issue 相关测试（或 `tsc --noEmit` 抽检），不重跑全量套件；抽检失败即打回。
+3. **改动边界**：`git diff <base>..HEAD --name-only` 核对无跨 issue 文件改动；有跨改视为不通过。
+4. **卫生**：`git status` 无 `[DEBUG-...]` 残留与未跟踪临时文件。
+5. **提交关联**：`git log` message 含 `#NN` 且与落盘 commit 一致；缺失或不一致视为不通过。
+
+任一项不通过 → 打回重派该子代理（仅该 issue），层内其他已通过不受影响；验收通过才计入层收敛。验收结论随层收敛一并输出。
+
+子代理内部的回合连续性、任务分解、Todo 规定、Git 历史保护与单线模式完全一致（见 [stages.md 阶段③ 3e/3f/3h](stages.md#阶段-③tdd-开发循环) 与 Git 安全前置）。子代理同样在入口记录 `BASE_HEAD` 并在每阶段出口校验 `git merge-base --is-ancestor $BASE_HEAD HEAD`，禁止 `git reset --hard`/`git checkout .`/`git clean -fd`/`git stash push --include-untracked` 等。
+
+### A4. 全量收敛
+
+全部层逐 issue 验收通过后，编排器执行：
+
+1. **全量测试套件**：跑仓库完整测试套件（阶段④口径），失败则按 A5 回退。
+2. **历史校验**：执行 `git merge-base --is-ancestor $BASE_HEAD HEAD`，若为 false 说明编排过程中历史被改写，立即经 `git reflog` 恢复后重跑收敛。
+3. **目录卫生**：`git status` 确认无 `[DEBUG-...]` 残留、无未跟踪临时文件；有残留则仅删本次临时产物后重检，禁止 `git reset --hard`/`git checkout .`/`git clean -fd`/`git stash push --include-untracked` 等。
+4. **汇总总结**：在会话输出汇总各 issue 的回执卡片关键信息（提交 hash / seams / 验收 checkbox / 测试结果 / 文档对齐）；不另写汇总文件，不透传子代理全量日志（各 issue 的 `## 实施总结` 已落盘，详查落盘文件）。
+
+### A5. 回退与冲突
+
+- **子代理内回退**：按 [stages.md 回退路由](stages.md#回退路由) 在子代理内闭环（typecheck 失败 → ③、测试失败 → ③、review 不通过 → ③/②/①）。
+- **层收敛失败**：层内任一子代理未达到 `resolved`（测试失败 / review 不通过 / commit-check 门禁失败）→ 该 issue 保持原 `Status`，编排器在层等待结束后报告失败清单，不自动进入下一层；待修复后重派该层失败节点。
+- **全量收敛失败**：A4 全量测试失败 → 定位到失败测试归属的 issue，回到其所在层重派对应子代理。
+- **文件冲突**：同层子代理若触及同一文件，后完成者 rebase 解决冲突后重跑 typecheck + 相关测试；跨层天然串行无冲突。冲突解决禁止使用 `git reset --hard`/`git checkout .`/`git clean -fd`/`git stash push --include-untracked` 丢弃对方提交，rebase 后必校验 `git merge-base --is-ancestor $BASE_HEAD HEAD` 且 `git log --oneline` 含全部层提交；冲突检测以 `git` 合并结果为准，编排器不做静态预判。
+- **环依赖**：A0 检测到环即报错终止，不派发任何子代理。
+
+### 出口条件
+
+- 全部 issue `Status: resolved` + 各自 `## 实施总结` 已落盘
+- 全量测试套件通过
+- 工作区干净（`git status` 无残留）
+
+### 边界
+
+- 单 issue / 单 spec 不走本文件
+- 子代理不跨 issue 改动；编排器不替子代理写实现代码
+- 汇总总结只在对话输出，不落盘额外汇总文件
+- TDD 语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，不在本文件重写
+