@opengsd/gsd-path 1.0.0 → 1.2.0

package/skills/gsd-path/references/build-native.md

@@ -0,0 +1,502 @@
+# Native dispatch and build recovery
+
+Read only when no owner-supplied child command exists, a driver receipt requires
+manual recovery, or the wave uses verify-only review. Entry and bookkeeping
+preconditions remain in the build skill. Do not repeat a proven driver step.
+
+## Wave loop
+
+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):
+
+```text
+python3 <absolute dispatch_driver.py> round --repo <absolute primary> --wave <N> \
+  --child-command '<owner command>' [--wait <owner seconds>] \
+  [--child-timeout <owner seconds>]
+```
+
+`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>'`, using the
+[model-policy CLI contract](model-policy.md#cli-lifecycle). The panel command
+resolves membership,
+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
+an existing isolate in place. A model-selection rejection before launch creates
+no isolate; follow the [model-policy contract](model-policy.md). For other
+blocks, 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 follows [build recovery](build-recovery.md) 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 follow [build recovery](build-recovery.md) to
+   `$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.
+   Generate the coder's intent view with `python3 <absolute task_context.py>
+   --repo <absolute isolated-worktree> --task <absolute task file>` and include
+   its output in the brief. The helper preserves all global rules and falls
+   back to full intent when projection is ambiguous. Never summarize it by hand.
+   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 a returned `ready` coder, run `python3 <absolute dispatch_driver.py>
+     finish --repo <absolute primary> --task-id <id>`. This action works with
+     native child tools; no child command is needed. It reproduces serial work
+     in its prepared sidecar, runs authoritative Verify, records exact output,
+     lands through `isolation.py`, records eligible ledger evidence, and retires
+     the isolate. A `landed` receipt proves those steps; do not run them again
+     or author another implementation narrative. A blocked receipt preserves
+     its failure evidence and follows the recovery rule, never a manual bypass.
+     Keep the pre-finish declared-path check above. Each landing re-opens step 2
+     so ready dependents can run while unrelated children remain in flight.
+   - 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 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>
+     --exclude-family <known canonical-reviewer family>`; repeat
+     `--exclude-family` for every known parent and canonical-reviewer family,
+     including all deep review lenses, before persisting the roster. Omit
+     unknown identities. Also pass `--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.
+     Resolve model choices through the dispatch model-policy contract. 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 canonical 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 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)`.
+
+## Completion
+
+Run `python3 <absolute dispatch_driver.py> complete --repo <absolute primary>`
+even when the coders used native child tools. Follow the build skill's Completion
+handoff. The runtime owns landing evidence, transition, and checkpoint; ship owns
+project Verify. Never repeat a proven operation in a manual sequence.

package/skills/gsd-path/references/build-recovery.md

@@ -0,0 +1,78 @@
+# Return a blocked build to its contract owner
+
+Use this contract only for an active milestone at `build/blocked`: a documented
+structural plan defect, or an explicit user ruling that changes approved intent.
+It does not reopen ship, archived milestones, or lookahead. Build owns entry;
+Define owns intent corrections; Plan owns the replacement task inventory and
+approval. Routing remains a caller handoff under AGENTS.md.
+
+## Build: checkpoint and enter
+
+1. Record the finding or verbatim user ruling in STATE through its helper.
+   Stop dispatch. Use the normal recovery and retirement procedures until
+   every task is either unstarted `pending` with null dispatch metadata or
+   proven `done`. Preserve owned uncommitted work before any retirement.
+   Settle reviewers and their sidecars too. Dispatch records must have no pending
+   cleanup; records with reviewer `worktree` and `branch` ownership must also
+   record `cleanup_complete`. A `blocked` or `collected` outcome alone does not
+   prove retirement. Records that never owned a reviewer sidecar do not require
+   that retirement receipt. Use the existing dispatch retirement procedures;
+   recovery does not retire sidecars itself. Never infer that a timed-out child
+   stopped. Checkpoint the blocked state and artifacts using the Build
+   bookkeeping contract; the primary must be clean.
+2. Run `pipeline_state.py transition` with the complete current state expected,
+   `--set-status active`, and the matching target and event:
+
+   | Cause | Target | Exact event |
+   | --- | --- | --- |
+   | User changes a criterion, constraint, or veto | `--set-phase define` | `build intent corrections requested` |
+   | Task inventory, dependency, or wave repair | `--set-phase plan` | `build plan repair requested` |
+
+   The helper records the committed recovery base in STATE atomically. Do not
+   author or edit that record. Milestone, branch, integration settings, and
+   landed task contracts remain fixed throughout recovery.
+3. Return to the router or name the selected explicit skill. The route names
+   `corrections` for Define and `build-repair` for Plan. Other blocked-build
+   failures continue through ordinary Build recovery.
+
+## Define and Plan: prepare before editing
+
+Run the bundled `pipeline_state.py prepare-build-recovery --repo <absolute-root>`
+before changing any recovery artifact. This repeatable operation preserves the
+old review directory under `plan/build-recovery-<base>/review` and starts a fresh
+active review directory. STATE's recorded base owns an interrupted move; rerun
+this command to finish it. The helper validates the preserved bytes against Git.
+Do not remove, rewrite, or use the preserved reviews as current approval.
+
+**Define corrections.** Read the existing intent and governing program artifacts.
+Interview only the requested change; append the user's words under
+`## Corrections`, revise the affected intent, and present the delta for approval.
+Keep the milestone identity. Reclassify the lane using the normal lane rules.
+After approval, use the normal `define/active → define/done` transition and route
+from the approved lane. Standard intent goes through Research and Decide again;
+quick and milestone intent use their existing evidence gates. A program charter
+or roadmap conflict still requires its legal owner gate; this path cannot waive it.
+
+**Plan build-repair.** Read the corrected intent, current synthesis, existing plan,
+task files, and recovery base. Use the normal planner, lint, panel, and approval
+gates. Repair the remaining task inventory as needed, including split, rename,
+dependency, or wave changes. Keep IDs ordered and contiguous. Preserve every
+landed task file byte-for-byte, including its recorded base and proof. Any new
+work to satisfy a corrected criterion belongs in new pending tasks, not rewritten
+landed contracts. A plan-only recovery must not change approved intent.
+
+## Approve and return to Build
+
+Use normal `pipeline_state.py approve --kind plan --expected-head <HEAD>`.
+Neither `--patch` nor `--defer-checkpoint` is legal for recovery. The helper
+checks landed-task preservation and restored intent ownership, restores review
+evidence only for unchanged contracts, and creates the normal journaled plan
+checkpoint. A failed approval leaves recovery open.
+
+Return through `plan/done → build/active` with event `build started`. The dispatch
+driver uses a separate record directory for this recovery base, while retaining
+the milestone budget ledger. Resume only from the new approved task inventory.
+Unchanged wave evidence remains usable; changed waves need review in the new
+record directory. Retained task Verify receipts remain historical evidence for
+their original task and base, never proof for a changed task. Final review still
+requires current-HEAD evidence before shipment.

package/skills/gsd-path/references/coder.md

@@ -7,12 +7,17 @@ Execute exactly one task for `$gsd-path-build`.
 - Require the brief to name the assigned task file, task template, and
   `.project/intent/INTENT.md` by absolute path, plus the isolated
   linked-worktree root returned by `isolation.py isolate-task`. Read the
-  task file, template, and INTENT.md fully from that worktree.
+  task file fully from that worktree. Use the generated intent context in the
+  brief when supplied; it retains global rules, corrections, and owned or
+  explicitly referenced criteria with source hashes. Otherwise read INTENT.md
+  fully. Read the task template only to resolve a missing or ambiguous field;
+  the completed task already supplies the implementation contract.
   On a serial dispatch round that root is the primary worktree on the bound
   branch; still never edit a sibling task's files. On a parallel round never
   edit the primary worktree.
-- Read the project `AGENTS.md` and every existing path listed in the task's
-  `files` frontmatter before editing.
+- Apply the project `AGENTS.md`; read it if the host has not already supplied
+  that exact file. Read every existing path listed in the task's `files`
+  frontmatter before editing. Load WORKFLOW.md only for a workflow ambiguity.
 - Treat Context, Approach, Interface contract, owned INTENT success
   criteria, Acceptance criteria, and Verify as the implementation contract.
   Owned SCs, Criteria, Verify, and the Interface contract define done;