@heihei0299/matt-skills 1.6.3 → 1.6.4-test.1

package/.agents/skills/show-me/SKILL.md

@@ -0,0 +1,5 @@
+---
+name: show-me
+description: Show the current state or demo for review.
+---
+Show the current implementation or state for the user to review.

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

@@ -1,6 +1,6 @@
 ---
 name: tdd-implement
-description: "TDD seam red-green loop: use when the user provides a spec/ticket for test-first implementation or asks for red-green loop through typecheck/review/commit. For non-TDD implementation use implement; for technique alone use tdd."
+description: "Multi-task orchestrator: use when the user provides a spec/ticket or Type:task issues (wayfinder/to-tickets/single spec) for test-first implementation. Main agent executes tasks sequentially by Blocked-by Kahn order, each task full ①→⑦ implement (seam red-green → typecheck → code-review → commit-check → single commit). For non-TDD use implement; for technique alone use tdd."
 ---
 
 # TDD Implement
@@ -11,33 +11,30 @@ description: "TDD seam red-green loop: use when the user provides a spec/ticket
 
 ## 分支
 
-- **单线**：单 spec / 单 issue，走下节 Steps ①→⑦（详规见 [stages.md](references/stages.md)）。
-- **多 issue 编排**：`.scratch/<feature>/issues/` 下多文件且含 `Blocked by` 时走编排模式——见下节与 [orchestration.md](references/orchestration.md)。
-
-## 多 issue 编排（按依赖分层并行）
-
-触发见 [orchestration.md](references/orchestration.md)；`.scratch/<feature>/issues/` 下多文件且部分含 `Blocked by` 时触发，主过程 A0 依赖图 → A1 Kahn 分层 L1入度0→L2→Ln → A2 分层调度（逐个 subagent single 派发、共享 working tree，禁止主会话直做；`N>1` 时串行错峰派发以减同文件竞写，文件冲突由后完成者 rebase 解决） → A3 子代理契约 → A4 全量收敛 → A5 回退与冲突（最小重派：按失败点精确回退、精确定位单 issue 单 seam，全量保留为详规真相源）。必须先编排子代理计划（输出依赖图/DAG 与 Kahn 分层 `L1..Ln` 并确认）后才派发，禁止跳过计划直接派发导致重复调度；编排模式下所有 issue 的 `①→⑦` 必须经子代理执行、主会话仅编排与验收，禁止任何“为省开销/效率”在主会话直做；层收敛 4 项（验收/相关测试/`git status`仅删`[DEBUG-...]`/ `BASE_HEAD`历史校验 `git merge-base --is-ancestor`）与子代理回执卡片（≤30行、缺字段视为不通过）、打回重派、rebase 冲突处理等可执行约束全量见 orchestration.md。
+- **入口**：单 `spec` 文件（`.scratch/<feature>/spec.md` 或等价）/ `Type: task` 的 `issue`（`wayfinder`/`to-tickets` 产出）均视同单 `task`，走下节 Steps ①→⑦；`Type: research/prototype/grilling` 分流至对应技能。
+- **多 issue 编排**：`.scratch/<feature>/issues/` 下多 `task` 时走编排模式——见上节与 [orchestration.md](references/orchestration.md)。
+## 多 issue 编排（按依赖串行，主代理直接执行）
 
