@heihei0299/matt-skills 1.3.3 → 1.5.2

package/template/.pi/skills/diagnose-fix/references/anti-patterns.md

@@ -1,20 +0,0 @@
-# 反模式清单（Diagnose-Fix）
-
-SKILL.md 正文各阶段规则是正面约束；本文件是负向边界（不做什么），为细节唯一出处。SKILL.md 只引用本文件，不重复内容。
-
-## 诊断阶段
-
-- 不跳过反馈回路直接猜根因：回路未红之前不进入假设、不写修复代码
-- 不把最小复现留在 harness 里：必须转写为正确 seam 上的回归测试，harness 只作诊断工具
-- 不一次改多个变量：探针一次只改一个，`[DEBUG-...]` 前缀标记
-
-## 修复阶段
-
-- 不绕过测试直接改代码（见 SKILL.md ②无逃生舱）——没有 seam 是 finding，不是豁免
-- 不套用 tdd-implement 重流程：见 SKILL.md ②轻量声明——单 seam 修复直走红-绿，不引入重流程编排
-- 不重写 tdd 技能的红-绿语义：seam 定义、好测试标准、mocking 边界一律查上游技能
-
-## 回归阶段
-
-- 不遗留探针：`[DEBUG-...]` 前缀的临时改动在回归验证后全部清理
-- 不跳过原始反馈回路的重跑：最小化场景绿 ≠ 原始症状消失

package/template/.pi/skills/grill-to-spec/agents/openai.yaml

@@ -1,5 +0,0 @@
-interface:
-  display_name: "Grill to Spec"
-  short_description: "从模糊想法到可执行 Spec — 只打磨设计、产出领域文档与 Spec，不写代码"
-policy:
-  allow_implicit_invocation: false

package/template/.pi/skills/grill-to-spec/references/rules.md

@@ -1,33 +0,0 @@
-# 守则：Grill-to-Spec 产出物格式细则
-
-三类产出物（Glossary / ADR / Spec）格式的**唯一细节出处**，由 SKILL.md 直链引用。SKILL.md 只保留流程、导航与不可协商规则，本文件不重复流程内容。
-
-## Glossary 守则
-
-- 懒创建：首个术语解析时才建 `CONTEXT.md`；多上下文时先确认归属，归属不清则询问
-- 只是 glossary：零实现细节，不当 spec/scratch pad
-- 只收本上下文特有术语，通用编程概念不收
-- 定义 WHAT 非 HOW，1-2 句；opinionated，同义词列 `_Avoid_`；术语解析即 inline 更新，不批量
-
-## ADR 守则
-
-- 三条件全满足才提议（难逆转 / 无上下文费解 / 真实权衡）；`docs/adr/` 懒创建
-- 格式：标题 + 1-3 句正文；可选节（Status/Considered Options/Consequences）按需，大多数不需要
-- 编号：`0001-slug.md` 顺序递增，扫描最高号 +1
-- 草稿经用户显式确认后落盘，任何情况无例外（见 SKILL.md 流程① 与不可协商规则）
-
-## 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:` 行记录
-
-## 反模式（不做什么）
-
-- 不把守则当逐条朗读的检查清单——守则约束产出物格式，不约束对话节奏
-- 不把 ADR 当 glossary 一样 inline 更新（见 SKILL.md 不可协商规则）
-- 不产出守则之外的文件：产出物只有三种（Glossary / ADR / Spec）
-- 不在本文件之外重复守则细节——SKILL.md 与 references 之间信息只在一处存在

package/template/.pi/skills/scaffold-functional-test/SKILL.md

