@opengsd/gsd-path 1.0.0 → 1.1.0

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

@@ -0,0 +1,33 @@
+## Milestone abandon (program flow only)
+
+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.
+
+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.

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

@@ -0,0 +1,494 @@
+# 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 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 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 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)`.
+
+## 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-build/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-build/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;

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

@@ -122,6 +122,12 @@ directory for the full logical session; resumptions reuse it. Record completed
 parent CLI run events and each native child's session events with stable logical
 task names before the next dispatch. The helper reads host counters and refuses
 incomplete or ambiguous usage; never estimate tokens or reset the ledger.
+When the verified CLI adapter reports cumulative counters across `resume`, record
+each later invocation with `--previous-events <previous recorded CLI events>`.
+The helper checks thread identity and records only the new output, preserving the
+raw total and predecessor. Keep that chain in order; never sum cumulative totals.
+Use ordinary `record` for per-invocation counters. An unknown counter convention
+is unproven usage, not permission to guess.
 Run `admit` for the next task and stop dispatch on a blocked result. Preserve
 its output in the dispatch evidence. This gates observed usage only: concurrent
 or in-flight work can overrun before the host reports usage. Codex CLI has no