@heihei0299/matt-skills 1.6.4-test.0 → 2.0.0

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

@@ -1,63 +1,95 @@
 ---
 name: commit-check
-description: "Run the pre-commit gate before any commit: verify docs match the implementation, align README, keep the directory clean, and write a clear commit message. Use whenever the user is about to commit or asks to check anything about the commit — e.g. verifying docs/README are in sync, cleaning up temp files, scanning for secrets/keys/.env in the change, or having you write the commit message. Not for general PR/code review (that's code-review), and not for explaining git/commit conventions (that's a teach task)."
+description: "检查 matt-skills 当前 staged commit 的范围、敏感信息和 commit message，并按改动路径执行对应同步检查。"
+disable-model-invocation: true
 ---
 
 # Commit Check
 
-提交前的**门禁检查**：文档一致性 → 保持目录卫生 → 规范 commit message，三项全过才允许 commit。本技能是轻量检查清单，不重写 code-review 的审查语义（[code-review](.agents/skills/code-review/SKILL.md) 是唯一事实源），也不替代任何完整实现流程——它是任何 commit 前的通用门禁，无论改动来自哪个流程。
+用户显式调用 `/commit-check` 后运行本技能。它是提交前的 staged commit gate：检查将要提交的内容是否属于当前逻辑变更、是否包含敏感信息、以及 commit message 是否可追溯。
 
-## 三项检查（全部通过才 commit）
+本技能只检查，不负责 staging，不执行 `git commit`，也不要求整个工作区干净。通过后报告 `ready to commit`，由调用方执行提交。
 
-### ① 文档一致性
-> 覆盖原 ① 审查文档 的全部检查项与原 ② 对齐 README 的全部检查项
+## 三项核心 gate
 
-- 本次改动涉及的行为/接口/配置/命令是否有对应文档（README、`docs/`、技能正文）描述
-- 文档描述与实现一致：无过期信息、无声称未实现的功能、无遗留的旧接口描述
-- 发现不一致 → 先修文档（或更新实现），再进入下一步
-- 改动涉及项目结构、分发文件、技能/命令清单时，检查 README 中对应的结构说明、映射表、清单是否同步
-- 改动涉及用法/CLI/配置/示例时，检查 README 对应描述与实际一致
-- **重点聚焦（README + matt-skills 流程）**：本次门禁优先对齐 `README.md` 与 matt-skills 流程相关文件——`AGENTS.md`（路由）、`CONTEXT.md`（术语）、`docs/agents/*`（`skill-design.md`/`runtime-discipline.md`/`issue-tracker.md`/`triage-labels.md`/`domain.md`）、`template/` 镜像（含 `.agents/skills` 全量、`AGENTS.md`、`CONTEXT.md`、`docs/agents`）、`.agents/skills/*`（技能正文与 `references/`）、`config/*` 与 `scripts/build-template.js`；改动触及上述任一文件时，逐项核对 README 的结构说明/清单/映射表与模板镜像是否同步，未同步先修复再 commit
-- 存在模板镜像/分发副本时，确认源文件与副本同步（如有守护测试，跑一遍确认）
-- **特例**：`AGENTS.md` 的 `tdd-implement ↔ implement` 路由行 + 技能文件 + `.gitignore` 的 `.pi/` 忽略，且存在 `AGENTS.md.bak` 时，视为模板同步预期增量，不回滚
-### ② 保持目录卫生
+### ① Staged scope
 
-- `git status` 确认工作区只含预期改动：无残留未跟踪文件、无临时产物（调试脚本、日志、备份文件、`[DEBUG-...]` 残留）
-- 无关文件（一次性脚本、转储、探针、调试日志）直接追加至 `.gitignore`，不执行删除；仅对本次产生的 `[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` 无输出）
+- 读取 `git diff --cached --name-status` 和 `git diff --cached`。
+- staged diff 必须非空，并且只包含当前用户请求的逻辑变更。
+- 列出 staged 文件和关键 diff，无法确认范围时报告疑点并阻塞。
+- 调用方负责 `git add`；本技能不自动 stage、unstage 或清理文件。
+- 工作区可以保留其它未暂存修改；不以 `git status` 全干净作为出口条件。
 
-### ③ 规范 commit message
+### ② Sensitive scan
 