+触发见 [orchestration.md](references/orchestration.md)；`.scratch/<feature>/issues/` 下多文件时触发，主过程 A0 依赖图 → A1 Kahn 分层 L1入度0→L2→Ln → A2 主代理串行调度（按层串行、层内亦串行，主代理直接执行完整 ①→⑦，禁止子代理派发；每 issue 单独 `commit`，绿后即 `code-review` + `commit-check` 双门禁） → A3 层收敛 → A4 全量收敛。`Blocked by` 仍为排序输入，三入口（单 `spec` / `Type: task` issue / `wayfinder task`）同构。强制维护 `.scratch/<feature>/progress.md`（`DAG` + `Layers` + `Progress` 表，派生视图，真相源为 `spec` + `issues/*.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 红-绿循环（红→绿→typecheck）串行推进至全绿 | 所有 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-状态--实施总结) |
-
-子代理内部仍走上表 ①→⑦（其中 ④ 为相关测试口径，全量由编排器收敛）。
+| ① 理解需求 | 读取入口并建立验证矩阵 | 需求无待决歧义，验证命令已确定 | [stages.md#阶段-①](references/stages.md#阶段-①理解需求) |
+| ② 确认 Seams | 从明确 spec/ticket 生成 seams 与 Todo；详规列出的确认门槛例外（含破坏性操作） | seams/Todo 已生成且无待决歧义 | [stages.md#阶段-②](references/stages.md#阶段-②确认-seams测试接缝) |
+| ③ TDD 开发循环 | 逐 seam 红-绿循环（红→绿→typecheck）串行推进 | 所有 seams 红-绿完成 + typecheck 通过 | [stages.md#阶段-③](references/stages.md#阶段-③tdd-开发循环) |
+| ④ 最终全量测试 | 所有 issue 完成后按验证矩阵只运行一次全量命令；多 issue 由 A4 执行，单 spec 在 issue 收尾后执行 | 全量测试通过 | [stages.md#阶段-④](references/stages.md#阶段-④完整测试套件) |
+| ⑤ Code Review | 每个 issue 恰好执行一次 Standards + Spec 双轴 review；findings 只做 targeted 修复，不再次 review | 每个 issue 的一次 review 已完成 | [stages.md#阶段-⑤](references/stages.md#阶段-⑤code-review) |
+| ⑥ Commit | 运行一次最终 commit-check 门禁并提交 | commit 完成且历史校验通过 | [stages.md#阶段-⑥](references/stages.md#阶段-⑥commit) |
+| ⑦ 收尾 | 复核门禁证据，处理 issue 总结与目录卫生 | 总结完成、工作区干净 | [stages.md#阶段-⑦](references/stages.md#阶段-⑦收尾文档对齐--issue-状态--实施总结) |
+主代理串行时每个 `task` 先走 `①→②→③→⑤→⑥→⑦` 并单独 commit；所有 issue 完成后再执行阶段④全量收敛（单 spec 只有一个 issue，也在其收尾后执行一次）。
 
 ### 阶段间流转
 
 - 正常流转：出口条件满足即进入下一阶段，不在阶段间停顿。
-- 回退路由：见 [stages.md#回退路由](references/stages.md#回退路由)；编排模式回退见 [orchestration.md#A5](references/orchestration.md#a5-回退与冲突)。
+- 回退路由：见 [stages.md#回退路由](references/stages.md#回退路由)；编排模式回退见 [orchestration.md](references/orchestration.md)。
 - 回合连续性与任务分解：见 [stages.md ③-3e/3f](references/stages.md#阶段-③tdd-开发循环)（红→绿→typecheck→下一 seam 一个回合内串行完成，直至阶段出口；预告下一步后立即执行；write>150 行/replace>5 处拆小步）。
 
 ## 引用
@@ -47,4 +44,4 @@ description: "TDD seam red-green loop: use when the user provides a spec/ticket
 - 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 编排详规：[orchestration.md](references/orchestration.md)（A0-A1 排序 + 主代理串行，不含子代理）

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

@@ -1,17 +1,18 @@
-# 多 issue 编排（按依赖分层并行）
+# 多 issue 编排（按依赖串行，主代理直接执行）
 
-本文件仅在多 issue 编排模式下生效；单 issue / 单 spec 走 [stages.md](stages.md) 单线流程，不经过本文件。
+本文件仅在多 `task` 编排时生效；单 `spec` / 单 `task` 走 [stages.md](stages.md) 单线 ①→⑦，主代理直接执行完整流程并单独提交，不经子代理。
 
-多 issue 触发条件：`.scratch/<feature>/issues/` 下存在多个 issue 文件且至少部分含 `Blocked by` 依赖声明。
+多 issue 触发条件：`.scratch/<feature>/issues/` 下存在多个 `Type: task` 的 issue 文件（`wayfinder`/`to-tickets` 产出或等价），按 `Blocked by` 组织依赖。
+
+三入口（单 `spec` / 单 `task` / 多 `task`）在单 issue 层面同构：`spec`/`issue` 均为 `task` 闭环输入，`research`/`prototype`/`grilling` 分流不进本技能。编排层 Feature—`.scratch/<feature>/` 下全部 `task` 按 `Blocked by` 分层。
 
 ## 目录
 
 - [A0. 依赖图构建](#a0-依赖图构建)
 - [A1. 拓扑分层](#a1-拓扑分层)
-- [A2. 分层调度](#a2-分层调度)
-- [A3. 子代理契约（单 issue 单代理）](#a3-子代理契约单-issue-单代理)
+- [A2. 主代理串行调度](#a2-主代理串行调度)
+- [A3. 层收敛](#a3-层收敛)
 - [A4. 全量收敛](#a4-全量收敛)
-- [A5. 回退与冲突](#a5-回退与冲突)
 - [出口条件](#出口条件)
 - [边界](#边界)
 
@@ -24,8 +25,8 @@
    - `Blocked by: 01, 02` / `Blocked by: 01（…）` → 依赖 `01`、`02` 对应的 issue 文件（按编号前缀匹配）
    - 无法解析的行 → 视为无依赖，并在编排总结中注明告警
 2. 以 issue 编号为节点、`Blocked by` 为有向边构建 DAG；若检测到环，立即报错并列出环上节点，不进入调度。
-3. 读取 `spec.md`（若存在）作为各子代理的共享上下文；同时读取 `CONTEXT.md` 与 `docs/adr/` 供一致性校验。
-
+3. 读取 `spec.md`（若存在）作为共享上下文；同时读取 `CONTEXT.md` 与 `docs/adr/` 供一致性校验。
+4. **强制初始化 `progress.md`**：在 `.scratch/<feature>/progress.md` 落 `## DAG` + `## Layers (Kahn L1..Ln)` + `## Progress` 空表（`| NN | Status | Commit | Review | Tests |`），作为编排态唯一派生视图（真相源仍为 `spec` + `issues/*.md`）。
 ### A1. 拓扑分层
 
 对 DAG 做 Kahn 分层（BFS 拓扑）：