@@ -1,77 +0,0 @@
----
-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 running tests (use instance-test) nor for TDD (use tdd-implement)"
----
-
-# Scaffold Functional Test
-
-从本仓库的 spec 自动脚手架出**仓库专属的功能测试 skill**。本技能为**非 Long-Horizon 轻量 skill**（一次性 scaffold，不做多 seam 红绿循环），一次性完成「读 spec → 推导实例 → 落盘 skill → 自验证」闭环。术语定义见 `CONTEXT.md`。
-
-## 产出物
-
-- 定制 skill 目录：`.agents/skills/<repo>-functional-test/`（含 `SKILL.md` + `references/instances.md` + 可选 `scripts/run.sh`）
-- 指纹：`spec hash` + `generatedAt` 写入生成物头部，用于后续执行前校验
-- 保护：`<!-- manual -->` 标记段不被覆盖
-
-生成物纳入 git，可回归复用，不进入 `template/` 再分发（生成器本身才随 Template Snapshot 分发）。
-
-## Steps
-
-### ① 采集 Spec
-
-解析用户传入的 spec 路径，默认 `.scratch/<feature>/spec.md`。
-
-- 若 spec 存在：读取 `CONTEXT.md`/`docs/adr/` 相关术语与决策，提取待覆盖行为清单（以验收标准为锚点）。
-- 若 spec 不存在：回退到 `README` + `--help` 输出倒推行为清单，但必须进入 Step ② 的清单确认关卡，不静默臆测。
-
-完成：待覆盖行为清单已固定，无未澄清歧义。
-
-### ② 推导实例
-
-按混合推导策略生成实例草案：
-
-- 以验收标准为锚点，需求/接口/边界为补充，可为 spec 未显式写的隐含行为（如 `--help` 文案、错误码、幂等性）补实例，但每条实例必须标注**溯源**（spec 章节/行号或 `README/--help` 来源），无溯源的实例视为幻觉需删除。
-- 每实例声明**受控扩展模型**：必选 `prompt/command/expected files/content/expected stdout phrases/expected exit code`，可选 `setup/env/timeout/type/teardown`，默认 `type: cli`。
-- **强制门禁**：实例清单必须与用户确认后才进入 Step ③；无确认不落盘。
-
-完成：实例清单已获用户确认，每实例含溯源与完整四元组。
-
-### ③ 脚手架落盘
-
-按受控扩展模型写入定制 skill 目录：
-
-- `SKILL.md`：执行语义（见下节「执行语义」）
-- `references/instances.md`：实例集（含溯源、必选+可选字段、头部 `spec hash` + `generatedAt`）
-- 不覆盖 `<!-- manual -->` 保护段；覆盖式更新需经用户确认；重生成时先给出 diff 建议，用户确认后才应用。
-
-完成：定制 skill 目录已落盘，指纹正确，人工段受保护。
-
-### ④ 自验证
-
-落盘后立即按实例执行语义串行执行一轮实例集作自验证：
-
-- `mktemp -d` 隔离（或项目支持的 `git worktree` / `--dest`），单线程串行，不并行。
-- 每实例捕获 stdout/stderr 与 exit code，按 `test -f`/`grep -q`/`diff` 对比判定 `PASS`/`FAIL`，单 FAIL 不阻断后续。
-- 对话内输出 `PASS m/n` + per-instance evidence（`expected vs actual diff` + `run dir`），失败不回滚生成物但给出 gap 供迭代 `regenerate`。
-- 成功默认清理临时目录、失败默认保留（`--keep` 保留全部）；`--report` 显式开启才落盘报告文件。
-
-完成：自验证已执行，对话内汇总完成，证据可复现。
-
-## 执行语义（生成物复用）
-
-生成物本身的执行语义与 `instance-test` 一致：`mktemp -d` 串行、`PASS m/n` 汇总、证据含 `expected vs actual diff` + `run dir`。执行前校验 `spec hash` 指纹：若当前 spec 已变更，提示「spec 已变更，建议重跑 scaffold-functional-test」但不自动覆盖，需用户显式确认才 regenerate。
-
-## 不做什么
-
-- 不替代 `tdd`/`tdd-implement` 的红绿循环与 `commit-check` 门禁
-- 不自动织入每次 `tdd-implement` 或 `commit-check`；仅 `tdd-implement --with-functional` 显式 opt-in
-- 不支持并行执行与 `docker` 隔离
-- 不处理超出混合推导锚点范围的源码静态分析隐式行为挖掘
-
-## 引用
-
-- 领域术语：`CONTEXT.md`
-- 技能设计规则：`docs/agents/skill-design.md`
-- 示范产物：`.agents/skills/instance-test/`（本仓库专属，见其 SKILL.md）
-- Issue tracker：`docs/agents/issue-tracker.md`

