execute-plan

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Execute Plan

执行计划

When to use

使用场景

YES:

meta/specs/NNN-slug/

has a

plan.md

with wave-grouped

[ ]

tasks (from write-plan) ready to execute; resuming a partially executed plan.

NO: no waves yet (use

write-plan

); design undecided (use

tech-design

); plan Status is already FROZEN.

适用：

meta/specs/NNN-slug/

目录下存在包含带

[ ]

标记的波次分组任务的

plan.md

（来自write-plan），且任务已准备好执行；恢复部分执行的计划。

不适用：尚无波次（使用

write-plan

）；设计未确定（使用

tech-design

）；计划状态已为FROZEN。

Protocol

协议

Input

输入

Spec folder:
```
meta/specs/NNN-slug/
```
(or a path to either file in it). Reads both
```
plan.md
```
(waves, log) and
```
spec.md
```
(ACs, D-NNN-XX decisions, Structure Outline).

规格目录：
```
meta/specs/NNN-slug/
```
（或目录内任意文件的路径）。读取
```
plan.md
```
（波次、日志）和
```
spec.md
```
（ACs、D-NNN-XX决策、结构大纲）。

Execution model

执行模型

Parent agent (orchestrator):

Reads plan + spec, dispatches subagents, runs review gates, commits.
Never reads source code files or writes code itself (the Step 5 docs sync is the exception — durable-docs-update runs inline and manages its own reading).
Edits
```
spec.md
```
ONLY in Step 2.5 (promotion) and Step 6 (ship gate).

Use the model the user requests. Otherwise, choose the implementer model per logical task:

Sonnet — only when every condition holds:
- The edit is fully specified and follows an existing pattern.
- Its assigned files are known and bounded.
- It requires no unresolved choice about behavior, architecture, or contract.
- It touches no schema, migration, auth, security, concurrency, payments, destructive data, or public/shared/external interface.
- The dispatch names a check that can verify the result.
Opus — otherwise. Use Opus when any Sonnet condition fails or is unclear.
Grouped work: classify all work assigned to one subagent together; any Opus condition selects Opus.
Escalation: when the orchestrator selected Sonnet, upgrade to Opus if new scope, coupling, or ambiguity appears. Never downgrade during the same task.
Authority: model choice never bypasses decision gates or reduces review and verification.

Subagents (implementers):