@@ -37,101 +38,52 @@ L2 = 移除 L1 后入度为 0 的节点
 Ln = 最后一层
 ```
 
-每层内节点互无依赖，可并行；层间有依赖，必须串行。分层结果在编排开始前一次性展示给用户确认（合规交互点），确认后才派发。
-若两 issue 在阶段②已声明预期改动同一文件，编排器在 A0 后提示建议追加 `Blocked by` 使其串行（轻提示，不强制）；主要仍靠 A2 串行错峰自然错峰。
-### A2. 分层调度
-
-```
-for each 层 Li in L1..Ln:
-  并行派发：为 Li 中每个 issue 启动一个子代理（single 模式，共享 working tree，禁止 parallel tasks 数组；N>1 时串行错峰派发）
-  等待：阻塞直到 Li 全部子代理返回回执卡片
-  验收：编排器按 A3 验收清单逐 issue 验收（只认回执卡片的关键信息 + 抽检验证在最新 HEAD 上执行，不消费全量日志）
-  层收敛验证：验收全通过进入全量验证（完成条件 4 项，全部通过才进下一层，任一失败按 A5 最小重派该 issue）：①该层全部 issue 验收通过 ②相关测试套件通过（全量仅在 A4） ③`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 最小重派处理。
-- **冲突判定（Q1/Q2）**：同文件即冲突，以 `HEAD` 已移动（`git log` 已含先完成者 `#NN`）为准判定慢者前后不一致；不在工作区瞬时覆盖时判定。
-- **回合连续性**：编排器在层间不结束回合——一层收敛后立即派发下一层，直到全部层完成或外部阻塞；预告下一层后立即执行。
-- **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 验收，打回重派直至验收通过才计入层收敛。
+每层内节点互无依赖（但仍串行执行，主代理一次一 issue）；层间有依赖，必须串行。分层结果在编排开始前一次性展示给用户确认（合规交互点），确认后才进入 A2。若两 issue 在阶段②已声明预期改动同一文件，建议追加 `Blocked by` 使其串行（轻提示，不强制）。
 
-- **输入**：
-  - `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 行）：
+### A2. 分层调度（主代理串行）
 
 ```
