@heihei0299/matt-skills 1.6.1 → 1.6.2

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

@@ -16,7 +16,7 @@ description: "TDD seam red-green loop: use when the user provides a spec/ticket
 
 ## 多 issue 编排（按依赖分层并行）
 
-触发见 [orchestration.md](references/orchestration.md)；`.scratch/<feature>/issues/` 下多文件且部分含 `Blocked by` 时触发，主过程 A0 依赖图 → A1 Kahn 分层 L1入度0→L2→Ln → A2 分层调度（层内 `N>1` 时每 issue 独立 `git worktree` + `wt/<feature>-#NN` 分支隔离、按序 `merge --no-ff` 归集，`N==1` 退化共享） → A3 子代理契约 → A4 全量收敛 → A5 回退与冲突（最小重派：按失败点精确回退、失败分支增量 fix、精确定位单 issue 单 seam，全量保留为详规真相源）。必须先编排子代理计划（输出依赖图/DAG 与 Kahn 分层 `L1..Ln` 并确认）后才派发，禁止跳过计划直接派发导致重复调度；层收敛 4 项（验收/相关测试/`git status`仅删`[DEBUG-...]`/ `BASE_HEAD`历史校验 `git merge-base --is-ancestor`）与子代理回执卡片（≤30行、缺字段视为不通过）、打回重派（重建全新 worktree 最小 fix）、merge 冲突显式化等可执行约束全量见 orchestration.md。
+触发见 [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。
 
 ## Steps
 

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

@@ -38,27 +38,23 @@ Ln = 最后一层
 ```
 
 每层内节点互无依赖，可并行；层间有依赖，必须串行。分层结果在编排开始前一次性展示给用户确认（合规交互点），确认后才派发。
-
+若两 issue 在阶段②已声明预期改动同一文件，编排器在 A0 后提示建议追加 `Blocked by` 使其串行（轻提示，不强制）；主要仍靠 A2 串行错峰自然错峰。
 ### A2. 分层调度
 
 ```
 for each 层 Li in L1..Ln:
-  准备：若 Li 内 N>1 则为每个 issue 创建独立 worktree——幂等清理同名 `wt/<feature>-#NN` 与 `.worktrees/<feature>-#NN` 后 `git worktree add .worktrees/<feature>-#NN -b wt/<feature>-#NN $BASE_HEAD`；N==1 时复用主 worktree，不创建。
-  并行派发：为 Li 中每个 issue 启动一个子代理（single 模式，cwd 为对应 worktree，禁止 parallel tasks 数组）
+  并行派发：为 Li 中每个 issue 启动一个子代理（single 模式，共享 working tree，禁止 parallel tasks 数组；N>1 时串行错峰派发）
   等待：阻塞直到 Li 全部子代理返回回执卡片
-  验收：编排器按 A3 验收清单逐 issue 验收（只认回执卡片的关键信息 + 抽检验证在对应 worktree/归集后主分支上执行，不消费全量日志）
-  归集：若 N>1 按编号升序在主分支上 `git merge --no-ff wt/<feature>-#NN` 顺序归集各分支；N==1 时归集即该分支已在主分支。归集冲突按 A5 仅打回冲突单 issue
-  层收敛验证：验收全通过进入全量验证（完成条件 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 重建全新 worktree 最小重派该 issue
-  清理：该层归集后幂等清理该层 worktree（`git worktree remove -f .worktrees/<feature>-#NN && git branch -D wt/<feature>-#NN && git worktree prune`），失败 issue 的 worktree 保留至重派时以失败分支为增量基础重建
+  验收：编排器按 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 最小重派处理；已通过者的归集先行，不阻塞归集。
-- **Worktree 隔离**：层内 `N>1` 时文件系统级隔离，后完成者不再覆盖先完成者工作区；`N==1` 退化为共享 worktree 以省成本。worktree 路径 `.worktrees/<feature>-#NN` 不纳入 `git status`，分支 `wt/<feature>-#NN` 与 worktree 一一对应。
+- **等待语义**：层内任一子代理失败不取消同层其他子代理；待层内全部返回后统一按 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` 等（需显式确认）。归集后主分支 `git log --oneline` 含全部层已通过 issue 的 `#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 执行单元**，输入与产出严格界定：
@@ -69,8 +65,7 @@ for each 层 Li in L1..Ln:
   - `spec.md`（feature 级共享 spec，若无则以该 issue 正文为准）
   - 分配的单个 `NN-<slug>.md`（唯一 issue 输入）
   - `CONTEXT.md` + `docs/adr/`（术语与决策一致性）
-  - （worktree 隔离时）分配的独立 worktree 路径 `.worktrees/<feature>-#NN` 与分支 `wt/<feature>-#NN`，`cwd` 为该 worktree
-- **执行**：严格走 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) 为唯一事实源，不在子代理内重写。worktree 下在独立分支上执行，入口记录 `WT_BASE_HEAD=$(git rev-parse HEAD)` 并自检 `merge-base --is-ancestor`，`N==1` 时复用主 worktree。
+- **执行**：严格走 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` + 底部 `## 实施总结`
@@ -107,7 +102,7 @@ for each 层 Li in L1..Ln:
 
 任一项不通过 → 打回重派该子代理（仅该 issue），层内其他已通过不受影响；验收通过才计入层收敛。验收结论随层收敛一并输出。
 
