@opengsd/gsd-path 1.0.0 → 1.2.0

package/skills/path/BUILD.md

@@ -3,6 +3,8 @@ name: gsd-path-build
 description: Execute or resume an approved GSD Path plan with isolated task worktrees, deterministic commits, and independent wave review. Use only when the user explicitly invokes $gsd-path-build or an active $gsd-path router explicitly routes to this phase.
 ---
 
+Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+
 # GSD Path Build Orchestrator
 
 Orchestrate coders, task landing, and reviewers from the main conversation.
@@ -22,23 +24,14 @@ rule; never invoke an explicit-only sibling skill yourself.
   marks an interrupted milestone-abandon transaction: resume the Milestone
   abandon procedure below before any recovery or dispatch. `build/done` is
   recovery-only: follow [Completion](#completion) instead of dispatching.
-- Read the local [coder role](references/coder.md),
-  [reviewer role](references/reviewer.md), [dispatch contract](references/dispatch.md),
-  [task template](templates/task.md),
-  [wave-review template](templates/wave-review.md),
-  [wave-panel template](templates/wave-panel.md), and
-  [skeptic template](templates/skeptic.md). Resolve them to absolute
-  paths before briefing agents. Resolve `scripts/review_panel.py` when
-  PLAN.md Config names a review panel. Resolve `scripts/review_findings.py`
-  for blocked-wave finding sets. Resolve `scripts/check_handoffs.py`
-  for Intent coverage. Resolve `scripts/pipeline_state.py` for guarded state
-  transitions. Resolve `scripts/isolation.py` for task isolation, recovery,
-  verify sidecars, task landing, and bookkeeping checkpoints; do not invent
-  `git worktree add`, `--detach`, commit, or cherry-pick commands. Resolve
-  `scripts/build_state.py` for the ready set, task reconciliation, the
-  landed-task proof, and the verify ledger
-  (`.project/build/verify-ledger.jsonl`, one JSON line per run: command,
-  commit, result, timestamp); do not select or reconcile tasks in prose.
+- Resolve the bundled `scripts/dispatch_driver.py`, `scripts/workflow_run.py`,
+  `scripts/pipeline_state.py`, `scripts/isolation.py`, and `scripts/build_state.py`.
+  Helpers own task selection, state, Git, and evidence. Use their receipts.
+- Read the [dispatch contract](references/dispatch.md) only when dispatching
+  native children or resolving host counters. Children read their assigned role
+  and template; the parent resolves those paths without loading their contents.
+  Load the task template only when writing or repairing a task. Load the
+  wave-panel and skeptic templates only when those branches apply.
 - There is no board file. Task frontmatter is the only task-state record;
   when a report or question needs a wave summary, render it inline from the
   task files and wave reviews. Record escalations and plan defects in the
@@ -107,6 +100,11 @@ rule; never invoke an explicit-only sibling skill yourself.
 checkpoint `.project/` records uses this helper. Record the exact full HEAD
 before the first metadata change in that checkpoint, then run:
 
+Explicit configuration edits in `.project/config.json` and
+`.project/model-policy.json` are expected bookkeeping. Include them in the next
+normal checkpoint before a clean dispatch base; they may remain pending while
+an already dispatched task lands. Existing model selections stay pinned.
+
 ```text
 python3 <absolute isolation.py> checkpoint \
   --repo <absolute primary> \
@@ -128,573 +126,54 @@ brief unless the canonical `build: abandon milestone <slug>` checkpoint moves
 that same brief into `.project/archive/`; build adds fix tasks and repairs
 briefs, it never replans.
 
-## Wave loop
+## Execute from runtime receipts
 
-For each `## Wave N` in PLAN.md order (a wave's tasks are the task files whose
-`wave` equals N):
-
-**Dispatch driver.** Steps 1–5 below are deterministic, and the bundled
-`scripts/dispatch_driver.py` runs them: recover, settle exited coders, the
-bookkeeping checkpoint, `ready`, brief lint, `prepare-task`, `activate-task`,
-one child per ready task, then Verify in the isolate, Log append, `land`,
-`verify-record`, and `retire` in task-id order. Prefer it whenever the owner
-supplies a child command (a headless CLI that reads the brief on stdin, for
-example `claude -p --output-format json ...` or `codex exec --json ...`; the
-owner's flags own the child's permissions):
+For each wave in PLAN.md, use the existing dispatch driver when the owner has
+supplied a child command. Preserve that command and its permission flags; never
+invent a headless command or widen permissions to enable the driver.
 
 ```text
 python3 <absolute dispatch_driver.py> round --repo <absolute primary> --wave <N> \
-  --child-command '<owner command>' [--wait <owner seconds>] \
-  [--child-timeout <owner seconds>]
+  --child-command '<owner command>'
 ```
 
