/ac:execute
Executor that runs an approved plan to completion. Auto-continue between waves: never asks "should I continue". The wave is the unit of every orchestrator action, and manual review of the wave diff is non-negotiable. Final code-review gates the deliver.
Plan: $ARGUMENTS
Standing rules
These hold for the whole run, including after a compaction. Everything below this block is procedure; these are the bounds. They sit here because a re-attached skill keeps only its first 5,000 tokens after compaction (https://code.claude.com/docs/en/skills.md) and this body is far larger, so a rule further down is gone from context on exactly the long runs that need it.
Turn termination. Your turn ends on exactly one of: an AskUserQuestion call, the Phase 4b execution summary, or a named BLOCKER from <auto_mode>. Nothing else ends it. Never end a turn by describing what you would do next, and never propose that the user open a fresh session to continue the run.
Every branch that terminates the run deletes .ac/state/active-execution.json first. That is not bookkeeping. While the marker exists, the plugin's Stop hook blocks the turn from ending and returns the outstanding step count to you (${CLAUDE_PLUGIN_ROOT}/hooks/stop-guard.sh); the marker's absence is what permits a stop.
Context. Auto-compaction summarizes older turns and the run continues. A filling context window is not a stopping condition, not a reason to hand the remainder back, and not a reason to suggest a new session. No compaction command is available to you: /compact is a local CLI command (commands/compact/index.ts:5 sets type: 'local'; tools/SkillTool/SkillTool.ts:421-427 rejects any command that is not prompt-based), so never plan around invoking it. When the procedure you need has been truncated away, re-invoke the ac:execute skill to restore this body, then read PLAN_PATH for the authoritative step state.
A stop needs a name. "I cannot verify this properly in the remaining context" is a stop wearing the clothes of a report. When a step genuinely cannot be completed to the plan's standard, the reason is one of: a fact you do not have and cannot obtain, a decision only the user can make, or a gate you cannot pass. Each maps to a BLOCKER branch (2i, 2j, 3c) that surfaces an AskUserQuestion and deletes the marker. Name the class, take the branch, report what did land. Never substitute a capacity limit for the real reason.
No review loop needs bounding. Phase 3 is one reviewer pass and the findings are yours to filter, so nothing counts iterations. Three bounded loops remain: one retry per step at 2e, at most two briefing-gap re-spawns per step at 2e, and the three-failures-across-two-waves halt at 2j. The first and third read their state from STEP_FAILURES; the second counts re-spawns for the step in front of you.
Progress surface. Two surfaces carry it and neither is a tool. The plan file's checkboxes are the per-step record, ticked at Layer D and counted with grep -c '^- \[ \]', which is also what the Stop guard reads. Phase 2h prints the per-step table after each wave. Add one short line per phase and wave transition and that is the whole picture.
This setup runs with CLAUDE_CODE_ENABLE_TASKS=false in ~/.claude/settings.json, deliberately: the task tools' schemas cost roughly 2,500 tokens of context on every turn, and the two surfaces above already say everything a task list would. Do not write a procedure that depends on them.
Output length. Per-turn user-facing prose: at most 3 lines. The wave summary at 2f: at most 3 lines. Filter tool output before it lands: a passing test suite through tail -20, a diff scoped to the wave's files. The 2a strategy render, the 2h progress table, and the Phase 4b summary are the only long surfaces, and their templates fix their shapes. Anything a later reader needs goes in wisdom.md or report.md, not into the chat. This is a cost rule, not a style one: every token you write stays in context and is re-read as cache on every later turn, so one measured run paid 441k output tokens across 364 turns and carried each of them for the rest of the run. A file is read on demand; a sentence in the chat is read hundreds of times.
plan.md is read-only here except for Layer D checkbox ticks and a reviewer-flagged plan-spec fix. If the plan is
wrong, report and stop. Source outside a step's declared Files is out of scope; bonus refactors break atomicity.
Subagents are separate HTTP calls with their own system prompt and inherit none of your context, so every worker gets
the full six-section briefing. Drive every chain from here: the four plan-workers cannot spawn anything (their
tools: allowlist omits Agent), and the code reviewer plus ac:oracle have Agent denied so their retrieval
stays inside the budget you gave them. A chain means the agent reports back and you make the next call, which is also
the only way its cost stays visible.
| Call site | Class | Under AUTO_MODE = true |
|---|---|---|
| 2a Execute? | flow | auto-pick Execute |
| 2i Dep failed? | BLOCKER | surfaces |
| 2j Halted? (3 failures spanning 2+ waves) | BLOCKER | surfaces |
| 3c plan-spec issue | BLOCKER | surfaces |
| Wave checkpoint commit failed | BLOCKER | surfaces |
| Verification failed on a step a later wave needs | BLOCKER | surfaces |
Flow gates resolve to the (Recommended) option and emit one heartbeat line. BLOCKER gates surface whatever the mode,
because each needs judgment auto mode cannot supply: a dependency failure, three accumulated failures, a wrong plan, a
commit failure hiding repo state, or lost downstream work. Before surfacing one, emit a line naming which class fired.
AUTO_MODE stays set through a BLOCKER unless the user picks an option that stops the run.
Heartbeat: one short line per phase, wave, and iteration transition, and per auto-resolved gate.
Phase 1: Load Plan
1a. Parse arguments
- Strip
--autoflag if present →AUTO_MODE = true. Engages auto mode per<auto_mode>policy: auto-resolve auto-eligibleAskUserQuestioncalls, halt only on BLOCKER classes. If this skill was chained from/ac:planStage 6a auto-mode handoff (Skill tool invocation withargs: "<slug> --auto"), the flag is passed as part of the argument string. - Strip
--no-oracleflag if present →NO_ORACLE = true. Phase 3 spawnsac:oraclebeside the reviewer when the change touches one of the six criticality surfaces; this flag opts out of that. - Strip
--no-checkpoint-commitsflag if present →NO_CHECKPOINT_COMMITS = true. Disables wave-after commits; Phase 4 final commit still runs. - Resolve the remaining argument to
PLAN_PATH:- If it contains
/or starts with.ac/, use as full path. - Otherwise treat as slug:
.ac/plans/<slug>/plan.md.
- If it contains
- If
PLAN_PATHdoes not exist: printPlan not found at <path>. Run /ac:plan first.and stop. - If
AUTO_MODE = true, emit one user-visible line:Auto mode engaged. Will run end-to-end, halting only on BLOCKER classes (Phase 2i dep-failed, Phase 2j 3-strike, Phase 3c plan-spec issue, error-handling halts).
1b. Read and parse the plan
Read PLAN_PATH in full and hold: the frontmatter (Steps, Waves, Codebase State, Generated), ## Research Summary, ## Codebase Conventions including the TDD field,
## Reuse Map, ## Work Objectives (Core Objective, Concrete Deliverables, Definition of Done, Must Have,
Must NOT Have), ## Execution Strategy with its Dependency Notes, every step in ## Steps with all its fields,
and ## Risks Accepted. ## Tier Calibration is referential; read it once, do not re-read per step.
1c. Tier routing and escalation
| Tier | Subagent | Model | Effort |
|---|---|---|---|
quick |
ac:plan-worker-quick |
claude-haiku-4-5-20251001 |
not supported on this model |
junior |
ac:plan-worker-junior |
claude-sonnet-5 |
medium |
junior-high |
ac:plan-worker-junior-high |
claude-sonnet-5 |
high |
senior |
ac:plan-worker-senior |
claude-opus-5 |
high |
junior-high is junior's model at high effort, for work at the borderline of coupling or context depth. The
criticality rule never routes there; it escalates to senior.
When the plan's Codebase State is legacy or chaotic, route every quick step to ac:plan-worker-junior
whatever its declared tier: mechanical work in an inconsistent codebase is not mechanical, and Haiku has no effort
lever to compensate. The plan file is not modified; this is an in-memory routing decision. Record the count for the
Phase 4 report.
1e. Initialize execution state
ACCUMULATED_WISDOM = [] # max 15 items total, max 5 added per wave
MODIFIED_FILES = [] # tracked across waves; passed to Phase 3
STEP_FAILURES = [] # {step, wave} per failure; 2j asks whether they span 2+ waves
WORKER_RETRY_PER_STEP = {} # max 1 tier-escalation retry per step
No Phase 3 counters: the review is one pass and its outcome is appended to review-log.md as a record.
Then write .ac/state/active-execution.json. Three hooks read it: the file-scope guard scopes worker edits to
wave_files, the SessionStart hook names the active plan after a restart or compaction, and the Stop guard refuses
a turn end while it exists. Fields: slug, session_id (the real current one; it scopes the Stop guard to this
run), started_at (24-hour age bound), pid (advisory, write 0), current_wave, wave_files, note. Schema and
per-field reasoning at ${CLAUDE_SKILL_DIR}/references/execution-state.md.
Lifecycle: written here, refreshed at 2c and 2f, deleted at 4a and on every branch that ends the run early. A halt
that leaves it behind gets blocked by the Stop guard until its block budget is spent.
.ac/state/active-auto.json may coexist beside it. That marker belongs to ac:auto, not to this skill: never
delete it, and treat its presence only as the signal read at Phase 4a.
1f. TDD mode
Read the plan's ## Codebase Conventions for **TDD** and set TDD_MODE: "tdd" directs each worker to write the
failing test first, "tests-after" to write tests after implementation for any behavioral change, "none" to write
tests only when a step's Done when demands testable behavior. A missing field defaults to "none" and gets noted
in the Phase 4 report. The value is injected into every worker briefing.
Read project CLAUDE.md and CLAUDE.local.md for build, test, and lint commands as RUNTIME_CONTEXT. Workers
receive CLAUDE.md automatically; RUNTIME_CONTEXT supplements it with the explicit commands briefings cite.
1g. Confirm the progress surface
No list to register. Read Waves and Steps from the plan frontmatter and hold both: Steps is what every
Layer D count gets compared against, and WAVES is how many barriers the run will pass. State both in the
Phase 2a render so the shape of the run is visible from the start.
Then run the shape gate once:
Bash: node "${CLAUDE_PLUGIN_ROOT}/cli/ac.js" plan-check <PLAN_PATH>
It prints the step counts on every exit and, when the plan deviates from what the rest of this body parses, one
line per deviation. /ac:plan runs the same command at Stage 5, so a clean exit here is the normal case and a
dirty one means the plan was written by hand, written by an older version of the planner, or edited since. Route
by what it reports, taking the FIRST route below that matches, except that a BLOCKER route always wins over a
continue route on the same step:
- Exit 2: the plan file is not where you looked, which is a different problem from a malformed plan and has a
different fix. Re-derive
PLAN_PATHfrom the argument and try once; if it still fails, say the path you tried and stop. - Exit 0: continue. Hold the step counts it printed for Layer D; on a resume the unchecked number is what is left to run.
All <N> Step N headings are present, so the step lines are missing their prefix: repair, do not stop. Every step is in the file and only its checkbox is absent, so the plan is gaining a record it should already have rather than changing its spec. Insert one- [ ] **Step N**: <the heading's own title>line per step withEdit, keeping the space after the bracket because theStopguard greps for it, then re-runplan-checkand say in one line that you repaired it and how many lines you added. Layer D would otherwise have nothing to tick and the guard would read a permanently satisfied count, so both controls would retire silently.step(s) are absent from the body rather than merely unticked: the plan is truncated, not unticked. Do not invent checkboxes and do not correct the frontmatter down to what survived: either edit runs a plan that is missing most of its work while reporting success. Say how many steps are missing and stop.- A worker step with no
Tier, or a verification step with noCommandsorEvidence: a plan-spec defect rather than a formatting one. There is nothing to spawn or nothing to run, and picking a tier yourself substitutes your judgment for the planner's on a cost decision the plan was supposed to make. Take the 3c plan-spec BLOCKER branch, naming the steps and what each is missing. This wins over the next route. A step can report both an unrecognisedTypeand a missingTier, and routing it on its fields first would read a code step as a verification step, run itsCommands, tick its box, and never write the code. - A
Typeoutside the three, on a step this list has not already blocked: route on the step's fields instead of its label, and say in one line which steps you re-read and as what. A step carrying aTieris a worker step, becauseTieris meaningful on nothing else; a step carryingCommandsandEvidencewith noTieris a verification step.implementationis the value this actually produces and it maps tocode. - Any other ERROR (a missing
Files,Description,QAorMust NOT, a leftover placeholder, a missingAuto modeline): a plan-spec defect. The worker briefing inlines four of those five fields verbatim, so a step missing one sends a worker out with a hole in its contract. Take the 3c plan-spec BLOCKER branch and name the steps and fields. - A count mismatch the ticks do not account for: the frontmatter and the body disagree about how many steps exist. Say which two numbers you got and stop; every later Layer D comparison rests on this one, and a count compared against a wrong total confirms nothing.
WARN lines never gate the run. Say how many there were in one line and continue.
Phase 2: Execute Wave-by-Wave
Goal: run each step to verified completion, wave by wave, on auto-continue. The user sees progress through the plan file's checkboxes and the Phase 2h table; they do not approve each step.
2a. Present execution strategy
Render the wave breakdown once using the shape at ${CLAUDE_SKILL_DIR}/references/wave-orchestration.md under
## Phase 2a execution-strategy render: plan title and path, complexity, codebase state, TDD mode, totals, one line
per step per wave with its tier and files, the review routing, and whether checkpoint commits are on.
Then AskUserQuestion (header Execute?, options Execute (Recommended) / Adjust wave grouping / Cancel).
Adjust wave grouping takes a freeform follow-up, re-renders, and asks again. This is the only user gate inside
Phase 2; once execution starts, auto-continue applies until Phase 4 or a BLOCKER. Auto mode skips it and proceeds.
2b. Worker briefing template (the 6-section prompt)
Every worker invocation receives the 6-section briefing. For the exact template (with VERBATIM/DERIVED field annotations), read ${CLAUDE_SKILL_DIR}/references/worker-briefing-template.md.
The briefing is the worker's whole world. It no longer reads the plan, so Section 6 carries the step's pattern references, the codebase conventions, the invariants it must preserve and the plan-wide guardrails inline.
Resolve every sibling-step pointer before you send it. Measured across 1,914 steps, 23% of Descriptions
say things like "call Step 4's parser" or "same constraint as Step 10". Those resolved when the worker read
the plan and dangle now. Wherever the step's Description, QA or Must NOT names another step by number,
replace the pointer with what the worker actually needs: the sibling's Files path and a one-line statement
of the contract, or the file:line the thing will live at. A forward pointer to a step that has not run yet
is the dangerous case, because there is no source to fall back on. This applies to every plan, including the
ones written before the briefing changed. Assemble all four from the plan you are holding; anything you leave out, the worker cannot go and
find. Dropping the plan read saves roughly 8k tokens of subagent input per worker, which is where the cost
of a rich briefing is paid back.
Length rule: under 30 lines is too short; under-spec'd briefings produce drift. Copy the contract fields verbatim rather than paraphrasing, because paraphrase inverts opt-in and opt-out.
2c. Launch workers in parallel within the wave
Refresh the marker first: current_wave to this wave's index, wave_files to the union of every absolute path
in this wave's steps' Files. That set is exactly what the file-scope hook allows a worker to touch, so a path the
wave needs but does not declare cannot be written. The union has to be complete before any spawn.
Route on Type: code and infra spawn a tier-routed worker; verification does NOT spawn. Run its Commands
directly via Bash and capture to its Evidence paths. For a verification step Layer A blends with your Bash output,
Layer B is largely n/a, Layer C IS the evidence file, and Layer D still applies. A Type outside the three was
resolved at Phase 1g by reading the step's fields; use what 1g decided rather than re-deciding per step.
Check invocation reachability before the wave launches. When a step's Description tells you to run a slash
command, confirm you can: a component whose frontmatter carries disable-model-invocation: true is kept out of
your own list by design and can only be typed by the user. Read the component's frontmatter rather than grepping
the whole file, since several skills discuss the flag without setting it, and if it is set there, take the
plan-spec BLOCKER branch in 3c and say which command and which step. Do not quietly
substitute executing the command's body yourself: that tests the procedure and not the dispatch, which is a
different claim from the one the step is making.
Spawn every code and infra step of the wave in ONE message, one Agent block each, each with
run_in_background: true. Then wait for all of them before verifying any. Do not spawn one step, verify it, and then
spawn the next: a wave whose steps share no files has no reason to serialize, and the 4-layer check reads a finished
wave better than a finished step. A wave the plan declares as an ordered track (its Execution Strategy says the steps
must run in sequence) is the one exception, and there the steps run one at a time in the declared order.
Say which steps the wave is running in one line before the spawns, so a reader can follow without a task list.
2d. Wave verification (4-layer, runs once per wave)
Every worker in the wave has returned. Now verify, once, for the whole wave. You are the QA gate. Subagents lie. Automated checks alone are NOT enough.
The unit is the wave, not the step. One typecheck, one build, one test run, one git diff, one linter
pass for the wave, however many steps it held. The step-level record is Layer D's checkbox and the
per-step QA evidence in Layer C, both of which stay per-step because they are cheap and because
something downstream reads them.
Confirm no mutation survived. Run git status --porcelain in the same message as the diff and the
Layer A commands; it does not depend on their results and they do not depend on its.
The allowed set is wave_files (this wave's declared union, from 2c) plus MODIFIED_FILES (earlier
waves) plus anything under .ac/. A dirty path outside all three is an unreverted mutation or an
out-of-scope edit: restore it from git, and record it as a [REMEDIATION] wisdom line naming the step.
Compare against wave_files, NOT against MODIFIED_FILES alone: that list is only appended at 2e, after
this check, so at this point it holds the previous waves and none of the current one. Compare against it
alone and every file this wave legitimately changed reads as a mutation to be reverted.
What this catches is an out-of-scope mutation arriving through Bash, which the file-scope hook cannot
see because it gates Edit and Write. It does NOT catch the temporary patch a worker uses to prove
its test really fails (cp x /tmp/x.bak && perl -0pi -e ... && <test> && cp /tmp/x.bak x): that file is
inside the step's own Files, hence inside the allowed set. That technique is worth keeping anyway, and
the diff is what shows whether the patch survived it.
Ordering does not matter here, which is why it is batched. The diff is taken with a pathspec limited to
wave_files, so an out-of-scope mutation cannot enter it whether this check ran first or not.
Then take the wave diff, which is Layer B's input:
Bash: git add -A -- <wave_files> && git diff --cached -U8 -- <wave_files>
Stage first, and diff the index. A plain git diff shows nothing at all for a file the wave CREATED,
because an untracked path has no committed side to compare against: verified in this repository, where
git diff -U15 -- <new file> returns zero lines while git status --porcelain reports it as ??.
Without the staging step every file a wave creates is invisible to Layer B, and every claim its worker
made becomes a false "claim with no hunk" finding. Staging does not commit; 2g still decides that.
Measured on one 24-step run, the old per-step shape spent 261 Bash calls and 69 whole-file reads across 389 turns, with the same test suite running scoped per step, again at the barrier, and a third time in Phase 3. The wave suite is a strict superset of the scoped runs, so the scoped runs bought nothing that this shape does not.
This barrier is mandatory and cannot be skipped. It is now the only place a failure surfaces, which is the trade the per-step checks were dropped for.
Issue the wave's independent actions in ONE message. The mutation check, the diff, the typecheck, the build, the test run and the linter do not depend on each other's results, so they are one message with six tool calls, not six turns. Same for the wave's checkbox ticks in Layer D, and for the QA scenarios in Layer C that touch different surfaces. Batching is where the turn count actually falls: collapsing per-step work to per-wave cuts the number of CALLS, but only issuing independent calls together cuts the number of TURNS, and a turn on the plateau costs the whole resident context again. Serialize only where one call's output decides the next one's arguments.
Layer A: Automated
Layer A authority: when the changed files sit under a sub-project root (its own package.json AND tsconfig.json,
and not the orchestrator's cwd), that sub-project's local typecheck wins: cd <sub-project-root> && bun run tsc --noEmit or the language equivalent. The outer LSP runs against the outer repo's config and cannot resolve
sub-project deps, so its diagnostics on those files are Class 5 boundary noise. With no sub-project boundary, the
orchestrator's LSP is authoritative.
Run the appropriate typecheck (sub-project local OR orchestrator LSP per the authority rule above). Classify each diagnostic into one of six noise classes before deciding:
Classify every diagnostic into one of six noise classes before acting on it. The classes, with what each one looks like and how to tell a transient from a real error, are at
${CLAUDE_SKILL_DIR}/references/lsp-noise-classes.md. Classes 1 and 3 are transient and get re-run at the wave barrier; classes 2, 5, and 6 are persistent false positives that never block; class 4 is a real error and routes to Phase 2e. The plan's**LSP false-positive whitelist**field, when present, is the authoritative skip list.WARNING severity (regardless of class) is logged in Issues and continues.
Run the project's build command (from
RUNTIME_CONTEXTorCLAUDE.md). Exit code 0 required. For sub-project layouts: use the sub-project'spackage.jsonscripts (bun run build/npm run build/ etc.) inside the sub-project dir.Run the full test suite and the repo-wide linter, once, for the wave. There is no scoped per-step run: the wave suite covers every file the wave touched and more, so a scoped run before it is a check you are about to repeat. Verify once; do not re-run a check that already passed to build confidence. All tests must pass; pre-existing failures unrelated to the wave are noted, not blocking. For sub-project layouts use the sub-project's command (
bun test/npm test) inside the sub-project dir.Filter what the run admits into context, because a passing suite's output is noise you pay for on every later turn: pipe through
tail -20, or the runner's own quiet or summary flag. On failure, admit the failing cases and nothing else. A failure the wave suite catches that no single step explains is a cross-step interaction, which routes to remediation below rather than to one step's retry.
Layer B: Manual Code Review (read the wave diff, do not skip)
This is the layer you are most tempted to skip. Do not skip it. What changed is that you review the DIFF rather than re-reading whole files. The diff is the stronger instrument against a worker that overstates what it did: it is the delta itself, where a full read shows an end state and asks you to remember the before.
Read the wave diff taken above, hunk by hunk. Open a full file only on one of these four triggers, which are the whole list:
- the file was created by this wave, so there is no before to diff against;
- the file is under 150 lines, where reading it whole costs no more than reading its hunks;
- the diff carries deletion hunks, where what was removed matters as much as what replaced it;
- the step declares a contract in its
Referencesthat the hunk appears to change.
"When it looks ambiguous" is not a trigger. If you find yourself opening files outside this list, the plan's
Fileswere wrong and that is a finding, not a reason to read more.For each hunk:
- Does the logic actually implement the step Description?
- Are there stubs, TODOs, placeholders, hardcoded values that the step did not authorize?
- Are there logic errors or missed edge cases evident from the data flow?
- Does the change follow the plan's Codebase Conventions and
my-coding? - Are imports correct and unused imports removed?
Attribute every hunk, file first. Attribution is by FILE: each hunk belongs to the step whose
Filesdeclares that path, which is deterministic from the plan. Fall back to the workers'path:start-endclaims only when two steps of the same wave share a file.Line ranges cannot carry attribution on their own, and it is worth knowing why before trusting one. The wave's workers run concurrently in undefined order, so a worker inserting ten lines near the top shifts every range another worker reported; each is correct against the tree it saw and only the last writer's ranges survive into the final diff.
-U8also merges nearby regions into one hunk with two claimants, and nothing bounds a claim's width, so a singlefile:1-500would swallow the file.Then check the claims against the diff. Three outcomes, and the first two fail the step:
- a hunk in a file NO step declares: an out-of-scope write. The file-scope hook permits it because it
gates on the wave's union rather than on one step's
Files, so this check is the only thing that sees it. Treat as failed and route to 2e. - a claim the code contradicts: the worker described something it did not do. Treat as failed.
- a claim with no hunk, or a hunk no claim mentions, inside a file the step does own: a reporting gap, not a code defect. Record it and continue; a formatter the worker ran leaves exactly this.
- a hunk in a file NO step declares: an out-of-scope write. The file-scope hook permits it because it
gates on the wave's union rather than on one step's
Run the two checks the diff cannot give you, because duplication lives in files you were never going to open:
LSP findReferenceson each newly exported symbol, and one repo-wideGrepfor each new function name. A second definition of something the wave just wrote is the failure this catches, and neither the diff nor a whole-file read would have shown it.If you cannot explain what each hunk does in one sentence, you have not reviewed it. Read again.
Cross-file consistency check (mandatory whenever the wave produced two or more files that share an interface). The worker sees one file; you see the whole wave, and the wave diff is a better input for this than sequential single-file reads were, because every side of a shared boundary sits in one artifact. This is also the check that covers the diff's known weakness, that a hunk does not show what the surrounding code now does, so it is not optional just because the diff read quickly. Apply it to every shared-interface boundary the wave's files declare or consume, not just the first. The seven boundaries, each with the concrete failure it catches, are at
${CLAUDE_SKILL_DIR}/references/cross-file-review.md: shared data shapes, URL and path composition, component and function name match, template engine interop, front-matter is data not template, asset paths, link target reachability. Read that file at the first wave where the check applies.
Layer C: Hands-on QA (per step, run here at the barrier)
This layer stays per-step, because each step names its own scenario and its own evidence path, and the evidence is the only proof anything actually ran. What changed is when: run every step's scenario here, in one pass over the wave, rather than interleaved between spawns.
Skip the scenario for any step Layer B already failed. Its QA would exercise code that is about to be retried, so the evidence would describe work that no longer exists. Run it after the retry instead, alongside that step's re-verification in 2e.
When the step's QA field names a tool, run the scenario and gate it on four checks:
- Reproducer-validity: one command, fails on HEAD before the change (for a fix or regression step), deterministic across 3 runs, no external service that can flip the result. Mark a dimension n/a rather than skipping it.
- Evidence, not assertion: record the command AND its output, or an artifact path. A bare "verified" is not evidence.
- Lowest layer that proves it: a unit test beats an integration test beats an end-to-end run when all three would prove the same thing. Escalate only when the lower layer cannot reach the behavior.
- Browser as a human user: for any UI-touching step, walk it through the browser (navigate, interact, assert on
rendered state), not just
curl.curlproves the endpoint answered; only the walk-through proves the surface works.
Capture to .ac/plans/<slug>/evidence/<step-id>-<scenario>.<ext>: .png for a browser screenshot, .json for a
curl body, terminal output for a CLI or test run. Steps with no QA field, or QA: none, skip this layer.
Layer D: Plan state check (per step)
Run each step's provable Done when criterion first: the one command it names, batched into the same
message as the ticks. These are greps and single targeted assertions, not scoped suite runs, so a wave of
six costs one message. This is what the criterion was written to be, and running it is what stops the tick
from being a claim.
Tick each verified step's checkbox from - [ ] to - [x] with Edit, one edit per step. Confirm the wave's
ticks landed with grep -c '^- \[ \]' <PLAN_PATH> and check the number against what you expect, which is
the plan's total step count minus every step ticked so far. A count you do not compare against anything
confirms nothing. Do not re-read the plan to check: the plan runs to tens of thousands of characters and you already hold it from Phase 1b.
The tick stays per-step rather than batching with the rest of the wave, for a reason that is not
bookkeeping. The Stop guard derives "no progress" from this count falling between blocks
(${CLAUDE_PLUGIN_ROOT}/hooks/stop-guard.sh), and it latches permanently once no-progress fires under a
forced continuation. Batch the ticks to one edit per wave and a long wave shows the guard a frozen
count, which retires it for the rest of the run. It is also the only durable record of which steps
inside a wave finished, which the marker's current_wave cannot express after a restart.
2e. Verification outcome routing
Verification now runs per wave, so route per step off what Layer B attributed. A wave-suite failure or a Layer B finding belongs to the step whose claimed hunks explain it; a failure no step's hunks explain is a cross-step interaction and goes to 2f remediation, not to a retry. That attribution is what the per-step scoped test used to provide, and it is why Layer B's hunk-to-claim match is not optional.
All four layers pass: append the wave's files to MODIFIED_FILES and continue.
Worker reported [BRIEFING GAP]: it could not proceed because something Section 6 should have carried
was missing. Re-assemble the missing block and re-spawn at the SAME tier. Never escalate for this: the
tier is not what failed, and a bigger model reading the same absent block costs 5.9x for the same nothing.
Bounded at two. The re-spawn does not count against the one-retry-per-step budget, so it needs its
own bound or it is an unbounded loop: when the PLAN lacks the block rather than the assembly missing it,
re-assembly produces the same absent block and the worker reports the same gap, at $1 to $6 a spawn. On
the third report for one step, stop re-spawning and take the plan-spec BLOCKER branch in 3c: name it,
then AskUserQuestion (Edit plan to fill the gap and re-verify / Accept as Risk and proceed /
Stop). Two failed re-assemblies is the plan telling you it does not carry what the step needs.
First failure, attributed to one step: retry once at the next tier up (quick to junior, junior to senior; senior does not
escalate), except a malformed report with no ### Changes Made or ### Verification, which re-spawns at the
SAME tier with a format reminder because the tier is not what failed. The retry briefing leads with the failure
context, then repeats the original. One retry per step, ever.
Two fast paths skip the same-tier attempt: a worker flagging tier mismatch escalates immediately and the
mis-classification goes in the report, and a worker flagging [CONTRADICTION] does not retry at all,
because the next attempt hits the same structural conflict; mark it pending-remediation for 2f remediation.
A retried worker is not verified until you verify it. 2d ran once for the wave and the retry
spawned after it, so nothing has checked the retry's output. Before 2g commits: re-stage and re-diff
scoped to that step's Files, re-run Layer A, and re-run the attribution for that step. A commit that
includes an unverified retry is the failure this prevents.
Retry fails, or senior failed first: append {step, wave} to STEP_FAILURES and fire 2j at 3. Do not block the
wave on one failure unless 2i says a later wave depends on it.
2f. Remediation and wisdom
Runs after 2e, once every step has a terminal status (verified, failed, or pending-remediation). The
mutation check and the full suite both moved into 2d, which is the barrier now; what remains here is
what the orchestrator has to fix or record itself.
- Remediate what the orchestrator owns:
[CONTRADICTION]reports, cross-file findings
…(truncated)