-- 格式遵循仓库约定（常见：`<type>(<scope>): <subject>`，type 用 feat/fix/docs/chore/refactor/test）
-> 模板：`feat(<scope>): <subject>` / `fix(<scope>): <subject>` — 例 `feat(tdd): add seam login`，`fix(ci): gate publish on verify`
-- subject 描述变更内容而非过程（不说"我做了什么"，说"改成了什么"）
-- 需要时补充 body：动机、影响范围、验收证据（测试结果、同步确认）
-- 一次 commit 只含一个逻辑变更；多主题拆多个 commit
+运行确定性扫描脚本，不手写 grep：
 
-## 不做什么
+```bash
+bash .agents/skills/commit-check/scripts/scan-sensitive.sh --staged-only
+```
 
-- 不做全量 code review：审查语义以 [code-review](.agents/skills/code-review/SKILL.md) 为唯一事实源，本技能不重写
-- 不替代实现流程的收尾：`tdd-implement` 阶段⑦已含文档对齐与目录卫生，本技能只管独立 commit 的门禁
-- 不发明扫描规则：敏感信息检测跑 `scripts/scan-sensitive.sh`，不每次重写 grep 模式
+- 结构化 secret assignment 和 private key block → **fail**。
+- 普通 `api_key`、`secret`、`token`、`password`、`.env` 等关键词 → **warning**，由调用方人工确认。
+- 扫描只针对 staged diff；不因未暂存内容阻塞本次 commit。
 
-## 执行顺序（回合内串行）
+### ③ Commit message
 
-1. 跑 ① 文档一致性 → ② 保持目录卫生 → ③ 写 commit message
-2. 任一项发现问题：修复后重跑该项，全部通过才 commit
-3. commit 后确认 `git status` 干净，工作结束
+- 使用 `<type>(<scope>): <subject>` 基本格式；`type` 使用 `feat`、`fix`、`docs`、`chore`、`refactor`、`test` 等仓库约定值。
+- subject 描述变更结果，不描述操作过程。
+- body 可选；只有确实需要时补充动机、影响范围或验收证据。
+- 一个 commit 只表达一个逻辑变更；多主题拆分提交。
+- 本技能检查并给出 message 结论，但不代替调用方执行 commit。
 
-**回合连续性**：三项检查在一个回合内串行完成，不等用户"继续"；发现问题立即修复并重查，直到三项全过或遇到外部阻塞（权限/授权缺失）。
+## matt-skills 路径适配
 
-## 出口条件
+以下 staged 路径触发 matt-skills 专属检查；普通源码或测试 commit 不触发这些额外检查：
 
-- [ ] 文档一致性（文档与 README 均已对齐）
-- [ ] 目录卫生（`git status` 干净，无临时产物/敏感信息）
-- [ ] commit message 规范（遵循仓库格式）
-- 三项全过 → commit
+```text
+README.md
+AGENTS.md
+CONTEXT.md
+docs/agents/**
+template/**
+.agents/skills/**
+config/**
+scripts/build-template.js
+.opencode/commands/**
+.pi/prompts/**
+```
 
-## 引用
+相关路径变更时：
 
-- 代码审查语义：[code-review](.agents/skills/code-review/SKILL.md)（唯一事实源，本技能不重写）
-- 完整实现流程：[tdd-implement](.agents/skills/tdd-implement/SKILL.md)（含流程内收尾的文档对齐与目录卫生）
+- README、公开行为、命令、配置或流程描述变化 → 检查对应文档与实现一致；
+- `AGENTS.md`、`CONTEXT.md`、`docs/agents/`、`template/`、技能或镜像变化 → 运行相关模板/契约测试，至少覆盖 `test/template-sync.test.js`；
+- `commit-check` 自身变化 → 运行 `test/commit-check.test.js` 和 `test/commit-check-scan.test.js`；
+- `tdd-implement` 变化 → 运行 `test/tdd-implement-stages.test.js`；
+- `config/`、构建脚本、opencode command 或 pi prompt 变化 → 运行对应 CLI、模板或命令测试；
+- 只检查本次 staged 路径相关的内容，不通读全部 README、docs 或模板。
+
+这些是 matt-skills 的条件化仓库检查，不改变上面的三项核心 gate。
+
+## Git history pointer
+
+遵循 `CONTEXT.md` 和 `docs/agents/` 中的 Git History Preservation 规则。本技能只在当前会话存在 `BASE_HEAD` 时执行必要祖先校验：
+
+```bash
+git merge-base --is-ancestor "$BASE_HEAD" HEAD
+```
+
+完整的禁止命令、恢复和 stash 规则只在仓库级文档维护，不在本技能重复展开。
+
+## 执行顺序与出口
+
+1. 检查 staged scope，确认 staged diff 非空且属于当前逻辑变更。
+2. 执行 `scan-sensitive.sh --staged-only`。
+3. 检查 commit message。
+4. 根据 staged 路径执行必要的 matt-skills 条件化检查。
+5. 输出 staged 文件、三项 gate 结果、warning、条件化检查结果和 `ready to commit` 或具体阻塞项。
+
+发现阻塞项时停止并报告；不自动修复、不自动 stage、不自动 commit。
+
+## 不负责的内容
+
+- 不做完整代码审查；审查语义由对应审查流程负责。
+- 不执行测试先行、typecheck、build、真实运行或 tracker 收尾；这些属于对应实现流程。
+- 不成为任何实现流程的自动子步骤；仅按 staged 路径提供本仓库提交 gate。