-`round` owns the entry transition described in Preconditions and branch
-binding, checkpointed as `build: start milestone`, and sets `build/blocked`
-on a dependency deadlock or a blocked
-recovery; every other stop stays with the parent. Act only on its receipt:
-`done` means every wave task landed — run
-`review --wave <N> --cycle <C> --child-command '<owner command>' [--wait
-<owner seconds>]` for step 6 at `full` or `deep` depth: it records the clean
-review base, creates one verify sidecar per lens, briefs one reviewer child
-per lens with every task's base and landing commit, validates each file in
-its sidecar, copies it to the canonical path, retires the sidecar, and only
-after every lens settles concludes: a passing cycle with no panel is
-checkpointed; with a panel configured (`panel_required: true`) run `panel
---wave <N> --cycle <C> --advertised <slugs> [--parent-slug <slug>]
---child-command '<owner command with {model}>'`, which resolves the panel,
-persists a skipped receipt or runs one panelist per family in its own
-sidecar, merges the family files, and makes the single on-pass checkpoint;
-`blocked` returns the `review_findings.py collect` grouping; when its
-`skeptic_groups` is non-empty, `skeptics --wave <N> --cycle <C>
---child-command '<owner command>'` runs one read-only skeptic per locator in
-its own sidecar at the review base, validates and collects each file, and
-reruns the helper; then `fix-tasks --wave <N> --cycle <C>` writes one
-lint-clean fix task per batch carrying the failed criteria and observations
-verbatim, or returns `escalate` for structural blockers, skeptic groups, the
-cycle cap, or an all-refuted ruling, which stay with step 7 and the user.
-The driver never writes a `verify-only` file (`status: not-applicable`);
-`in-flight` means call `round` again; `question` means answer from the
-approved artifacts or the user, record it with `answer --task-id <id>
---answer '<answer> — <citation>'`, and call `round` again, which redispatches
-the retained isolate; `blocked` names the task, reason, and output and leaves
-the isolate in place — apply the recovery, retry, or plan-defect procedure in
-steps 1–2 by hand, then call `round` again. The driver counts dispatches per
-task per milestone and stops at `--max-attempts` (default 2: the first
-dispatch plus this contract's one logged redispatch); owner token limits, when
-supplied, gate every dispatch through the milestone's budget ledger. Do not repeat a step the receipt
-already proves. Without a child command, dispatch through the runtime
-dispatch contract and perform steps 1–5 by hand.
-
-1. **Recover before dispatch.** Run `python3 <absolute isolation.py> recover
-   --repo <absolute primary>`. It is read-only and proves every `done` task's
-   landing commit from its exact stamped base (first-parent scan for
-   `<task-id>: <task title>`, body `Task:`/`Base:`/`Files:`, the base task's
-   declared path allow-list from the task file at that base, exact landing
-   metadata, append-only task-file body, and
-   patch equality with a retained task branch). Pending and `in-progress`
-   tasks bypass landing-history proof and report retained resume state or
-   `none`; failed and blocked tasks with retained isolation report
-   `reconcile`. Act only on its verdicts;
-   do not re-derive them in prose, rerun Verify on a proven commit, use an
-   unanchored log grep, infer a SHA from `done`, or reset unknown work.
-   - `attested`: an owner ruling stands in for the landing commit (see the
-     block escalation below); treat it as landed and never redispatch.
-   - `recovered`: the task is landed (`land` already stamped `status: done`
-     and `base`). Retire a still-present task worktree with `isolation.py
-     retire` only when the report shows it present, clean, and on the task
-     branch. If only `task_branch` remains, finish its proven interrupted
-     retirement with `retire --branch <task_branch> --force --landed-commit
-     <commit>`; both absent is valid.
-   - `resume`: continue from the returned `base`, `task_branch`, and worktree
-     (the primary itself when no task branch exists); when the report shows
-     the worktree absent, return the task to `pending` only when ownership is
-     clear. When `dispatch_retry` is true, reuse the returned clean isolate,
-     write fresh dispatch metadata and agent there, then dispatch; do not
-     recreate it. When `landing_retry` is true, do not resume implementation
-     or redispatch; rerun `land` against the returned isolate and base.
-   - `reconcile`: do not resume implementation. Preserve the returned isolate
-     evidence and follow the failed/blocked reconciliation in step 2.
-   - `block` on a `done` task with reason `done but no landing commit proves
-     it` or `done task has invalid base`: the work was committed outside
-     `land`. Never repair history or task frontmatter by hand. Set
-     `build/blocked`, present **Outcome** naming every such task, and ask the
-     user for a ruling per task; put any suggested ruling text in its own
-     fenced code block so it pastes cleanly. On an explicit ruling, run that task's Verify
-     at HEAD, record it with `python3 <absolute build_state.py> verify-record
-     --repo <absolute primary> --command <task Verify> --commit <HEAD>
-     --result pass`, then run `python3 <absolute isolation.py> attest --repo
-     <absolute primary> --task-file <task file> --ruling <ruling verbatim>`
-     (add `--base <SHA>` only to repair an abbreviated or invalid recorded
-     base). The helper stamps the task and creates the attestation commit
-     itself; each one moves HEAD, so attest tasks one at a time and rerun
-     `recover` afterwards.
-     - Rewritten lineage: when every `done` task is rejected with `commit does
-       not descend from its Base:` after a rebase or replay, the owner may run
-       `python3 <absolute isolation.py> adopt-rebase --repo <absolute primary>
-       --original-head <preserved original tip> --head <HEAD> --ruling
-       "<ruling verbatim>"`, commit the receipt
-       `.project/build/rebase-adoption.json` as `.project/` bookkeeping, and
-       rerun `recover`. The original lineage must stay reachable: keep a local
-       branch on the old tip until the milestone ships. Adopted tasks report
-       `attested` with `provenance: owner-authorized-rebase`.
-   - `block` for any other reason: set `build/blocked` with the returned
-     reason and stop.
-   - `none`: take no recovery action for that task.
-
-2. **Prepare the ready set.** Run `python3 <absolute build_state.py> ready
-   --repo <absolute primary>`. It is read-only: it validates every task's
-   frontmatter against its dispatch metadata and the recovery report, then
-   returns `ready` — the current wave's `pending` tasks whose dependencies are
-   all `done`, each with `id`, `title`, `deps`, `files`, `task_file`, and
-   `verify_heavy` — after proving that ready and `in-progress` tasks have
-   disjoint `files`. Dispatch exactly the tasks it returns; do not select,
-   order, or overlap-check tasks in prose. Readiness is continuous, not
-   layered: a task becomes selectable the moment its last dependency lands,
-   even while unrelated tasks still run, so rerun `ready` after each landing.
-   A `NEEDS-ORCHESTRATOR` block stays unselectable until its `Orchestrator
-   answer` is recorded in the task Log and the task is back to `pending`.
-   Its typed errors are the recovery rule:
-   - `task-recovery-required`: for each listed failed or blocked task run
-     `python3 <absolute build_state.py> reconcile --repo <absolute primary>
-     --task-id <id>` and act on its `classification`. `proven-landed`: the
-     task already landed at `landed_commit` and its frontmatter is stale —
-     reconcile the task file to that landed state and checkpoint it.
-     `resumable` or `reconcile`: apply the retry procedure below with the
-     returned `history.candidates` as the rejected evidence. `blocked`: set
-     `build/blocked` with the returned `reasons` and stop.
-   - `dependency-deadlock`: set `build/blocked` with its `tasks` list and stop.
-   - `ready-file-overlap` or `invalid-task-state`: a documented plan defect or
-     drifted bookkeeping; repair it before a new clean base.
-   A documented plan
-   defect may be repaired against INTENT.md and SYNTHESIS.md and logged before
-   a new clean base. A repair edits only the fields the lint or ruling named
-   in the tasks it named — `files`, Verify, Interface contract text, Intent
-   coverage rows, an ambiguous AC. It never adds, removes, splits, merges, or
-   renames tasks, moves a task between waves, or rewrites another task's
-   acceptance criteria; a defect that needs any of those sets `build/blocked`
-   with the lint output and returns to plan, which owns the task inventory.
-   A user ruling that changes a success criterion,
-   constraint, or veto is not a plan defect: set `build/blocked`, do not
-   rewrite the AC, and send `$gsd-path-define` to append INTENT.md
-   `## Corrections` before plan re-gates. A task Log is not that record. One failed implementation gets one logged redispatch when
-   its contract remains valid. Repeated failure, ambiguous ownership, a user
-   ruling, or a dependency deadlock sets build state to `blocked` and stops.
-   Concurrent tasks must have disjoint `files`; serialize overlapping fix
-   tasks. A retry never reuses a rejected dirty worktree: first copy its
-   validated append-only task Log delta into the primary task file, record the
-   rejected diff's exact path set and hash, and checkpoint the block bookkeeping.
-   After confirming every old change is task-owned, retire that exact worktree
-   with `python3 <absolute isolation.py> retire --repo <absolute primary>
-   --worktree <path> --branch <task_branch> --force --task-file <task path>`,
-   then create the retry. If retirement was interrupted after removing the
-   worktree, rerun the same command; the recorded failed or blocked task and
-   its exact base prove the remaining branch before deletion. Create the retry
-   from the new clean primary HEAD. After
-   resolving a recoverable `build/blocked` condition, use
-   `pipeline_state.py transition` with the blocked state and bound branch as
-   expected fields to set `build/active` and log the resolution. Checkpoint it
-   through the bookkeeping rule before recording that new dispatch-round base.
-
-3. **Isolate every task.** Checkpoint pending bookkeeping through the rule
-   above, then record clean `HEAD` as
-   this dispatch round's base — tasks dispatched in the same round share it;
-   a later round unlocked by fresh landings records the later HEAD — and
-   lint every ready task's brief with the bundled
-   `scripts/check_task_briefs.py --repo <absolute repo root> --base <recorded
-   base>` and re-check Intent coverage with
-   `python3 <absolute check_handoffs.py> plan --repo <absolute repo root>`
-   before creating any worktree; a lint or coverage failure is a documented plan
-   defect — repair it against INTENT.md and SYNTHESIS.md, then re-establish
-   the base. Then isolate each ready task with
-   `python3 <absolute workflow_run.py> prepare-task --repo <absolute primary>
-   --expected-head <recorded base> --task-id <id> --round-size <N>` where N is the
-   number of tasks in this dispatch round. Serial (`N=1`) returns the primary
-   worktree and `task_branch: null` — the coder works on the bound branch.
-   The runner also creates a named verification sidecar at this clean base
-   before dispatch. Retain both helper results in the dispatch evidence.
-   Parallel (`N>=2`) creates a named `gsd-path-task/<id>` branch and linked
-   worktree at that base; never a detached HEAD. Record dispatch through
-   `python3 <absolute isolation.py> activate-task --repo <returned worktree>
-   --base <recorded base> --task-id <id> --agent build_<id> --task-file
-   <exact selected task-file path> [--task-branch <returned task_branch>]`.
-   The helper sets `base`, `worktree`, `task_branch`, `status: in-progress`,
-   and `agent` in the isolated task and records parallel build authorization.
-   Do not edit those fields directly. Do not commit this dispatch state: it lands
-   inside the task's own commit, and `recover` derives it from the task
-   branch and worktree meanwhile. The primary stays clean during a parallel
-   round. Do not append a dispatch Log entry: the isolated task later appends
-   at that location, and two parallel appends make the cherry-pick ambiguous. Reuse a retained worktree only when
-   its recorded base, branch, and task agree exactly.
-
-4. **Dispatch the round.** Following the local runtime dispatch contract,
-   spawn one implementation-capable child per task with deterministic logical
-   task name `build_<task_id>`.
-   Its brief contains the absolute isolated-worktree root, coder role, task
-   file, task template, and the absolute INTENT.md path in that worktree.
-   Add no hidden implementation context; repair a
-   defective task contract before establishing the round base. Run ready work
-   up to capacity. Verify commands marked `Heavy: yes` (`verify_heavy` in the
-   ready set) run one at a time across every concurrent task, including the
-   step 5 rerun; light ones are unconstrained. Do not wait for the whole
-   round before unlocking dependents: each task landing in step 5 re-opens
-   step 2, and a newly ready
-   task dispatches in a fresh round at the current clean HEAD while unrelated
-   tasks still run. The wave advances to review only when every wave task is
-   `done`.
-
-5. **Verify and land serially as results arrive.** A coder returns only
-   `ready` or `blocked`; it never owns frontmatter or Git. Process each
-   completion when it lands — never wait for slower in-flight tasks first;
-   when several results wait, land them in task-id order.
-
-   - For `ready`, compare the complete worktree diff to `base`. Permit only
-     declared `files` plus append-only Log changes in that task file. Include
-     additions, deletions, renames, and binary changes; an unexpected path
-     blocks before any product commit.
-   - For serial work, reproduce the validated complete task patch, including
-     untracked additions, in the pre-created verification sidecar. Keep the
-     primary patch intact. Check its product diff against the primary task
-     diff before verifying; retire the sidecar through `isolation.py retire`
-     after preserving its evidence and removing only those reproduced changes.
-     Parallel work uses the task's existing isolated worktree.
-   - Run the task's Verify command in that isolated worktree. This rerun is the
-     authoritative task evidence; a command run in the primary or a sibling
-     worktree never counts. Append its exact result to the task Log. After
-     `land` returns, when `git rev-parse <landed commit>^` equals the
-     recorded `base` the landed tree is the verified tree: record the run
-     with `python3 <absolute build_state.py> verify-record --repo <absolute
-     primary> --command <task Verify> --commit <landed commit> --result
-     pass`. The ledger is `.project` bookkeeping; the next checkpoint
-     commits it.
-   - Land with
-     `python3 <absolute isolation.py> land --repo <absolute primary>
-     --source <isolated worktree> --base <recorded base> --task-id <id>
-     --title <task title> --task-file <task path> --allow-path <each declared
-     file>`. Do not invent commit or cherry-pick commands. For a serial round,
-     the primary must still be on the bound branch at the recorded base. A
-     non-zero exit reports the exact landing failure, such as an unexpected
-     path, base or branch mismatch, invalid task proof, conflict, or empty diff.
-     On conflict the helper aborts and leaves the primary clean on the bound
-     branch. Never leave task landing in progress.
-   - `land` stamps `status: done`, `base`, and null `worktree`/`task_branch`
-     into the task frontmatter and records `Base:` in the commit body, so the
-     product commit is the task's only commit; there is no `commit`
-     frontmatter field — `recover` proves the SHA from git. Do not write a
-     separate bookkeeping commit. Retire the isolate with
-     `python3 <absolute isolation.py> retire --repo <absolute primary>
-     --worktree <isolated worktree> [--branch <task_branch>]`. Serial rounds
-     return `retired: false` and leave the bound branch untouched. Each
-     completed task landing re-opens step 2: dispatch newly
-     ready dependents in a fresh round at the current clean HEAD instead of
-     idling behind unrelated in-flight tasks.
-   - A block whose Log delta leads with `NEEDS-ORCHESTRATOR:` is a contract
-     question, not a failure. When the approved artifacts (PLAN.md,
-     INTENT.md, SYNTHESIS.md, and the Interface contracts of every involved
-     task) pin exactly one answer, append `Orchestrator answer: <answer> —
-     <artifact citation>` to the task Log, return the task to `pending`,
-     checkpoint the bookkeeping, and let a later layer redispatch it; a question
-     redispatch never consumes the failed-implementation redispatch. When the
-     runtime's structured layer exposes a blocking ask/reply channel, relay
-     the answer through it with the worker held alive per the runtime
-     dispatch contract instead of redispatching. A dispatch-driver question
-     keeps the isolate active: record the answer with `dispatch_driver.py
-     answer`, and the next `round` redispatches that same isolate. When
-     the artifacts admit more than one reading, ask the user through an
-     interactive user-input tool when available, record the ruling verbatim
-     as the answer, and repair the task contract as a documented plan defect
-     when the ruling changes it — except a ruling that changes a success
-     criterion, constraint, or veto, which follows the define-Corrections
-     path above. A question block creates no product commit
-     and preserves the isolated worktree under the same retirement rule. Before
-     changing its canonical bookkeeping, revoke a parallel isolate's active
-     dispatch with `python3 <absolute isolation.py> deactivate-task --repo
-     <isolated worktree> --task-id <id> --task-branch <task_branch>`.
-   - A blocked report, invalid diff, or failed Verify creates no product
-     commit. Validate and copy the isolated task's append-only Log delta once;
-     it is the coder's sole block/implementation narrative. Add orchestrator
-     evidence only for a distinct diff or Verify rejection. Before changing the
-     task to `blocked` or `failed`, revoke a parallel isolate's active dispatch
-     with `python3 <absolute isolation.py> deactivate-task
-     --repo <isolated worktree> --task-id <id> --task-branch <task_branch>`.
-     Then update and checkpoint the bookkeeping and apply the recovery
-     rule. Preserve the isolated worktree unless and until the explicit clean
-     retry-retirement procedure in step 2 owns and removes it.
-
-6. **Review the wave.** The build orchestrator owns wave reviews; ship never
-   runs them. Only after every wave task is done, read the wave's
-   `Review depth` from PLAN.md (default `full`). At `full` or `deep` the
-   dispatch driver's `review` action performs the sidecar, brief, validate,
-   collect, and retire work of this step; perform it by hand only without a
-   child command.
-   - `full`: spawn one independent reviewer using deterministic logical task
-     name `review_wave_<wave>_cycle_<cycle>`. Supply every task path, its
-     recorded base and proven landing commit, the reviewer role, and
-     wave-review template, and the absolute INTENT.md path.
-     When INTENT selects quick lane and PLAN has one full wave, also assign
-     final scope: supply PLAN.md's Surface contract and the recorded review HEAD.
-     The same reviewer checks all success criteria and any remaining walkthrough
-     in this pass, records `Review scope: final` and `Reviewed HEAD`, and adds
-     Surface/Check/Observed fields to each surface criterion. Reuse recorded
-     command evidence when it already proves the named walkthrough; execute
-     only missing checks. Ship can then derive FINAL.md without another reviewer.
-     Record current clean primary HEAD as the review collection base. Create
-     a fresh review sidecar there; the serial task verification sidecar belongs
-     to the earlier task base and cannot be collected after landing.
-     Use `python3 <absolute isolation.py> isolate-verify --repo <absolute primary>
-     --base <recorded review base> --name wave-<N>-cycle-<C>`. Each task's
-     recorded base and landing commit still define its isolated review diff.
-     Keep primary HEAD fixed until collection completes. Brief the
-     recorded isolated Verify output per task (the Log entry the
-     orchestrator appended at landing). The reviewer must not re-run that
-     command or PLAN.md's project Verify. The reviewer
-     stages `.project/review/wave-N.cycleC.md` there; the
-     orchestrator validates it, atomically copies it to the primary canonical
-     path, and only then retires that sidecar with `retire`.
-   - `deep`: spawn two independent reviewers in parallel, each with a fresh
-     isolated context and its own verify sidecar from `isolate-verify` at the
-     recorded review base (`--name wave-<N>-cycle-<C>-contract` and
-     `wave-<N>-cycle-<C>-adversarial`). Supply both every task path, its
-     recorded base and proven landing commit, the reviewer role, and the
-     wave-review template, and the absolute INTENT.md path. The contract lens —
-     logical task name `review_wave_<wave>_cycle_<cycle>_contract` — does the
-     full review: apply each task's `commit^..commit` product patch to the
-     recorded base, check the recorded Verify plus the isolated diff, and
-     check every acceptance criterion,
-     owned INTENT success criterion, and interface contract. The adversarial
-     lens — logical task name
-     `review_wave_<wave>_cycle_<cycle>_adversarial` — tries to kill the work:
-     security holes, unhandled edge cases, failure modes, data-loss and
-     concurrency risks, and missing error handling. Each stages its own file
-     in its own worktree — `.project/review/wave-N.cycleC.contract.md` and
-     `.project/review/wave-N.cycleC.adversarial.md`; the orchestrator validates
-     each, atomically copies both to their primary canonical paths, and only
-     then retires those sidecars. The wave passes only when both lenses
-     return `pass`; any `blocked` lens blocks the wave, and both files'
-     findings feed the fix-task batching in step 7.
-   - A review file is written only during that cycle, at that cycle's recorded
-     base, by the writer the selected depth names: a dispatched reviewer at
-     `full` or `deep`, or the orchestrator at `verify-only`. Never backfill,
-     split, rename, or reconstruct a review file for a cycle that already ran,
-     and never write a placeholder verdict for a task that did not exist at
-     that cycle. A missing or non-canonical earlier artifact is reported to
-     the user; the
-     only repair is a new review cycle at the current HEAD, which counts
-     toward the cap.
-   - `verify-only`: spawn no reviewer. The orchestrator writes
-     `.project/review/wave-N.cycleC.md` itself from evidence it already
-     holds — per task, the Verify evidence and the declared-files diff
-     check — recording `Depth: verify-only`. Same command, same commit
-     reuses the recorded pass: the task's Verify evidence is the ledger
-     entry when `python3 <absolute build_state.py> verify-lookup --repo
-     <absolute primary> --command <task Verify> --commit <landed commit>`
-     returns `reuse: true`; otherwise run the command in an
-     `isolate-verify --historical-task <task id>` sidecar at that commit, record it with
-     `verify-record`, and use that result. A re-review after a fix cycle
-     follows the same rule. It checks each acceptance
-     criterion and each INTENT success criterion owned by the wave's tasks
-     against that evidence and the diff; anything it cannot
-     confirm from them is a finding, not a pass. Never spawn a review panel
-     at `verify-only`.
-   - After the canonical inherit reviewer (or orchestrator-written
-     `verify-only` file) is collected, run the optional review panel only
-     for `full` and `deep`. Inspect advertised model slugs and run
-     `python3 <absolute review_panel.py> resolve --plan <absolute PLAN.md>
-     --intent <absolute INTENT.md> --advertised <comma slugs>
-     --parent-slug <current model slug when known>` and `--charter
-     <absolute .project/CHARTER.md>` when that file exists. `status: off`
-     continues with no current-cycle panel artifact. For `skipped`,
-     persist the helper's exact JSON stdout as
-     `.project/review/wave-N.cycleC.panel.skipped.json` and continue without
-     a panel; do not translate or summarize the receipt. Exit 2 / `error`
-     blocks the wave. `ready` requires that skipped-receipt path to be absent,
-     then spawns one child per selected family with
-     logical task name `review_wave_<wave>_cycle_<cycle>_panel_<family>`,
-     the reviewer role in wave-panel mode, the wave-panel template, and the
-     exact helper-returned model slug when the host advertises model
-     selection. On `deep`, each panel brief is the adversarial lens only.
-     Never override the model on the canonical reviewer. Each child stages
-     its family file in its own verify sidecar from `isolate-verify`
-     (`--name wave-<N>-cycle-<C>-panel-<family>`); the parent validates
-     those files and runs `python3 <absolute review_panel.py> merge --kind
-     wave --wave <N> --cycle <C> --inputs <family files> --output
-     <absolute .project/review/wave-N.cycleC.panel.md> --mode
-     <detected|named>`. The inherit reviewer remains the only Wave verdict.
-     Do not average panel findings into that verdict or auto-create fix
-     tasks from preference findings.
-   - After the canonical inherit reviewer file (and each deep lens file) is
-     on the primary path, run
-     `python3 <absolute check_handoffs.py> wave --repo <absolute primary>
-     --review <canonical wave-review path>`. A non-zero exit is a blocked
-     wave, not a pass, including `verify-only`. Do not advance on helper
-     failure.
-
-7. **Fix or advance.** A valid canonical `pass` advances unless an
-   actionable review-panel finding is waiting for a user ruling. On
-   `blocked`, run `python3 <absolute review_findings.py> collect --repo
-   <absolute primary> --wave <N> --cycle <C>`, adding one `--helper-failure
-   "<helper and stderr>"` per bundled helper that exited non-zero in this
-   cycle. The helper alone reads PLAN.md Config (`max_review_cycles`,
-   `finding_skeptics`, `wave_budget`), the cycle's lens files, and every
-   skeptic file of the wave; it groups blocking findings by criterion
-   locator, collapses true duplicates, carries earlier refutations forward,
-   separates structural blockers, batches fix groups by disjoint file scope,
-   and reports `cap_reached`. Exit 2 blocks the wave. Never regroup,
-   re-derive a locator, or re-decide refutation in model reasoning; act on
-   the result in this order:
-   - `structural_blockers` non-empty: a missing or invalid lens, panel, or
-     skeptic artifact, a helper failure, or a finding that names no
-     contract criterion never enters skeptic filtering. Keep it blocking
-     through the ordinary blocked-wave handling — a fix task when applicable
-     or `build/blocked` escalation otherwise.
-   - `cap_reached` true: skip every branch below and use the cycle-cap
-     escalation at the end of this step.
-   - `skeptic_groups` non-empty: spawn one independent read-only skeptic
-     per listed locator, concurrently up to the advertised child capacity,
-     with logical task name
-     `review_wave_<wave>_cycle_<cycle>_skeptic_<criterion_locator>`, the
-     reviewer role in skeptic mode, the skeptic template, and its own verify
-     sidecar from `isolate-verify`
-     (`--name wave-<N>-cycle-<C>-skeptic-<criterion_locator>`) at the
-     recorded review base. Brief each with the group's `locator`,
-     `criterion` verbatim, every `observations` entry verbatim, the group's
-     `tasks` files, their recorded bases and proven landing commits, and the
-     absolute INTENT.md path. Each skeptic stages
-     `.project/review/wave-N.cycleC.skeptic-<criterion_locator>.md` in its
-     sidecar; validate each against the skeptic template, atomically copy it
-     to the primary canonical path, then retire that sidecar. Rerun the
-     helper; a locator refuted in an earlier cycle never gets a second
-     skeptic, and the helper already routes it.
-   - `all_refuted` true: stop and ask. Present **Outcome** with the blocked
-     verdict and the refutation count, **Review** linking the lens and
-     skeptic files, and **Next** listing `Re-run the review cycle with the
-     skeptic files in the reviewer briefs (recommended — no finding survived
-     scrutiny)` first, then `Open fix tasks from the findings anyway (an
-     explicit ruling that overrides their refutations)`. A selected re-run
-     consumes a cycle. After the user selects either option, record exact
-     full HEAD, then use `pipeline_state.py transition` with the exact
-     current phase, status, branch, and archive as expected and unchanged
-     phase/status as the result. Append `wave <N> cycle <C> all-refuted
-     ruling: <selected option verbatim>` to the STATE.md Log and require the
-     returned position to remain `build/active`. Checkpoint STATE.md and the
-     collected skeptic artifacts through the Bookkeeping checkpoint rule with
-     subject `build: record wave <N> cycle <C> skeptic ruling`, body `Why:
-     persist the all-refuted user ruling before acting`, and `Wave: <N>`. Do
-     not start the selected review cycle or create, batch, or dispatch fix
-     tasks until the checkpoint returns its commit. When the persisted ruling
-     selects `Open fix tasks from the findings anyway`, the override set is
-     every `refuted_groups` locator with its preserved `observations`; its
-     governing refutation is the group's `skeptic` entry (the current
-     cycle's file, or the earlier cycle's file for a same-evidence repeat).
-     Add that set to `fix_groups` for batching. No other ruling re-admits
-     refuted groups. Preserve their skeptic verdicts and eligibility
-     history. After a crash, resume the recorded choice without asking
-     again.
-   - Otherwise batch `fix_batches` into complete fix tasks from the task
-     template — one task per batch, never one per finding — each carrying
-     its groups' failed criteria and observed evidence verbatim. A group
-     with `repeat` true is evidence its earlier fix failed, never a new
-     finding; a re-review never spawns a duplicate fix task for a finding
-     already carried. Write each fix task to `.project/tasks/` with `wave`
-     set to the current wave or a newly appended `## Wave N` heading in
-     PLAN.md before dispatch. Its dependencies include every source task in
-     the batch; its files match the batch. In `## Review findings`, use one
-     `### <locator>` block per group, `Criterion: <verbatim criterion>`, and
-     every observation verbatim. Run the repair through the same isolated
-     layer loop, even when its appended wave repairs an earlier blocked wave.
-     After landing, call `review_findings.py repair-evidence --repo <primary>
-     --wave <source wave> --cycle <source cycle> --task <repair id>` and save
-     its JSON as the repair evidence for the next review. The helper validates
-     the carried batch, original and repair landings, isolated product scope,
-     unchanged source reports and reusable Verify. On success, brief the next
-     original-wave review with this receipt and the reviewer role's
-     **Re-review after a proven repair** contract. Reuse command evidence;
-     the new review judges the repaired product against the original criteria.
-     Preserve prior verdicts and source tasks. On helper rejection, resolve
-     the evidence blocker rather than redispatching an already proven fix.
-   At the cap, record all attempts in the STATE.md log and ask the user —
-   through an interactive user-input tool when available — after linking
-   the resolved absolute blocking wave review, every deep lens file for the
-   cycle, and every skeptic file collected for the wave, plus the STATE.md
-   attempt log. Ask whether to redirect the approach, raise the cap, or send
-   define to amend INTENT.md `## Corrections` — never rewrite an AC from a
-   Log waiver — or, in program flow (ROADMAP.md exists), to abandon the
-   milestone under the Milestone abandon procedure — listing the
-   orchestrator's recommended option first marked `(recommended)` with a
-   one-line reason drawn from the review evidence. Never choose silently.
-   When the canonical verdict is `pass` and `wave-N.cycleC.panel.md` reports
-   `Actionable` greater than 0, do not advance silently: present **Outcome**
-   with the canonical pass plus the actionable count, **Review** linking the
-   panel file, and **Next** listing `Open fix tasks from panel findings
-   (recommended)` first, then `Advance and keep panel findings as warnings`.
-   Preference-only panel warnings do not block advance. On pass, checkpoint
-   the review artifact, the panel file when present, STATE.md, and wave
-   bookkeeping, then report `wave N/M done, C review cycle(s)`.
+`round` owns entry transition, recovery, ready-set checks, brief lint, isolation,
+child dispatch, authoritative Verify, landing, ledger, retirement, and bookkeeping.
+Do not replay those steps or rewrite their results in another report.
+
+| Receipt | Next action |
+|---|---|
+| `in-flight` | Resume the same action to collect its existing children. |
+| `done` from round | Run `review` with the same repo, wave, child command, and the current cycle. |
+| Passing review, no panel required | Continue with the next wave or Completion. |
+| `panel_required: true` | Read the panel procedure in [native build](references/build-native.md), then use the driver's `panel` action. |
+| Blocked review with findings | Read step 7 in [native build](references/build-native.md); use `skeptics` or `fix-tasks` only as the finding receipt directs. |
+| `question` | Answer from approved artifacts or escalate; record with `answer --task-id <id> --answer '<answer> — <citation>'`, then resume round. |
+| Task/recovery `blocked` or structural escalation | Read the matching recovery or plan-defect branch in [native build](references/build-native.md). |
+
+Without an owner-supplied child command, read [native build](references/build-native.md)
+and the [dispatch contract](references/dispatch.md). That path uses native child
+tools with the same contracts and evidence. A `verify-only` wave also reads the
+native review procedure because the driver does not author that artifact.
+
+A failing helper stops the step: report stderr and run the forensics diagnostic
+under AGENTS.md. A live `in-flight` receipt is resumable work, not a failed helper.
+Apply owner budgets through the dispatch contract. Never infer a new limit.
 
 ## Completion
 