-子代理内部的回合连续性、任务分解、Todo 规定、Git 历史保护与单线模式完全一致（见 [stages.md 阶段③ 3e/3f/3h](stages.md#阶段-③tdd-开发循环) 与 Git 安全前置）。子代理同样在入口记录 `BASE_HEAD`（worktree 下为 `WT_BASE_HEAD`）并在每阶段出口校验 `git merge-base --is-ancestor $BASE_HEAD HEAD`，禁止 `git reset --hard`/`git checkout .`/`git clean -fd`/`git stash push --include-untracked` 等；worktree 入口幂等清理同名残留。
+子代理内部的回合连续性、任务分解、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. 全量收敛
 
@@ -121,9 +116,9 @@ for each 层 Li in L1..Ln:
 ### 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`，编排器在层等待结束后报告失败清单，已通过者先归集到主分支（按编号升序顺序 merge），不自动进入下一层；待修复后仅重派失败节点（重建全新 worktree，不复用旧目录；worktree 下以失败分支 `wt/<feature>-#NN` 为增量基础叠加最小 fix，仅当 `merge 冲突` 导致分叉时以主分支最新重建并 cherry-pick 已通过部分），同层其他已通过不受影响。层原子语义保持：`Li` 未全 `resolved` 不派 `L_{i+1}`，但已通过者的归集先行以减二次冲突。
+- **层收敛失败（最小重派）**：层内任一子代理未达到 `resolved`（含验收 5 项、相关测试、卫生、历史校验任一不过）→ 该 issue 保持原 `Status`，编排器在层等待结束后报告失败清单，不自动进入下一层；待修复后仅重派失败节点，同层其他已通过不受影响。层原子语义保持：`Li` 未全 `resolved` 不派 `L_{i+1}`。
 - **全量收敛失败（精确定位）**：A4 全量测试失败 → 以测试文件路径/报错栈精确定位到单 issue 单 seam，回到其所在层仅重派该 issue 的失败 seam + 相关测试，全量由编排器在重派后再次 A4 统一验证；无法精确定位时退化到层级重派，不重跑无关联 issue。
-- **文件冲突（显式化）**：worktree 隔离下冲突在归集 `merge` 时显式暴露（不再以共享 worktree 的“后完成者 rebase 覆盖”形式静默重跑），仅打回冲突归属的单 issue；跨层天然串行无冲突。冲突解决禁止使用 `git reset --hard`/`git checkout .`/`git clean -fd`/`git stash push --include-untracked` 丢弃对方提交，解决后必校验 `git merge-base --is-ancestor $BASE_HEAD HEAD` 且 `git log --oneline` 含全部层提交；冲突检测以 `git` 合并结果为准，编排器不做静态预判。
+- **文件冲突（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 检测到环即报错终止，不派发任何子代理。
 
 ### 出口条件
@@ -134,8 +129,8 @@ for each 层 Li in L1..Ln:
 
 ### 边界
 
-- 单 issue / 单 spec 不走本文件
-- 子代理不跨 issue 改动；编排器不替子代理写实现代码
+- 单 issue / 单 spec 不走本文件；但一旦进入编排模式（多 issue 且含 Blocked by），无论 N==1 还是 N>1，所有 issue 的 ①→⑦ 必须经子代理 single 派发完成，禁止主会话直做（编排器仅编排、验收、归集、清理）
+- 子代理不跨 issue 改动；编排器不替子代理写实现代码；主会话不直接写业务代码/测试/文档（仅做编排与验收）
 - 汇总总结只在对话输出，不落盘额外汇总文件
 - 必须先编排子代理计划（输出依赖图/DAG/Kahn 分层 `L1..Ln` 并确认）后才派子代理，禁止跳过计划直接派发导致重复调度
 - TDD 语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，不在本文件重写

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heihei0299/matt-skills",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "description": "Agent skills + 项目配置模板：一条命令初始化 opencode / pi-agent 项目（含 mattpocock/skills 上游技能）",
   "type": "module",
   "bin": {

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

@@ -16,7 +16,7 @@ description: "TDD seam red-green loop: use when the user provides a spec/ticket
 
 ## 多 issue 编排（按依赖分层并行）
 
-触发见 [orchestration.md](references/orchestration.md)；`.scratch/<feature>/issues/` 下多文件且部分含 `Blocked by` 时触发，主过程 A0 依赖图 → A1 Kahn 分层 L1入度0→L2→Ln → A2 分层调度（层内 `N>1` 时每 issue 独立 `git worktree` + `wt/<feature>-#NN` 分支隔离、按序 `merge --no-ff` 归集，`N==1` 退化共享） → A3 子代理契约 → A4 全量收敛 → A5 回退与冲突（最小重派：按失败点精确回退、失败分支增量 fix、精确定位单 issue 单 seam，全量保留为详规真相源）。必须先编排子代理计划（输出依赖图/DAG 与 Kahn 分层 `L1..Ln` 并确认）后才派发，禁止跳过计划直接派发导致重复调度；层收敛 4 项（验收/相关测试/`git status`仅删`[DEBUG-...]`/ `BASE_HEAD`历史校验 `git merge-base --is-ancestor`）与子代理回执卡片（≤30行、缺字段视为不通过）、打回重派（重建全新 worktree 最小 fix）、merge 冲突显式化等可执行约束全量见 orchestration.md。
+触发见 [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。
 
 ## Steps
 

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

@@ -38,27 +38,23 @@ Ln = 最后一层
 ```
 
 每层内节点互无依赖，可并行；层间有依赖，必须串行。分层结果在编排开始前一次性展示给用户确认（合规交互点），确认后才派发。
-
+若两 issue 在阶段②已声明预期改动同一文件，编排器在 A0 后提示建议追加 `Blocked by` 使其串行（轻提示，不强制）；主要仍靠 A2 串行错峰自然错峰。
 ### A2. 分层调度
 
 ```
 for each 层 Li in L1..Ln:
-  准备：若 Li 内 N>1 则为每个 issue 创建独立 worktree——幂等清理同名 `wt/<feature>-#NN` 与 `.worktrees/<feature>-#NN` 后 `git worktree add .worktrees/<feature>-#NN -b wt/<feature>-#NN $BASE_HEAD`；N==1 时复用主 worktree，不创建。
-  并行派发：为 Li 中每个 issue 启动一个子代理（single 模式，cwd 为对应 worktree，禁止 parallel tasks 数组）
+  并行派发：为 Li 中每个 issue 启动一个子代理（single 模式，共享 working tree，禁止 parallel tasks 数组；N>1 时串行错峰派发）
   等待：阻塞直到 Li 全部子代理返回回执卡片
-  验收：编排器按 A3 验收清单逐 issue 验收（只认回执卡片的关键信息 + 抽检验证在对应 worktree/归集后主分支上执行，不消费全量日志）
-  归集：若 N>1 按编号升序在主分支上 `git merge --no-ff wt/<feature>-#NN` 顺序归集各分支；N==1 时归集即该分支已在主分支。归集冲突按 A5 仅打回冲突单 issue
-  层收敛验证：验收全通过进入全量验证（完成条件 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 重建全新 worktree 最小重派该 issue
-  清理：该层归集后幂等清理该层 worktree（`git worktree remove -f .worktrees/<feature>-#NN && git branch -D wt/<feature>-#NN && git worktree prune`），失败 issue 的 worktree 保留至重派时以失败分支为增量基础重建
+  验收：编排器按 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 最小重派处理；已通过者的归集先行，不阻塞归集。
-- **Worktree 隔离**：层内 `N>1` 时文件系统级隔离，后完成者不再覆盖先完成者工作区；`N==1` 退化为共享 worktree 以省成本。worktree 路径 `.worktrees/<feature>-#NN` 不纳入 `git status`，分支 `wt/<feature>-#NN` 与 worktree 一一对应。
+- **等待语义**：层内任一子代理失败不取消同层其他子代理；待层内全部返回后统一按 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` 等（需显式确认）。归集后主分支 `git log --oneline` 含全部层已通过 issue 的 `#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 执行单元**，输入与产出严格界定：
@@ -69,8 +65,7 @@ for each 层 Li in L1..Ln:
   - `spec.md`（feature 级共享 spec，若无则以该 issue 正文为准）
   - 分配的单个 `NN-<slug>.md`（唯一 issue 输入）
   - `CONTEXT.md` + `docs/adr/`（术语与决策一致性）
-  - （worktree 隔离时）分配的独立 worktree 路径 `.worktrees/<feature>-#NN` 与分支 `wt/<feature>-#NN`，`cwd` 为该 worktree
-- **执行**：严格走 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) 为唯一事实源，不在子代理内重写。worktree 下在独立分支上执行，入口记录 `WT_BASE_HEAD=$(git rev-parse HEAD)` 并自检 `merge-base --is-ancestor`，`N==1` 时复用主 worktree。
+- **执行**：严格走 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` + 底部 `## 实施总结`
@@ -107,7 +102,7 @@ for each 层 Li in L1..Ln:
 
 任一项不通过 → 打回重派该子代理（仅该 issue），层内其他已通过不受影响；验收通过才计入层收敛。验收结论随层收敛一并输出。
 
-子代理内部的回合连续性、任务分解、Todo 规定、Git 历史保护与单线模式完全一致（见 [stages.md 阶段③ 3e/3f/3h](stages.md#阶段-③tdd-开发循环) 与 Git 安全前置）。子代理同样在入口记录 `BASE_HEAD`（worktree 下为 `WT_BASE_HEAD`）并在每阶段出口校验 `git merge-base --is-ancestor $BASE_HEAD HEAD`，禁止 `git reset --hard`/`git checkout .`/`git clean -fd`/`git stash push --include-untracked` 等；worktree 入口幂等清理同名残留。
+子代理内部的回合连续性、任务分解、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. 全量收敛
 
@@ -121,9 +116,9 @@ for each 层 Li in L1..Ln:
 ### 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`，编排器在层等待结束后报告失败清单，已通过者先归集到主分支（按编号升序顺序 merge），不自动进入下一层；待修复后仅重派失败节点（重建全新 worktree，不复用旧目录；worktree 下以失败分支 `wt/<feature>-#NN` 为增量基础叠加最小 fix，仅当 `merge 冲突` 导致分叉时以主分支最新重建并 cherry-pick 已通过部分），同层其他已通过不受影响。层原子语义保持：`Li` 未全 `resolved` 不派 `L_{i+1}`，但已通过者的归集先行以减二次冲突。
+- **层收敛失败（最小重派）**：层内任一子代理未达到 `resolved`（含验收 5 项、相关测试、卫生、历史校验任一不过）→ 该 issue 保持原 `Status`，编排器在层等待结束后报告失败清单，不自动进入下一层；待修复后仅重派失败节点，同层其他已通过不受影响。层原子语义保持：`Li` 未全 `resolved` 不派 `L_{i+1}`。
 - **全量收敛失败（精确定位）**：A4 全量测试失败 → 以测试文件路径/报错栈精确定位到单 issue 单 seam，回到其所在层仅重派该 issue 的失败 seam + 相关测试，全量由编排器在重派后再次 A4 统一验证；无法精确定位时退化到层级重派，不重跑无关联 issue。
-- **文件冲突（显式化）**：worktree 隔离下冲突在归集 `merge` 时显式暴露（不再以共享 worktree 的“后完成者 rebase 覆盖”形式静默重跑），仅打回冲突归属的单 issue；跨层天然串行无冲突。冲突解决禁止使用 `git reset --hard`/`git checkout .`/`git clean -fd`/`git stash push --include-untracked` 丢弃对方提交，解决后必校验 `git merge-base --is-ancestor $BASE_HEAD HEAD` 且 `git log --oneline` 含全部层提交；冲突检测以 `git` 合并结果为准，编排器不做静态预判。
+- **文件冲突（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 检测到环即报错终止，不派发任何子代理。
 
 ### 出口条件
@@ -134,8 +129,8 @@ for each 层 Li in L1..Ln:
 
 ### 边界
 
-- 单 issue / 单 spec 不走本文件
-- 子代理不跨 issue 改动；编排器不替子代理写实现代码
+- 单 issue / 单 spec 不走本文件；但一旦进入编排模式（多 issue 且含 Blocked by），无论 N==1 还是 N>1，所有 issue 的 ①→⑦ 必须经子代理 single 派发完成，禁止主会话直做（编排器仅编排、验收、归集、清理）
+- 子代理不跨 issue 改动；编排器不替子代理写实现代码；主会话不直接写业务代码/测试/文档（仅做编排与验收）
 - 汇总总结只在对话输出，不落盘额外汇总文件
 - 必须先编排子代理计划（输出依赖图/DAG/Kahn 分层 `L1..Ln` 并确认）后才派子代理，禁止跳过计划直接派发导致重复调度
 - TDD 语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，不在本文件重写

package/template/AGENTS.md

@@ -15,7 +15,7 @@
 
 1. 读 `CONTEXT.md`（术语）——没有则跳过
 2. 按行为路由表行动；未命中用 ask-matt 或直接澄清
-3. 探索代码库：优先 codegraph CLI（`codegraph explore`），无索引时派 explore 子代理
+3. 探索代码库：直接使用 `codegraph explore`（`codegrafh CLI`）；若无 `.codegraph/` 索引先执行 `codegraph init` 初始化，再 `explore`
 
 ## 执行原则
 
@@ -30,7 +30,7 @@
 
 命中即行动，回复中简短声明所用技能与原因。
 
-- 探索/定位/理解代码库 → 有 `.codegraph/` 索引：`codegraph explore`（CLI）优先；无索引用 explore 子代理
+- 探索/定位/理解代码库 → 直接使用 `codegraph explore`（`codegrafh CLI`）；若无 `.codegraph/` 索引先 `codegraph init` 初始化，再 `explore`（Q1 硬判定，Q2 意图文+文件锚点，Q3 仅完整源码免读，Q4 跨仓才传 projectPath，Q5 研调链用 research 另行触发）
 - 后台调研 → research；原型验证 → prototype
 - 实现（有 spec 且要求 TDD/测试先行）→ tdd-implement（seam red-green）；实现（有 spec 不要求 TDD）→ implement（无 spec 先 to-spec）；测试先行 → tdd
 - 设计打磨 → grilling；达成共识→spec → grill-to-spec（grilling→domain-modeling→to-spec）
@@ -49,8 +49,10 @@
 
 ## CodeGraph
 
-仓库被 CodeGraph 索引（根目录存在 `.codegraph/`）时，理解/定位代码**优先于** grep/find/读文件——一次调用拿到相关符号源码与调用路径：
+理解/定位代码**必须**使用 `codegrafh CLI`，直接优于 grep/find/读文件——一次调用拿到相关符号逐字源码与调用路径：
 
-- **CLI**：`codegraph explore "<符号名或问题>"` 一次回答大部分代码问题——相关符号的逐字源码 + 调用路径（含 grep 追不上的动态分派跳转）。在 query 中指名文件/符号即可读取其带行号的当前源码。
-
-没有 `.codegraph/` 目录则完全跳过 CodeGraph——是否建立索引由用户决定。
+- **CLI**：`codegraph explore "<符号名或问题>"` 一次回答大部分代码问题——相关符号的逐字源码 + 调用路径（含 grep 追不上的动态分派跳转）。在 query 中指名文件/符号即可读取其带行号的当前源码，默认 `maxFiles: 12` 覆盖跨 5-8 文件调用链。
+- **初始化**：若根目录无 `.codegraph/`，先执行 `codegraph init` 初始化索引，再 `explore`；已有索引直接 `explore`（硬判定，不回退 explore 子代理）。
+- **已读等价**：返回体含完整源码块的文件视为已 `Read`，不再重复 `read`；仅返回调用路径片段时补一次带行号 `read`。
+- **跨仓/子项目**：仅当探索第二代码库或 monorepo 子项目（根无索引但子目录有）时显式传 `projectPath`。
+与 `research`（后台调研产出 Markdown 文件）分工：`codegraph explore` 为代码定位唯一首选，`research` 仅用于需产出调研文档的后台任务。