-[回执] #NN <issue 标题>
-- 提交：<commit hash> — <message>
-- seams：<清单>
-- 测试：相关测试 <数量> 项全绿 / 失败清单（全量由编排器层收敛/A4 验证）
-- typecheck：通过 / 失败原因
-- review：Standards <通过/问题> / Spec <通过/问题>
-- 验收：checkbox <m/n 全绿，缺口说明>
-- 文档：<更新文件 / 无需更新>
-- 遗留：<如有>
+for each 层 Li in L1..Ln:
+  for each issue in Li（按编号顺序）:
+    主代理直接执行该 issue 的 issue 闭环：
+      ①理解需求 → ②生成 seams/Todo → ③红-绿循环（每 cycle 后 typecheck）→ ⑤一次 code-review → ⑥commit-check + 单独 commit → ⑦收尾（Status: resolved + ## 实施总结 + map.md 指针如为 wayfinder 产物 + 目录卫生）；④全量测试不在 issue 闭环内执行
+    产回执卡片（改动文件/测试结果/commit hash）并回写该 issue 文件后**强制更新 `progress.md` 该行**（`Status`/`Commit`/`Review`/`Tests`）后再取下一 issue
+  层收敛：该层全部 issue `Status: resolved` 且 `progress.md` 同步为 `done`、各自独立 commit 已落盘、相关测试通过、`git status` 卫生、历史校验通过，才进下一层
+全部层串行完成后进入 A4
 ```
 
-卡片字段缺一不可；缺失字段视为验收不通过。详细过程与证据留在子代理的 commit 与 issue 文件中，编排器按需抽检而非全量消费。
-
-#### 主代理验收（编排器逐 issue 验收）
-
-编排器收到回执后逐 issue 验收，不盲信子代理自检：
+- **回合连续性**：主代理在层内/层间不结束回合——一 issue 提交后立即取下一 issue，直到全部层完成或外部阻塞；预告下一 issue 后立即执行。
+- **Git 历史保护**：进入 A2 前记录 `BASE_HEAD=$(git rev-parse HEAD)`，每 issue 提交前校验 `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` 等。
+- **Chunking**：每 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 一致；缺失或不一致视为不通过。
+### A3. 层收敛
 
-任一项不通过 → 打回重派该子代理（仅该 issue），层内其他已通过不受影响；验收通过才计入层收敛。验收结论随层收敛一并输出。
+每层全部 issue 串行完成后，主代理执行层收敛 4 项（全部通过才进下一层）：
+1. 该层全部 issue `Status: resolved` 且 `## 实施总结` 已落盘且 `progress.md` 同步为 `done`
+2. 相关测试通过（该层 issue 相关；全量仅在 A4）
+3. `git status` 卫生（仅删本次临时产物）
+4. 历史校验 `git merge-base --is-ancestor $BASE_HEAD HEAD` 通过
 
-子代理内部的回合连续性、任务分解、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` 等。
+任一失败定位到该层失败 issue，重做该 issue 的失败 seam/阶段后重检该层。
 
 ### A4. 全量收敛
 
-全部层逐 issue 验收通过后，编排器执行：
-
-1. **全量测试套件**：跑仓库完整测试套件（所有 issue 执行完毕后的唯一全量，阶段④与 A2 已改为相关，仅此一次）
-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 Standards 味→⑤重构`、`review Spec 偏离→①`、`review seams 遗漏→②补 seams`、`commit-check 文档/卫生/message 失败→⑥/⑦ 对应阶段`。失败点之前的已 `done` seam/Todo 永不回退，仅重跑失败阶段及下游；`seams 清单` 与已绿 seam 默认复用，仅 `seams 遗漏/需求偏差` 两类才回到 `②/①` 重确认。
-- **层收敛失败（最小重派）**：层内任一子代理未达到 `resolved`（含验收 5 项、相关测试、卫生、历史校验任一不过）→ 该 issue 保持原 `Status`，编排器在层等待结束后报告失败清单，不自动进入下一层；待修复后仅重派失败节点，同层其他已通过不受影响。层原子语义保持：`Li` 未全 `resolved` 不派 `L_{i+1}`。
-- **全量收敛失败（精确定位）**：A4 全量测试失败 → 以测试文件路径/报错栈精确定位到单 issue 单 seam，回到其所在层仅重派该 issue 的失败 seam + 相关测试，全量由编排器在重派后再次 A4 统一验证；无法精确定位时退化到层级重派，不重跑无关联 issue。
-- **文件冲突（Q1-Q4）**：同文件即冲突（Q1 慢者因 `HEAD` 已移动致前后不一致）；慢者完成当前 seam 的 `红→绿→typecheck` 后再以新 HEAD 为基线 rebase，仅重做该冲突文件关联的 seam（其余已绿复用，Q3/Q4 最小化）；后完成者 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` 合并结果（`HEAD` 已移动）为准，编排器不做静态文件监听预判。
-- **环依赖**：A0 检测到环即报错终止，不派发任何子代理。
+全部层串行完成且各自层收敛通过后，执行：
+1. **全量测试套件**：这是多 issue 流程中唯一的全量回归点；全部层、全部 issue 串行完成后仅执行一次（失败修复后才允许必要重跑）
+2. **历史校验**：`git merge-base --is-ancestor $BASE_HEAD HEAD`，失败即 `reflog` 恢复后重跑
+3. **目录卫生**：`git status` 无 `[DEBUG-...]` 残留、无未跟踪临时文件
+4. **汇总总结**：在会话输出汇总各 issue 的回执卡片关键信息（提交 hash / seams / 验收 checkbox / 测试结果 / 文档对齐）；不另写汇总文件
 
 ### 出口条件
 
-- 全部 issue `Status: resolved` + 各自 `## 实施总结` 已落盘
+- 全部 issue `Status: resolved` + 各自 `## 实施总结` 已落盘且 `progress.md` 同步为 `done`
 - 全量测试套件通过
