execute-phase

执行阶段

单元步骤执行器。单元文档（由 unit-lane 创建）包含 Tasks P1…Pn、 Evidence 条目和 Progress 日志——它们取代 PLAN.md、TASKS.md、 progress.md 和 ACCEPTANCE.md。每个步骤都作为原子化的门禁/提交运行。

参数解析（按首次匹配）：

• <NN-slug> P<k> — 按分诊顺序指定的步骤（P1、P2、…）
• <NN-slug>（不带步骤）— 所有剩余步骤，每个步骤单独提交一次
• 单独的 P<k> — 当前单元中按位置指定的步骤（最后已知的 NN-slug）

绝不推断单元文档分诊区块中未列出的步骤 ID。

回合约定

结束回合前勾选每个方框；有未勾选的方框，表示回合尚未完成：

✓ Required user inputs were answered concretely (not defaulted). Nothing here
  is inferred: a gap runs `node scripts/needs-input.mjs <unit-dir>` and the
  `open-questions@1` block is pasted, then the run stops.
✓ Triage verified — unit doc Evidence section header matches
  `bun scripts/unit-route.mjs --triage <slug>` output block (PREFLIGHT.md)
✓ Unit doc read and step selected (explicit P<k> or first unfinished)
✓ Step executed and committed (one commit per step, conventional format)
✓ Evidence rows updated (command → exit/digest → output → verified-by)
✓ Progress log updated with a dated `YYYY-MM-DD HH:MM` entry that names the
  phase id (what, commit, next)
✓ Memory boundary ran — the phase's outcome saved under `unit/<NN-slug>/doc`,
  or the mirror marked pending when the layer is degraded
✓ Diff guard passed (on implement steps) — see `diff-guard` in PREFLIGHT.md
✓ → Next: block printed as the absolute last output

适用场景

• 来自 unit-lane 的已分诊单元：步骤包含 implement/tests/evidence → 使用 <NN-slug> 或 <NN-slug> P<k> 调用。
• 仅文档单元（分诊只返回 [docs, evidence]）不会加载此技能——由 unit-lane 指挥器就地执行。
• 执行所有剩余步骤：使用不带步骤参数的 <NN-slug>。
• 修复失败的步骤：<NN-slug> P<k>（重试同一步骤）。

输入——工件，而非问题

此技能绝不进行访谈。它读取输入——单元文档中的 Tasks、 unit-route.mjs --triage 的区块和路由的层级；缺失或含糊的输入都是缺口， 必须按固定顺序解决，绝不靠推断： （0）来源追溯（搜索仓库自身的文档并记录出处）→ （1）研究（提供 2–3 个具体选项及其权衡；请求进一步研究也是合理答复）→ （2）暂停：运行 node scripts/needs-input.mjs <unit-dir>，原样粘贴 open-questions@1 区块，然后停止。交互模式下，该 区块是暂停点；无人值守模式下，则视为硬失败。语法和退出代码见： orchestration-envelope 的 references/TURN_CONTRACT.md §Open questions。

不带参数的 <NN-slug> 会运行所有剩余步骤——阶段不是输入。文件 目标是单元文档中嵌套的 Relevant files: 元数据加上路径保护检查点。 --max-attempts N 默认值为 3；--force 会跳过依赖项和阶段 lint 门禁上的 停止（但不会跳过检查——PREFLIGHT.md 会在 Progress 日志中记录此覆盖），并且 无法绕过路径保护检查点。

步骤 0 — 发现项目

根据 Agent 指南的工作流约定和文档索引，读取 docs/features/<NN-slug>/SPEC.md 中的单元文档。确认其中包含 ## Tasks（P1…Pn）、 ## Evidence 和 ## Progress 章节。若缺少任何一项，说明单元尚未就绪—— 停止并建议先使用 unit-lane 进行分诊。

流程

1. 验证分诊是否为最新

运行 bun scripts/unit-route.mjs --triage <slug>，并将其区块与单元文档中 Evidence 章节的标题进行比较。不匹配 → 停止并先重新分诊。 此门禁确保执行器与 unit-lane 对步骤的理解一致。

2. 选择步骤

如果给定了步骤参数（例如 P2），则使用该步骤。否则，使用第一个未完成步骤—— 即 Tasks 中第一个复选框尚未勾选的 P。 绝不执行分诊跳过的步骤。

3. 前置门禁

按顺序运行门禁；任一失败 → STOP（参见 PREFLIGHT.md）：