Receive: plan file path + their assigned task IDs; the
```
AC-NNN-XX
```
texts their tasks cite and the relevant Structure Outline excerpt (both copied from spec.md into the dispatch — they don't hunt the spec); any prior
```
[Implementation]
```
log entries touching their files (the outline is frozen — the log is where reality lives).
Before the first write, resolve each target path and read its governing repository instructions and Claude path rules in
```
.claude/rules/
```
whose quoted
```
paths:
```
globs match it; use the intended path for a new file.
Implement the assigned work; read existing code in affected areas.
Code comments and test names:
- Write a comment only for what the code can't say — a constraint, assumption, or coupling; the comment carries the fact in prose.
- The dispatch's
```
D-NNN-XX
```
  /
```
AC-NNN-XX
```
  ids may label a comment beside its fact.
- Never cite task ids, wave numbers, or finding ids in code — use a date if "when" matters.
- A test that satisfies an AC carries the id in its name:
```
test_acNNN_XX_...
```
  .

Return:

{ files_changed: [paths], summary: string, discoveries: [{ type: "[Implementation]" | "[AC-affecting]" | "[Future]", note: string }] | null }

A deviation from the Structure Outline IS an
```
[Implementation]
```
discovery — there is no separate channel. If the task body conflicts with a copied current
```
AC-NNN-XX
```
text, the AC text is authoritative: implement to the AC and return the conflict as an
```
[AC-affecting]
```
discovery — never silently reconcile it.
A file assigned to another subagent in the same wave must NOT be edited — return
```
{ needs_scope_expansion: true, additional_files: [paths], justification: string }
```
instead; the parent reassigns and re-dispatches. Once per wave: a second
```
needs_scope_expansion
```
in the same wave stops the reshuffle — collapse the colliding tasks into ONE subagent and run them serially (the same escape wave rule 3 uses for declared overlap).
Keep Git mutations scoped to assigned files: never run
```
git stash
```
,
```
git checkout -- .
```
,
```
git reset
```
, or another command that changes the whole tree.
Scope every Git read to assigned paths.
Read a committed baseline without changing shared state with
```
git show HEAD:<path>
```
.
No file contents in returns — paths and summaries only.

父代理（编排器）：

读取计划+规格，调度子代理，运行评审关卡，提交代码。
从不读取源代码文件或自行编写代码（步骤5的文档同步是例外——durable-docs-update内联运行并自行管理读取操作）。
仅在步骤2.5（升级）和步骤6（发布关卡）中编辑
```
spec.md
```
。

使用用户指定的模型。否则，根据逻辑任务选择实现者模型：

Sonnet — 仅当所有条件满足时使用：
- 编辑内容完全明确且遵循现有模式。
- 已明确指定涉及的文件且范围有限。
- 无需解决关于行为、架构或契约的未决选择。
- 不涉及 schema、迁移、认证、安全、并发、支付、破坏性数据或公共/共享/外部接口。
- 调度中指定了可验证结果的检查项。
Opus — 其他情况。 当Sonnet的任一条件不满足或不明确时使用Opus。
分组工作： 将分配给同一子代理的所有工作归为一类；只要满足任一Opus条件，就选择Opus。
升级： 当编排器选择了Sonnet，但出现新的范围、耦合或歧义时，升级为Opus。同一任务中绝不降级。
权限： 模型选择绝不绕过决策关卡或减少评审与验证环节。

子代理（实现者）：

接收：计划文件路径+分配的任务ID；任务引用的
```
AC-NNN-XX
```
文本及相关结构大纲片段（均从spec.md复制到调度中——无需自行查找规格）；任何涉及其负责文件的先前
```
[Implementation]
```
日志条目（大纲已冻结——日志是实际情况的记录）。
在首次写入前，解析每个目标路径，并读取
```
.claude/rules/
```
中与该路径匹配的仓库指令和Claude路径规则；为新文件使用预期路径。
实现分配的工作；读取受影响区域的现有代码。
代码注释和测试名称：
- 仅在代码无法表达时编写注释——如约束、假设或耦合；注释用 prose 记录事实。
- 调度中的
```
D-NNN-XX
```
  /
```
AC-NNN-XX
```
  ID可标注在相关事实旁的注释中。
- 绝不在代码中引用任务ID、波次编号或发现ID——若需记录时间，使用日期。
- 满足AC的测试需在名称中包含ID：
```
test_acNNN_XX_...
```
  。

{ files_changed: [paths], summary: string, discoveries: [{ type: "[Implementation]" | "[AC-affecting]" | "[Future]", note: string }] | null }

与结构大纲的偏差属于
```
[Implementation]
```
发现——无单独上报渠道。若任务内容与复制的当前
```
AC-NNN-XX
```
文本冲突，以AC文本为准：按AC实现，并将冲突作为
```
[AC-affecting]
```
发现返回——绝不静默调和。
不得编辑同一波次中分配给其他子代理的文件——否则返回
```
{ needs_scope_expansion: true, additional_files: [paths], justification: string }
```
；父代理将重新分配并调度。同一波次中：若第二次出现
```
needs_scope_expansion
```
，停止重新分配——将冲突任务合并为一个子代理并串行执行（与规则3中声明重叠的逃逸波次规则相同）。
将Git变更限定在分配的文件范围内：绝不运行
```
git stash
```
、
```
git checkout -- .
```
、
```
git reset
```
或其他会改变整个仓库的命令。
将所有Git读取操作限定在分配的路径内。
使用
```
git show HEAD:<path>
```
读取已提交的基线，不改变共享状态。
返回内容中不得包含文件内容——仅返回路径和摘要。

Autonomy gate — resolve before asking

自主决策关卡 — 先解决再询问

This gate governs any mid-run

AskUserQuestion

on a reversible code decision. Out of scope (always ask): crash/timeout retry, verification-fail, contract amendment (→ Step 2.5), new-feature placement (→ Step 6.2), any destructive act. Auto-resolve only when the decision is grounded — it traces to a named source (a

D-NNN-XX

AC-NNN-XX

, cited spec line, or existing code at a

file:line

), never your reasoning alone — and you are ≥ 0.80 confident it fits this case. Then apply the disposition you'd otherwise recommend — the spec-mandated action (Tier 1) or the solver's fix (Tier 2) — and log it (below). A human-gated or not-diff-provable concern (a visual

D-NNN-XX

) never auto-fixes: log it as a

- P2

P3 [deferred]: F-NNN-XX — ...

entry in

## Wave Reviews

(the anchor form on the P2/P3 row of Step 2) with the recommendation — Step 6.2 triages it at the ship gate.

Ground the decision in tiers; stop at the first that resolves:

Tier 1 — Spec (parent, no subagent). The answer sits in a cited
```
AC-NNN-XX
```
, locked
```
D-NNN-XX
```
, plan task, or the frozen Structure Outline. A literal match is ~1.0 confident; applying a principle to this case is a judgment — score it honestly. ≥ 0.80 → proceed; below it, fall to Tier 2, don't ask yet.
Tier 2 — Investigation (two read-only subagents, serial). Dispatch a finder (Sonnet): "Does a source directly answer this — a
D-NNN-XX
/
AC-NNN-XX
, another spec line, or existing code? Return
{ source, excerpt }
only if it directly answers; merely related →
source: none
."
```
source: none
```
→ escalate. Else dispatch a solver (Opus): "From that source + the spec, return
{ fix, confidence, needs_decision_change }
— the simplest fix consistent with the locked decisions. Set
needs_decision_change
if the fix contradicts the
D-NNN-XX
's rationale, needs a decision changed, re-architects, or invents a default for behavior no source specifies."
```
confidence ≥ 0.80
```
and not
```
needs_decision_change
```
→ proceed; else escalate. The solver only proposes — the fix runs through the normal wave / fix-verify-loop path.
Tier 3 — Escalate. The step's
```
AskUserQuestion
```
, options with a recommendation, carrying the spec ref + finder/solver notes so the user decides fast.

Log every auto-resolve to

## Execution Log

under the wave's

### Wave N — [date]

heading:

- [auto-resolved]: <decision> — per <source>, conf 0.NN

. These are code-only and still pass Step 2/4 review — the backstop for a mis-scored proceed.

此关卡管理运行中关于可逆代码决策的任何

AskUserQuestion

。超出范围（始终询问）：崩溃/超时重试、验证失败、契约修订（→步骤2.5）、新功能放置（→步骤6.2）、任何破坏性操作。仅当决策有依据时自动解决——可追溯至指定来源（

D-NNN-XX

、

AC-NNN-XX

、引用的规格行或

file:line

处的现有代码），绝非仅凭自身推理——且你对该情况的置信度**≥0.80**。然后应用你原本会推荐的处理方式——规格规定的操作（Tier 1）或解决方案（Tier 2）——并记录（如下）。人工管控或无法通过diff验证的问题（可视化

D-NNN-XX

）绝不自动修复：在

## Wave Reviews

中记录为

- P2

P3 [deferred]: F-NNN-XX — ...

条目（步骤2中P2/P3行的锚点格式）并给出建议——步骤6.2将在发布关卡进行分类处理。

按层级确定决策依据，找到第一个能解决问题的层级即停止：

Tier 1 — 规格（父代理，非子代理）。 答案存在于引用的
```
AC-NNN-XX
```
、锁定的
```
D-NNN-XX
```
、计划任务或冻结的结构大纲中。字面匹配的置信度约为1.0；将原则应用于当前情况属于判断——如实评分。≥0.80 → 继续；低于该值则进入Tier 2，暂不询问。
Tier 2 — 调查（两个只读子代理，串行执行）。 调度一个查找者（Sonnet）：“是否有来源直接回答此问题——
D-NNN-XX
/
AC-NNN-XX
、其他规格行或现有代码？仅在直接回答时返回
{ source, excerpt }
；仅相关则返回
source: none
。”
```
source: none
```
→ 升级。否则调度一个解决者（Opus）：“根据该来源+规格，返回
{ fix, confidence, needs_decision_change }
——与锁定决策一致的最简单修复方案。若修复与
D-NNN-XX
的原理矛盾、需要更改决策、重新架构或为无来源指定的行为设定默认值，则设置
needs_decision_change
为true。”
```
confidence ≥0.80
```
且
```
needs_decision_change
```
为false → 继续；否则升级。解决者仅提出方案——修复需通过正常的波次/修复验证循环流程。
Tier 3 — 升级。 触发步骤的
```
AskUserQuestion
```
，提供选项及建议，并附上规格引用+查找者/解决者的备注，以便用户快速决策。

将每个自动解决的决策记录在

## Execution Log

中对应波次的

### Wave N — [date]

标题下：

- [auto-resolved]: <decision> — per <source>, conf 0.NN

。这些仅与代码相关，仍需通过步骤2/4的评审——这是对误判继续操作的兜底措施。

Review policy — choose the smallest safe gate

评审策略 — 选择最小的安全关卡

The orchestrator chooses each review unit without asking. A review unit changes review timing, not execution state — every wave keeps its own dispatch, checkbox flips, and commit.

One wave — default. Use when any two-wave condition fails or risk is unclear.
Two waves — use only when all conditions hold:
- Both adjacent waves are low-risk and reversible.
- Together they name no more than 4 files.
- Any dependency between them is local and explicit.
- Neither touches schema, migrations, concurrent writes, auth, permissions, security boundaries, payments, destructive data paths, or a public/shared/external interface.
- No earlier review debt is pending.

Before dispatch:

Marker: append

- Review pending: Waves N–M — base <SHA>

under

## Wave Reviews

; use

N–N

for one wave.

Base: use
```
HEAD
```
before the unit's first implementation commit.
Size: count implementation files and lines; exclude spec-folder bookkeeping unless it changes the contract.

After each wave in a two-wave unit:

Close early: shorten the marker to the completed prefix and review now when the implementation diff exceeds 4 files or 200 changed lines, or the wave produces an AC-affecting discovery, decision/outline drift, scope expansion into the next wave, or any high-risk surface above.
Continue: otherwise execute the second wave before reviewing the unit.

编排器自行选择每个评审单元，无需询问。评审单元仅改变评审时机，不改变执行状态——每个波次保留自己的调度、勾选状态和提交记录。

单波次 — 默认。 当任何双波次条件不满足或风险不明确时使用。
双波次 — 仅当所有条件满足时使用：
- 两个相邻波次均为低风险且可逆。
- 总共涉及不超过4个文件。
- 波次间的依赖关系是局部且明确的。
- 均不涉及schema、迁移、并发写入、认证、权限、安全边界、支付、破坏性数据路径或公共/共享/外部接口。
- 无未处理的早期评审债务。

调度前：

标记： 在

## Wave Reviews

下添加

- Review pending: Waves N–M — base <SHA>

；单波次使用

N–N

。

基线： 使用评审单元首次实现提交前的
```
HEAD
```
。
规模： 统计实现文件和行数；除非变更契约，否则排除规格目录的管理文件。

双波次单元中每个波次完成后：

提前关闭： 当实现diff超过4个文件或200行变更，或波次产生AC-affecting发现、决策/大纲偏差、范围扩展至下一波次，或涉及上述任何高风险内容时，将标记缩短为已完成的前缀并立即评审。
继续： 否则在评审单元前执行第二个波次。

Step 1 — Wave execution loop

步骤1 — 波次执行循环

Read the plan fresh — fix-verify-loop or a promotion may have changed it. Extract
```
PLAN_SLUG
```
from the folder name (
```
meta/specs/014-daily-digest/
```
→
```
014-daily-digest
```
). If the plan header's
```
**Base SHA:**
```
is already set (a resume), adopt it as
```
PLAN_BASE_SHA
```
and skip the rest of this item. Fresh start only: first the staleness check —
```
LAST=$(git log -1 --format=%H -- meta/specs/<slug>/plan.md)
```
; skip it if
```
LAST
```
is empty (plan never committed), else run
```
git diff $LAST -- meta/specs/<slug>/spec.md
```
(working tree included, so uncommitted spec edits count); any output means the plan was sequenced against an older spec — stop and route to write-plan. Then check
```
git status --porcelain
```
excluding the spec folder's files (they fold into the Wave 1 commit); if dirty,
```
AskUserQuestion
```
: "Stash and proceed (Recommended)" / "Commit and proceed" / "Abort". Then record
```
PLAN_BASE_SHA=$(git rev-parse HEAD)
```
and set the plan header's
```
**Base SHA:**
```
line.
On session re-entry, resolve any
```
Review pending:
```
marker before new implementation:
- Completed wave exists: shorten the marker to the completed prefix and review it through Step 3.5.
- No completed wave; assigned files clean: resume its first unchecked wave.
- No completed wave; assigned files dirty:
```
AskUserQuestion
```
  : "Resume from the partial changes (Recommended)" / "Stash them and restart the wave" / "Abort plan". On Resume, dispatch one recovery implementer with the unchecked task IDs and existing diff to reconcile and finish the wave; use the user-requested model, or Opus by default.
Find the next
```
### Wave N
```
with any
```
[ ]
```
tasks. Resuming mid-wave → dispatch only unchecked tasks. No unchecked tasks anywhere → resolve any pending review, then run Step 4; during a Step 6.2 ship-debt phase, return to its Review coverage item instead.
With no pending unit, choose one or two waves by the Review policy and append its pending marker. With a pending unit, use its first unchecked wave.
Launch one subagent per logical task in the wave, in parallel, using the model selected above.
```
Must land together with:
```
tasks go to one subagent and are classified together.
Collect results. Crash/timeout →
```
AskUserQuestion
```
: "Retry this item (Recommended)" / "Skip and mark dependents blocked" / "Abort plan". Don't commit a partial wave.
Append each returned discovery to the plan's
```
## Execution Log
```
under a
```
### Wave N — [date]
```
heading, with its type tag (
```
[Future]
```
entries take the next
```
F-NNN-XX
```
— Plan anchors, skills/write-plan/SKILL.md). Any
[AC-affecting]
discovery → run Step 2.5 now, before committing the wave. Other blocking issues → run the Autonomy gate; on escalation,
```
AskUserQuestion
```
: "Resolve and retry (Recommended)" / "Skip and mark dependents blocked" / "Override and proceed" / "Abort plan".
Flip the wave's tasks to
```
[x]
```
— the flip must land IN the wave commit (it's the resume state).
Stage and commit:
```
git add [wave files + plan] && git commit -m "plan(<PLAN_SLUG>): Wave N complete — [brief summary]"
```
. On Wave 1, also
```
git add
```
any uncommitted spec.md (Step 1.1's fold-in); if
```
git status --porcelain
```
on the spec folder shows anything but spec.md/plan.md, leave those unstaged and tell the user.
If the review unit is complete or an early-close condition fired, run Steps 2–3.5. Otherwise return to Step 1 for its second wave.
Return to Step 1 after the review unit closes.

重新读取计划——修复验证循环或升级可能已修改计划。从目录名中提取
```
PLAN_SLUG
```
（
```
meta/specs/014-daily-digest/
```
→
```
014-daily-digest
```
）。若计划标题中的
```
**Base SHA:**
```
已设置（恢复执行），将其设为
```
PLAN_BASE_SHA
```
并跳过本项其余内容。仅首次启动时：先进行过时检查——
```
LAST=$(git log -1 --format=%H -- meta/specs/<slug>/plan.md)
```
；若
```
LAST
```
为空（计划从未提交）则跳过，否则运行
```
git diff $LAST -- meta/specs/<slug>/spec.md
```
（包含工作树，因此未提交的规格编辑也会被计入）；若有输出，说明计划是基于旧版规格制定的——停止并转向write-plan。然后检查
```
git status --porcelain
```
（排除规格目录的文件——它们将合并到Wave 1提交中）；若有未提交变更，触发
```
AskUserQuestion
```
：“暂存并继续（推荐）” / “提交并继续” / “中止”。然后记录
```
PLAN_BASE_SHA=$(git rev-parse HEAD)
```
并设置计划标题中的
```
**Base SHA:**
```
行。
重新进入会话时，在新实现前解决任何
```
Review pending:
```
标记：
- 已完成波次存在： 将标记缩短为已完成的前缀并通过步骤3.5进行评审。
- 无已完成波次；分配文件干净： 恢复第一个未勾选的波次。
- 无已完成波次；分配文件有变更： 触发
```
AskUserQuestion
```
  ：“从部分变更恢复（推荐）” / “暂存变更并重启波次” / “中止计划”。选择恢复时，调度一个恢复实现者，传入未勾选的任务ID和现有diff以协调并完成波次；使用用户指定的模型，默认使用Opus。
找到下一个包含
```
[ ]
```
任务的
```
### Wave N
```
。恢复波次中途进度→仅调度未勾选的任务。无任何未勾选任务→解决任何待处理评审，然后运行步骤4；若处于步骤6.2的发布债务阶段，则返回其评审覆盖项。
若无待处理单元，根据评审策略选择1-2个波次并添加待处理标记。若有待处理单元，使用其第一个未勾选的波次。
为波次中的每个逻辑任务并行启动一个子代理，使用上述选定的模型。标记为
```
Must land together with:
```
的任务分配给同一个子代理并归为一类。
收集结果。崩溃/超时→触发
```
AskUserQuestion
```
：“重试此项（推荐）” / “跳过并标记依赖项为阻塞” / “中止计划”。不提交部分完成的波次。
将每个返回的发现添加到计划的
```
## Execution Log
```
中对应波次的
```
### Wave N — [date]
```
标题下，并附上类型标签（
```
[Future]
```
条目使用下一个
```
F-NNN-XX
```
——Plan anchors, skills/write-plan/SKILL.md）。任何
[AC-affecting]
发现→立即运行步骤2.5，再提交波次。其他阻塞问题→运行自主决策关卡；若升级，触发
```
AskUserQuestion
```
：“解决并重试（推荐）” / “跳过并标记依赖项为阻塞” / “覆盖并继续” / “中止计划”。
将波次的任务标记改为
```
[x]
```
——此修改必须包含在波次提交中（这是恢复状态的依据）。
暂存并提交：
```
git add [wave files + plan] && git commit -m "plan(<PLAN_SLUG>): Wave N complete — [brief summary]"
```
。Wave 1提交时，还需
```
git add
```
任何未提交的spec.md（步骤1.1中的合并内容）；若规格目录的
```
git status --porcelain
```
显示除spec.md/plan.md外的其他文件，将其保留为未暂存并告知用户。
若评审单元已完成或触发提前关闭条件，运行步骤2-3.5。否则返回步骤1执行第二个波次。
评审单元关闭后返回步骤1。

Step 2 — Review unit + Drift check

步骤2 — 评审单元 + 偏差检查

Read

REVIEW_BASE

from the pending marker, set

REVIEW_HEAD=$(git rev-parse HEAD)

, and spawn every

code-reviewer

against

git diff $REVIEW_BASE..$REVIEW_HEAD

. Review the whole unit, never task or commit slices, so cross-task and cross-wave bugs stay visible. Reviewer count scales with the unit's actual size and risk:

R1 — contract & correctness — always. Criteria below.
R2 — cross-task & regression — add for every Step 6.2 ship-debt unit, when the unit spans two waves, or when its implementation diff exceeds 4 files or 200 changed lines, counting size by the Review policy. Charter: "Find bugs from how this review unit's changes interact — a signature, shared state, or config one task changed that another task or an existing caller now depends on. An empty result is valid."
R3 — data integrity — add whenever the diff touches schema, migrations, or concurrent writes (any size). Charter: transactions, races, partial writes, migration reversibility — Step 4's data-integrity seat runs these plan-wide.

Merge findings (dedup by file + line-span + root cause, keep max severity) before the table below; at most three reviewers.

Criteria (R1): the code-gated
```
AC-NNN-XX
```
texts cited by the unit's tasks (copied from the spec).
```
[human-gated:]
```
ACs are excluded — they can't be verified against a diff (the ship gate routes them to Post-ship verification). Plus standard correctness/security/edge-case analysis.
Drift question (posed to R1, whose dispatch also carries the unit's Structure Outline excerpts — the same ones the implementers got): "Does this diff contradict any locked
D-NNN-XX
in spec.md, or deviate from the Structure Outline excerpt? Cite the decision ID or outline element and the contradicting hunk." The outline half is the independent net — implementers self-report only the deviations they notice.
Scope: this review unit's diff only, not the whole plan. Single pass, no verifier; findings have
```
verdict: null
```
and
```
validated_by: "reviewer"
```
.

Finding	Action
None	Record `0 findings — clean` beside the pending marker; continue to Step 3.5.
Drift hit (diff contradicts a `D-NNN-XX` )	Run the Autonomy gate. Grounded + reversible (the `D-NNN-XX` is the source) → conform without asking: confirmed P1 with `validated_by: "reviewer"` → Step 3, log `[auto-resolved]` . A human-gated/visual `D-NNN-XX` isn't diff-provable → log it as a `- P2` / `P3 [deferred]:` entry (P2/P3 row below), don't ask. Only if the gate escalates (not confident, or the reviewer challenges the decision) → `AskUserQuestion` : "Fix code to conform to the D-NNN-XX (Recommended)" / "The decision is wrong — supersede it" (→ Step 2.5) / "Accept with risk note in Wave Reviews".
Outline-drift hit (diff deviates from the outline; no `D-NNN-XX` or AC contradicted)	A detail delta the implementer didn't self-report: append it as an `[Implementation]` entry to the Execution Log and continue — no pause. (A deviation that also contradicts an `AC-NNN-XX` or locked `D-NNN-XX` takes the Drift-hit / Step 2.5 path instead.)
P0/P1	Set `verdict: "confirmed"` , `validated_by: "reviewer"` , and evidence from the review unit → fix-verify-loop (Step 3).
P2/P3 not fixed	Log in `## Wave Reviews` as `- P2 [deferred]: F-NNN-XX — ...` / `- P3 [deferred]: F-NNN-XX — ...` with the why — line-leading `-` required: the ship-gate anchor is `^- P[0-9]+ \[deferred\]:` , and the F id follows the colon (Plan anchors, skills/write-plan/SKILL.md).

Write the unit's findings tally and Drift result beside its pending marker once Step 3 outcomes are known. Step 3.5 replaces that marker with the completed review record. Only pause where the table says so.

从未处理标记中读取

REVIEW_BASE

，设置

REVIEW_HEAD=$(git rev-parse HEAD)

，并针对

git diff $REVIEW_BASE..$REVIEW_HEAD

生成所有

code-reviewer

。评审整个单元，而非任务或提交片段，以便跨任务和跨波次的bug可见。评审员数量根据单元的实际规模和风险调整：

R1 — 契约与正确性 — 始终启用。标准如下。
R2 — 跨任务与回归 — 针对每个步骤6.2的发布债务单元、单元跨两个波次，或实现diff超过4个文件或200行变更时添加（按评审策略统计规模）。职责：“查找此评审单元的变更相互作用产生的bug——某个任务变更的签名、共享状态或配置，而另一个任务或现有调用方依赖这些内容。无结果也是有效结果。”
R3 — 数据完整性 — 当diff涉及schema、迁移或并发写入时添加（无论规模）。职责：事务、竞争条件、部分写入、迁移可逆性——步骤4的数据完整性席位将在整个计划范围内运行这些检查。

在下表前合并发现（按文件+行范围+根本原因去重，保留最高严重性）；最多三名评审员。

标准（R1）：单元任务引用的代码管控
```
AC-NNN-XX
```
文本（从规格复制）。
```
[human-gated:]
```
ACs除外——无法通过diff验证（发布关卡将其路由至发布后验证）。加上标准的正确性/安全/边缘情况分析。
偏差问题（向R1提出，其调度也包含单元的结构大纲片段——与实现者收到的相同）：“此diff是否与spec.md中任何锁定的
D-NNN-XX
矛盾，或偏离结构大纲片段？引用决策ID或大纲元素及矛盾的代码块。” 大纲部分是独立的检查——实现者仅报告他们注意到的偏差。
范围：仅评审此单元的diff，而非整个计划。单次检查，无验证者；发现的
```
verdict: null
```
且
```
validated_by: "reviewer"
```
。

发现	操作
无	在未处理标记旁记录 `0 findings — clean` ；继续步骤3.5。
偏差命中（diff与 `D-NNN-XX` 矛盾）	运行自主决策关卡。有依据且可逆（ `D-NNN-XX` 为来源）→无需询问即可调整：确认P1并设置 `validated_by: "reviewer"` →步骤3，记录 `[auto-resolved]` 。人工管控/可视化 `D-NNN-XX` 无法通过diff验证→记录为 `- P2` / `P3 [deferred]:` 条目（下方P2/P3行），不询问。仅当关卡升级（不置信，或评审员质疑决策）→触发 `AskUserQuestion` ：“修复代码以符合D-NNN-XX（推荐）” / “决策有误——取代它”（→步骤2.5） / “接受并在Wave Reviews中记录风险”。
大纲偏差命中（diff偏离大纲；未与 `D-NNN-XX` 或AC矛盾）	实现者未自行报告的细节差异：将其作为 `[Implementation]` 条目添加到执行日志并继续——无需暂停。（若偏差同时与 `AC-NNN-XX` 或锁定的 `D-NNN-XX` 矛盾，则采用偏差命中/步骤2.5流程。）
P0/P1	设置 `verdict: "confirmed"` 、 `validated_by: "reviewer"` 及评审单元的证据→修复验证循环（步骤3）。
P2/P3未修复	在 `## Wave Reviews` 中记录为 `- P2 [deferred]: F-NNN-XX — ...` / `- P3 [deferred]: F-NNN-XX — ...` 并说明原因——必须以 `-` 开头：发布关卡的锚点为 `^- P[0-9]+ \[deferred\]:` ，F id位于冒号后（Plan anchors, skills/write-plan/SKILL.md）。

步骤3结果确定后，在单元的未处理标记旁记录发现计数和偏差结果。步骤3.5将该标记替换为已完成的评审记录。仅在表格指定的位置暂停。

Step 2.5 — Promote an [AC-affecting] discovery (user-gated)

步骤2.5 — 升级[AC-affecting]发现（人工管控）

Triggered the moment an

[AC-affecting]

discovery is logged (Step 1.7) or a Drift hit resolves to "the decision is wrong" (Step 2). Never auto-apply — this amends the contract.

Log first: write the
```
[AC-affecting]
```
Execution Log entry if none exists — the Drift path arrives without one, and the marker must have an entry to count against. It states the contradiction and evidence.
Present via
```
AskUserQuestion
```
: the contradiction, the evidence, the proposed spec change (revised
```
AC-NNN-XX
```
text and/or
```
D-NNN-XX
```
supersession with new decision block). Also grep
```
plan.md
```
for unchecked
```
- [ ]
```
tasks citing the revised
```
AC-NNN-XX
```
or the superseded old id and list each (title + first body line) in the same question with a disposition: keep / amend / drop — re-pointing a citation updates a label, not the task's instructions. Apply amend/drop edits to
```
plan.md
```
as part of the promotion commit. Options: "Promote to spec (Recommended)" / "Adjust the proposal" / "Abort plan".
On approval, edit the spec(s) (AC line / decision block formats are canonical in
```
skills/product-interview/SKILL.md
```
's spec template). Worked example: old id
```
D-014-03
```
, new id
```
D-014-11
```
.
- Revise the
```
AC-NNN-XX
```
  in place, appending
```
*(revised per D-NNN-XX)*
```
  — ACs are the live contract, one current truth; the why lives in the decision trail.
- Supersede the old decision in the spec file that owns its id — a cross-spec supersession flips a prior spec's block: set
```
Status: superseded
```
  , add
```
Superseded-by: <new id>
```
  . Touch nothing else in the block.
- Append the new block to the current spec's spec.md, with the current spec's
```
NNN
```
  and the next
```
XX
```
  (highest existing
```
XX
```
  in this spec + 1) —
```
Supersedes: <old id>
```
  , rationale citing the evidence and
```
plan Wave N
```
  . Heading type marker: inherit the superseded block's
```
[product]
```
  /
```
[tech]
```
  , or
```
[tech]
```
  if the change is build-originated (marker is advisory — see the canonical Decisions comment).
Classify the supersession, then re-point. Additive = every claim under the old id stays true; behavior-changing = some claim is now false. Either way, grep
```
plan.md
```
for the old id and re-point citations to the new id. A behavior-changing supersession also sweeps the repo: grep the old id across code and docs, dispatch ONE subagent with the hit list and the implementers' comment rules; per hit —
- still true → leave it (the id resolves through the Status line);
- now false → rewrite the prose to the current fact and re-point the label to the new id;
- pointless → delete the comment.
The subagent returns
```
files_changed
```
to stage in the promotion commit.
Close the log entry: append
```
promoted-to-spec [date]: AC-NNN-XX revised, <old id> superseded by <new id>.
```
— ALWAYS lowercase and hyphenated; this is the ship gate's count-compare anchor (Plan anchors, skills/write-plan/SKILL.md). Never write the hyphenated token outside a real marker (unhyphenated prose is safe — the hyphen is what the gate counts).

Commit:

git add [spec folder(s)] [swept files] && git commit -m "plan(<PLAN_SLUG>): promote [AC-affecting] — <old id> superseded by <new id>"

. Resume where execution stopped.

当记录

[AC-affecting]

发现（步骤1.7）或偏差命中判定为“决策有误”（步骤2）时触发。绝不自动应用——这会修改契约。

先记录：若尚未存在
```
[AC-affecting]
```
执行日志条目，则写入——偏差流程到达时可能没有该条目，且标记必须有对应条目才能计数。记录矛盾点及证据。
通过
AskUserQuestion
呈现：矛盾点、证据、提议的规格变更（修订后的
```
AC-NNN-XX
```
文本和/或
```
D-NNN-XX
```
取代块）。同时在
```
plan.md
```
中查找引用修订后的
```
AC-NNN-XX
```
或被取代旧ID的未勾选
```
- [ ]
```
任务，并在同一问题中列出每个任务（标题+第一行内容）及处理方式：保留/修订/删除——重新指向引用会更新标签，而非任务指令。将修订/删除编辑应用到
```
plan.md
```
，作为升级提交的一部分。选项：“升级到规格（推荐）” / “调整提议” / “中止计划”。
批准后，编辑规格（AC行/决策块格式遵循
```
skills/product-interview/SKILL.md
```
规格模板中的标准格式）。示例：旧ID
```
D-014-03
```
，新ID
```
D-014-11
```
。
- 原地修订
```
AC-NNN-XX
```
  ，添加
```
*(revised per D-NNN-XX)*
```
  ——ACs是实时契约，只有一个当前事实；原因记录在决策轨迹中。
- 在拥有该ID的规格文件中取代旧决策——跨规格取代会修改先前规格的块：设置
```
Status: superseded
```
  ，添加
```
Superseded-by: <new id>
```
  。不修改块中其他内容。
- 将新块添加到当前规格的spec.md中，使用当前规格的
```
NNN
```
  和下一个
```
XX
```
  （此规格中现有最高
```
XX
```
  +1）——
```
Supersedes: <old id>
```
  ，理由引用证据和
```
plan Wave N
```
  。标题类型标记：继承被取代块的
```
[product]
```
  /
```
[tech]
```
  ，若变更源于构建则使用
```
[tech]
```
  （标记仅作参考——见标准Decisions注释）。
分类取代操作，然后重新指向引用。 累加式=旧ID下的所有声明仍然有效；行为变更=某些声明现在无效。无论哪种情况，在
```
plan.md
```
中查找旧ID并将引用重新指向新ID。行为变更的取代操作还需扫描仓库：在代码和文档中查找旧ID，调度一个子代理处理命中列表并遵循实现者的注释规则；每个命中项——
- 仍然有效→保留（ID通过Status行解析）；
- 现在无效→将 prose 重写为当前事实并将标签重新指向新ID；
- 无意义→删除注释。
子代理返回
```
files_changed
```
以暂存到升级提交中。
关闭日志条目：添加
```
promoted-to-spec [date]: AC-NNN-XX revised, <old id> superseded by <new id>.
```
——始终使用小写和连字符；这是发布关卡计数对比的锚点（Plan anchors, skills/write-plan/SKILL.md）。绝不在非真实标记中使用连字符格式（非连字符的prose是安全的——连字符是关卡计数的标识）。

提交：

git add [spec folder(s)] [swept files] && git commit -m "plan(<PLAN_SLUG>): promote [AC-affecting] — <old id> superseded by <new id>"

。恢复执行中断的位置。

Fix-loop packet

修复循环数据包

Every

fix-verify-loop

invocation in Steps 3–4 passes:

Findings: Confirmed P0/P1 findings with their
```
validated_by
```
value and verdict evidence.
Artifact paths: The call's approved base paths below. A finding or its evidence may identify another path, but editing it requires the fix-loop scope-expansion gate.
Criteria: The call's governing criteria below plus each finding's criterion.

Call	Base artifact paths	Governing criteria
Review unit — Step 3	Review-unit files	ACs cited by the unit
Regression review — Step 3.5	Review-unit files plus files in the reviewed fix commit	ACs cited by the unit
Final review — Step 4	Files changed in `$PLAN_BASE_SHA..HEAD`	Code-gated ACs relevant to the findings
Verification failure — Step 4	Files changed in `$PLAN_BASE_SHA..HEAD`	The expected project-verification result and relevant code-gated ACs

步骤3-4中每次调用

fix-verify-loop

都会传递：

发现：已确认的P0/P1发现及其
```
validated_by
```
值和判定证据。
工件路径：下方调用的批准基线路径。发现或其证据可能标识另一个路径，但编辑该路径需要修复循环范围扩展关卡。
标准：下方调用的管控标准加上每个发现的标准。

调用	基线工件路径	管控标准
评审单元 — 步骤3	评审单元文件	单元引用的ACs
回归评审 — 步骤3.5	评审单元文件加上已评审修复提交中的文件	单元引用的ACs
最终评审 — 步骤4	`$PLAN_BASE_SHA..HEAD` 中变更的文件	与发现相关的代码管控ACs
验证失败 — 步骤4	`$PLAN_BASE_SHA..HEAD` 中变更的文件	预期的项目验证结果及相关代码管控ACs

Step 3 — Review-unit fix-verify-loop

步骤3 — 评审单元修复验证循环

P0/P1 findings (incl. confirmed Drift fixes) → invoke the fix-verify-loop skill with the Fix-loop packet. On a returned escalation,

AskUserQuestion

: "Retry with guidance (Recommended)" / "Accept and defer" (→ log

[deferred]

in Wave Reviews) / "Skip finding" / "Abort plan".

Commit fixes separately:

plan(<PLAN_SLUG>): Waves N-M fixes — [summary]

(use

Wave N

for a one-wave unit).

P0/P1发现（包括确认的偏差修复）→调用fix-verify-loop技能并传入修复循环数据包。若返回升级，触发

AskUserQuestion

：“通过指导重试（推荐）” / “接受并推迟”（→在Wave Reviews中记录

[deferred]

） / “跳过发现” / “中止计划”。

单独提交修复：

plan(<PLAN_SLUG>): Waves N-M fixes — [summary]

（单波次单元使用

Wave N

）。

Step 3.5 — Review fixes commit (regression check)

步骤3.5 — 评审修复提交（回归检查）

If Step 3 produced a fixes commit, spawn

code-reviewer

scoped to its diff when the fix reached outside the review unit's files (

git show --name-only --format= HEAD

vs the unit file-set) or the diff is sizeable — directionally 2+ files or ~50 lines; otherwise skip the review. Clean or P2/P3-only → continue (deferred entries logged as in Step 2). P0/P1 → set

verdict: "confirmed"

validated_by: "reviewer"

, and evidence from the regression review → fix-verify-loop with the Fix-loop packet → commit as

Waves N-M regression fixes

(

Wave N

for one wave). Regression-fix commits are not re-reviewed here; Step 4 therefore selects Full.

Set

Fix coverage

none

when Step 3 made no commit,

reviewed through <SHA>

when every fix commit received this regression check, and

unreviewed

when any fix or regression-fix commit did not.

Close the unit by replacing its pending marker and adjacent provisional lines with:

markdown

undefined

若步骤3产生了修复提交，当修复超出评审单元文件范围（

git show --name-only --format= HEAD

与单元文件集对比）或diff规模较大（大致2个以上文件或约50行）时，生成

code-reviewer

检查其diff；否则跳过评审。无问题或仅P2/P3→继续（推迟条目按步骤2记录）。P0/P1→设置

verdict: "confirmed"

、

validated_by: "reviewer"

及回归评审的证据→调用修复循环数据包进行修复验证循环→提交为

Waves N-M regression fixes

（单波次单元使用

Wave N

）。回归修复提交在此处不再评审；因此步骤4选择Full模式。

当步骤3未产生提交时，设置

Fix coverage

为

none

；当每个修复提交都接受了此回归检查时，设置为

reviewed through <SHA>

；当任何修复或回归修复提交未接受检查时，设置为

unreviewed

。

通过将未处理标记及相邻临时行替换为以下内容来关闭单元：

markdown

undefined

Review unit: Waves N–M

Range: <REVIEW_BASE>..<REVIEW_HEAD>
Seats: R1[, R2, R3]
AC evidence: <AC-NNN-XX PASS — file:line; ... | none>
Findings: <N findings: M fixed, D dropped by pre-gate, E demoted | 0 findings — clean>
Drift: <none | disposition>
Fix coverage: <none | reviewed through <SHA> | unreviewed>


Keep every anchored deferred entry directly below the completed block; marker replacement never removes deferred findings.

Range: <REVIEW_BASE>..<REVIEW_HEAD>
Seats: R1[, R2, R3]
AC evidence: <AC-NNN-XX PASS — file:line; ... | none>
Findings: <N findings: M fixed, D dropped by pre-gate, E demoted | 0 findings — clean>
Drift: <none | disposition>
Fix coverage: <none | reviewed through <SHA> | unreviewed>


将所有锚定的推迟条目直接保留在已完成块下方；标记替换绝不删除推迟发现。

Step 4 — Final review

步骤4 — 最终评审

Land Step-4 fixes. After any Step-4

fix-verify-loop

invocation:

Resolve. Resolve every escalation and staged-change choice.
Match. When accepted staged changes remain, confirm the path set from
```
git diff --staged --name-only
```
exactly matches the accepted
```
files_changed
```
; resolve any mismatch before continuing.
Commit. Before the next review or verification step, commit the matched paths as
```
plan(<PLAN_SLUG>): final review fixes — [summary]
```
or
```
plan(<PLAN_SLUG>): verification fixes — [summary]
```
. With no accepted staged changes, continue without a commit.

Review Step-4 fixes. After Land Step-4 fixes, continue when no fix was committed; otherwise classify the commit from its diff:

Gate	Use when	Action
Small	Every condition holds: at most 2 files and 100 changed lines; one code path; no Review-policy high-risk surface; clear affected criteria, callers, and consumers.	Invoke `two-pass-review` over the fix commit, its affected callers and consumers, and only the ACs or decisions the fix can change.
Medium	Small does not fit; at most 3 affected final-review seats, including Seat B, can be named; no Full condition holds.	Run the affected seats in parallel over the fix commit and affected surrounding code. Merge P0/P1 findings, then verify them once under the final-review Verify rule.
Full	Any condition holds: more than 5 files or 400 changed lines; a Review-policy high-risk surface; a contract, decision, or outline change; 4 or more affected seats; unclear evidence or blast radius.	Re-run Full over the updated `$PLAN_BASE_SHA..HEAD` diff.

Small and Medium report only regressions caused by the fix, reuse unaffected final-review evidence, and return confirmed P0/P1 findings to the final-review fix rule below.

After all waves and pending reviews close, select code-gated ACs with

grep -E '^- \*\*AC-[0-9]+' spec.md | grep -F '[code-gated]'

, then choose the final mode over

git diff $PLAN_BASE_SHA..HEAD

Use Integration only when all conditions hold:

Every wave belongs to a completed review unit.
Every fix commit has review coverage.
Every confirmed P1 was fixed; none was deferred or skipped.
No P0 occurred; at most two confirmed P1s occurred, all in one review unit.
No regression review found another P1.
No decision or outline drift occurred.
No AC-affecting promotion occurred.
The build touched none of the Review policy's high-risk surfaces.
The spec has no more than 11 code-gated ACs.
The blast radius is clear.

Use Full when any Integration condition fails or its evidence is unclear, including any deferred or skipped P1, unreviewed fix, P0, more than two P1s, P1s across units or in regression review, drift, promotion, high-risk work, or unclear blast radius.

Integration review: spawn one

code-reviewer

over the full diff, licensed to inspect unchanged callers and consumers. Give it every code-gated

AC-NNN-XX

, every

D-NNN-XX

block, and the Structure Outline. Charter: "Return per-AC PASS/FAIL evidence, then find cross-wave or caller regressions and whole-build decision/outline drift that review-unit passes could not see. Do not repeat isolated implementation commentary already settled in completed review units. An empty finding set is valid."

Full review: run the panel below. For either mode, the two-pass-review protocol rules apply: zero P0/P1 across all seats → skip the verifier and present the clean result with

checks_run

. If the verifier rejects every finding, record the disagreement and continue with zero confirmed P0/P1 findings; do not start another review automatically.

Dispatch in parallel — every seat is a

code-reviewer

agent receiving the full

$PLAN_BASE_SHA..HEAD

diff:

Seat A — contract. Criteria: every code-gated
```
AC-NNN-XX
```
(mechanical selection grep above) + standard correctness/security/edge-case analysis.
Seat B — regression / blast radius. Scope: the changed files PLUS their unchanged callers/consumers — explicitly licensed to read outside the diff. Criteria: "Find behavior outside this feature that the diff breaks — callers and consumers of changed signatures, shared state or config, existing behavior no AC describes. Whether the feature's own ACs pass is Seat A's job, not yours. An empty result is a valid result."
Seat C — decision & outline drift. Receives ALL
```
D-NNN-XX
```
blocks from spec.md (including superseded, to catch reversion) + the frozen Structure Outline. Criteria: "Does the whole diff contradict any locked
```
D-NNN-XX
```
or deviate from the frozen Structure Outline? Cite the decision or outline element and the contradicting hunk. A contract-level contradiction is a Step 2.5 promotion, not just a fix. An empty result is a valid result."
Conditional — AC clusters. If code-gated ACs ≥ 12: partition them into clusters of ≤ 8 and dispatch one Seat-A-style reviewer per cluster (its AC subset + the full diff); Seat A then carries only the correctness/security mandate, no ACs.
Conditional — data integrity. If the diff touches schema, migrations, or concurrent writes: one more reviewer chartered on transactions, races, partial writes, and migration reversibility.

Merge (parent): dedup by file + line-span + root cause; keep the max severity; note which seats flagged each finding.

Verify: ONE

verifier

agent over the merged finding set — never one per seat. Set every adjudicated finding's

validated_by

verifier

. If the deduped P0/P1 findings exceed 4, batch the verification by relatedness (shared files, symbols, or call chains — never split findings that reference the same code path) and stitch the verdicts back into one envelope.

Confirmed P0/P1 → fix-verify-loop with the Fix-loop packet. A finding that contradicts an

AC-NNN-XX

or locked

D-NNN-XX

(not just fails it) is a contract break: log it as an

[AC-affecting]

Execution Log entry and run Step 2.5 — final review has no wave commit, but promotion works the same.

Fix: apply Land Step-4 fixes, then Review Step-4 fixes.
Promotion: any Step-2.5 promotion forces the post-fix gate to Full because Integration requires a stable contract.
Retry limit: run one post-fix gate automatically. If resolving that gate changes code or the contract again, finish the resolution, then
```
AskUserQuestion
```
: "Run another post-fix review (Recommended)" / "Abort plan".
Completion: Small or Medium merges its evidence with the unaffected prior evidence; Full replaces the prior result. Record only a final state covered by that evidence. A later Step 6.2 ship-debt phase keeps the record valid only by merging review evidence for every added code change.

Verification run (conditional). After final-review fixes pass their post-fix gate, the parent runs the project's test/verification command once over the final state, if one exists — reading PASS/FAIL only, never source.

No command → skip.
Pass → note
```
verification: passed
```
.
Fail, or can't run →
```
AskUserQuestion
```
: "Fix" / "Accept (pre-existing or intended)" / "Abort". You classify; the parent never reads the test to guess why. "Fix" → create a confirmed finding with
```
validated_by: "machine"
```
and evidence naming the exact command and observed failure; state only what the result proves, invoke fix-verify-loop with the Fix-loop packet, apply Land Step-4 fixes and Review Step-4 fixes, then run verification again. "Accept" → log an accepted risk in the
```
### Final review
```
block, carried into the completion record.

Record the selected mode, per-AC PASS/FAIL evidence, and the verification-run outcome in a

### Final review

block appended to

## Wave Reviews

— file-backed so it survives a session boundary; Step 6.3 copies it into the spec.

落地步骤4修复。 每次调用步骤4的

fix-verify-loop

后：

解决。 解决所有升级和暂存变更选择。
匹配。 若仍有已接受的暂存变更，确认
```
git diff --staged --name-only
```
的路径集与已接受的
```
files_changed
```
完全匹配；继续前解决任何不匹配。
提交。 在下次评审或验证步骤前，将匹配的路径提交为
```
plan(<PLAN_SLUG>): final review fixes — [summary]
```
或
```
plan(<PLAN_SLUG>): verification fixes — [summary]
```
。若无已接受的暂存变更，直接继续。

评审步骤4修复。 在落地步骤4修复后，若无修复提交则继续；否则根据diff对提交进行分类：

关卡	使用场景	操作
Small	所有条件满足：最多2个文件和100行变更；一个代码路径；无评审策略中的高风险内容；明确受影响的标准、调用方和消费者。	对修复提交、其受影响的调用方和消费者以及仅与修复相关的ACs或决策调用 `two-pass-review` 。
Medium	Small不适用；最多可指定3个受影响的最终评审席位（包括Seat B）；无Full条件满足。	并行运行受影响席位检查修复提交及受影响的周边代码。合并P0/P1发现，然后根据最终评审验证规则进行一次验证。
Full	任何条件满足：超过5个文件或400行变更；评审策略中的高风险内容；契约、决策或大纲变更；4个或更多受影响席位；证据或影响范围不明确。	针对更新后的 `$PLAN_BASE_SHA..HEAD` diff重新运行Full模式。

Small和Medium仅报告修复导致的回归，重用未受影响的最终评审证据，并将已确认的P0/P1发现返回至下方的最终评审修复规则。

所有波次和待处理评审关闭后，选择代码管控ACs：

grep -E '^- \*\*AC-[0-9]+' spec.md | grep -F '[code-gated]'

，然后针对

git diff $PLAN_BASE_SHA..HEAD

选择最终模式：

仅当所有条件满足时使用Integration：

每个波次都属于已完成的评审单元。
每个修复提交都有评审覆盖。
每个已确认的P1都已修复；无推迟或跳过。
未发生P0；最多发生两个已确认的P1，且均在同一评审单元。
回归评审未发现其他P1。
未发生决策或大纲偏差。
未发生AC-affecting升级。
构建未涉及评审策略中的任何高风险内容。
规格包含不超过11个代码管控ACs。
影响范围明确。

当任何Integration条件不满足或证据不明确时使用Full，包括任何推迟或跳过的P1、未评审的修复、P0、两个以上的P1、跨单元或回归评审中的P1、偏差、升级、高风险工作或影响范围不明确。

Integration评审： 生成一个

code-reviewer

检查完整diff，许可检查未变更的调用方和消费者。提供所有代码管控

AC-NNN-XX

、所有

D-NNN-XX

块和结构大纲。职责：“返回每个AC的PASS/FAIL证据，然后查找评审单元通过检查无法发现的跨波次或调用方回归以及整体构建的决策/大纲偏差。不重复已在完成的评审单元中解决的孤立实现注释。无发现集是有效结果。”

Full评审： 运行下方的评审组。无论哪种模式，two-pass-review协议规则均适用：所有席位均无P0/P1→跳过验证者并呈现

checks_run

的干净结果。若验证者拒绝所有发现，记录分歧并继续，视为无已确认的P0/P1发现；不自动启动另一次评审。

并行调度——每个席位都是接收完整

$PLAN_BASE_SHA..HEAD

diff的

code-reviewer

代理：

Seat A — 契约。 标准：每个代码管控
```
AC-NNN-XX
```
（上述机械选择的grep结果）+标准正确性/安全/边缘情况分析。
Seat B — 回归 / 影响范围。 范围：变更的文件+未变更的调用方/消费者——明确许可读取diff外的内容。标准：“查找此diff破坏的功能外行为——变更签名、共享状态或配置的调用方和消费者，以及AC未描述的现有行为。功能自身的AC是否通过是Seat A的职责，与你无关。无结果是有效结果。”
Seat C — 决策与大纲偏差。 接收spec.md中的所有
```
D-NNN-XX
```
块（包括已取代的，以检测回退）+冻结的结构大纲。标准：“整个diff是否与任何锁定的
```
D-NNN-XX
```
矛盾或偏离冻结的结构大纲？引用决策或大纲元素及矛盾的代码块。契约级矛盾属于步骤2.5的升级，而非仅修复。无结果是有效结果。”
条件性 — AC集群。 若代码管控ACs≥12：将其划分为≤8个集群，并为每个集群调度一个Seat A风格的评审员（其AC子集+完整diff）；Seat A仅负责正确性/安全任务，不处理ACs。
条件性 — 数据完整性。 若diff涉及schema、迁移或并发写入：增加一个评审员，负责事务、竞争条件、部分写入和迁移可逆性。

合并（父代理）：按文件+行范围+根本原因去重；保留最高严重性；记录每个发现由哪些席位标记。

验证：一个

verifier

代理检查合并后的发现集——绝不每个席位一个验证者。将每个裁决后的发现的

validated_by

设置为

verifier

。若去重后的P0/P1发现超过4个，按相关性批量验证（共享文件、符号或调用链——绝不拆分引用同一代码路径的发现），然后将裁决合并为一个结果。

已确认的P0/P1→修复验证循环并传入修复循环数据包。与

AC-NNN-XX

或锁定的

D-NNN-XX

矛盾的发现（不仅是未通过）属于契约破坏：记录为

[AC-affecting]

执行日志条目并运行步骤2.5——最终评审无波次提交，但升级流程相同。

修复： 应用落地步骤4修复，然后评审步骤4修复。
升级： 任何步骤2.5的升级都会强制修复后的关卡使用Full模式，因为Integration需要稳定的契约。
重试限制： 自动运行一次修复后关卡。若解决该关卡再次变更代码或契约，完成解决后触发
```
AskUserQuestion
```
：“运行另一次修复后评审（推荐）” / “中止计划”。
完成： Small或Medium将其证据与未受影响的先前证据合并；Full替换先前结果。仅记录该证据覆盖的最终状态。后续步骤6.2的发布债务阶段仅通过合并每个新增代码变更的评审证据来保持记录有效。

验证运行（条件性）。 最终评审修复通过修复后关卡后，若存在项目的测试/验证命令，父代理在最终状态下运行一次——仅读取PASS/FAIL，从不读取源代码。

无命令 → 跳过。
通过 → 记录
```
verification: passed
```
。
失败或无法运行 → 触发
```
AskUserQuestion
```
：“修复” / “接受（预先存在或预期）” / “中止”。由你分类；父代理从不读取测试来猜测原因。“修复”→创建一个
```
validated_by: "machine"
```
的已确认发现，证据命名确切命令和观察到的失败；仅陈述结果证明的内容，调用修复循环数据包进行修复验证循环，应用落地步骤4修复和评审步骤4修复，然后再次运行验证。“接受”→在
```
### Final review
```
块中记录已接受的风险，并带入完成记录。

在

## Wave Reviews

中添加一个

### Final review

块，记录选定的模式、每个AC的PASS/FAIL证据和验证运行结果——基于文件存储，以便跨会话边界保留；步骤6.3将其复制到规格中。

Step 5 — Comments and durable docs

步骤5 — 注释与持久化文档

Route before the sweep:

Already complete. If the
```
### Final review
```
block contains
```
**Durable-docs phase:** complete
```
, continue to Step 6 without rerunning the sweep.
Untriaged ship debt. If any
```
[Future]
```
or
```
[deferred]
```
entry lacks a
```
**Ship-debt triage:**
```
disposition, write
```
**Durable-docs phase:** pending
```
in the
```
### Final review
```
block and enter Step 6.2. Return here after the ship-debt phase closes.
Ready. Otherwise, write
```
**Durable-docs phase:** pending
```
unless it already exists, then run one final sweep over the full plan diff.

Invoke the durable-docs-update skill via the Skill tool inline. It sweeps the comments, syncs the docs, and reports both. Pass:

scope —
```
$PLAN_BASE_SHA..HEAD
```
(Mode B);
discoveries — the typed Execution Log entries;
context — the spec's Background + ACs;
spec — the
```
spec.md
```
path, so it mines the locked
```
D-NNN-XX
```
decisions as candidates.

Commit only the files durable-docs-update changed:

git add [those paths] && git commit -m "plan(<PLAN_SLUG>): durable docs sync"

—

plan.md

may hold unstaged Wave-Review text that must not ride along. Replace the pending marker with

**Durable-docs phase:** complete

. This step runs once after the last code phase and before the Completion record.

在扫描前判断：

已完成。 若
```
### Final review
```
块包含
```
**Durable-docs phase:** complete
```
，直接继续步骤6，无需重新扫描。
未分类的发布债务。 若任何
```
[Future]
```
或
```
[deferred]
```
条目缺少
```
**Ship-debt triage:**
```
处理方式，在
```
### Final review
```
块中写入
```
**Durable-docs phase:** pending
```
并进入步骤6.2。发布债务阶段关闭后返回此处。
准备就绪。 否则，写入
```
**Durable-docs phase:** pending
```
（若尚未存在），然后针对完整计划diff运行一次最终扫描。

通过Skill工具内联调用durable-docs-update技能。它会扫描注释、同步文档并报告两者。传递：

scope —
```
$PLAN_BASE_SHA..HEAD
```
（Mode B）；
discoveries — 带类型的执行日志条目；
context — 规格的Background + ACs；
spec —
```
spec.md
```
路径，以便提取锁定的
```
D-NNN-XX
```
决策作为候选。

仅提交durable-docs-update变更的文件：

git add [those paths] && git commit -m "plan(<PLAN_SLUG>): durable docs sync"

—

plan.md

可能包含未暂存的Wave-Review文本，不得随此次提交一起提交。将未处理标记替换为

**Durable-docs phase:** complete

。此步骤在最后一个代码阶段之后、完成记录之前运行一次。

Step 6 — Ship gate

步骤6 — 发布关卡

Run the plan's

## Ship Gate

checklist; every box must be resolved before freezing.

Promotion check (count-compare, Execution-Log-scoped):
```
sed -n '/^## Execution Log/,/^## Wave Reviews/p' plan.md | grep -c '^- \[AC-affecting\]'
```
must equal the same slice piped to
```
grep -ci 'promoted-to-spec'
```
. Any shortfall → run Step 2.5 for the unmarked entries now; an unpromoted contract break fails the gate.

Triage every untriaged
[Future]
and
[deferred]
entry:

Analyze. An entry is triaged when its

F-NNN-XX

id has a recorded disposition under

**Ship-debt triage:**

in the

### Final review

block. Before asking, write

**Ship-debt phase:** triage

there so an interruption resumes this item. Use one read-only subagent per four untriaged entries, capped at four subagents:

min(4, ceil(entry_count / 4))

. Split the entries evenly. Each subagent verifies its entries against the final code, spec, and review evidence, then returns one

ShipDebtAssessment

per entry. With no untriaged entries and no recorded

fix-now

disposition awaiting a task, replace a

triage

marker with

closed

; a pending durable-docs phase returns to Step 5, otherwise continue to item 3.

ShipDebtAssessment {
  id: "F-NNN-XX",
  status: "valid" | "stale" | "unclear",
  evidence: string,
  status_confidence: 0.0-1.0,
  recommendation: "fix-now" | "defer" | "future" | "drop",
  reason: string,
  recommendation_confidence: 0.0-1.0
}

Ask. Present the assessments in as few

AskUserQuestion

batches as the tool allows, with one independently selectable question per assessment. Put each recommended choice first and record every disposition in the

### Final review

block:

**Ship-debt triage:**
- <id> — <status> (<status_confidence>): <evidence>
  Recommendation: <recommendation> (<recommendation_confidence>) — <reason>
  Disposition: <fix-now | defer | future: destination | drop>

Choice	Use when	Result
`fix-now`	A valid defect or shipped hole fits the current contract and approved scope.	Add it to the ship-debt phase.
`defer`	A valid shipped limitation will not be fixed now.	Record it under "Deferred / what this does NOT close".
`future`	The item is a separate feature outside the current contract.	Ask the user where to place it; keep it visible and record its destination.
`drop`	The item is stale or noise.	Let it die with the plan.

Record each answer immediately. After every entry has a disposition, enter the fix-now phase when any recorded

fix-now

item lacks a task; otherwise replace the phase marker with

**Ship-debt phase:** closed

; a pending durable-docs phase returns to Step 5, otherwise continue to item 3.

Fix-now phase. Run at most one. If it has already run, omit

fix-now

from later questions.

Plan. Set
```
SHIP_DEBT_BASE_SHA=$(git rev-parse HEAD)
```
and replace the phase marker directly with
```
**Ship-debt phase:** build — base <SHA>
```
. Append every recorded
```
fix-now
```
item that lacks a task using the canonical task format, the next stable
```
T
```
id, its existing
```
F-NNN-XX
```
id, and its governing
```
AC-NNN-XX
```
or
```
D-NNN-XX
```
citations; cite every AC whose outcome the fix can change. Group the tasks into dependency-ordered
```
### Wave N: Ship debt — <summary>
```
waves of at most five tasks; run independent tasks in parallel.
Build. Run the normal wave dispatch, commit, and Steps 2–3.5 review rules through every appended wave; when no unchecked tasks remain, continue to Review coverage instead of Step 4.
Review coverage. Re-run Step 4 in Full mode after any Step 2.5 promotion or decision/outline drift; otherwise re-run Step 4 only when a ship-debt review unit ends with
```
Fix coverage: unreviewed
```
.
Verify. If Step 4 reran, use its verification result; otherwise run the project verification command with Step 4's no-command/pass/fail handling.
Close. If Step 4 reran, replace the earlier
```
### Final review
```
block with its new record while preserving the phase marker and triage dispositions. Otherwise merge the ship-debt review units' evidence for every cited AC into that block and append the phase's verification result. Replace the phase marker with
```
**Ship-debt phase:** closed
```
; a pending durable-docs phase returns to Step 5, otherwise restart Step 6 at item 1. Later questions offer only
```
defer
```
,
```
future
```
, or
```
drop
```
.

When a

future

item is manually placed in a text home, begin its copied text with

promoted from F-NNN-XX

Write the spec's Completion record (format canonical in
```
skills/product-interview/SKILL.md
```
's spec template; copy, don't move — the plan keeps its log):
- ```
Shipped: [date]
```
  , Status Complete/Partial.
- Criteria results: per-AC PASS/PARTIAL/FAIL with 1-line evidence from the
```
### Final review
```
  block, updated after any Step 6.2 ship-debt phase. Honest — FAIL/PARTIAL when warranted.
- Post-ship verification: manual test cases covering the whole feature (happy path, edges, error/empty states), derived from the spec's
```
## UX
```
  section + ACs, each an unchecked
```
- [ ]
```
  line written
```
steps → expected result
```
  . Every human-gated
```
AC-NNN-XX
```
  MUST appear as a
```
steps → expected
```
  line led by
```
AC-NNN-XX:
```
  — owed, not orphaned (the diff never verified them). Confirm coverage mechanically:
```
grep -E '^- \*\*AC-[0-9]+' spec.md | grep -F '[human-gated:'
```
  (grep the open
```
[human-gated:
```
  form — it carries the inline "how" text; a closed bracket matches nothing and silently drops every human-gated AC) — every hit needs a matching
```
AC-NNN-XX:
```
  line. If nothing is human-observable: write
```
None — nothing manually observable
```
  .
- Deferred / what this does NOT close: every item selected
```
defer
```
  in Step 6.2, with severity.
- Review filter stats: one line aggregating the Wave Reviews tallies — findings dropped by fix-verify-loop's pre-gate and findings demoted, across all review units — so what the filter rejected stays visible.
Run one orchestration-prose pass. Invoke the
```
tighten-instruction
```
and
```
structure-prose
```
skills via the Skill tool, then relay both lenses to one Sonnet subagent. Run this pass once, after all parent-authored prose exists and before changing ship state.
- Scope: only parent-authored prose in the plan's
```
## Execution Log
```
  and
```
## Wave Reviews
```
  (including
```
### Final review
```
  ), plus the spec's new Completion record.
- Shape only: improve clarity and structure without changing meaning, evidence, decisions, statuses, or task state. Preserve every ID and checkbox line verbatim.
- Anchors: record each count before the pass and verify it afterward; discard a file's edits if any count or form changes.
  - ```
  [Implementation]
```
  ,
```
  [AC-affecting]
```
  ,
```
  [Future]
```
  , and
```
  [auto-resolved]
```
  entries must still start
```
  - [Tag]
```
  .
- ```
[deferred]
```
    entries must still start
```
- P<severity> [deferred]:
```
    .
  - Promotion markers must remain lowercase
```
promoted-to-spec
```
    .
  - Ship-debt state must retain
```
**Ship-debt phase:** triage
```
    ,
```
**Ship-debt phase:** build — base <SHA>
```
    , or
```
**Ship-debt phase:** closed
```
    , plus each
```
Disposition:
```
    line.
  - Durable-docs state must retain
```
**Durable-docs phase:** pending
```
    or
```
**Durable-docs phase:** complete
```
    .
Confirm every review, verification, docs, and ship-debt decision is resolved; run every applicable project check not already passed on the current state.
Flip spec
```
Status:
```
→
```
Shipped
```
. Check the plan's Ship Gate boxes, set plan
```
Status: FROZEN [date]
```
.

Commit:

git add [spec folder] && git commit -m "plan(<PLAN_SLUG>): ship — completion record, plan frozen"

运行计划的

## Ship Gate

检查清单；冻结前必须解决每个检查项。

升级检查（计数对比，限定执行日志范围）：
```
sed -n '/^## Execution Log/,/^## Wave Reviews/p' plan.md | grep -c '^- \[AC-affecting\]'
```
必须等于同一范围通过
```
grep -ci 'promoted-to-spec'
```
得到的结果。任何缺口→立即为未标记的条目运行步骤2.5；未升级的契约破坏将导致关卡失败。

分类所有未分类的
[Future]
和
[deferred]
条目：

分析。 当条目

F-NNN-XX

的

### Final review

块中

**Ship-debt triage:**

下记录了处理方式时，视为已分类。询问前，在该块中写入

**Ship-debt phase:** triage

，以便中断后从该项恢复。每4个未分类条目使用一个只读子代理，最多4个：

min(4, ceil(entry_count / 4))

。平均分配条目。每个子代理根据最终代码、规格和评审证据验证其条目，然后为每个条目返回一个

ShipDebtAssessment

。若无未分类条目且无记录的

fix-now

处理方式等待任务，将

triage

标记替换为

closed

；若持久化文档阶段未完成则返回步骤5，否则继续第3项。

ShipDebtAssessment {
  id: "F-NNN-XX",
  status: "valid" | "stale" | "unclear",
  evidence: string,
  status_confidence: 0.0-1.0,
  recommendation: "fix-now" | "defer" | "future" | "drop",
  reason: string,
  recommendation_confidence: 0.0-1.0
}

询问。 以工具允许的最少

AskUserQuestion

批次呈现评估结果，每个评估对应一个独立可选的问题。将每个推荐选项放在首位，并在

### Final review

块中记录每个处理方式：

**Ship-debt triage:**
- <id> — <status> (<status_confidence>): <evidence>
  Recommendation: <recommendation> (<recommendation_confidence>) — <reason>
  Disposition: <fix-now | defer | future: destination | drop>

选择	使用场景	结果
`fix-now`	有效的缺陷或发布漏洞符合当前契约和批准范围。	添加到发布债务阶段。
`defer`	有效的发布限制现在不修复。	记录在“推迟 / 本次未解决的问题”下。
`future`	该条目是当前契约外的独立功能。	询问用户放置位置；保持可见并记录目的地。
`drop`	条目已过时或无效。	随计划结束而废弃。

立即记录每个答案。所有条目都有处理方式后，若任何记录的

fix-now

条目缺少任务，则进入立即修复阶段；否则将阶段标记替换为

**Ship-debt phase:** closed

；若持久化文档阶段未完成则返回步骤5，否则继续第3项。

立即修复阶段。 最多运行一次。若已运行，后续问题不再提供

fix-now

选项。

计划。 设置
```
SHIP_DEBT_BASE_SHA=$(git rev-parse HEAD)
```
并将阶段标记直接替换为
```
**Ship-debt phase:** build — base <SHA>
```
。使用标准任务格式、下一个稳定的
```
T
```
ID、现有
```
F-NNN-XX
```
ID及其管控的
```
AC-NNN-XX
```
或
```
D-NNN-XX
```
引用，添加每个缺少任务的已记录
```
fix-now
```
条目；引用修复可能影响结果的所有AC。将任务按依赖顺序分组为
```
### Wave N: Ship debt — <summary>
```
波次，每个波次最多5个任务；并行运行独立任务。
构建。 通过每个添加的波次运行正常的波次调度、提交和步骤2–3.5评审规则；无未勾选任务时，转向评审覆盖而非步骤4。
评审覆盖。 若发生步骤2.5升级或决策/大纲偏差，重新运行步骤4的Full模式；否则仅当发布债务评审单元以
```
Fix coverage: unreviewed
```
结束时重新运行步骤4。
验证。 若步骤4重新运行，使用其验证结果；否则按步骤4的无命令/通过/失败处理方式运行项目验证命令。
关闭。 若步骤4重新运行，用新记录替换之前的
```
### Final review
```
块，同时保留阶段标记和分类处理方式。否则将发布债务评审单元的每个引用AC的证据合并到该块中，并添加阶段的验证结果。将阶段标记替换为
```
**Ship-debt phase:** closed
```
；若持久化文档阶段未完成则返回步骤5，否则重新启动步骤6的第1项。后续问题仅提供
```
defer
```
、
```
future
```
或
```
drop
```
选项。

当

future

条目手动放置到文本位置时，复制的文本以

promoted from F-NNN-XX

开头。

编写规格的完成记录（格式遵循
```
skills/product-interview/SKILL.md
```
规格模板中的标准格式；复制，不移动——计划保留其日志）：
- ```
Shipped: [date]
```
  ，状态为Complete/Partial。
- 标准结果：每个AC的PASS/PARTIAL/FAIL，附带
```
### Final review
```
  块中的1行证据，步骤6.2发布债务阶段后更新。如实记录——必要时标记FAIL/PARTIAL。
- 发布后验证：覆盖整个功能的手动测试用例（正常路径、边缘情况、错误/空状态），源自规格的
```
## UX
```
  部分+ACs，每个用例为未勾选的
```
- [ ]
```
  行，格式为
```
steps → expected result
```
  。每个人工管控的
```
AC-NNN-XX
```
  必须作为
```
AC-NNN-XX:
```
  开头的
```
steps → expected
```
  行——必须覆盖，不得遗漏（diff从未验证过它们）。机械确认覆盖范围：
```
grep -E '^- \*\*AC-[0-9]+' spec.md | grep -F '[human-gated:'
```
  （grep开放的
```
[human-gated:
```
  格式——包含内联“如何”文本；闭合括号不匹配任何内容，会静默丢弃所有人工管控AC）——每个命中项都需要对应的
```
AC-NNN-XX:
```
  行。若无人工可观察内容：写入
```
None — nothing manually observable
```
  。
- 推迟 / 本次未解决的问题：步骤6.2中选择
```
defer
```
  的每个条目，附带严重性。
- 评审过滤统计：一行汇总Wave Reviews的计数——修复验证循环前置关卡丢弃的发现和降级的发现，覆盖所有评审单元——以便可见过滤器拒绝的内容。
运行一次编排prose优化。 通过Skill工具调用
```
tighten-instruction
```
和
```
structure-prose
```
技能，然后将两个视角传递给一个Sonnet子代理。此优化运行一次，在所有父代理编写的prose完成后、更改发布状态前。
- 范围： 仅计划的
```
## Execution Log
```
  和
```
## Wave Reviews
```
  （包括
```
### Final review
```
  ）中的父代理编写prose，加上规格的新完成记录。
- 仅优化结构： 在不改变含义、证据、决策、状态或任务状态的前提下提高清晰度和结构。保留每个ID和勾选行的原文。
- 锚点： 优化前记录每个计数，优化后验证；若任何计数或格式变更，丢弃文件的编辑。
  - ```
  [Implementation]
```
  、
```
  [AC-affecting]
```
  、
```
  [Future]
```
  和
```
  [auto-resolved]
```
  条目必须仍以
```
  - [Tag]
```
  开头。
- ```
[deferred]
```
    条目必须仍以
```
- P<severity> [deferred]:
```
    开头。
  - 升级标记必须保持小写
```
promoted-to-spec
```
    。
  - 发布债务状态必须保留
```
**Ship-debt phase:** triage
```
    、
```
**Ship-debt phase:** build — base <SHA>
```
    或
```
**Ship-debt phase:** closed
```
    ，加上每个
```
Disposition:
```
    行。
  - 持久化文档状态必须保留
```
**Durable-docs phase:** pending
```
    或
```
**Durable-docs phase:** complete
```
    。
确认所有评审、验证、文档和发布债务决策均已解决；运行当前状态下所有未通过的适用项目检查。
将规格的
```
Status:
```
改为
```
Shipped
```
。勾选计划的Ship Gate检查项，设置计划
```
Status: FROZEN [date]
```
。

提交：

git add [spec folder] && git commit -m "plan(<PLAN_SLUG>): ship — completion record, plan frozen"

。

Step 7 — Report

步骤7 — 报告

The Completion record in

spec.md

is the durable summary — don't duplicate it. Report in this exact shape — a scan of this block is how the user learns what happened, so give substance to what they're knowingly carrying and counts to what was routinely handled:

**Build complete: [NNN-slug]**
- Built: [what shipped, one line]
- Tests: [passed | failed — accepted: why | no command]
- ACs: [n] PASS, [m] FAIL/PARTIAL — [name each non-pass | all pass]
- Spec changed mid-build: [old id → new id — what changed, one line each | none]
- Accepted risks (carried, not fixed): [one line each — see Wave Reviews | none]
- Deferred debt: [one line each, with severity | none]
- Handled autonomously: [N] outline deviations, [M] auto-resolved decisions (see Execution Log)
- Docs: [files touched | none needed]
- Post-ship verification (you verify): [each item, one per line | none]

(Counts write

when empty — a zero is information, not noise. A field with two or more items nests them as sub-bullets.)

spec.md中的完成记录是持久化摘要——不要重复。按以下精确格式报告——用户通过扫描此块了解情况，因此要明确说明他们已知晓的内容和常规处理的计数：

**Build complete: [NNN-slug]**
- Built: [已发布内容，一行]
- Tests: [passed | failed — accepted: 原因 | no command]
- ACs: [n] PASS, [m] FAIL/PARTIAL — [列出每个未通过项 | all pass]
- Spec changed mid-build: [旧ID → 新ID — 变更内容，每行一个 | none]
- Accepted risks (carried, not fixed): [每行一个 — 见Wave Reviews | none]
- Deferred debt: [每行一个，带严重性 | none]
- Handled autonomously: [N] outline deviations, [M] auto-resolved decisions (see Execution Log)
- Docs: [修改的文件 | none needed]
- Post-ship verification (you verify): [每个项，每行一个 | none]

(空值填写

——零是信息，而非噪声。包含两个或更多项的字段以子项目符号嵌套。)

Resumability

可恢复性

Wave-granular via
[x]
checkboxes — on resume, find the first wave with
```
[ ]
```
tasks, dispatch only those.
Ship-debt resume. A
```
**Ship-debt phase:** triage
```
marker resumes Step 6.2 from the first entry without a recorded disposition. A
```
build — base <SHA>
```
marker restores
```
SHIP_DEBT_BASE_SHA
```
, materializes any recorded
```
fix-now
```
item without a task, then resumes the first unchecked Ship debt wave or Review coverage. A
```
closed
```
marker never offers another fix-now phase.
Durable-docs resume. A
```
**Durable-docs phase:** pending
```
marker resumes Step 6.2 while ship debt is open and Step 5 after ship debt closes. A
```
complete
```
marker continues Step 6.
Pending review outranks unchecked work. On session re-entry, close any completed prefix through Step 3.5; when none completed, resume or recover the first unchecked wave by Step 1.2's clean/dirty rule.
PLAN_BASE_SHA
recovers from the plan header's
```
**Base SHA:**
```
line; fallback: take the first
```
plan(<PLAN_SLUG>): Wave
```
commit (
```
git log --format=%H --grep="plan(<PLAN_SLUG>): Wave" --reverse | head -1
```
), then walk to its parent, skipping past any
```
plan(<PLAN_SLUG>): promote
```
commits — a Wave-1 promotion lands BEFORE the Wave-1 commit, and the base is the commit before all of them.
Promotion commits (Step 2.5) interleave safely — wave state lives in the checkboxes, not the git history.
The flips are the resume authority — checkbox flips land in their own wave's commit (Step 1.8-9); Wave-Review blocks and deferred entries are written to disk immediately and ride the next commit (fixes, next wave, or ship) — that lag is fine.

通过
[x]
勾选框实现波次粒度恢复 — 恢复时，找到第一个包含
```
[ ]
```
任务的波次，仅调度这些任务。
发布债务恢复。
```
**Ship-debt phase:** triage
```
标记从第一个无记录处理方式的条目恢复步骤6.2。
```
build — base <SHA>
```
标记恢复
```
SHIP_DEBT_BASE_SHA
```
，实例化任何无任务的已记录
```
fix-now
```
条目，然后恢复第一个未勾选的发布债务波次或评审覆盖。
```
closed
```
标记不再提供立即修复阶段。
持久化文档恢复。
```
**Durable-docs phase:** pending
```
标记在发布债务开放时恢复步骤6.2，发布债务关闭后恢复步骤5。
```
complete
```
标记继续步骤6。
待处理评审优先于未完成工作。 重新进入会话时，通过步骤3.5关闭任何已完成的前缀；若无已完成内容，按步骤1.2的干净/变更规则恢复或恢复第一个未勾选的波次。
PLAN_BASE_SHA
从计划标题的
```
**Base SHA:**
```
行恢复；备选方案：找到第一个
```
plan(<PLAN_SLUG>): Wave
```
提交（
```
git log --format=%H --grep="plan(<PLAN_SLUG>): Wave" --reverse | head -1
```
），然后回溯到其父提交，跳过所有
```
plan(<PLAN_SLUG>): promote
```
提交——Wave-1升级在Wave-1提交之前，基线是所有这些提交之前的提交。
升级提交（步骤2.5）可安全交错 — 波次状态存储在勾选框中，而非git历史中。
勾选框是恢复的权威依据 — 勾选框变更包含在对应波次的提交中（步骤1.8-9）；Wave-Review块和推迟条目立即写入磁盘并随下次提交（修复、下一波次或发布）提交——此延迟无影响。

Rules

规则

One wave per commit. A review unit contains one wave or two eligible adjacent waves; every wave keeps its own commit and resume checkbox state.
Typed tags are line-anchored grep targets. Execution Log entries start
```
- [Implementation]
```
,
```
- [AC-affecting]
```
,
```
- [Future]
```
, or
```
- [auto-resolved]
```
; deferred Wave Review entries start
```
- P<severity> [deferred]:
```
. Exact forms live under Plan anchors in
```
skills/write-plan/SKILL.md
```
. Never log a discovery untagged or start a narrative line with a bracketed tag.
The spec's Structure Outline is frozen. Keep mid-build design changes in this skill: contract changes use Step 2.5; implementation-only changes become
```
[Implementation]
```
entries that later-wave dispatches carry so subagents trust the log over the outline.
*(revised per D-NNN-XX)*
is a human-readable convention, not a gate anchor — nothing greps it; don't build checks on it.
ACs are verified by reviewers against diffs, never self-certified by the implementing subagent.
Post-ship learnings route onward. After the ship commit, new learnings go to the spec or durable docs, not back into the plan.

每个波次对应一个提交。 评审单元包含一个波次或两个符合条件的相邻波次；每个波次保留自己的提交和恢复勾选状态。
带类型的标签是行锚定的grep目标。 执行日志条目以
```
- [Implementation]
```
、
```
- [AC-affecting]
```
、
```
- [Future]
```
或
```
- [auto-resolved]
```
开头；推迟的Wave Review条目以
```
- P<severity> [deferred]:
```
开头。精确格式见
```
skills/write-plan/SKILL.md
```
中的Plan anchors。绝不记录无标签的发现，也绝不以括号标签开头编写叙述行。
规格的结构大纲已冻结。 构建中的设计变更在此技能中处理：契约变更使用步骤2.5；仅实现变更成为
```
[Implementation]
```
条目，后续波次调度将携带这些条目，以便子代理信任日志而非大纲。
*(revised per D-NNN-XX)*
是人类可读约定，而非关卡锚点 — 无内容grep它；不要基于它构建检查。
ACs由评审员根据diff验证，绝不由实现子代理自我认证。
发布后学习成果路由至其他地方。 发布提交后，新的学习成果进入规格或持久化文档，而非返回计划。