-- 工作区干净（`git status` 无残留）
+- 工作区干净且 `progress.md` 与 `issues/*.md` 一致（不一致时以 `issues/*.md` 为准，`progress.md` 为派生可重算）
 
 ### 边界
 
-- 单 issue / 单 spec 不走本文件；但一旦进入编排模式（多 issue 且含 Blocked by），无论 N==1 还是 N>1，所有 issue 的 ①→⑦ 必须经子代理 single 派发完成，禁止主会话直做（编排器仅编排、验收、归集、清理）
-- 子代理不跨 issue 改动；编排器不替子代理写实现代码；主会话不直接写业务代码/测试/文档（仅做编排与验收）
+- 单 issue / 单 spec 不走本文件编排，但一旦进入多 issue 编排（多 `task`），所有 issue 的 ①→⑦ 均由主代理串行直接执行，禁止子代理派发
+- 不跨 issue 改动；主代理按层串行，一次一 issue 一 commit
 - 汇总总结只在对话输出，不落盘额外汇总文件
-- 必须先编排子代理计划（输出依赖图/DAG/Kahn 分层 `L1..Ln` 并确认）后才派子代理，禁止跳过计划直接派发导致重复调度
+- 必须先输出依赖图/DAG 与 Kahn 分层 `L1..Ln` 并确认后才进入 A2，禁止跳过计划直接执行导致乱序
 - TDD 语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，不在本文件重写
-

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

@@ -1,7 +1,6 @@
 # 阶段详细定义
 
