@opengsd/gsd-path 1.0.0

package/README.md

@@ -0,0 +1,280 @@
+# GSD Path
+
+A disk-backed project pipeline for AI coding agents. It turns a raw idea into
+shipped code through gated phases — inspect, define, research, decide,
+roadmap, plan, build, and ship — with every handoff written to `.project/`
+so any session can resume from disk alone. A single milestone or a full
+multi-milestone program: program flow adds a charter and roadmap above the
+milestone loop. While a milestone builds, the next one can be planned in
+parallel under `.project/next/` (lookahead); a building milestone can also be
+abandoned on an explicit ruling, archiving its partial work for a re-slice.
+
+**Supported hosts:** Codex, Claude Code, Grok, OpenCode, GitHub Copilot CLI,
+Qwen Code, Antigravity CLI, Cursor, Zed, Kiro, and Kimi Code.
+Support means the installer and dispatch contract exist. See the
+[host trust matrix](https://github.com/open-gsd/gsd-path/blob/main/docs/trust-validation/HOST-MATRIX.md) for live milestone
+proof and each host's guard tier.
+
+## Documentation
+
+**Start at [DOCS.md](DOCS.md)** — install, use, understand, and update in one hub.
+
+| Guide | Use when |
+| --- | --- |
+| **[DOCS.md](DOCS.md)** | Full map + FAQ (recommended) |
+| **[QUICK.md](QUICK.md)** | First run checklist (~5 min) |
+| **[FULL.md](FULL.md)** | Complete install-to-ship walkthrough |
+| **[UPDATE.md](UPDATE.md)** | Refresh skills, hooks, or contracts |
+| [WORKFLOW.md](WORKFLOW.md) | Phase-by-phase agent SOP |
+| [HOOKS.md](HOOKS.md) | Optional archive/git guard hooks |
+| [GUIDE.md](GUIDE.md) | Pointer to the guides above |
+
+```bash
+# New user
+node scripts/install.mjs --all --dry-run && node scripts/install.mjs --all
+cd your-repo && node scripts/install.mjs --all --project "$(pwd)"
+# In agent: invoke the router (see Install summary below)
+
+# Already installed
+node scripts/install.mjs --update
+cd your-repo && node scripts/install.mjs --update --project "$(pwd)"   # also refresh .gsd-path/
+```
+
+Interactive: `npx @opengsd/gsd-path` with no flags opens the OpenGSD wizard (pick hosts, scope, contracts, hooks; dry-run first)
+
+npm (once published to npm): `npx @opengsd/gsd-path --all` · Help: `node scripts/install.mjs --help`
+
+## Skills
+
+Canonical explicit-only skills are installed.
+Invoke the **router** by default; use phase skills for one step only, or use a
+sidecar to discuss, diagnose, or undo without advancing.
+
+| Skill | Role |
+| --- | --- |
+| `path` | Router short name — same as `gsd-path` (`/path`, `$path`) |
+| `gsd-path` | Router — detects state, runs next phase (`status` reports without advancing) |
+| `gsd-path-inspect` | Phase 0 — brownfield codebase map + doc audit |
+| `gsd-path-define` | Phase 1 — intent definition |
+| `gsd-path-research` | Phase 2 — parallel evidence researchers |
+| `gsd-path-decide` | Phase 3 — evidence → decisions |
+| `gsd-path-roadmap` | Phase 3.5 — program: slice charter into milestone roadmap |
+| `gsd-path-plan` | Phase 4 — waves and task contracts |
+| `gsd-path-build` | Phase 5 — parallel coders + serial task landing |
+| `gsd-path-ship` | Phase 6 — verify, approve, archive, and ship |
+| `gsd-path-discuss` | Any-phase discussion with durable dialogue and answers |
+| `gsd-path-docs-audit` | Standalone doc-vs-code drift check |
+| `gsd-path-loop` | Standalone bounded loop runner driven by a LOOP.md spec |
+| `gsd-path-forensics` | Read-only stuck-pipeline diagnosis |
+| `gsd-path-migrate` | [Import GSD Core work and review hook coexistence](MIGRATE.md) |
+| `gsd-path-undo` | Helper-owned undo of unpublished pipeline work |
+
+See [invocation by host](#install-summary). Phase names keep the `gsd-path-` prefix.
+
+## The flow
+
+```mermaid
+flowchart TD
+    R{"gsd-path router"} --> I["0 · inspect (brownfield)"]
+    R --> D["1 · define → INTENT.md / CHARTER.md"]
+    I --> D
+    D -->|"standard / program lane"| RE["2 · research → evidence files"]
+    D -->|"quick lane"| P
+    RE --> DE["3 · decide → SYNTHESIS.md"]
+    DE -->|"program scope"| RM["3.5 · roadmap → ROADMAP.md"]
+    RM -->|"approved → checkpoint commit"| DM["define (milestone mode)"]
+    DM --> MQ{"roadmap entry has open questions?"}
+    MQ -->|"yes"| RE
+    MQ -->|"no"| P["4 · plan → PLAN.md + task contracts"]
+    DE -->|"milestone / single-project scope"| P
+    P -->|"approved → checkpoint commit"| B["5 · build"]
+    B --> W{"wave loop"}
+    W -->|"briefs linted at base SHA"| C["parallel coders, isolated worktrees"]
+    C -->|"streaming: dependents dispatch as deps land"| V{"wave review"}
+    V -->|"full — or deep: contract + adversarial lenses"| F{"verdict"}
+    F -->|"blocked → criterion triage"| W
+    F -->|"pass → next wave"| W
+    F -->|"all waves pass"| S["6 · ship — final review"]
+    C -.->|"NEEDS-ORCHESTRATOR question"| O["orchestrator answers from artifacts, or asks you"]
+    O -.-> C
+    B -.->|"lookahead: next milestone in .project/next/"| MI["inspect current code + docs"]
+    MI --> MB["define (milestone + brownfield mode)"]
+    MB --> MQ
+    B -->|"explicit ruling: abandon milestone"| AB["archive partial work → re-slice roadmap"]
+    AB --> RM
+    S -->|"approved → archive + ship commit"| MG["direct merge or user-merged PR + tag"]
+    MG -->|"validate-integrated passes"| A["shipped"]
+    A -->|"another program milestone → bind next gsd-path/M00N"| MI
+    A -->|"single-milestone restart → bind next gsd-path/M00N"| I
+    A -->|"program complete"| PC["stop"]
+```
+
+For an existing Git repository, initialization writes STATE.md first. Before
+entering inspect or define, the router fetches `origin/main`, creates or adopts
+`gsd-path/M001` there, and records the binding in state. Build only uses that
+recorded milestone branch; it never creates or selects one. See the
+[phase workflow](WORKFLOW.md#phase-0--inspect-gsd-path-inspect).
+
+At any non-shipped phase, `/gsd-path-discuss` (or `$gsd-path-discuss` in
+Codex) records the conversation in `.project/discuss/` without advancing or
+editing the phase handoff. Required decisions carry a named owner and remain
+pending until that phase records how it applied them; the router will not
+advance past an unresolved required follow-up.
+
+**Build, under the hood:**
+
+- Task briefs are linted against the real base tree (`check_task_briefs.py`)
+  before any agent is dispatched, and every coder runs a preflight — paths
+  exist or are declared, interface contracts match siblings verbatim — so a
+  wrong map dies in the first minute.
+- Task isolation and landing go through `isolation.py`: named branches only,
+  never a detached HEAD. A serial dispatch round works on the bound branch;
+  a parallel round gets `gsd-path-task/<id>`.
+- Dispatch streams: a dependent task starts the moment its dependencies
+  land, never idling behind unrelated in-flight tasks. Task landing
+  stays serial and every Verify reruns in the isolated worktree.
+- Wave review depth is `full`, `verify-only`, or `deep`; findings carry
+  forward by criterion across fix cycles. Each depth's writer and evidence
+  rules live in the canonical [build contract](skills/gsd-path-build/SKILL.md).
+  Optional skeptic triage for blocked `deep` reviews is defined in
+  [WORKFLOW.md](WORKFLOW.md#phase-4--plan-gsd-path-plan).
+- A coder with an ambiguous contract asks `NEEDS-ORCHESTRATOR` instead of
+  guessing; on hosts with a blocking ask/reply channel the worker stays
+  alive for the answer.
+- Roadmap and plan approvals are checkpoint commits, so planning work never
+  sits uncommitted until build.
+
+Invoke the router explicitly to start or advance a phase. Once a project has an
+owned `.project/STATE.md`, a plain prompt such as “continue the project” answers
+read-only with the current handoff and names the next skill; it never advances
+a phase or edits state. Phase skills stop at their handoff; invoke the router
+again to continue.
+The discussion sidecar is the exception: it can be invoked at any non-shipped
+phase and returns only a durable conversation record.
+
+The router classifies **brownfield**, **greenfield**, owned, and orphaned
+project state before routing; see [DOCS.md](DOCS.md#faq). Brownfield →
+inspect then define. Greenfield → define. It does not infer the verdict from
+a directory listing.
+**Quick lane** (tiny scope) may skip research/decide — see [FULL.md](FULL.md).
+
+For an explicit new-GitHub request, the router previews the owner, visibility,
+default checkout, `gsd-path/M001` branch, and sibling linked worktree. A
+journaled helper performs the approved creation and safely resumes a matching
+partial remote/clone/worktree transaction; the default checkout stays clean.
+
+## Handoff contract
+
+```text
+.project/
+  STATE.md                    phase, branch, archive transaction
+  REPOSITORY.md               persistent new-GitHub checkout/worktree binding
+  CHARTER.md                  program scope and vetoes; never archives
+  ROADMAP.md                  milestone slicing; never archives
+  SYNTHESIS.md                program decisions (top level); never archives
+  next/                       lookahead track: next milestone's artifacts during build
+  intent/INTENT.md            goal, vetoes, constraints, surfaces
+  research/
+    evidence-codebase.md      brownfield ground truth (inspect)
+    DOCS-AUDIT.md             doc verdicts + remediation queue
+    RESEARCH.md               dispatch manifest (dimensions researched/skipped)
+    evidence-domain.md        domain evidence
+    evidence-stack.md         stack evidence
+    evidence-pitfalls.md      pitfalls evidence
+    evidence-similar.md       similar projects evidence
+    SYNTHESIS.md              gated decisions
+  plan/PLAN.md                waves, dependencies, surface contract, verify
+  tasks/T###-slug.md          task contract: files, interface, criteria, base SHA, status
+  review/                      review evidence; see WORKFLOW.md#handoff-contract
+  discuss/DIALOGUE.md         any-phase dialogue transcript
+  discuss/ANSWERS.md          durable discussion answers and decisions
+  LESSONS.md                  optional carried-forward planning lessons
+  archive/<NNN>-<slug>/       shipped milestones (read-only after ship)
+```
+
+Shipping moves milestone artifacts into `archive/` with a MANIFEST. It then
+either merges the milestone's `gsd-path/M00N` branch into `main` directly or
+opens/reuses a GitHub PR and waits for its user-controlled merge. Path reports
+shipped only after a two-parent merge and the milestone tag validate. Before
+any next-milestone files change, the router binds
+a new `gsd-path/M00N` at the updated `origin/main`. `STATE.md`, `REPOSITORY.md`,
+`LESSONS.md`, `next/`, and the program artifacts (`CHARTER.md`, `ROADMAP.md`,
+top-level `SYNTHESIS.md`) remain active project metadata.
+
+## Install (summary)
+
+Node 18.17+. Project installs also require Python 3.9+. Validates package,
+backs up existing skills, and rolls back on failure.
+**Always** `--dry-run` first when unsure.
+
+```bash
+node scripts/install.mjs --all --dry-run
+node scripts/install.mjs --all
+node scripts/install.mjs --claude --cursor
+node scripts/install.mjs --all --local
+node scripts/install.mjs --all --project /path/to/project
+node scripts/install.mjs --update
+node scripts/install.mjs --all --update --project /path/to/project   # refresh .gsd-path/; keeps contracts
+```
+
+| Flag | User skills root | Invoke |
+| --- | --- | --- |
+| `--codex`, `--zed` | `~/.agents/skills` | Codex: `$path` or `$gsd-path`; Zed: `/path` or `/gsd-path` |
+| `--claude` | `~/.claude/skills` | `/path` or `/gsd-path` |
+| `--cursor` | `~/.cursor/skills` (+ subagent) | `/path` or `/gsd-path` |
+| `--grok` | `~/.grok/skills` | `/path` or `/gsd-path` |
+| `--opencode` | OpenCode config `skills/` | `/path` or `/gsd-path` (OpenCode v2 host) |
+| `--copilot` | `~/.copilot/skills` | `/path` or `/gsd-path` |
+| `--qwen` | `~/.qwen/skills` | `/path` or `/gsd-path` |
+| `--antigravity` | Antigravity skills dir | `/path` or `/gsd-path` |
+| `--kiro` | `~/.kiro/skills` | `/path` or `/gsd-path` |
+| `--kimi` | `~/.kimi-code/skills` | `/path` or `/gsd-path` |
+
+OpenCode stable: ask to load and use the `gsd-path` skill.
+`gsd-path` remains the canonical router name; `path` is its short menu alias.
+For a single phase, use `$gsd-path-plan` in Codex or `/gsd-path-plan` on slash hosts.
+
+`scripts/install.py` — Python install, including `--local` and `--update`.
+The Node CLI remains the interactive and npm entry point. See [FULL.md](FULL.md) and
+[UPDATE.md](UPDATE.md) for `--hooks`, `--hooks-refresh`, `--local`, and host notes.
+
+Optional **`--hooks`** with `--project` — [HOOKS.md](HOOKS.md).
+
+Something off? `node scripts/install.mjs --doctor [--project PATH]` — read-only
+health check of installs, guard hooks, and pipeline state.
+
+## Agent execution
+
+Define and build orchestrators run in the main task. Researchers, deciders,
+planners, coders, and reviewers delegate via host-specific adapters. See
+[FULL.md — Agent execution](FULL.md#agent-execution-how-work-is-delegated) for
+the authoritative host API table and delegation rules.
+
+`platforms/` is installer-only — not user-invoked skills.
+
+## Testing
+
+Contributors and CI use one offline gate. See **[TEST_ENVIRONMENT.md](TEST_ENVIRONMENT.md)** for prerequisites, tiers, fixtures, and troubleshooting.
+
+```bash
+make install && make verify    # same path as GitHub Actions CI
+```
+
+## Repository layout
+
+| Path | Purpose |
+| --- | --- |
+| `DOCS.md` | Documentation hub |
+| `QUICK.md` | Quick start |
+| `FULL.md` | Full guide |
+| `UPDATE.md` | Updating |
+| `HOOKS.md` | Guard hooks |
+| `skills/` | Canonical skills and generated aliases declared in [the resource manifest](scripts/skill-resources.json) |
+| `platforms/` | Host dispatch adapters |
+| `scripts/install.mjs` | Installer (npm `gsd-path` bin) |
+| `scripts/install.py` | Python installer |
+| `AGENTS.md` | Operating rules (installed to projects) |
+| `WORKFLOW.md` | Phase SOP (installed to projects) |
+| `TEST_ENVIRONMENT.md` | Local/CI test setup and tiers |
+| `fixtures/` | Sample `.project/` pipeline for manual runs |
+| `LICENSE` | MIT |

package/RUNTIME.md

@@ -0,0 +1,229 @@
+# Workflow runner and observed token budgets
+
+The runner assembles arguments for existing canonical helpers. It returns a JSON
+receipt containing each command, exit code, stdout, stderr, and parsed result.
+`build-evidence` also appends a step with `script` and `evidence` fields naming
+the written proof file.
+A failed helper stops the sequence before any later gate or checkpoint. Preserve
+that receipt with the phase evidence; a blocked receipt routes to forensics.
+It does not dispatch models or supply owner approvals.
+
+## Workflow commands
+
+Use the absolute `workflow_run.py` path in the active skill's scripts directory.
+All commands require `--repo <absolute repository root>`.
+
+| Command | Required input | Result |
+| --- | --- | --- |
+| `route` | Optional `--project-dir .project/next` | Canonical route; follow its action even when it blocks or requests recovery. |
+| `gate-plan` | Git HEAD; optional lookahead project directory | Pending discussion, intent coverage, brief paths, and panel configuration checked in order. |
+| `approve-plan` | Owner approval and `--expected-head <reviewed full SHA>` | Plan gates followed by the existing journaled approval checkpoint. |
+| `lint-round` | Git HEAD; optional `--project-dir .project/next` | Task brief checks against HEAD, then plan handoff checks. |
+| `prepare-task` | `--expected-head <clean base> --task-id <id> --round-size <ready task count>` | Canonical task isolation; serial work also gets a verification sidecar before the primary becomes dirty. |
+| `build-evidence` | `--expected-head <full SHA>` | Canonical landing proof written to `<project-dir>/build/evidence.json` (default: `.project/build/evidence.json`). |
+
+Plan approval recovery remains `pipeline_state.py resume-checkpoint`. Pre-Git
+approvals and patch approvals retain their existing canonical flows. The runner
+never changes a recorded base, retries a failed mutation, or repairs state itself.
+
+Checkpoint inputs must use the top-level `.project` entries defined by
+[`isolation.PROJECT_ENTRIES`](scripts/isolation.py); ship verification uses the
+same allowlist. `isolation.py checkpoint` refuses pending paths under any other
+top-level entry and asks for their removal before checkpointing. This check does
+not inspect nested entries inside an allowed directory.
+
+For serial work, keep the returned verification sidecar until the coder finishes.
+Validate the full task diff, reproduce only that patch in the sidecar, compare the
+product diffs, and run Task Verify there. Record that exact evidence before landing.
+The runner avoids having to remove a live product patch merely to create a sidecar.
+Task verification, wave review, and ship-only project verification retain their
+existing responsibilities.
+
+## Dispatch driver
+
+`dispatch_driver.py` in the router and build bundles runs one build wave's
+deterministic loop so the orchestrating model only supplies judgment. `round`
+and `finish` run recovery against Git and the task files before processing
+dispatch records under the Git common directory
+(`gsd-path/dispatch/<milestone slug>/<task>/attempt-N/`). The milestone slug
+replaces `/` in the bound branch with `-` (for example, `gsd-path/M001`
+becomes `gsd-path-M001`). `answer` and `status`
+read the newest attempt records. Records are keyed by the bound branch, so a
+new milestone starts with no attempts and the previous milestone's records
+remain as evidence.
+Review attempts use `gsd-path/dispatch/<milestone slug>/reviews/<logical name>/attempt-N/`;
+panel attempts use the same layout under `panels/` instead of `reviews/`, and
+skeptic attempts under `skeptics/`.
+`status` and `answer` cover task attempts only.
+
+| Command | Result |
+| --- | --- |
+| `round --repo <root> --wave <N> --child-command '<cmd>' [--wait <s>] [--child-timeout <s>] [--capacity <N>] [--max-attempts <N>] [--task-limit <N> --session-limit <N> --budget-authority '<policy>']` | Enter `build/active` from `plan/done` or `build/blocked` (event `build started`, checkpoint `build: start milestone`); recover, settle exited children, `ready`, checkpoint bookkeeping, lint, isolate, dispatch; Verify, land, record, retire each result in task-id order. Receipt status `done`, `in-flight`, `question`, or `blocked`; a dependency deadlock or blocked recovery also sets `build/blocked` and checkpoints it. |
+| `review --repo <root> --wave <N> --cycle <C> --child-command '<cmd>' [--wait <s>] [--child-timeout <s>] [--repair-evidence <receipt>]` | Step 6 at `full` or `deep` depth: clean review base, one verify sidecar and reviewer child per lens, validate in the sidecar, collect, retire; after every lens settles, checkpoint a `pass` when no panel is configured, or return the `review_findings.py collect` grouping on `blocked`. `verify-only` returns `not-applicable`; `panel_required` reports the PLAN panel setting. |
+| `panel --repo <root> --wave <N> --cycle <C> --advertised <slugs> [--parent-slug <slug>] --child-command '<cmd with {model}>' [--wait <s>]` | Step 6 panel: `review_panel.py resolve`; `off`, a persisted skipped receipt, or one panelist per family in its own sidecar; collect, `review_panel.py merge`, then the single on-pass checkpoint with the review. |
+| `skeptics --repo <root> --wave <N> --cycle <C> --child-command '<cmd>' [--wait <s>] [--child-timeout <s>]` | Step 7 skeptic branch: one read-only skeptic per `skeptic_groups` locator in its own sidecar at the recorded review base, briefed with the criterion, every observation, and the cited tasks verbatim; validate with `review_findings.py`, collect, retire, then rerun the helper. `none` without skeptic groups; `escalate` for structural blockers or the cycle cap. The skeptic files stay uncommitted for the fix-task or ruling checkpoint. |
+| `fix-tasks --repo <root> --wave <N> --cycle <C>` | Step 7 batching: one fix task per `review_findings.py collect` batch with the failed criteria and observations verbatim, lint-checked; `escalate` for structural blockers, skeptic groups, cycle cap, or all-refuted. |
+| `complete --repo <root>` | Completion: clean primary at `build/active` (or a crash-left `build/done`), no unfinished wave, the archive-time review cycle check (`discussion_validate.review_cycle_counts`: contiguous cycles, passing last cycle, panel and skeptic artifacts present); `workflow_run.py build-evidence` at HEAD; `pipeline_state.py transition` to `ship/active` with event `build done; final review pending`; checkpoint `build: complete milestone`. |
+| `finish --repo <root> --task-id <id>` | Recover first; return a proven landing without repeating Verify, or verify, land, record, and retire one returned task. Without a dispatch record, derive the isolate from task frontmatter. |
+| `answer --repo <root> --task-id <id> --answer '<text>'` | Append `Orchestrator answer:` to the isolate's task Log; the next `round` redispatches that isolate. |
+| `status --repo <root>` | Every task's newest dispatch record. |
+
+The child command is owner-supplied shell words. The driver runs it with the
+isolated worktree as its working directory and the self-contained brief on
+stdin; the owner's flags decide the child's permissions and model. Verified
+templates: `claude -p --output-format json <owner permission flags>` and
+`codex exec --json <owner sandbox flags>`. A coder child ends its final message with
+`RESULT: <task id> ready|blocked`; no line means blocked. A Log delta whose
+first entry after the last recorded `Orchestrator answer:` leads with
+`NEEDS-ORCHESTRATOR:` is a question only when the child exits successfully;
+a timeout or nonzero exit is a failure even if the child wrote a question.
+Canonical reviewer children instead return the `Wave verdict:` line in their
+validated review artifact; they do not need a `RESULT:` line.
+Panel children write family findings without a Wave verdict. The panel command
+replaces literal `{model}` in its child command with the resolved family slug.
+`--wave` is required and pins the parent-selected wave, including on resumed
+calls. In `round`, an unfinished earlier wave blocks dispatch before the bookkeeping
+checkpoint. Child completion is recorded in `exit.json`; the parent alone
+writes `state.json`.
+For `review`, `panel`, and `skeptics`, when the child process is gone and `finished_at` is
+unset, the driver rereads that attempt's state and exit receipt before
+collecting the result or blocking with
+`child wrapper exited without recording a result`.
+`--wait`, `--child-timeout`, and `--capacity` (concurrent children) have
+no defaults. `--max-attempts` defaults to 2 dispatches per task per milestone,
+the build contract's one logged redispatch after the first attempt; question
+redispatches do not count. At the limit `round` returns `blocked` naming the
+task, and a person rules.
+
+Token budgets are opt-in. Passing `--task-limit`, `--session-limit`, and
+`--budget-authority` together configures this milestone's ledger at
+`gsd-path/budget/<milestone slug>.json` under the Git common directory, records
+each child's usage from its captured stdout when it exits, and runs `admit`
+before preparing or activating a fresh task and before each question
+redispatch; a blocked admission stops the round. The ledger's
+policy is fixed once configured. Later rounds and `finish` enforce that policy
+even when budget flags are omitted; only explicit flags configure it. Each
+attempt records its own usage, including question redispatches. A new milestone
+gets a new ledger. Usage
+is read from Codex `--json` events or Claude `--output-format json`; output
+that proves no usage stops the round rather than estimating. At most one `Heavy: yes`
+Verify task is in flight at a time, and a round stops at a wave boundary.
+Without `--wait`, the call returns after processing currently available work;
+children continue running. `--capacity`, when supplied, must be positive.
+
+Every action except `status` holds a
+repository-scoped advisory lock for the whole call, including `--wait`.
+A concurrent invocation returns `blocked`
+with `another dispatch_driver invocation holds the lock`; wait for the
+active call to return before retrying. Bookkeeping also blocks if an
+in-progress primary task has no open dispatch record.
+
+Verify output is saved in `verify.json`. A `verify-record` ledger entry is
+written only when the landing commit's parent equals the recorded task base;
+a later parallel landing can therefore have no ledger entry.
+
+For task attempts, the driver reports and never repairs: a failed child, a failed Verify, a
+recovery or reconciliation verdict, or a `ready` error returns `blocked` with
+the evidence, and the isolate stays in place for the build contract's
+documented procedure.
+
+Resume an `in-flight` review with the same wave and cycle. Missing lens records
+are dispatched only while the primary is clean and HEAD still matches the
+recorded base. For cycle 2 or later, every previous-cycle lens artifact must
+exist before dispatch. Invalid review files remain in their sidecars for
+inspection. Collection progress is saved before cleanup; a cleanup failure
+returns `blocked` with helper findings, and a later call retries cleanup.
+Reusing a collected verdict requires the canonical artifact to match its saved
+validation hash. Review inputs must still match the recorded base: only this
+cycle's review artifacts may differ, and HEAD may advance only by the cycle's
+own review checkpoint. Other changes block reuse and require a new cycle.
+
+Resume an `in-flight` panel with `panel` for the same wave and cycle. Before
+the first spawn, it saves the families, slugs, mode, and base in
+`panels/wave-N-cycle-C/roster.json` under the milestone's dispatch directory.
+Missing families resume only at that base. Merge waits for the whole roster
+and successful cleanup; later calls retry pending cleanup. Before merging or
+checkpointing, HEAD must still equal the recorded base. Only this cycle's
+review files, panel family files, merged panel, and skipped receipt may differ.
+Other changes return `blocked` with
+`inputs changed after the review base; run a new cycle` and no checkpoint.
+A skipped-panel retry uses the base saved in this cycle's review records;
+missing records block with `review base is not recorded; run review first`.
+An interrupted checkpoint's skipped receipt is reused only if it is a JSON
+object with `status: skipped`; other contents block as an invalid receipt.
+The same input guard runs before writing or reusing that receipt and again
+before checkpointing. Panel `status`
+describes panel processing; `review_verdict` holds the canonical verdict.
+A blocked canonical review leaves `checkpoint: null`, including for a skipped
+panel, so `fix-tasks` can checkpoint the blocked review with its repairs.
+
+Resume an `in-flight` skeptic run with `skeptics` for the same wave and cycle.
+Dispatching missing locators requires HEAD to equal the recorded review base.
+Panel and skeptic collection save validated fields and a content hash before
+moving the staged file. If interrupted after that move, collection resumes
+through its receipt only when the canonical file matches the saved hash.
+
+`fix-tasks` reconciles existing repair tasks and PLAN rows before linting and
+checkpointing. It creates missing batches in an appended repair wave and
+reports new tasks in `created`, reused tasks in `existing`, and batches already
+covered by other repair tasks in `carried`. Status `created` includes restored
+PLAN rows or pending project bookkeeping; `exists` means nothing was written
+and no project changes needed a checkpoint. Status `none` means no batches
+need work; `escalate` leaves the named decisions with build step 7 and the user.
+Each generated fix-task Verify runs the distinct source Verify commands in
+separate subshells under `set -e`. An `exit 0` or trailing comment in one source
+cannot skip the next source command, and a failing subshell stops the Verify.
+
+## Token accounting
+
+`token_budget.py` is in the router and build bundles. Limits have no defaults.
+The dispatch driver owns its ledger as described [above](#dispatch-driver).
+For manual accounting, configure one ledger for the logical session, outside
+the worktree, using the owner's exact
+limits and their authority. For example, use a path under the Git common directory
+returned by Git; do not assume `.git` is a directory in a linked worktree.
+
+```text
+python3 <token_budget.py> configure --ledger <absolute ledger> --task-limit <owner value> --session-limit <owner value> --authority <quoted owner policy>
+python3 <token_budget.py> record --ledger <absolute ledger> --task <logical task> --events <completed host event file>
+python3 <token_budget.py> admit --ledger <absolute ledger> --task <next logical task>
+```
+
+The metric is the host's `output_tokens`, including its reported reasoning output;
+reasoning is not added again. Input and cached input are not included. Resumptions
+reuse the ledger and task identity. Each CLI invocation uses its immutable event
+file. Re-observing that file is idempotent; new invocations accumulate. Native
+single-invocation child sessions and Claude `--output-format json` usage
+receipts are supported. Resumed native child logs with
+ambiguous cumulative counters fail closed; use separate CLI run receipts instead.
+Record every completed parent invocation and child, not only coder work.
+
+`admit` blocks once observed task or session output reaches the configured limit.
+A negative exit is not permission to start a new ledger, rename the task, or omit
+usage. Incomplete usage cannot establish remaining budget. Configuration preserves
+existing observations and refuses a changed policy for the same session ledger.
+
+This is **observed admission enforcement**. Concurrent, unreported, and in-flight
+usage remains unproven. Codex CLI 0.153.4 exposes usage after execution but its help
+and published configuration list no hard output-token cap. Use
+`admit --require-hard-cap` when hard enforcement is required: this host returns
+blocked with `hard_cap_supported: false`. These helpers do not make a strict
+budget-compliance claim. Other hosts need a verified counter/cap adapter.
+
+Sources checked for this host: local `codex exec --help`,
+[official CLI reference](https://developers.openai.com/codex/cli/reference), and
+[official configuration reference](https://developers.openai.com/codex/config-reference).
+The Responses API's generation limits are a different interface; they do not
+establish a Codex CLI capability.
+
+## Lean final verification
+
+The ship bundle's `workflow_run.py prepare-final --repo <root> --expected-head
+<full SHA>` sequences landing proof, isolated project Verify, evidence collection,
+and final reuse. A command/commit receipt stores exact stdout/stderr once; retry
+rebuilds its gap view and cleans up an interrupted sidecar without another run.
+Legacy receipts without output require reconciliation if no valid proof can be
+recovered. A full quick-lane wave explicitly covering final scope supplies FINAL.md
+when every criterion and surface walkthrough is proven and Git shows unchanged
+product and contracts. Other scopes retain final review. The output names whether
+review is needed; models do not route reuse by comparing prose or file sizes.