1. 路径保护检查点 — 对照受保护路径（例如 tests/、fixtures/）检查已提交范围。退出码为 1 → STOP，并显示门禁拒绝块。不得通过 --force 绕过（任何标志都无法覆盖）。
2. 阶段 lint — 仅当步骤为 implement 且单元包含 Tasks P1…Pn 时，运行 bun scripts/phase-lint.mjs <unit-doc>。解析 Tasks 部分（而非 PLAN.md/TASKS.md）。退出码为 1 → STOP。如果脚本不存在，则手动应用八条 phase-contract 规则，标记为较弱，并披露此情况。
3. 写入前映射器 — 对于 implement 步骤，在创建分支、提交计划或编辑源代码/测试之前，先确定写入前映射器的契约： (implementation-discovery)：它会完成七个证据问题的确认，并将结果分流为 READY | REPLAN | NEEDS-DESIGN | BLOCKED；只有 READY 才授权首次写入。
4. 依赖项/不变量检查 — 按 unit-lane 的分类规则目录执行：确保所需依赖已合并；保留架构不变量，或提供明确记录的决策作为依据（在编辑前阻止 violates/introduces/ changes）。

4. 执行步骤

按照此步骤对应的 unit-lane 参考文档（references/STEPS.md 目录）执行： 一行概括 — 阅读步骤参考文件，完成其检查清单，并提交工作。对于 implement 步骤：先编写测试（在有价值的地方采用测试优先，例如核心/领域、编排 — 在实现前记录失败的 red 运行所用命令、退出码和失败测试名称），再使测试通过。UI/适配器胶水代码可以在实现后测试。

5. 步骤后

1. 差异保护（仅限 implement 步骤）：运行 bun scripts/diff-guard.mjs --base <last-step-commit> --unit <unit> — 原样粘贴输出块。BREACH → STOP （重新分类，或记录例外）。防止作弊：绝不要通过删除注释、空行、文档或测试来缩小差异。
2. 证据行：每项满足的 AC 一行 — | AC | command | exit/digest | output (≤2 lines) | verified-by |。追加到 Evidence 部分。
3. 进度日志：追加一条带日期的记录 — YYYY-MM-DD HH:MM — <what was done> → <commit sha> — next: <what is next>。
4. 记忆边界 — 此步骤是一个阶段转换。遵循 记忆协议：首次读取记忆前，运行一次 agentic-workflow memory probe，并将其判定结果记录在 Evidence 中；步骤完成后，在 topic_key: "unit/<NN-slug>/doc" 下保存阶段 ID、变更内容、Evidence 结果以及任何发现，并明确填写 project 和会话归属（§5）。degraded 判定需记录，并将镜像标记为待处理 — 但绝不会阻塞此步骤。
5. 提交：运行 git add <changed files>，然后运行 git commit -m "<type>(<scope>): <step-summary>" — 执行该命令并粘贴 SHA。

6. 红色门禁（修复循环）

每个步骤后：运行项目的验证门禁（类型检查 + 测试 + 构建）。

• 门禁通过 → 继续。

• 门禁失败 → 在进度日志中记录退出码和失败测试名称，修复同一步骤并重试。默认 --max-attempts 3（用户指定的值优先）。

• 重试次数耗尽 → STOP，并显示：

  UNIT LOOP — <unit> BLOCKED at <P<k>>
  Reason: <NO-PROGRESS|ATTEMPT-BUDGET> · Attempts: <n>
  Last validator: <command> → <exit/status + compact failure>
  Preserved: no red commit; acceptance blob <sha> unchanged
  
  → Next: inspect the named blocker, then re-run /execute-phase <unit> <P<k>>
    · architecture/product decision required → resolve it before resuming
    · continue atomically → /execute-phase <unit> <P<k>>
  

7. 整单元模式

调用时仅提供 <NN-slug> 而不指定步骤：循环执行所有剩余步骤，每步各提交一次。这仅限操作者明确选择 — unit-lane 的交接始终只指定一个阶段（<NN-slug> P<k>），因此，lane 交接中单独出现 <NN-slug> 属于缺陷；循环执行前请重新阅读交接内容。每个步骤后：运行门禁、执行步骤、运行差异保护（若为 implement）、更新证据/进度并提交。跳过中间评审检查点；强制要求的最终评审会覆盖累计的全部差异。若任一步骤的门禁失败：修复该步骤（最多 --max-attempts 次），然后继续循环。终止时显示：

UNIT LOOP — <unit> COMPLETE
Steps: <n> · Commits: <sha list> · Gate: PASS
PR: <url>

→ Next: /review-change on the changed HEAD — the mandatory end review
  · findings (REVIEW-FAIL) → /fold-findings repairs them; a fresh /review-change follows the fold
  · merge gate after REVIEW-PASS → /audit-pr