-单线 ①→⑦ 的详细定义；多 issue 编排主过程见 [SKILL.md](../SKILL.md#多-issue-编排按依赖分层并行)，详规见 [orchestration.md](orchestration.md)。TDD 语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，不在此重写。
-
+单 `spec` / 单 `task` 与多 `task`（按 `Blocked by` 依赖分层串行、主代理直接执行）共用下表 ①→⑦；多 issue 编排（A0-A1 排序 + 主代理串行）见 [SKILL.md](../SKILL.md) 与 [orchestration.md](orchestration.md)。TDD 语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，不在此重写。
 ## 目录
 
 - [阶段 ①：理解需求](#阶段-①理解需求)
@@ -20,23 +19,26 @@
 
 ### 入口条件
 
-- 用户提供了 spec 或一组 ticket
+- 用户提供了单 `spec` 文件（`.scratch/<feature>/spec.md` 或等价）或一个 `Type: task` 的 ticket（`wayfinder`/`to-tickets` 产出，含 `Blocked by`/`Status`）；`Type: research/prototype/grilling` 分流至对应技能，不进本技能
 
 ### 操作
 
-1. 完整读取 spec/ticket 内容
-2. 若存在 `CONTEXT.md` 和 `docs/adr/`，先阅读，确保术语和 ADR 决策不被违背
-3. 如有歧义，先向用户澄清再继续
+1. 完整读取入口（`spec` 或 `issue`）内容
+2. 使用读取预算：按需读取 `CONTEXT.md` 的相关术语；ADR 只读与 spec、触及符号或失败证据相关的条目，不批量读取无关文档
+3. 使用仓库规定的代码探索入口；探索结果包含完整源码时视为已读，不再次 `read` 同一文件，除非文件发生漂移或只返回调用路径
+4. 如有歧义，先向用户澄清再继续；无歧义时直接进入阶段②
+5. 建立一次验证矩阵：列出 targeted tests、typecheck、全量测试以及 spec 要求的 smoke、package 或 security checks，后续复用证据，避免等价命令重复执行
 
 ### 出口条件
 
 - 能用自己的话复述需求
 - 无未澄清的歧义
+- 验证矩阵已建立，且每项命令/检查已有明确触发条件
 
 ### 边界
 
-
----
+- `CONTEXT` 术语冲突时以 `CONTEXT` 为准，必要时先 `domain-modeling` 纠偏
+- 单 `spec` 与单 `task` 同构，均走 ①→⑦；多 `task` 由 [orchestration.md](orchestration.md) A0-A1 排序后主代理串行，不经子代理
 
 ## 阶段 ②：确认 Seams（测试接缝）
 
@@ -47,14 +49,14 @@
 ### 操作
 
 1. 列出所有将要测试的公共接口（seams）
-2. 每个 seam 需包含：名称、输入、预期输出
-3. 向用户展示 seams 清单并确认
-4. 用户确认后才写任何测试代码
-5. seams 确认后生成 todo 清单（每 seam 一个 todo，格式与状态机见 [Todo 规定](#todo-规定)）
+2. 每个 seam 包含：名称、输入、预期输出，以及对应的最小验证命令
+3. spec/ticket 已给出明确验收标准时，直接生成 Todo 并展示精简 seam 卡片；不等待用户确认
+4. 仅在歧义、验收缺口、范围变化、破坏性操作或互斥方案时暂停确认
+5. seams 确认门槛满足后生成 todo 清单（每 seam 一个 todo，格式与状态机见 [Todo 规定](#todo-规定)）
 
 ### 出口条件
 
-- 用户明确同意了 seams 清单
+- seams/Todo 已生成，且没有待决的歧义、验收缺口或需要用户选择的方案
 
 ### 边界
 
@@ -77,7 +79,7 @@
 
 #### 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)。
+**读取预算（TDD Reference Cache）**：在阶段③入口加载 tdd 技能的相关规则一次；每个 cycle 仅按当前 seam 定位需要的 [`tdd/tests.md`](.agents/skills/tdd/tests.md) 与 [`tdd/mocking.md`](.agents/skills/tdd/mocking.md) reference，不重复阅读全文。TDD 语义与测试规则以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，不再在此重写。
 
 本阶段只执行编排：按阶段②生成的 todo 清单逐条推进（大小任务层次与 Subtodo 格式见 [Todo 规定](#todo-规定)），每完成一个 todo（红-绿 cycle + typecheck）立即更新其状态为 `done`，再进入下一个 todo。
 
@@ -136,20 +138,18 @@
 
 ### 入口条件
 
-- 阶段 ③ 完成，typecheck 通过
-
+- 所有 issue 已完成其实现、targeted tests、typecheck、一次 code-review、commit 和收尾；多 issue 从 orchestration A4 进入，单 spec 在唯一 issue 收尾后进入
+- 阶段④不是 issue 闭环步骤，不得在任一 issue 完成时提前执行
 ### 操作
-
-1. 运行仓库的完整测试套件（单线模式的唯一全量；多 issue 子代理此步仅相关，全量由 A4 统一执行）
-2. 检查所有测试是否通过
-
+1. 按阶段①建立的验证矩阵，运行仓库规范的唯一全量测试命令；正常路径只执行一次
+2. 若失败，先运行失败测试或最小相关子集定位原因；修复对应 issue 后才重跑全量命令
+3. 记录最终全量结果，不同时运行等价命令（例如 `npm test` 与其展开命令），除非本次改动了 package script 本身
+4. 检查所有测试是否通过
 ### 出口条件
-
-- 全部测试通过
-
+- 全量测试通过
 ### 边界
-
-- 测试失败时回到阶段 ③ 修复，修复后重新运行完整套件——进入 review 前必须全绿
+- 多 issue 仅由 A4 在所有 issue 完成后执行；单 spec 在唯一 issue 收尾后执行
+- 全量测试失败时回到失败 issue 的修复路径；修复后只做必要的定向诊断和全量重跑
 
 ---
 
@@ -157,16 +157,14 @@
 
 ### 入口条件
 
-- 完整测试套件通过
-
+- 阶段③ targeted tests 和 typecheck 通过；阶段④全量测试尚未执行也不构成此阶段入口条件
 ### 操作
-
-1. 调用 [code-review 技能](.agents/skills/code-review/SKILL.md) 按**双轴**审查当前所有改动：
+1. 每个 issue 恰好调用一次 [code-review 技能](.agents/skills/code-review/SKILL.md)，按**双轴**审查当前 issue 的改动：
    - **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. 审查发现的问题按 [回退路由](#回退路由) 处理
+   - 两轴独立报告、**互不掩盖**；该 issue 不再次调用 code-review
+2. 审查发现的问题按 [回退路由](#回退路由) 处理，并只重跑受影响的 targeted checks；修复不触发第二次 review
+3. 记录该 issue 的一次 review 结果，通过后进入 commit 和收尾
 
 ### 出口条件
 
@@ -178,8 +176,6 @@
 - review 通过后才进入 commit
 - 审查结果只在对话输出，不生成书面审查报告（不落盘 `review-*.md` 类文件）
 
----
-
 ## 阶段 ⑥：Commit
 
 ### 入口条件
@@ -188,9 +184,10 @@
 
 ### 操作
 
-1. 调用 [commit-check 技能](.agents/skills/commit-check/SKILL.md) 执行提交门禁——四项检查：①审查文档 ②对齐 README ③保持目录卫生 ④规范 commit message
+1. 在一次最终门禁中调用 [commit-check 技能](.agents/skills/commit-check/SKILL.md)：完成三项检查——文档一致性、目录卫生、commit message；目录卫生包含敏感扫描，spec 要求时再执行 package dry-run 等必要检查
 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
+3. 三项门禁、历史校验和必要检查全部通过才 commit；门禁证据保持为最终基线，未改文件不在 commit 后重复扫描或打包
+4. 将工作提交到当前分支，附清晰的 commit message（单 issue 单提交，如 `feat(<feature>): <issue title> (#NN)`）；多 issue 时每 issue 独立提交后才取下一 issue
 
 ### 出口条件
 
@@ -198,9 +195,8 @@
 
 ### 边界
 
-- Commit message 格式与内容由 commit-check ④ 把关（描述变更内容而非过程）
-
----
+- Commit message 格式与内容由 commit-check ③ 把关（描述变更内容而非过程）
+- 每 issue 独立提交，主代理串行时一 issue 一 commit 后再进入下一 issue 的 ①
 
 ## 阶段 ⑦：收尾（文档对齐 + issue 状态 + 实施总结）
 
@@ -210,7 +206,7 @@
 
 ### 操作
 
-1. **对齐文档**：检查 README 与 `docs/` 中涉及本次实现的描述（用法、CLI、配置、示例、架构、行为）是否与实现一致；不一致则更新文档，并单独 commit（message 遵循 commit-check ④ 规范，如 `docs: align README with <feature>`）
+1. **复核文档对齐**：以阶段⑥ commit-check 已记录的 README/docs/config/package 对齐证据为准；本阶段只复核并记录“无需更新”或已更新文件，不重复读取、编辑或追加 commit。若证据缺失或不一致，标记阶段⑥门禁失败并停止收尾，不将 issue 标为 resolved。
 2. 若本次实现有关联 issue/ticket（`.scratch/<feature-slug>/issues/`）：先审查该 issue——从 issue 提取验收标准（无显式验收标准节时以其正文行为要求为准），逐条转写为 checkbox 清单并逐条验证：通过标 `- [x]`，未通过保留 `- [ ]` 并注明缺口（证据：文件:行号 / 测试名）。全部打勾后才允许下一步：
 3. 将 `Status:` 行改为 `resolved`（无该行则追加），不改动 spec 与既有 Comments
 4. 在 issue 文件底部追加实施总结（`## 实施总结` 标题）：
@@ -225,9 +221,9 @@
    - 文档对齐：<更新了哪些文件 / 无需更新>
    - 遗留 / 后续建议：<如有>
    ```
-
-5. 无关联 issue（直接实现用户给的 spec）→ 跳过状态更新，将总结作为会话最终输出
-6. **保持目录卫生**：仅清理本次实现产生的临时产物——`[DEBUG-...]` 标记的调试代码/日志、一次性脚本、临时文件与备份文件；用 `git status` 确认工作区只含预期改动，无残留未跟踪文件后才结束。Git 历史保护与禁令见本文件阶段③ [Git 安全前置](#git-安全前置历史保护)与 `docs/agents/skill-design.md` Rule 4，仅删本次临时产物，禁止为达干净而执行 git 层破坏性命令。
+5. **强制更新 `progress.md`**：在 `.scratch/<feature>/progress.md` 更新该 `NN` 行的 `Status`/`Commit`/`Review`/`Tests`（派生视图，真相源仍为 `issues/*.md`）
+6. 无关联 issue（直接实现用户给的 spec）→ 跳过状态更新，将总结作为会话最终输出
+7. **保持目录卫生**：仅清理本次实现产生的临时产物——`[DEBUG-...]` 标记的调试代码/日志、一次性脚本、临时文件与备份文件；用 `git status` 确认工作区只含预期改动，无残留未跟踪文件后才结束。Git 历史保护与禁令见本文件阶段③ [Git 安全前置](#git-安全前置历史保护)与 `docs/agents/skill-design.md` Rule 4，仅删本次临时产物，禁止为达干净而执行 git 层破坏性命令。
 
 ### 出口条件
 
@@ -246,20 +242,20 @@
 
 ## Todo 规定
 
-本节复用 `tdd`/`implement` 的 Todo 规定，`tdd-implement` 仅做多 issue 编排与串联，不再重写层次细节。
+本节复用 `tdd`/`implement` 的 Todo 规定，`tdd-implement` 仅做多 issue 串行（主代理按依赖顺序）与单 issue 闭环，不再重写层次细节。
 
 ### 拆分层级（大小任务层次）
 
 1. **大任务**：Goal/Ticket——整个实现单元，对应一次完整的 tdd-implement 流程
-2. **中任务**：Seam（阶段②确认）——一个红-绿循环单元，每 seam 一个 Todo
+2. **中任务**：Seam（阶段②生成）——一个红-绿循环单元，每 seam 一个 Todo
 3. **小任务**：Todo——seam 内可独立验证、可勾选的执行单元（T1/T2/T3…）
 4. **执行步**：Subtodo——Todo 内的串行步骤（红 → 绿 → typecheck），回合内逐步勾选推进
 
-> 编排模式新增一层见 [SKILL.md](../SKILL.md#多-issue-编排按依赖分层并行) 主过程与 [orchestration.md](orchestration.md) 详规：**编排层** Feature——`.scratch/<feature>/` 下全部 issues，按 `Blocked by` 分层；每层一组并行子代理，每子代理一个 issue 的完整 ①→⑦。
+> 多 issue（串行）新增一层见 [SKILL.md](../SKILL.md#多-issue-编排按依赖串行主代理直接执行) 与 [orchestration.md](orchestration.md)：**编排层** Feature——`.scratch/<feature>/` 下全部 issues，按 `Blocked by` 分层；主代理按层串行、层内亦串行，每 issue 完整 ①→⑦ 并单独提交。
 
 ### Todo 清单格式
 
-阶段② seams 确认后立即生成 todo 清单，每个 seam 一个 todo：
+阶段② seams 生成且确认门槛满足后立即生成 todo 清单，每个 seam 一个 todo：
 
 - 编号：`T1`、`T2`、`T3`…
 - 描述：seam 名称 + 输入 + 预期输出
@@ -267,7 +263,7 @@
 - 完成标准（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 清单为**分层清单**：`L1: [01, 02] → L2: [03, 04] → L3: [05]`，每层按依赖串行（不再并行）；每 issue 的 DoD 为 `Status: resolved` + 独立 commit + 实施总结已落盘。
 
 ### Todo 状态机
 
@@ -277,7 +273,7 @@ pending → in-progress → done
 ```
 
 - Subtodo 不单独设 `blocked`——阻塞状态归父 Todo，Subtodo 跟随父状态
-- 编排模式下 issue 粒度状态机：`pending → in-progress(子代理已派发) → done(Status: resolved)`；`blocked` 表示 `Blocked by` 依赖未满足，待前层全 `resolved` 后自动解阻。
+- 编排模式下 issue 粒度状态机：`pending → in-progress(主代理执行中) → done(Status: resolved)`；`blocked` 表示 `Blocked by` 依赖未满足，待前层全 `resolved` 后自动解阻。
 
 ### 粒度与回合归属
 
@@ -287,13 +283,13 @@ pending → in-progress → done
 - 每完成一个 todo 立即更新其状态，再进入下一个
 - todo 状态只按实际推进更新（pending → in-progress → done），不基于旧快照重写整个清单；已完成项（done）永不回退
 - 全部 todo 为 done 才进入阶段④
-- 编排模式下：每层全部 issue `done` 才进入下一层；全部层 `done` 后编排器做全量收敛验证。
+- 编排模式下：前层全部 issue `done` 才进入下一层；全部层 `done` 后执行全量收敛（A4）。
 
 ### 阻塞处理
 
 - 外部阻塞（权限拒绝、缺失授权、依赖不可用）→ 标记 `blocked`，记录所需授权或替代路径
 - 不静默停止；恢复后回到 `in-progress` 继续
-- 编排模式下：`Blocked by` 依赖阻塞由编排器自动管理——前层未全 `resolved` 时后层 `blocked`，前层收敛后自动解阻派发；不需人工确认依赖满足。
+- 编排模式下：`Blocked by` 依赖阻塞由主代理按层自动管理——前层未全 `resolved` 时后层 `blocked`，前层提交后自动解阻；不需人工确认依赖满足。
 
 ---
 
@@ -307,5 +303,4 @@ pending → in-progress → done
 | ⑤ Code Review | seams 遗漏 | → ② 补充 seams |
 | ⑤ Code Review | 需求偏差 | → ① 澄清需求 |
 
-编排模式回退主过程见 [SKILL.md](../SKILL.md#多-issue-编排按依赖分层并行) A5，详规见 [orchestration.md#A5](orchestration.md#a5-回退与冲突)：子代理内回退按上表在子代理内闭环；编排器层收敛失败（全量测试失败 / 目录不干净）→ 定位到失败 issue 所在层重派对应子代理。
-
+编排模式回退见 [orchestration.md](orchestration.md)：单 issue 内回退按上表在当 issue 内闭环；层收敛/全量失败定位到失败 issue 所在层重做该 issue 的失败 seam。