-Run `python3 <absolute dispatch_driver.py> complete --repo <absolute primary>`
-from a clean primary at `build/active` or crash-left `build/done`. It checks
-readiness and the archive-time review cycle contract before recording landing
-proof, entering `ship/active`, and checkpointing. A blocked receipt stops
-completion; a `done` receipt proves these steps, so do not repeat
-them. For manual completion:
-after every wave passes, record exact full HEAD and prove every task landed
-with `python3 <absolute workflow_run.py> build-evidence --repo <absolute primary>
---expected-head <HEAD>`. The runner writes the wrapped `verify-landed` result
-to `.project/build/evidence.json`; that path is the only landing-proof
-location the ship runtime recognizes, so never save the receipt under another
-name. The result must return one
-`proven-landed` or `attested` evidence entry per task, and any non-zero exit
-blocks completion. A `done` task without landing proof follows the `block`
-handling in step 1 above (owner ruling, Verify, `verify-record`, `attest`).
-Then run
-`pipeline_state.py transition`, expecting `build/active` plus the exact branch
-and archive, to set `phase: ship`, `status: active` with event `build done;
-final review pending`. Checkpoint that transition through the rule above with
-subject `build: complete milestone` and a concrete `Why:` body. Do not run
-PLAN.md's project Verify here — ship runs it once. This
-keeps the primary worktree clean and avoids a separate review-phase transition
-checkpoint. Report waves, exact task commits, fixed findings, and remaining risk.
-Link the resolved absolute final wave review as the review surface and state
-that ship is next. Do not merge to the default branch, tag, mark `shipped`, or
-integrate; ship owns FINAL.md, project Verify, and those steps. When invoked
-directly, stop and tell the user to explicitly
-invoke `$gsd-path`, which routes to ship; do not invoke an explicit-only sibling
-skill yourself.
-If a crash leaves `build/done`, use that phase and status as the expected
-transition values, then checkpoint the same `ship/active` result before
-returning to the router.
+```text
+python3 <absolute dispatch_driver.py> complete --repo <absolute primary>
+```
 