package/template/.pi/skills/scaffold-functional-test/agents/openai.yaml

@@ -1,5 +0,0 @@
-interface:
-  display_name: "Scaffold Functional Test"
-  short_description: "Scaffold a repo-specific functional-test skill from spec — not for running tests nor TDD"
-policy:
-  allow_implicit_invocation: true

package/template/.pi/skills/tdd-implement/SKILL.md

@@ -1,48 +0,0 @@
----
-name: tdd-implement
-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
-
-`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）规则。术语定义见 `CONTEXT.md`，技能设计规则见 `docs/agents/skill-design.md`。
-
-## 分支
-
-- **单线**：单 spec / 单 issue，走下节 Steps ①→⑦（详规见 [stages.md](references/stages.md)）。
-- **多 issue 编排**：`.scratch/<feature>/issues/` 下多文件且含 `Blocked by` 时走编排模式——编排器按依赖分层并行调度，子代理各自治完成 ①→⑦。详见 [orchestration.md](references/orchestration.md)。
-
-## Steps
-
-按序执行，每步达到完成条件才进入下一步；进入任一步前先读取其在 [stages.md](references/stages.md) 的定义。
-
-| 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-状态--实施总结) |
-
-编排模式流转见 [orchestration.md](references/orchestration.md)；子代理内部仍走上表 ①→⑦（其中 ④ 为相关测试口径，全量由编排器收敛）。
-
-### 阶段间流转
-
-- 正常流转：出口条件满足即进入下一阶段，不在阶段间停顿。
-- 回退路由：见 [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)
-- 单线详规：[stages.md](references/stages.md)
-- 多 issue 编排：[orchestration.md](references/orchestration.md)
-- Issue tracker 约定：[issue-tracker.md](../../docs/agents/issue-tracker.md)

package/template/.pi/skills/tdd-implement/agents/openai.yaml

@@ -1,5 +0,0 @@
-interface:
-  display_name: "TDD Implement"
-  short_description: "Implement from spec/ticket via TDD red-green loop"
-policy:
-  allow_implicit_invocation: false

package/template/.pi/skills/tdd-implement/references/stages.md

@@ -1,316 +0,0 @@
-# 阶段详细定义
-
-单线 ①→⑦ 的详细定义；多 issue 编排见 [orchestration.md](orchestration.md)。TDD 语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，不在此重写。
-
-## 目录
-
-- [阶段 ①：理解需求](#阶段-①理解需求)
-- [阶段 ②：确认 Seams（测试接缝）](#阶段-②确认-seams测试接缝)
-- [阶段 ③：TDD 开发循环](#阶段-③tdd-开发循环)
-- [阶段 ④：完整测试套件](#阶段-④完整测试套件)
-- [阶段 ⑤：Code Review](#阶段-⑤code-review)
-- [阶段 ⑥：Commit](#阶段-⑥commit)
-- [阶段 ⑦：收尾（文档对齐 + issue 状态 + 实施总结）](#阶段-⑦收尾文档对齐--issue-状态--实施总结)
-- [Todo 规定](#todo-规定)
-- [回退路由](#回退路由)
-
----
-
-## 阶段 ①：理解需求
-
-### 入口条件
-
-- 用户提供了 spec 或一组 ticket
-
-### 操作
-
-1. 完整读取 spec/ticket 内容
-2. 若存在 `CONTEXT.md` 和 `docs/adr/`，先阅读，确保术语和 ADR 决策不被违背
-3. 如有歧义，先向用户澄清再继续
-
-### 出口条件
-
-- 能用自己的话复述需求
-- 无未澄清的歧义
-
-### 边界
-
-- 本阶段只澄清需求——实现与测试设计在后续阶段进行
-
----
-
-## 阶段 ②：确认 Seams（测试接缝）
-
-### 入口条件
-
-- 需求已澄清，无歧义
-
-### 操作
-
-1. 列出所有将要测试的公共接口（seams）
-2. 每个 seam 需包含：名称、输入、预期输出
-3. 向用户展示 seams 清单并确认
-4. 用户确认后才写任何测试代码
-5. seams 确认后生成 todo 清单（每 seam 一个 todo，格式与状态机见 [Todo 规定](#todo-规定)）
-
-### 出口条件
-
-- 用户明确同意了 seams 清单
-
-### 边界
-
-- 一个 seam 对应一个公共接口上的一个待测行为（输入 + 预期输出）：一个 seam = 一个测试 + 一个最小实现 cycle；同一接口的多个行为拆分为多个 seam，而非内部函数
-
-> Seams 定义参考：[tdd 技能](.agents/skills/tdd/SKILL.md#seams--where-tests-go)
-
----
-
-## 阶段 ③：TDD 开发循环
-
-### 入口条件
-
-- Seams 已确认
-
-### 操作
-
-#### Git 安全前置（历史保护）
-
-- 进入本阶段前记录 `BASE_HEAD=$(git rev-parse HEAD)`，后续所有 `git` 操作必须满足 `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`、`git rebase -i` 等（需显式用户确认才可执行；`stash` 如需使用改用 `--keep-index` 并在 `pop` 后校验）。术语与禁令见 `CONTEXT.md` Git History Preservation 与 `docs/agents/skill-design.md` Rule 4。
-
-#### TDD 编排
-
-**红-绿循环前与循环中都查阅 tdd 技能各节**（Every section applies on every cycle）：TDD 语义与测试规则以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，不再在此重写——好测试标准见 [tdd/tests.md](.agents/skills/tdd/tests.md)，Mock 指南见 [tdd/mocking.md](.agents/skills/tdd/mocking.md)。
-
-本阶段只执行编排：按阶段②生成的 todo 清单逐条推进（大小任务层次与 Subtodo 格式见 [Todo 规定](#todo-规定)），每完成一个 todo（红-绿 cycle + typecheck）立即更新其状态为 `done`，再进入下一个 todo。
-
-#### 3a/3b. 红-绿（Red-Green）
-
-红-绿循环的执行规则（Red before green、One slice at a time、Anti-patterns、垂直切片）以 tdd 技能为准，见 [tdd/SKILL.md](.agents/skills/tdd/SKILL.md) 与 [tdd/tests.md](.agents/skills/tdd/tests.md)。
-
-#### 3c. 切换 seam
-
-每完成一个 seam 立即进入下一个 seam，同一回合内串行推进，不等用户"继续"。
-
-#### 3d. Typecheck
-
-- 每个 cycle 结束后运行 typecheck
-- 发现问题立即修复，修复后再继续
-
-#### 3e. 回合连续性
-
-- 每个红-绿 cycle 及其 typecheck 必须在一个回合内串行完成：测试 → 分析失败 → 修正 → 重跑 → 全绿，中途不输出、不停止、不等用户"继续"
-- **单个 seam 全绿不是回合终点**：它只是阶段③的内部步骤；阶段③的出口是"所有 seams 红-绿完成 + typecheck 通过"，在出口达成前不停顿、不等待确认，直接进入下一个 seam
-- 预告下一步后立即执行该步骤，回合终点仅为合规交互点、外部阻塞或阶段出口条件满足
-- 进度输出并入工具调用序列，不单独结束回合——输出后继续执行，直到三类终点之一达成
-- 输出只发生在：合规交互点（用户确认）、外部阻塞（明确说明所需授权或替代路径）、阶段出口条件满足时
-- 外部阻塞（如权限拒绝）时明确请求授权或改用不冲突的路径，不静默等待
-
-#### 3f. 任务分解（Chunking）
-
-- 单次 `write` 超过 ~150 行：先写骨架再分批补全
-- 批量 `replace` 超过 ~5 处：分批执行，每批后立即 typecheck 验证
-
-#### 3g. Todo 更新纪律
-
-- 每完成一个红-绿 cycle（含 typecheck），按实际推进更新对应 todo 状态：`in-progress` → `done`
-- 更新基于当前实际状态，不基于旧快照重写整个清单；已完成项（done）永不回退
-
-#### 3h. Git 历史保护（Git History Preservation）
-
-- 阶段出口前必做祖先校验：`git merge-base --is-ancestor $BASE_HEAD HEAD` 若为 false，说明历史被改写（`reset --hard`/`checkout .`/`clean -fd`/`stash --include-untracked` 等导致），立即经 `git reflog` 找回并恢复 `BASE_HEAD` 后的提交，校验通过才算出口条件满足。
-- 为达 `git status` 干净仅删本次产生的 `[DEBUG-...]`/一次性脚本等未跟踪临时文件，禁止用 git 层命令达到干净。详见 `CONTEXT.md` Git History Preservation 与 `docs/agents/skill-design.md` Rule 4。
-
-### 出口条件
-
-- 所有 seams 的红-绿循环完成
-- Typecheck 通过
-
-### 边界
-
-- 每个 cycle 后运行 typecheck
-- 全部 todo 为 done 才进入阶段④
-- 测试质量规则（公共接口验证、独立断言、mock 边界、重构归属 review）见 tdd 技能，不在本阶段重写
-
-> Mock 指南：[tdd/mocking.md](.agents/skills/tdd/mocking.md)
-> 好测试标准：[tdd/tests.md](.agents/skills/tdd/tests.md)
-
----
-
-## 阶段 ④：完整测试套件
-
-### 入口条件
-
-- 阶段 ③ 完成，typecheck 通过
-
-### 操作
-
-1. 运行仓库的完整测试套件
-2. 检查所有测试是否通过
-
-### 出口条件
-
-- 全部测试通过
-
-### 边界
-
-- 测试失败时回到阶段 ③ 修复，修复后重新运行完整套件——进入 review 前必须全绿
-
----
-
-## 阶段 ⑤：Code Review
-
-### 入口条件
-
-- 完整测试套件通过
-
-### 操作
-
-1. 调用 [code-review 技能](.agents/skills/code-review/SKILL.md) 按**双轴**审查当前所有改动：
-   - **Standards 轴**：改动是否符合仓库文档化的编码标准（含 smell baseline 判断）
-   - **Spec 轴**：改动是否忠实实现来源 spec/issue（逐条对照验收要求）
-   - 两轴独立报告、**互不掩盖**——一轴通过另一轴失败时仍须修复后重审
-2. **派发方式（强制）**：两轴必须用 subagent **single 模式**（`agent`+`task`）或 `subagent_consult` 逐个派发；**禁止 parallel `tasks` 数组**——pi-subagents 对 parallel 结果只保留前 160 字节摘要（`truncateUtf8(summary, 160)`），中文/多行报告必被截断（标记 `… [truncated by pi-subagents]`）。需要更完整输出时，要求子代理把报告写入临时文件，主代理再读取
-3. 审查发现的问题按 [回退路由](#回退路由) 处理
-
-### 出口条件
-
-- Code review 通过
-
-### 边界
-
-- 重构在此阶段进行，而非 TDD 循环阶段
-- review 通过后才进入 commit
-- 审查结果只在对话输出，不生成书面审查报告（不落盘 `review-*.md` 类文件）
-
----
-
-## 阶段 ⑥：Commit
-
-### 入口条件
-
-- Code review 通过
-
-### 操作
-
-1. 调用 [commit-check 技能](.agents/skills/commit-check/SKILL.md) 执行提交门禁——四项检查：①审查文档 ②对齐 README ③保持目录卫生 ④规范 commit message
-2. **历史校验**：commit 前执行 `git merge-base --is-ancestor $BASE_HEAD HEAD`，若为 false 说明历史被改写，立即经 `git reflog` 恢复 `BASE_HEAD` 后的提交，校验通过才继续
-3. 四项**全部通过才 commit**（含历史校验 `git merge-base --is-ancestor $BASE_HEAD HEAD` 通过）：将工作提交到当前分支，附清晰的 commit message
-
-### 出口条件
-
-- Commit 完成
-
-### 边界
-
-- Commit message 格式与内容由 commit-check ④ 把关（描述变更内容而非过程）
-
----
-
-## 阶段 ⑦：收尾（文档对齐 + issue 状态 + 实施总结）
-
-### 入口条件
-
-- Commit 完成（阶段⑥出口）
-
-### 操作
-
-1. **对齐文档**：检查 README 与 `docs/` 中涉及本次实现的描述（用法、CLI、配置、示例、架构、行为）是否与实现一致；不一致则更新文档，并单独 commit（message 遵循 commit-check ④ 规范，如 `docs: align README with <feature>`）
-2. 若本次实现有关联 issue/ticket（`.scratch/<feature-slug>/issues/`）：先审查该 issue——从 issue 提取验收标准（无显式验收标准节时以其正文行为要求为准），逐条转写为 checkbox 清单并逐条验证：通过标 `- [x]`，未通过保留 `- [ ]` 并注明缺口（证据：文件:行号 / 测试名）。全部打勾后才允许下一步：
-3. 将 `Status:` 行改为 `resolved`（无该行则追加），不改动 spec 与既有 Comments
-4. 在 issue 文件底部追加实施总结（`## 实施总结` 标题）：
-
-   ```
-   ## 实施总结
-   - 提交：`<commit hash>` — `<commit message>`
-   - 实现的 seams：<清单>
-   - 验收标准：逐条 `- [x]`（未全绿列出缺口）
-   - 测试结果：<全绿 / 数量>
-   - typecheck：通过
-   - 文档对齐：<更新了哪些文件 / 无需更新>
-   - 遗留 / 后续建议：<如有>
-   ```
-
-5. 无关联 issue（直接实现用户给的 spec）→ 跳过状态更新，将总结作为会话最终输出
-6. **保持目录卫生**：仅清理本次实现产生的临时产物——`[DEBUG-...]` 标记的调试代码/日志、一次性脚本、临时文件与备份文件；用 `git status` 确认工作区只含预期改动，无残留未跟踪文件后才结束。禁止为达干净而执行 `git reset --hard`、`git checkout .`、`git clean -fd`、`git stash push --include-untracked` 等（需显式用户确认；`stash` 如需使用改用 `--keep-index` 并在 `pop` 后校验 `git merge-base --is-ancestor $BASE_HEAD HEAD`）。
-
-### 出口条件
-
-- 文档与实现对齐（无相关文档或已更新）
-- issue 状态已更新（或确认无 issue）
-- 实施总结已落盘 / 输出
-- 工作区干净（临时产物已清理，`git status` 无残留未跟踪文件）
-
-### 边界
-
-- 只追加不改写：不修改 spec.md 与既有 Comments 内容
-- 文档对齐仅限与本次实现直接相关的描述，不顺手重构无关文档
-- 总结写事实（提交 / 测试 / 遗留），不写过程叙述
-
----
-
-## Todo 规定
-
-本节为阶段②/③的共用规定，完成"任务拆分"到"回合内执行"的闭环。
-
-### 拆分层级（大小任务层次）
-
-1. **大任务**：Goal/Ticket——整个实现单元，对应一次完整的 tdd-implement 流程
-2. **中任务**：Seam（阶段②确认）——一个红-绿循环单元，每 seam 一个 Todo
-3. **小任务**：Todo——seam 内可独立验证、可勾选的执行单元（T1/T2/T3…）
-4. **执行步**：Subtodo——Todo 内的串行步骤（红 → 绿 → typecheck），回合内逐步勾选推进
-
-> 编排模式新增一层见 [orchestration.md](orchestration.md)：**编排层** 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`，前层收敛后自动解阻派发；不需人工确认依赖满足。
-
----
-
-## 回退路由
-
-| 当前阶段 | 回退条件 | 回退目标 |
-|----------|----------|----------|
-| ③ TDD 开发 | typecheck 失败 | → ③ 修复类型错误 |
-| ④ 完整测试套件 | 测试失败 | → ③ 修复失败测试 |
-| ⑤ Code Review | 实现错误 | → ③ 修复实现 |
-| ⑤ Code Review | seams 遗漏 | → ② 补充 seams |
-| ⑤ Code Review | 需求偏差 | → ① 澄清需求 |
-
-编排模式回退见 [orchestration.md#A5](orchestration.md#a5-回退与冲突)：子代理内回退按上表在子代理内闭环；编排器层收敛失败（全量测试失败 / 目录不干净）→ 定位到失败 issue 所在层重派对应子代理。
-