8. Descope 守卫

执行过程中，在创建任何议题之前，都要先用 descope 测试进行分类。 Descope（将验收标准或任务移出范围）必须先获得用户明确批准， 然后记录在单元文档的 ## References 部分（而不是后续议题）中，格式如下： - <YYYY-MM-DD> — descoped: "<criterion>" — approved by user。 议题绝不能成为 descope 的第一条记录。

必需的参考文件

当相关主题处于活动状态时，必须加载以下文件：

• PREFLIGHT.md — 所有门禁阻断项（依赖项、状态、执行前、证据、lint、路径保护）
• EXECUTION_CONTRACT.md — 步骤完成门禁、架构不变量
• PRE_EXECUTION_GATE.md — 执行前审查门禁、规范化器顺序
• FOLDING.md — 审查发现的折叠周期
• DESCOPE.md — descope 测试和修订规则
• FORGE_BODY.md — forge 操作（gh 正文文件规则）

护栏

允许：

• 仅执行单元文档 Evidence 标题中列出的已分诊步骤
• 仅修改验收标准和步骤任务涵盖的内容
• 更新单元文档（Evidence、Progress、References）
• 遵循项目 Workflow 约定的 Conventional Commit 消息
• 步骤自身的参考文件（从单元文档目录单跳读取）

禁止：

• 绝不提交红色状态（测试失败）——在步骤范围内修复，否则记录阻碍并停止。
• 绝不削弱验证器（放宽断言、降低覆盖率）——修复必须保持至少同等强度的断言。
• 绝不执行分诊时跳过的步骤——目录具有权威性。
• 绝不编辑单元文档的验收标准（这属于需经用户同意后重新分诊）。
• 绝不超出 Non-goals 定义的范围——实现过程中发现的问题绝不能扩大单元范围。
• 绝不臆造验收标准——向用户提出具体选项。

与其他技能的关系

unit-lane 负责执行（分诊 → 判断步骤 → 收尾阶梯），并按每轮一个阶段的方式交接执行（<NN-slug> P<k>，附带目录层级）；本技能执行指定阶段，或仅在操作者明确选择时执行所有剩余步骤。只要仍有阶段未完成，收尾交接就必须准确指定一个阶段和层级；最后一个阶段完成后，则恢复执行该工作流。fold-findings 负责修复审查发现。审查包的各个维度（review-implementation、review-code、review-security、review-perf、review-a11y、review-debt）共同组成审查步骤；workflow-status 会将流程导向此处。triage-issue 将议题纳入工作流。本技能是步骤执行器，每轮调用它，便会在完整门禁机制下执行单元的一个已分诊步骤。

可移植性（Claude Code 以外的 Agent）

• 没有斜杠菜单——在全新对话中打开此 SKILL.md 并严格遵循。凡是写明 run 的地方，都直接执行 shell 命令。
• 没有模型层级——分诊和审查使用能力最强的模型；执行步骤可以使用成本较低的模型。审查所用模型绝不能弱于作者使用的模型。
• 没有 /loop/子 Agent——调用 <NN-slug> 执行所有剩余步骤（内置循环），或调用 <NN-slug> P<k> 执行单个步骤。
• 没有新建工作进程——直接执行，并在每次提交后将状态归纳到单元文档中；绝不重新读取此前的文件。

完成条件

• 已实现请求的范围（指定阶段，或在操作者明确要求执行所有剩余步骤时完成全部剩余步骤），门禁为绿色，单元文档中的 Evidence/Progress 已更新（Progress 条目注明阶段 ID），且工作已提交。
• 已打印结尾的 → Next: 区块。

收尾建议

只能选择一种终态——根据单元的 Tasks 部分选择，绝不打印 Tasks 部分未定义的阶段 ID：

仍有阶段未完成：

→ Next: /execute-phase <NN-slug> P<k+1> (tier: <tier>) — one phase per turn; <tier> is the catalog's implement entry
  · whole-unit operator run complete → /review-change (mandatory end review)
  · findings (REVIEW-FAIL) → /fold-findings repairs them; a fresh /review-change follows the fold
  · merge gate after REVIEW-PASS → /audit-pr — the merge gate

刚刚完成最后一个阶段（lane-run 单元）：

→ Next: /unit-lane <NN-slug> — resume the conductor for the remaining judgment steps
  · whole-unit operator run complete → /review-change (mandatory end review)
  · findings (REVIEW-FAIL) → /fold-findings repairs them; a fresh /review-change follows the fold
  · merge gate after REVIEW-PASS → /audit-pr — the merge gate