-## Milestone abandon (program flow only)
+Use this runtime even when coders used native child tools. It proves all tasks
+landed and wave reviews passed, writes the canonical build evidence, enters
+`ship/active`, and checkpoints. A blocked receipt stops completion. On a done
+receipt, report waves, task commits, fixed findings, and remaining risk; link the
+absolute final wave review and use the executable phase handoff in AGENTS.md. Ship owns project Verify,
+final review, archive, and publication; do not repeat or enter them here.
 
-Abandon the active milestone only on an explicit user ruling — from the
-review-cycle-cap escalation, a decision invalidation, or a direct request.
-Require `.project/ROADMAP.md`; a single-milestone project has no abandon
-path — stop and let the user decide how to restart.
+## Milestone abandon
 
-1. Retire every recorded task worktree and branch with `isolation.py retire`
-   after confirming ownership, recording each discarded uncommitted diff's
-   exact path set and hash in the STATE.md log. Never discard work the
-   recorded metadata cannot own.
-2. Run the bundled `scripts/archive_milestone.py abandon --repo <absolute
-   repo root> --slug <milestone slug> --reason <user ruling, verbatim>`.
-   This one helper-owned transaction journals the exact request and starting
-   HEAD before mutation; archives the partial artifacts without review gates;
-   marks the exact ROADMAP entry `Status: abandoned` with its `Archive:` path;
-   appends `- <NNN>-<slug> — abandoned: <collapsed ruling>` exactly once to
-   LESSONS.md; transitions STATE to `roadmap/active` with `milestone: null`
-   and `archive: null`; and creates the checkpoint with exact subject `build:
-   abandon milestone <slug>` and body `Why: <collapsed ruling>`. The manifest
-   `Reason:` and checkpoint `Why:` are the same normalized ruling.
-3. Rerun the same command with the same slug and ruling after any interruption.
-   It resumes archive moves, metadata, state transition, or checkpoint from
-   the journaled starting HEAD; a changed slug, ruling, archive, branch, or
-   manifest reason blocks. Success returns the archive, exact checkpoint
-   commit, and `committed` or `already-complete` status. Never edit or commit
-   any part of this transaction manually and never select another sequence
-   number.
-4. Return to the router, which routes `roadmap/active` to the roadmap
-   contract in re-slice mode. The abandoned code stays on the build branch
-   until the next milestone's integration, then reaches the default branch as
-   inert history; the re-slice plans around it. Never revert product commits
-   yourself.
+Only when the owner abandons a program milestone or STATE.archive records an
+interrupted abandon, read [milestone abandon](references/build-abandon.md).