package/.agents/skills/commit-check/scripts/scan-sensitive.sh

@@ -1,36 +1,29 @@
 #!/usr/bin/env bash
-# Deterministic secret scan for commit-check check ③.
-# The grep patterns are fragile to freehand — run this instead of re-writing
-# the scan every time. Two confidence tiers:
-#   FAIL  — structured secrets (KEY=value assignments, private key blocks)
-#   WARN  — bare keywords (may legitimately appear in docs that mention them)
-# Checks the staged diff (fail) and, unless --staged-only is passed, reports
-# matches in the unstaged diff (warn).
-#
-# Usage:
-#   scripts/scan-sensitive.sh            # staged (fail) + unstaged (warn)
-#   scripts/scan-sensitive.sh --staged-only
+# Deterministic staged-diff secret scan for commit-check.
+# FAIL: structured assignments and private-key blocks.
+# WARN: bare keywords that may legitimately appear in documentation.
 set -euo pipefail
 
+if [[ $# -gt 1 || ( $# -eq 1 && "$1" != "--staged-only" ) ]]; then
+  echo "usage: $0 [--staged-only]" >&2
+  exit 2
+fi
+
 fail_patterns='(api[_-]?key|secret|token|passwd|password)[[:space:]]*[=:][[:space:]]*[^[:space:]]{8,}|BEGIN (RSA|OPENSSH|EC|DSA) PRIVATE KEY'
 warn_patterns='(api[_-]?key|secret|token|passwd|password|\.env)'
 
+staged_diff=$(git diff --cached -U0)
 fail=0
 
-if git diff --cached -U0 | grep -inE "$fail_patterns"; then
+if grep -inE "$fail_patterns" <<< "$staged_diff"; then
   echo "❌ Structured secrets found in STAGED diff — remove them before committing." >&2
   fail=1
 else
   echo "✅ No structured secrets in staged diff."
-  if git diff --cached -U0 | grep -inE "$warn_patterns"; then
-    echo "⚠  Keyword matches in STAGED diff — eyeball whether they are real secrets." >&2
-  fi
 fi
 
-if [[ "${1:-}" != "--staged-only" ]]; then
-  if git diff -U0 | grep -inE "$fail_patterns"; then
-    echo "⚠  Structured-secret matches in UNSTAGED diff — decide whether they belong in the commit." >&2
-  fi
+if grep -inE "$warn_patterns" <<< "$staged_diff"; then
+  echo "⚠  Keyword matches in STAGED diff — eyeball whether they are real secrets." >&2
 fi
 
 exit "$fail"

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

@@ -1,48 +1,45 @@
 ---
 name: tdd-implement
-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."
+description: "完成已确认的 spec/ticket 的 test-first/TDD 交付闭环。"
+disable-model-invocation: true
 ---
 
 # 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)；本技能只编排阶段与运行时规则。
+`seam` + `red-green` 是本技能的领衔词。它把一个 spec 或 task issue 编排成四个交付阶段；TDD 的红-绿语义、测试质量和 mock 边界以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，本技能只定义交付编排。
 
-本技能是**长程任务**（Long-Horizon Skill）：多阶段串行执行，自带**回合连续性**（Turn Continuity）与**任务分解**（Chunking）规则。术语定义见 `CONTEXT.md`，技能设计规则见 `docs/agents/skill-design.md`。
+本技能是 **Long-Horizon Skill**：阶段按顺序连续执行，并自带 **Turn Continuity** 与 **Chunking**。术语见 `CONTEXT.md`，技能设计规则见 `docs/agents/skill-design.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 编排（按依赖串行，主代理直接执行）
+- **单 issue**：单个 `.scratch/<feature>/spec.md`、等价 spec 或 `Type: task` issue，按下方四个 Steps 完成一个交付闭环。
+- **多 issue**：`.scratch/<feature>/issues/` 下存在多个 `Type: task` 文件时，先读取 [orchestration.md](references/orchestration.md)，按 `Blocked by` 构建 DAG、Kahn 分层，再由主代理按层串行完成各 issue。
+- `Type: research`、`prototype`、`grilling` 分流到对应技能，不进入本技能。
 
-触发见 [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
+多 issue 的 A0-A5 是编排控制活动，不是额外的产品交付阶段：依赖图、分层、串行调度、层收敛、全量收敛和回退/冲突处理的详规只在 [orchestration.md](references/orchestration.md) 中维护。
 
-按序执行，每步达到完成条件才进入下一步；进入任一步前先读取其在 [stages.md](references/stages.md) 的定义。
+## 四阶段 Steps
 
-| 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) 中对应定义。
 
-主代理串行时每 `task` 仍走上表 ①→⑦（每 issue 单独 `commit`，`code-review` + `commit-check` 双门禁逐 issue，全量由 A4 收敛）。
+| Step | 做什么 | 出口条件 |
+|---|---|---|
+| ① **Contract** | 读取入口，提取 Acceptance Criteria，建立 Scope Ledger、Preflight、验证矩阵和 Behavior/Seam 边界 | 需求无待决歧义，验证命令已确定；知道做什么、从哪里验证、什么不做 |
+| ② **Red-Green** | 以 Behavior 为粒度执行有效 Red → 最小 Green → formatter/typecheck → 最小相关测试 | 所有 Behaviors 均有有效 Red、实现全绿，formatter/typecheck 和最小相关测试通过 |
+| ③ **Verify** | 运行当前 issue 影响范围测试、必要 build、要求的真实运行验证；执行一次 Standards + Spec Review | 最终 diff 的相关证据通过，真实运行验证完成（如要求），无 blocking finding |
+| ④ **Deliver** | 对齐 docs/README，执行敏感信息扫描，检查 staged diff、commit message 和必要的 Git history，创建独立 commit，更新 issue/progress.md | commit 已创建，Acceptance Criteria 全部通过，Tracker 与工作区反映真实完成状态 |
 
-### 阶段间流转
+## 运行时纪律
 
-- 正常流转：出口条件满足即进入下一阶段，不在阶段间停顿。
-- 回退路由：见 [stages.md#回退路由](references/stages.md#回退路由)；编排模式回退见 [orchestration.md](references/orchestration.md)。
-- 回合连续性与任务分解：见 [stages.md ③-3e/3f](references/stages.md#阶段-③tdd-开发循环)（红→绿→typecheck→下一 seam 一个回合内串行完成，直至阶段出口；预告下一步后立即执行；write>150 行/replace>5 处拆小步）。
+- 四个阶段都从入口连续执行到自身出口：预告下一步后立即执行；进度输出并入工具调用序列，输出后继续执行。只有合规交互点、明确的外部阻塞或阶段出口条件结束当前回合。
+- 一个 seam 是公共可观察边界；一个 Behavior 是一个红-绿 cycle；一个 seam 可以包含多个 Behaviors。Seam/Behavior 的细节和 Todo 粒度见 [stages.md](references/stages.md)。
+- 当前 issue 的范围、Acceptance Criteria、Out of Scope、测试/typecheck/build/真实运行证据和最终 commit 必须可追溯。Seam 或专项测试绿色不代表 issue 完成；四阶段出口全部满足后才可标记 `resolved`。
+- 多 issue 模式中，每个 issue 只提交一个独立 commit；issue 影响范围测试在 Step ③ 执行，全仓测试由 orchestration 的 A4 在全部 issue 完成后执行一次。
 
 ## 引用
 
 - 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)（A0-A1 排序 + 主代理串行，不含子代理）
+- 四阶段详规：[stages.md](references/stages.md)
+- 多 issue 编排：[orchestration.md](references/orchestration.md)

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

@@ -1,89 +1,166 @@
-# 多 issue 编排（按依赖串行，主代理直接执行）
+# 多 issue 编排（按依赖分层串行）
 
-本文件仅在多 `task` 编排时生效；单 `spec` / 单 `task` 走 [stages.md](stages.md) 单线 ①→⑦，主代理直接执行完整流程并单独提交，不经子代理。
+本文件仅在 `.scratch/<feature>/issues/` 下存在多个 `Type: task` issue 时生效。单 `spec` / 单 `task` 直接按 [stages.md](stages.md) 的四阶段闭环执行。A0-A5 是编排控制活动，不是额外的产品交付阶段。
 
-多 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` 分层。
+主代理按依赖分层、层内按编号串行执行；每个 issue 由同一个主代理完成 Contract → Red-Green → Verify → Deliver，并创建一个独立 commit。实现细节以 [stages.md](stages.md) 为准，TDD 语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为准。
 
 ## 目录
 
-- [A0. 依赖图构建](#a0-依赖图构建)
-- [A1. 拓扑分层](#a1-拓扑分层)
-- [A2. 主代理串行调度](#a2-主代理串行调度)
-- [A3. 层收敛](#a3-层收敛)
-- [A4. 全量收敛](#a4-全量收敛)
-- [出口条件](#出口条件)
-- [边界](#边界)
+- [A0：依赖图与编排 Preflight](#a0依赖图与编排-preflight)
+- [A1：Kahn 拓扑分层](#a1kahn-拓扑分层)
+- [A2：分层串行调度](#a2分层串行调度)
+- [A3：层收敛](#a3层收敛)
+- [A4：全量收敛](#a4全量收敛)
+- [A5：回退与冲突处理](#a5回退与冲突处理)
 
 ---
 
-### A0. 依赖图构建
+## A0：依赖图与编排 Preflight
 
-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/` 供一致性校验。
-4. **强制初始化 `progress.md`**：在 `.scratch/<feature>/progress.md` 落 `## DAG` + `## Layers (Kahn L1..Ln)` + `## Progress` 空表（`| NN | Status | Commit | Review | Tests |`），作为编排态唯一派生视图（真相源仍为 `spec` + `issues/*.md`）。
-### A1. 拓扑分层
+1. 扫描 `.scratch/<feature>/issues/` 下全部 `NN-<slug>.md`，逐文件解析 `Blocked by`：
+   - `Blocked by: None`、`Blocked by: （无）` 或无此行：无依赖；
+   - `Blocked by: 01, 02` 或 `Blocked by: 01（…）`：依赖对应编号 issue；
+   - 无法解析：按无依赖处理，并在编排总结中记录告警。
+2. 以 issue 编号为节点、`Blocked by` 为有向边构建 DAG；检测到环时列出环上节点并停止调度。
+3. 读取共享 `spec.md`（若存在）、`CONTEXT.md` 和与本次改动有关的 ADR。
+4. 完成编排级 Preflight：记录当前 `HEAD`、工作区状态、`BASE_HEAD=$(git rev-parse HEAD)`、测试/typecheck/build 命令、真实运行路径和敏感信息扫描脚本可用性。后续只使用已经确认的命令和路径。
+5. 强制初始化 `.scratch/<feature>/progress.md`：
 
-对 DAG 做 Kahn 分层（BFS 拓扑）：
+   ```markdown
+   ## DAG
+   ## Layers (Kahn L1..Ln)
+   ## Progress
+   | NN | Status | Commit | Review | Tests |
+   |---|---|---|---|---|
+   ```
 
-```
-L1 = 全部入度为 0 的节点（可立即开始）
+   `progress.md` 是派生视图，真相源仍是 `spec.md` 与 `issues/*.md`。
+
+### A0 出口
+
+- DAG 已构建且无环；
+- 编排 Preflight 和 `BASE_HEAD` 已记录；
+- `progress.md` 已存在并可回写；
+- 依赖解析告警已记录。
+
+## A1：Kahn 拓扑分层
+
+对 DAG 做 Kahn 分层：
+
+```text
+L1 = 全部入度为 0 的节点
 L2 = 移除 L1 后入度为 0 的节点
-…
+...
 Ln = 最后一层
 ```
 
-每层内节点互无依赖（但仍串行执行，主代理一次一 issue）；层间有依赖，必须串行。分层结果在编排开始前一次性展示给用户确认（合规交互点），确认后才进入 A2。若两 issue 在阶段②已声明预期改动同一文件，建议追加 `Blocked by` 使其串行（轻提示，不强制）。
+每层内节点互无依赖，但仍由主代理按编号串行执行。层间必须串行。编排开始前一次性向用户展示 DAG 和 `L1..Ln`，得到确认后进入 A2；这是合规交互点，不把每个 seam 或每个 issue 的正常切换变成确认点。
 
-### A2. 分层调度（主代理串行）
+### A1 出口
 
-```
-for each 层 Li in L1..Ln:
+- Kahn 分层结果已展示并确认；
+- 每个 issue 都属于一个层；
+- 同文件预期冲突已记录，必要时已通过依赖顺序隔离。
+
+## A2：分层串行调度
+
+```text
+for each layer Li in L1..Ln:
   for each issue in Li（按编号顺序）:
-    主代理直接执行该 issue 的完整 ①→⑦：
-      ①理解需求 → ②确认 seams → ③红-绿循环（每 cycle 后 typecheck）→ ④相关测试 → ⑤code-review（双轴，逐 issue）→ ⑥commit-check + 单独 commit → ⑦收尾（Status: resolved + ## 实施总结 + map.md 指针如为 wayfinder 产物 + 目录卫生）
-    产回执卡片（改动文件/测试结果/commit hash）并回写该 issue 文件后**强制更新 `progress.md` 该行**（`Status`/`Commit`/`Review`/`Tests`）后再取下一 issue
-  层收敛：该层全部 issue `Status: resolved` 且 `progress.md` 同步为 `done`、各自独立 commit 已落盘、相关测试通过、`git status` 卫生、历史校验通过，才进下一层
-全部层串行完成后进入 A4
+    主代理执行四阶段：
+      ① Contract
+      ② Red-Green
+      ③ Verify（当前 issue 影响范围）
+      ④ Deliver（独立 commit + Tracker 收尾）
+    产出回执卡片并回写 issue
+    强制更新 progress.md 的 Status/Commit/Review/Tests
+  通过 A3 层收敛后进入下一层
+全部层完成后进入 A4
 ```
 
-- **回合连续性**：主代理在层内/层间不结束回合——一 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 产回执卡片并回写后再继续，防单回合截断。
+每个 issue 的 Verify 只运行当前 issue 影响范围内的完整测试；全仓测试不在每个 issue 中重复执行。每个 issue 只做一次正式 Standards + Spec Review；修复 blocking finding 后执行定向复核，不重新启动完整 review。
+
+主代理在层内和层间连续调度：一个 issue 的 Deliver 出口满足后，立即取下一个 issue，直到全部层完成或发生明确外部阻塞。进度输出并入执行序列，不在正常切换点等待用户“继续”。
+
+进入 A2 前记录的 `BASE_HEAD` 必须在每个 issue 的阶段出口和 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: Standards + Spec, 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 均完成四阶段并有独立 commit；
+- issue、回执卡片和 `progress.md` 一致；
+- 相关测试通过，工作区卫生和历史校验通过；
+- 没有未记录的跨 issue 改动。
+
+## A3：层收敛
+
+每层全部 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：全量收敛
+
+全部层完成且各层收敛通过后：
 
-### A3. 层收敛
+1. 按 A0 的验证矩阵运行一次仓库全量测试；这是多 issue 流程唯一的全量回归点。只有修复全量失败后才允许必要重跑；
+2. 执行 `git merge-base --is-ancestor $BASE_HEAD HEAD`；失败时按 A5 恢复后重验；
+3. 执行 `git status`，确认无 `[DEBUG-...]`、一次性脚本或未跟踪临时文件；
+4. 汇总各 issue 回执卡片的 commit、Behaviors、Acceptance Criteria、测试、真实运行和文档对齐结果；汇总只在对话输出，不另写汇总文件。
 
-每层全部 issue 串行完成后，主代理执行层收敛 4 项（全部通过才进下一层）：
-1. 该层全部 issue `Status: resolved` 且 `## 实施总结` 已落盘且 `progress.md` 同步为 `done`
-2. 相关测试通过（该层 issue 相关；全量仅在 A4）
-3. `git status` 卫生（仅删本次临时产物）
-4. 历史校验 `git merge-base --is-ancestor $BASE_HEAD HEAD` 通过
+### A4 出口
 
-任一失败定位到该层失败 issue，重做该 issue 的失败 seam/阶段后重检该层。
+- 全部 issue 已有独立 commit、实施总结和 `progress.md` 派生记录；
+- 全量测试通过；
+- 工作区卫生、历史校验和真实运行要求均满足；
+- `progress.md` 与 `issues/*.md` 一致，不一致时以 issue 真相源为准并修复派生视图。
 
-### A4. 全量收敛
+## A5：回退与冲突处理
 
-全部层串行完成且各自层收敛通过后，执行：
-1. **全量测试套件**：跑仓库完整测试套件（仅此一次全量）
-2. **历史校验**：`git merge-base --is-ancestor $BASE_HEAD HEAD`，失败即 `reflog` 恢复后重跑
-3. **目录卫生**：`git status` 无 `[DEBUG-...]` 残留、无未跟踪临时文件
-4. **汇总总结**：在会话输出汇总各 issue 的回执卡片关键信息（提交 hash / seams / 验收 checkbox / 测试结果 / 文档对齐）；不另写汇总文件
+A5 负责所有编排级失败，不把失败静默吞掉，也不把不相关问题塞入当前 issue：
 
-### 出口条件
+| 失败类别 | 处理 |
+|---|---|
+| Contract 歧义、验收缺口、范围变化 | 回到该 issue 的 Contract，补 Scope Ledger、Behavior 和验证矩阵 |
+| Red-Green 的有效 Red、实现、typecheck 或 targeted test 失败 | 回到该 issue 的 Red-Green，修复当前 Behavior 并重新验证 |
+| Verify 的测试、build、真实运行或 review blocking finding 失败 | 回到受影响 issue 的对应阶段；修复后只做受影响检查和 delta review |
+| Deliver 的 docs、敏感扫描、commit 或 Tracker 失败 | 保持 issue 未 resolved，修复 Deliver 门禁后重新验证 |
+| 全量测试失败 | 定位到引入失败的 issue，按上述路径修复；只在修复后重跑必要范围和全量测试 |
+| `Blocked by` 依赖未完成 | 后续 issue 保持 `blocked`，前置 issue resolved 后自动解阻 |
+| 多 issue 预期修改同一文件 | 记录冲突，按编号串行；无法安全归属时暂停并请求用户决定 |
+| Git 历史祖先校验失败 | 立即停止写入，使用 `git reflog` 找回 `BASE_HEAD` 之后的提交，校验通过后继续 |
 
-- 全部 issue `Status: resolved` + 各自 `## 实施总结` 已落盘且 `progress.md` 同步为 `done`
-- 全量测试套件通过
-- 工作区干净且 `progress.md` 与 `issues/*.md` 一致（不一致时以 `issues/*.md` 为准，`progress.md` 为派生可重算）
+主代理不跨 issue 无记录改动；不通过第二次完整双轴 review 来掩盖定向修复。外部权限、model、browser 或 tool 不可用时遵循 [stages.md](stages.md) 的 Tool Failure Budget，最多一次有依据的 fallback，仍失败则标记 `blocked/unavailable` 并报告实际状态。
 
-### 边界
+### A5 出口
 
-- 单 issue / 单 spec 不走本文件编排，但一旦进入多 issue 编排（多 `task`），所有 issue 的 ①→⑦ 均由主代理串行直接执行，禁止子代理派发
-- 不跨 issue 改动；主代理按层串行，一次一 issue 一 commit
-- 汇总总结只在对话输出，不落盘额外汇总文件
-- 必须先输出依赖图/DAG 与 Kahn 分层 `L1..Ln` 并确认后才进入 A2，禁止跳过计划直接执行导致乱序
-- TDD 语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，不在本文件重写
+- 失败原因已分类并记录；
+- 回退目标明确，受影响证据已重新验证；
+- 冲突已按依赖顺序解决或已明确请求用户决策；
+- DAG 顺序、issue 状态、commit 和 `progress.md` 保持一致。