okstra 0.206.0 → 0.207.0

package/runtime/prompts/launch.template.md

@@ -7,7 +7,7 @@
 
 **Enforced:** `validators/validate_session_conformance.py` reads the selected adapter's evidence within the run window and reports a missing checkpoint. Missing lines are advisories, not failures — by the time the validator runs the session that would have emitted the line has ended, so the finding records that the run is hard to follow, not that its work is wrong.
 
-Emit one `PROGRESS: <phase-id> <verb-phrase>` line as plain user-facing text at every checkpoint enumerated in the lifecycle core contract (`{{OKSTRA_LEAD_CONTRACT_PATH}}` "Progress reporting (BLOCKING)") — phase-1-intake start/complete, phase-2-prompts, phase-3-team-create, phase-4-dispatch (per worker), phase-5-collect (per worker), phase-5.5-convergence (per round), phase-6-synthesis, phase-7-persist, and final `complete`. One line per checkpoint, never batched, never replaced with prose. This is the only signal the user has during multi-minute silent windows. Record each one with `okstra lead-progress append --project-root <dir> --run-manifest <path> --phase <phase-id>` and emit the `progressLine` it prints — that call is what puts the checkpoint where the validator reads it.
+Emit one `PROGRESS: <phase-id> <verb-phrase>` line as plain user-facing text at every checkpoint enumerated in the lifecycle core contract (`{{OKSTRA_LEAD_CONTRACT_PATH}}` "Progress reporting (BLOCKING)") — phase-1-intake start/complete, phase-2-prompts, phase-3-team-create, phase-4-dispatch (per worker), phase-5-collect (per worker), phase-5.5-convergence (per round), phase-6-synthesis, phase-7-persist, and final `complete`. One line per checkpoint, never batched, never replaced with prose. This is the only signal the user has during multi-minute silent windows. Record each one with `okstra lead-progress append --project-root <dir> --run-manifest <path> --phase <phase-id>` and emit the `progressLine` it prints — that call is what puts the checkpoint where the validator reads it. The exception is a checkpoint the command performing the step records itself (`team dispatch`, `team await`, `team reclaim`, `worker-dispatch`, `report-finalize`; the contract lists which): emit the `PROGRESS:` line that command prints and do not append it again.
 
 When the run manifest declares `activityContractVersion: 1`, call `okstra agent-activity append` before each required activity boundary. Only after the structured append succeeds, emit the matching `PROGRESS:` line and the immediately following `ACTIVITY:` projection from the same fields. If the structured append fails, do not mark that boundary completed. Never reconstruct structured activity by parsing `ACTIVITY:` conversation text.
 
@@ -189,7 +189,7 @@ The **default is full re-verification**. Narrow this re-run to the impacted stag
    ```
    The CLI reads the plan's dependency graph from the prior `implementationPlanning.stageMap`, which is authoritative for the impacted stage numbers. The CLI prints JSON `{mode, reverify_stages, carry_stages, reason}` **and writes the same decision** to the record this run's manifest names in `incrementalDecisionPath`. You do not transcribe it: the report writer receives it through its authoring contract, and `incremental-carry` reads the same record. An `unresolved` result is a question back to you and is deliberately not recorded.
 4. **`mode == "full"`** → run the existing full re-verification path unchanged; ignore `reverify_stages` / `carry_stages`.
-5. **`mode == "incremental"`** → scope every worker dispatch prompt to `reverify_stages` only (the downstream closure of the impacted stages). Do NOT re-analyze `carry_stages` — their prior plan-item verdicts are carried forward verbatim (see `prompts/profiles/implementation-planning.md` "Cross-verification mode" and `prompts/lead/convergence.md` "Convergence scope"). When the pin in step 0 was `auto`, this is the decision — do not upgrade it to full.
+5. **`mode == "incremental"`** → scope every worker dispatch prompt to `reverify_stages` only (the downstream closure of the impacted stages). Do NOT re-analyze `carry_stages` — their prior plan-item verdicts are carried forward verbatim (see `scripts/okstra_ctl/phases/implementation_planning/profile.md` "Cross-verification mode" and `prompts/lead/convergence.md` "Convergence scope"). When the pin in step 0 was `auto`, this is the decision — do not upgrade it to full.
 6. **`mode == "unresolved"`** → ask the user for stage numbers; re-enter step 3 with those numbers in `--impacted`. Do not fall back to full. Do not record `unresolved` as `incrementalDecision`. Then continue from the new `mode`.
 7. **Merge carried-forward verdicts.** In `incremental` mode the report writer receives the carried stage rows as a packet source and is told, in its own authoring contract, to copy them unchanged — you do not repeat that instruction to it. After `okstra plan-items seed --narrative ... --state ...`, the lead runs:
    ```

package/runtime/prompts/lead/adapters/cmux.md

@@ -33,7 +33,7 @@ Keep the selected host relay's dispatch permission guidance when calling `okstra
 | `await_workers` | Run `okstra team await --project-root <root> --run-manifest <path>` through the host's asynchronous shell facility. |
 | `redispatch_worker` | Create the core-specified fresh jobs file and dispatch it with a new `dispatchKind`; never reuse a live worker conversation. |
 | `shutdown_workers` | Run `okstra team teardown --project-root <root> --run-manifest <path>` only after the user-approved cleanup gate. |
-| `record_lead_event` | Append progress and activity records to the manifest-provided `leadEventsPath`. Use `okstra lead-progress append --project-root <dir> --run-manifest <path> --phase <phase-id>` for a checkpoint and `okstra agent-activity append --project-root <dir> --run-manifest <path> --kind <kind> ...` for an activity record; both resolve the ledger path from the run manifest. Emit the matching `PROGRESS:` line — the command prints it as `progressLine` — and, when an activity record is required, the immediately following `ACTIVITY:` line from the same structured fields. |
+| `record_lead_event` | Append progress and activity records to the manifest-provided `leadEventsPath`. Use `okstra lead-progress append --project-root <dir> --run-manifest <path> --phase <phase-id>` for a checkpoint the command performing that step does not record itself (the lead contract "Progress reporting" lists the ones `team dispatch`, `team await`, `team reclaim`, `worker-dispatch` and `report-finalize` record; emit the `PROGRESS:` lines they print instead) and `okstra agent-activity append --project-root <dir> --run-manifest <path> --kind <kind> ...` for an activity record; both resolve the ledger path from the run manifest. Emit the matching `PROGRESS:` line — the command prints it as `progressLine` — and, when an activity record is required, the immediately following `ACTIVITY:` line from the same structured fields. |
 | `collect_usage` | Collect artifact/CLI-log-backed usage through the existing Okstra token-usage path; never substitute another runtime's session log. |
 
 An `implementation` run calls `dispatch_worker` twice: once for the Executor, then — after `await_workers` settles it — once for the verifiers. That second call's `--workers` list must omit the Executor's worker ID: it is materialized as the Executor on every dispatch, so a batch still carrying it is refused again. A verifier started beside the Executor observes base HEAD instead of the stage diff, so a single batch holding both is refused by `scripts/okstra_ctl/dispatch_core.py` `_validate_implementation_phase_order`, `--dry-run` included.
@@ -61,7 +61,8 @@ Use the screen to tell "still working" from "stuck", and to see at a glance whic
 - Worker completion is valid only from `workerDispatches[]`, terminal status sidecars, and required Result Paths. Pane creation alone is not completion.
 - Reverify uses a fresh jobs file at `runs/<task-type>/state/reverify-jobs-r<N>-<task-type>-<seq>.json`, sets `dispatchKind: "reverify-r<N>"`, and dispatches with `okstra team dispatch --project-root <root> --run-manifest <path> --dispatch-kind reverify-r<N> --jobs-file <jobs-file>`.
 - Report-writer uses a fresh one-job jobs file with `dispatchKind: "report-writer"` and the same schema, then dispatches through `okstra team dispatch --project-root <root> --run-manifest <path> --jobs-file <jobs-file>`.
-- Generate v2 jobs files with `okstra agent-prompt jobs --project-root <root> --run-manifest <path> --dispatch-kind <kind> --metadata <prompt-meta.json> [--metadata <prompt-meta.json>] --out <jobs-file>`. Pass only the metadata paths for the core-planned batch. The command derives the `workers` array, canonical role execution, result headers, and five digests, and verifies them through the same consumer used at dispatch. Do not transcribe those fields. Identical output is reused; differing output is preserved and requires a new `--out` path. Existing v1 files remain readable by dispatch.
+- Build a batch's jobs file in the call that materializes it: one `materialize --batch <file> --jobs-out <jobs-file>` call for every worker of the batch (convergence "Invocation materialization gate"), or one `materialize … --jobs-out <jobs-file>` call for the report writer, chained with `&& okstra team dispatch … --jobs-file <jobs-file>` in the same shell command. One materialize, verify, or jobs call per worker adds one lead turn over the whole context per worker; `team dispatch` verifies every invocation of the jobs file, so no `agent-prompt verify` call precedes it.
+- For metadata already materialized (a retry), generate v2 jobs files with `okstra agent-prompt jobs --project-root <root> --run-manifest <path> --dispatch-kind <kind> --metadata <prompt-meta.json> [--metadata <prompt-meta.json>] --out <jobs-file>`. Pass only the metadata paths for the core-planned batch. The command derives the `workers` array, canonical role execution, result headers, and five digests, and verifies them through the same consumer used at dispatch. Do not transcribe those fields. Identical output is reused; differing output is preserved and requires a new `--out` path. Existing v1 files remain readable by dispatch.
 - `workerResultPath` is the path the prompt tells the worker to write: the prompt's `**Result Path:**`, or `**Worker Result Path:**` for the report writer. `okstra team dispatch` refuses an entry whose value differs from that anchor, because the collector waits on `workerResultPath` while the worker writes where the anchor says. A reverify result is named `<worker-id>-worker-reverify-r<N>-<task-type>-<seq>.md`: the `-worker-` token is what the audit sidecar name inserts `-audit-` after (a name without it is refused with `worker result path has no canonical -worker- token`), and the round label is what keeps one round's file apart from the next. The report writer's `workerResultPath` is the roster's `resultPath` for `report-writer` and its `**Result Path:**` is the run manifest's `reportNarrativePath` — the report-writer materialization ([report-writer](../report-writer.md)) refuses any other pair. **Enforced:** `_validate_jobs_file_prompt_anchors` in `scripts/okstra_ctl/dispatch_state.py`, `_validate_report_writer_paths` in `scripts/okstra_ctl/agent/prompt_cli/materialize.py`.
 - `role` names the role execution's own role — `verifier` for reverify, `report-writer` for the report writer. It is not a per-round label: `dispatch_state.py` requires the entry's `role` to equal both the role execution's `role` and the duty's role, so a value like `worker-reverify-r<N>` is refused as `jobs file v2 identity does not match role execution authority`. The round lives in `dispatchKind` and in `invocationRef`. The report-writer completion paths include its narrative Markdown, worker-result pointer, and audit sidecar; they do not include the Phase 7 report record.
 - After either dispatch, run `okstra team await --project-root <root> --run-manifest <path>` before evaluating terminal status or completion paths.
@@ -69,5 +70,5 @@ Use the screen to tell "still working" from "stuck", and to see at a glance whic
 ## Completion, cleanup, and resume
 
 - Await through `okstra team await`; raw Result Path polling is forbidden for this backend.
-- Reclaim terminal panes after each batch through `okstra team reclaim --project-root <root> --run-manifest <path>` before dispatching the next batch. Reserve `teardown` for run completion.
+- Reclaim terminal panes after each batch through `okstra team reclaim --project-root <root> --run-manifest <path>` before dispatching the next batch; it records `phase-batch-cleanup` itself. Reserve `teardown` for run completion.
 - Resume from run artifacts and lead-events checkpoints. After usage collection, persistence, and the core user-approval gate, run `okstra team teardown --project-root <root> --run-manifest <path>` and tear down only Okstra-owned panes recorded for the run.

package/runtime/prompts/lead/context-loader.md

@@ -9,7 +9,7 @@
 
 Do not open, parse, or infer Okstra-owned task, run, discovery, or active-context JSON. This contract uses the fixed text views below before the lead contract is loaded, so it cannot bypass that boundary.
 
-- `okstra model-io project-context --project-root <project-root> --task-ref <task-ref>` provides project identity and the pointer for one explicit task reference. `task-ref` accepts a bare task ID, full task key, or that task's manifest path.
+- `okstra model-io project-context --project-root <project-root> --task-ref <task-ref>` provides project identity and the pointer for one explicit task reference. `task-ref` accepts a bare task ID, full task key, or that task's manifest path. A bare task ID matches the catalog `taskId` exactly, which is the whole task-id segment (`task-42-fix-login`), not a ticket-number prefix of it and not a `<group>/<task-id>` path.
 - `okstra model-io run-input --run-manifest <run-manifest-path>` provides the current run identity, worker roster, model assignments, and permitted artifact paths.
 
 ## Step 1: Resolve the Task and Run Paths

package/runtime/prompts/lead/convergence.md

@@ -52,7 +52,7 @@ Configure this in the `convergence` block of `task-manifest.json`. If the block
 | `verificationMode` | `"lightweight"` | `"lightweight"` or `"full-reanalysis"` |
 | `adversarial` | phase-aware: `true` for `requirements-discovery` / `error-analysis` / `implementation-option-selection` / `implementation-planning` / `project-analysis` / `feature-analysis` / `change-impact-analysis`, `false` otherwise | When `true`, Phase 5.5 runs in **adversarial mode** (see §"Adversarial Verification Mode"): verifiers actively try to refute each finding, the burden of proof sits on the claim, and `verificationMode` is forced to `"full-reanalysis"` scoped to the finding's cited evidence. Resolved by `scripts/okstra_ctl/render.py` `_build_convergence_block` and recorded in `config.adversarial` of the convergence state artifact. |
 
-**Auto-disable rule (BLOCKING).** Convergence requires ≥2 analyser workers to produce a meaningful consensus tally. When the active profile's `Required workers:` block (see `prompts/profiles/*.md`) resolves to fewer than 2 analyser workers — e.g. `release-handoff` (zero analyser workers, lead-only) — the lead MUST treat `convergence.enabled` as `false` for that run regardless of manifest configuration, skip Phases 5.5 and the plan-body verification round ([plan-body-verification](./plan-body-verification.md)), and record `finalState: "converged"` with `totalRounds: 0`, `round2SkippedReason: "auto-disabled"`, an empty `roundHistory`, and an explanatory note in `config` (e.g. `"autoDisabled": "fewer-than-two-analysers"`). The plan-body round inherits the same rule via its `gating=false` advisory path.
+**Auto-disable rule (BLOCKING).** Convergence requires ≥2 analyser workers to produce a meaningful consensus tally. When the active profile's `Required workers:` block (see `prompts/profiles/*.md`) resolves to fewer than 2 analyser workers — e.g. `release-handoff` (zero analyser workers, lead-only) — the lead MUST treat `convergence.enabled` as `false` for that run regardless of manifest configuration, skip Phases 5.5 and the plan-body verification round (`plan-body-verification` (the absolute path in **Okstra Runtime Resources**)), and record `finalState: "converged"` with `totalRounds: 0`, `round2SkippedReason: "auto-disabled"`, an empty `roundHistory`, and an explanatory note in `config` (e.g. `"autoDisabled": "fewer-than-two-analysers"`). The plan-body round inherits the same rule via its `gating=false` advisory path.
 
 ## Finding Category
 
@@ -66,7 +66,7 @@ Configure this in the `convergence` block of `task-manifest.json`. If the block
 
 ## Convergence Algorithm
 
-**Majority definition (BLOCKING).** "Majority" means *strictly greater than half* of the non-error votes for that finding (`verification-error` votes are excluded from both numerator and denominator). Ties — including the 1-AGREE / 1-DISAGREE case in a two-analyser roster — are NOT a majority: in intermediate rounds the finding is **carried forward**; in the final executed round the finding is classified `contested`. In adversarial mode a tie whose DISAGREE carries `counter-evidence` does not carry forward — it is classified `contested` in that round (§"Adversarial Verification Mode"). This rule applies identically to the plan-body verification round ([plan-body-verification](./plan-body-verification.md)) where the same verdict tokens are reused.
+**Majority definition (BLOCKING).** "Majority" means *strictly greater than half* of the non-error votes for that finding (`verification-error` votes are excluded from both numerator and denominator). Ties — including the 1-AGREE / 1-DISAGREE case in a two-analyser roster — are NOT a majority: in intermediate rounds the finding is **carried forward**; in the final executed round the finding is classified `contested`. In adversarial mode a tie whose DISAGREE carries `counter-evidence` does not carry forward — it is classified `contested` in that round (§"Adversarial Verification Mode"). This rule applies identically to the plan-body verification round (`plan-body-verification` (the absolute path in **Okstra Runtime Resources**)) where the same verdict tokens are reused.
 
 **Enforced:** the engine owns the classifier and replays it — `scripts/okstra_ctl/convergence_engine.py` `validate_final_state` recomputes each finding's expected final classification from its recorded votes and rejects the state when the persisted value differs, and `finalize` runs that same check before it writes, so a tie scored as a consensus never reaches the artifact. `okstra convergence validate` is the same call on demand. Nothing re-derives the majority rule outside the engine; a second implementation would only drift from it.
 
@@ -258,6 +258,35 @@ keeps its legacy read-only identity resolution for that schema version. The
 returned `promptPath` is the only body that may be dispatched; do not append
 role prose or reconstruct model headers after materialization.
 
+Materialize a whole dispatch batch — every row of one round plan, every
+critic-gap verification row of one dispatch kind — in one `okstra agent-prompt
+materialize --project-root <root> --run-manifest <run-manifest> --batch <file>
+--jobs-out <jobs-file>` call, not one call per worker. The batch file holds
+`{"invocations": [...]}`; each entry maps the per-invocation flags above,
+without the leading `--`, to their values (`"invocation-id"`, `"audience"`,
+`"assignment-ref"`, `"source-role-execution-ref"`, `"worker-id"`,
+`"dispatch-kind"`, `"instruction"`, `"prompt"`, `"result"`, and `"replace-undispatched": true` for a legacy v1 correction). A batch refuses those flags at the top level, so a v1 correction re-run through a batch carries `"replace-undispatched": true` in its entry. Each entry is
+materialized exactly as the single call would be and fails with the same error;
+a failure names the entry and every invocation already materialized, and an
+identical rerun after the fix reuses those unchanged. `--jobs-out` then writes
+the verified jobs file as `okstra agent-prompt jobs` would, so for
+`runner=cli-wrapper` rows one shell command covers the batch: render the
+instruction files, create the batch file, run `materialize --batch …
+--jobs-out <jobs-file> && <dispatcher> --project-root <root> --run-manifest
+<run-manifest> --dispatch-kind <kind> --jobs-file <jobs-file>`, where
+`<dispatcher>` is the one the planned execution surface selects below —
+`okstra team dispatch` when `terminalBackend` is `cmux-pane`, otherwise
+`okstra worker-dispatch`. `--jobs-out` needs a v2 run manifest
+(`executionIdentityVersion: 2`) and a path under the run directory; both are
+checked before any entry is materialized, so a legacy v1 run materializes the
+batch without `--jobs-out` and dispatches as it did before. `runner=native-session`
+rows are never chained into a jobs-file dispatcher: materialize them in the
+batch without `--jobs-out`, then `verify`, `record-dispatch` and the host call
+per row as below. Each worker in its own materialize call costs one lead turn
+over the whole context per worker. The batch call is `materialize_batch` in
+`scripts/okstra_ctl/agent/prompt_cli/batch.py`; the pre-materialization check is
+`check_jobs_target` in `scripts/okstra_ctl/agent/prompt_cli/jobs.py`.
+
 If the dispatch gate then rejects that prompt, preserve its prompt, metadata,
 reservation, and append-only Invocation bytes. A v2 reverify correction uses a
 fresh `--invocation-id` and fresh prompt/metadata path; the materializer rejects
@@ -267,8 +296,11 @@ may fix the task-instructions file and re-run the same `materialize` call with
 row names the invocation, replacement is rejected even for v1 and the prompt is
 history. Do not delete prompt, metadata, or reservation files by hand.
 
-Run `okstra agent-prompt verify --project-root <dir> --run-manifest <path> --metadata
-<metadataPath> --text` immediately before dispatch. A failed verification is a
+Before a native-session dispatch, run `okstra agent-prompt verify --project-root
+<dir> --run-manifest <path> --metadata <metadataPath> --text`. A `--jobs-file`
+dispatch needs no separate `verify` call: jobs generation and the dispatcher
+both run the same verification (`validate_dispatch_prompts` in
+`scripts/okstra_ctl/dispatch_state.py`). A failed verification is a
 pre-dispatch contract failure. For `runner=native-session`, pass only the
 returned `hostModelValue` to the host model argument. For
 `runner=cli-wrapper`, follow the planned execution surface after
@@ -305,15 +337,15 @@ The generated `**Errors log path:**` and `**Errors sidecar path:**` headers use
 
 An older instruction file may already contain the fixed boundary. Matching values are retained once; conflicting model, task type, or forbidden-actions values are reported with the expected value and a materialization remedy. Do not edit a dispatched prompt. Use a fresh invocation ID and prompt path for a dynamic reverify correction; undispatched initial prompts can be regenerated in place by the existing recovery path.
 
-After materialization, generate the batch file from the returned metadata paths:
-
 Name the reverify result `<role-slug>-worker-reverify-r<N>-<task-type>-<seq>.md` under the run's authorized worker-results directory. Its generated audit path is checked before dispatch.
 
+Materialize the round's workers and generate their jobs file in the one batch call (§"Invocation materialization gate"):
+
 ```bash
-okstra agent-prompt jobs --project-root <root> --run-manifest <manifest> --dispatch-kind reverify-r<N> --metadata <first-meta.json> --metadata <second-meta.json> --out <run-state>/reverify-jobs-r<N>.json
+okstra agent-prompt materialize --project-root <root> --run-manifest <manifest> --batch <run-state>/reverify-batch-r<N>.json --jobs-out <run-state>/reverify-jobs-r<N>.json
 ```
 
-Pass only the current engine-planned batch. The generator reads the actual result headers and canonical role execution, verifies all inputs, then publishes the file. Dispatch the emitted file with the selected adapter's `--jobs-file`; do not copy identity, path, or digest fields by hand. Existing v1 jobs-file consumers remain available.
+`okstra agent-prompt jobs --project-root <root> --run-manifest <manifest> --dispatch-kind reverify-r<N> --metadata <meta.json> --out <jobs-file>` builds the same file from metadata that is already materialized, such as a retry's. Pass only the current engine-planned batch. The generator reads the actual result headers and canonical role execution, verifies all inputs, then publishes the file. Dispatch the emitted file with the selected adapter's `--jobs-file`; do not copy identity, path, or digest fields by hand. Existing v1 jobs-file consumers remain available.
 
 ### Required reverify output contract (BLOCKING)
 
@@ -603,7 +635,7 @@ Render the critic-only task instructions with `okstra convergence critic-prompt
 verbatim — the same pattern as `okstra plan-items prompt` at round 1. Then run
 `okstra agent-prompt
 materialize` with `--audience scope-critic`, `--assignment-ref critic/scope`,
-the critic worker ID, and `--dispatch-kind critic`. Verify the returned
+`--worker-id scope` (the run-input Worker Roster line), and `--dispatch-kind critic`. Verify the returned
 `metadataPath` before dispatch and use its `promptPath` without modification.
 For `runner=native-session`, use only `hostModelValue`; for
 `runner=cli-wrapper`, use `okstra team dispatch` when `terminalBackend` is
@@ -696,8 +728,8 @@ The `final-verification` phase uses the same fresh one-shot `redispatch_worker`
 
 Before that call, write the acceptance-only task instructions and run `okstra
 agent-prompt materialize` with `--audience acceptance-critic`,
-`--assignment-ref critic/acceptance`, the critic worker ID, and
-`--dispatch-kind critic`. **The final-verification 96-nonblank-line prompt-body
+`--assignment-ref critic/acceptance`, `--worker-id acceptance` (the run-input
+Worker Roster line), and `--dispatch-kind critic`. **The final-verification 96-nonblank-line prompt-body
 cap applies to this dispatch too** — `resolve_prompt_plan` exempts a critic from
 the analysis equality group, not from the cap. The anchors and the duty contract
 account for roughly 51 of those lines, so the instructions you write have a
@@ -761,4 +793,4 @@ If `convergence.enabled: false`, this contract is skipped. Phase 6 operates usin
 
 ## Plan-body verification mode (implementation-planning only)
 
-Moved to its own contract: [plan-body-verification](./plan-body-verification.md). It fires only for `task-type = implementation-planning`, as a Phase 6 sub-step after the report-writer draft — read that file at that sub-step, NOT during the Phase 5.5 finding convergence this contract governs. The finding queue (`F-*`, this contract) and the plan-item queue (`P-*`, that contract) are disjoint — see its "MUTUAL EXCLUSION" section.
+Moved to its own contract: `plan-body-verification` (the absolute path in **Okstra Runtime Resources**). It fires only for `task-type = implementation-planning`, as a Phase 6 sub-step after the report-writer draft — read that file at that sub-step, NOT during the Phase 5.5 finding convergence this contract governs. The finding queue (`F-*`, this contract) and the plan-item queue (`P-*`, that contract) are disjoint — see its "MUTUAL EXCLUSION" section.

package/runtime/prompts/lead/okstra-lead-contract.md

@@ -23,7 +23,7 @@ This document is the operating contract and phase index. Detailed procedures liv
 | [context-loader](./context-loader.md) | Phase 1 task-bundle discovery, manifest fields, run-directory layout |
 | [team-contract](./team-contract.md) | Phase 2–5 worker roster, model assignment rules, prompt composition (anchor headers, `[Required reading]`, `[Error reporting]`), worker output contract, terminal statuses, usage tracking |
 | [convergence](./convergence.md) | Phase 5.5 finding convergence loop, finding categories, reverify dispatch, convergence state schema. Use the bounded common read under Doctrine lazy reads |
-| [plan-body-verification](./plan-body-verification.md) | Phase 6 plan-body verification sub-step (implementation-planning only) — plan-item extraction, verdict semantics, gate resolution, state schema. Read only the common procedure at that sub-step, using the bounded read below |
+| `plan-body-verification` (the absolute path in **Okstra Runtime Resources**) | Phase 6 plan-body verification sub-step (implementation-planning only) — plan-item extraction, verdict semantics, gate resolution, state schema. Read only the common procedure at that sub-step, using the bounded read below |
 | [report-writer](./report-writer.md) | Phase 6 final-report authorship, dispatch template, resume-safe dispatch, shared-graph integrity check, Phase 7 token-usage collector |
 
 Read-side inspection (`/okstra-inspect`) and scheduling (`/okstra-schedule-gen`) are user-invoked skills, not lead support contracts — the lead does not consult them during a run.
@@ -65,10 +65,10 @@ Every `okstra` command the lead documents cite, grouped by phase, each spelled w
 
 | Command | Use when | Procedure |
 |---|---|---|
-| `okstra lead-progress append --project-root <dir> --run-manifest <path> --phase <phase-id>` | Every `PROGRESS` checkpoint; print the `progressLine` it returns. `--phase` accepts only the listed phase ids; use `--worker`, `--field NAME=VALUE`, and `--detail <text>` for the rest | this contract "Progress reporting" |
+| `okstra lead-progress append --project-root <dir> --run-manifest <path> --phase <phase-id>` | Every `PROGRESS` checkpoint the command performing that step does not record itself; print the `progressLine` it returns. `--phase` accepts only the listed phase ids; use `--worker`, `--field NAME=VALUE`, and `--detail <text>` for the rest | this contract "Progress reporting" |
 | `okstra agent-activity append --project-root <dir> --run-manifest <path> --kind <kind> --agent <agent> --outcome <outcome> --summary <text>` | Before each activity boundary when the run manifest declares `activityContractVersion: 1` | launch prompt "Progress reporting" |
 | `okstra error-log append-observed --out <errors-path> --task-key <key> --phase <phase> --agent <provider-worker> --agent-role <role> --model <model> --error-type <type> --command-kind <kind> --command <command> --message <text>` | Record an observed failure. `--agent` takes the provider worker id (`codex-worker`); an execution label goes in `--execution-label` | this contract "Errors log path wiring"; `team-contract` "Worker error-log command" |
-| `okstra approval-decision open --ledger <path> --task-key <key> --task-type <type> --run-seq <seq> --clarification-id <C-NNN> --ticket-id <id> --statement <text> --expected-form <form> --classification <class> --origin <origin> --user-confirmation <text> --unblock-condition <text> --recommended-disposition <disposition>` | Open an approval blocker after the user confirmed it | this contract "User confirmation before an approval blocker" |
+| `okstra approval-decision open --ledger <path> --task-key <key> --task-type <type> --run-seq <seq> --clarification-id <C-NNN> --ticket-id <id> --statement <text> --expected-form <form> --classification <class> --origin <origin> --user-confirmation <text> --unblock-condition <text> --recommended-disposition <disposition> [--supersedes <C-NNN>]` | Open an approval blocker after the user confirmed it | this contract "User confirmation before an approval blocker" |
 | `okstra approval-decision carry --ledger <path> --clarification-id <C-NNN> --from-responses <path>` | Carry a decision answered in an earlier run | `report-writer` "Role-owned inputs" |
 | `okstra approval-decision resolve --ledger <path> --clarification-id <C-NNN> --disposition <disposition> --user-text <text> --user-response-ref <ref>` | Record the user's disposition of an approval row; it touches no verdict | `plan-body-verification` "Round protocol" |
 | `okstra user-response show --report <path>` | Not a lead step: the `okstra-user-response` skill reads approval rows through it, so an `origin` outside the schema enum breaks every later read | `plan-body-verification` "Round protocol" |
@@ -77,24 +77,25 @@ Every `okstra` command the lead documents cite, grouped by phase, each spelled w
 
 | Command | Use when | Procedure |
 |---|---|---|
-| `okstra agent-prompt materialize --project-root <dir> --invocation-id <id> --audience <audience> --instruction <path> --prompt <path>` | Materialize every worker prompt; the command owns the anchor headers and paths | `convergence` "Invocation materialization gate"; `report-writer` "Report-writer dispatch" |
-| `okstra agent-prompt verify --project-root <dir> --metadata <path>` | Immediately before each dispatch | `convergence` "Invocation materialization gate" |
+| `okstra agent-prompt materialize --project-root <dir> --invocation-id <id> --audience <audience> --instruction <path> --prompt <path>` | Materialize one worker prompt; the command owns the anchor headers and paths. Add `--jobs-out <jobs-file>` in run mode to also write its verified jobs file (report writer) | `convergence` "Invocation materialization gate"; `report-writer` "Report-writer dispatch" |
+| `okstra agent-prompt materialize --project-root <dir> --run-manifest <path> --batch <file> --jobs-out <jobs-file>` | Materialize every worker of one dispatch batch and write its jobs file in one call — one call per batch, never one per worker. For `runner=cli-wrapper` rows chain the dispatcher the execution surface selects in the same shell command: `&& okstra team dispatch … --jobs-file <jobs-file>` on `terminalBackend: cmux-pane`, `&& okstra worker-dispatch … --jobs-file <jobs-file>` otherwise. `--jobs-out` needs a v2 run manifest; `runner=native-session` rows take the batch without `--jobs-out` and keep their per-row `verify` + `record-dispatch` + host call | `convergence` "Invocation materialization gate" |
+| `okstra agent-prompt verify --project-root <dir> --metadata <path>` | Immediately before a native-session dispatch (`record-dispatch`). Not needed before a `--jobs-file` dispatch: jobs generation and the dispatcher verify every invocation | `convergence` "Invocation materialization gate" |
 | `okstra agent-prompt record-dispatch --project-root <dir> --run-manifest <path> --metadata <path> --enforcement-mode <mode>` | Record a native-session dispatch | `convergence` "Invocation materialization gate" |
 | `okstra agent-prompt jobs --project-root <dir> --run-manifest <path> --dispatch-kind <kind> --metadata <path> --out <jobs-file>` | Build a verified jobs file for `okstra team dispatch` | cmux adapter "cmux dispatch details" |
-| `okstra team dispatch --project-root <dir> --run-manifest <path>` | Dispatch pane-backed workers (`terminalBackend` is `cmux-pane`) | cmux adapter "Semantic operation mapping" |
-| `okstra worker-dispatch --project-root <dir> --run-manifest <path>` | Dispatch CLI-backed workers when `terminalBackend` is not `cmux-pane` | this contract "Model assignments" |
-| `okstra codex-dispatch --project-root <dir> --run-manifest <path>` | CLI-backed dispatch for a prepared Codex run; never under the cmux adapter | cmux adapter "cmux dispatch details" |
+| `okstra team dispatch --project-root <dir> --run-manifest <path>` | Dispatch pane-backed workers (`terminalBackend` is `cmux-pane`). Records `phase-3-team-create`, `phase-4-dispatch` and `phase-6-synthesis` as this contract "Progress reporting" describes; emit its `progressLines` | cmux adapter "Semantic operation mapping" |
+| `okstra worker-dispatch --project-root <dir> --run-manifest <path>` | Dispatch CLI-backed workers when `terminalBackend` is not `cmux-pane`. Records `phase-3-team-create`, `phase-4-dispatch`, `phase-5-collect` and `phase-6-synthesis`; emit its `progressLines` | this contract "Model assignments" |
+| `okstra codex-dispatch --project-root <dir> --run-manifest <path>` | CLI-backed dispatch for a prepared Codex run; never under the cmux adapter. Same command as `worker-dispatch`, and records the same checkpoints | cmux adapter "cmux dispatch details" |
 
 ### Phase 5 — await and collect
 
 | Command | Use when | Procedure |
 |---|---|---|
-| `okstra team await --project-root <dir> --run-manifest <path>` | Wait for pane-backed workers | cmux adapter "Semantic operation mapping" |
+| `okstra team await --project-root <dir> --run-manifest <path>` | Wait for pane-backed workers. Records `phase-5-poll` on entry and again when the counts changed, and `phase-5-collect` for each `initial` dispatch it settled; emit the `PROGRESS:` lines it prints | cmux adapter "Semantic operation mapping" |
 | `okstra worker-liveness --team-state <path> --dispatch-id <id>` | Probe a pending worker; add `--wait` to block until result, death, or timeout | `team-contract` "Mid-run liveness probes" |
 | `okstra agent-prompt link-result --project-root <dir> --run-manifest <path> --dispatch-id <id> --result <path>` | Link a returned result to its dispatch | `convergence` "Invocation materialization gate" |
 | `okstra agent-prompt reject-result --project-root <dir> --run-manifest <path> --dispatch-id <id> --superseded-by <id> --reason <text>` | Retire a linked result before a corrective dispatch links its own | `plan-body-verification` "Round protocol" |
 | `okstra worker-audit-check --run-dir <path> --task-type <type> --seq <seq>` | Check a live worker's audit sidecars and citations before accepting its result; add `--worker <id>` | `team-contract` "Lead Redispatch Policy on Result-Missing" |
-| `okstra team reclaim --project-root <dir> --run-manifest <path>` | Close finished dispatches' panes at a batch boundary | this contract "Progress reporting" |
+| `okstra team reclaim --project-root <dir> --run-manifest <path>` | Close finished dispatches' panes at a batch boundary and record `phase-batch-cleanup panes=<n>`; add `--gate` before a user gate, which prints `phase-gate-cleanup` and records nothing | this contract "Progress reporting" |
 
 ### Phase 5.5 / 5.6 — convergence and critic
 
@@ -138,9 +139,9 @@ Every `okstra` command the lead documents cite, grouped by phase, each spelled w
 
 | Command | Use when | Procedure |
 |---|---|---|
-| `okstra report-finalize --project-root <dir> --run-manifest <path> --report <path>` | Run the whole Phase 7 sequence; do not run its steps separately | `report-writer` "Phase 6 → Phase 7 execution sequence" |
+| `okstra report-finalize --project-root <dir> --run-manifest <path> --report <path>` | Run the whole Phase 7 sequence; do not run its steps separately. Without `--only` it records `phase-7-persist` first; emit its `progressLines` | `report-writer` "Phase 6 → Phase 7 execution sequence" |
 | `okstra report-translate check-data --run-manifest <path>` | Check an existing translation after a narrative correction | `report-writer` "Phase 6 → Phase 7 execution sequence" |
-| `okstra handoff record-verified --plan-run-root <dir> --stage <N> --report-path <path> --data-json <path>` | Record an accepted final-verification against its stage | this contract "Lifecycle Phase Boundaries" |
+| `okstra handoff record-verified --plan-run-root <dir> --stage <N> --report-path <path> --data-json <path>` | Record an accepted final-verification against its stage. `report-finalize` runs it in its `record-verified` step; run it by hand only to repair a registry after that step failed | `report-writer` "Phase 6 → Phase 7 execution sequence" |
 | `okstra team teardown --project-root <dir> --run-manifest <path>` | Close every recorded pane at the end of the run | cmux adapter "Semantic operation mapping" |
 
 **Names that do not exist.** Lead sessions have called these; each fails with `unknown command`. Use the command on the right.
@@ -205,7 +206,7 @@ User-utterance interpretation rule:
 - If the current phase's outputs are already complete and the user clearly wants to advance, reply with the phase-transition checklist above and the exact next-run command. Wait for explicit user confirmation before any action that belongs to the next phase.
 - If the Next-Phase Pointer target (`nextRecommendedPhase.phase`) is `implementation-planning`, the next run produces a **plan**, not code. The next run after that is `implementation`.
 
-**Enforced:** the Forbidden actions column is declared in `prompts/profiles/forbidden-actions.json` and scanned post-hoc by `validators/forbidden_actions.py` `scan_forbidden_actions`, which matches this run's task type through `forbidden_patterns_for` against the commands the run actually executed.
+**Enforced:** the Forbidden actions column is declared in each phase module’s `boundary.json` (`scripts/okstra_ctl/phases/<phase>/boundary.json`) and scanned post-hoc by `validators/forbidden_actions.py` `scan_forbidden_actions`, which matches this run's task type through `forbidden_patterns_for` against the commands the run actually executed.
 
 ## Progress reporting (BLOCKING)
 
@@ -219,12 +220,22 @@ A single okstra run frequently spans 30–120 minutes with multi-minute silent w
 
 Record each checkpoint with `okstra lead-progress append --project-root <dir> --run-manifest <path> --phase <phase-id>`, then emit the `progressLine` it prints as the user-facing line. The command resolves `leadEventsPath` from the run manifest and writes the checkpoint there — on a host whose adapter declares `sessionAccounting: artifact-only` that ledger is the only place the post-hoc validator can read it, so a conversation line alone leaves no trace and the run is reported as missing the checkpoint. Pass `--worker <role>` on the per-worker checkpoints (it rewrites a phase-specific functional label into the roster role team-state records), `--field NAME=VALUE` for the remaining `key=value` tokens in the order the line carries them, and `--detail <text>` where the line ends in a verb phrase; the wording listed below is the default for the fixed-prose checkpoints.
 
+Some checkpoints are recorded by the command that performs the step, because that command holds the fact the line states:
+
+- `okstra team dispatch` (on a `terminalBackend: cmux-pane` run) and `okstra worker-dispatch` / `okstra codex-dispatch` record `phase-3-team-create using implicit team` when the dispatch is the one that writes the implicit-team marker into team-state (no `teamCreate` recorded yet), `phase-4-dispatch` for each `initial` job, and `phase-6-synthesis` on the run's first report-writer dispatch.
+- On a `cmux-pane` run `okstra team await` records `phase-5-poll` on entry and again when the counts changed; `okstra team await` there and `okstra worker-dispatch` record `phase-5-collect worker=<role> status=<terminal-status>` for each `initial` dispatch they settled — the settlement is the result verification: the required artifact exists, the mutation audit passed and the result is linked to its dispatch, or the attempt closed as `error` / `timeout`. A retried attempt counts once its retry settles.
+- On a `cmux-pane` run `okstra team reclaim` records `phase-batch-cleanup`.
+- The team commands record nothing on any other `terminalBackend`: a run that dispatches with `okstra team dispatch` and waits with `okstra team await` there appends the team commands' checkpoints itself. `okstra worker-dispatch` still records its own, as listed above.
+- `okstra report-finalize` without `--only` records `phase-7-persist` before its first step, so `validate-run` reads it.
+
+Emit the `PROGRESS:` lines those commands print (the trailing text lines of `team await` and `team reclaim`, or `progressLines` in the JSON the others print) verbatim, and do not call `lead-progress append` for them — each extra call is one more lead turn over the whole context. Everything else still goes through `lead-progress append`: every other checkpoint; `phase-3-team-create` when the lead itself recorded the marker (the concurrent-run `skipped (concurrent-run)` variant); and `phase-4-dispatch`, `phase-5-collect` and `phase-6-synthesis` for a worker dispatched through a host-native primitive (`record-dispatch` / `link-result`). `phase-5-collect` from a command does not replace the lead's own acceptance check (`okstra worker-audit-check`), and on an activity-contract-v1 run each `worker-dispatched` / `worker-completed` activity is still the lead's to append. **Enforced:** `scripts/okstra_ctl/dispatch_checkpoints.py`, `record_checkpoint` in `scripts/okstra_ctl/lead_progress.py`, `tests/run/test_team_cmux_backend.py`, `tests/run/test_okstra_ctl_dispatcher.py`, `tests/report/test_report_finalize.py`.
+
 For an `implementation-planning` run whose run manifest declares `activityContractVersion: 1`, record every required activity boundary with `okstra agent-activity append` against the manifest-provided `leadEventsPath`. Model-facing calls pass prose through `--summary-file <md>` and a command through `--command`, `--command-cwd`, `--command-exit-code`, and `--command-output-file <md>`; do not construct `--command-record` JSON. The ordering is fixed: the structured append succeeds first, the matching `PROGRESS:` line is emitted second, and the immediately following `ACTIVITY:` line projects the same structured fields into the conversation language. Do not reconstruct structured activity from conversation text. If the append fails, do not present that activity boundary as completed.
 
 The live projection follows this shape:
 
 ```text
-PROGRESS: phase-4-dispatch worker=codex-worker model=gpt-6-sol
+PROGRESS: phase-4-dispatch worker=codex-worker model=gpt-6.1-sol
 ACTIVITY: id=A-001 agent=codex-worker summary="Verify Stage Map paths and commands" items=P-Step-001,P-Step-002 result=runs/.../codex-worker-....md outcome=pending
 ```
 
@@ -237,19 +248,19 @@ Required checkpoints:
 - `PROGRESS: phase-1-intake reading task bundle` — at the start of Phase 1, before issuing parallel Read calls.
 - `PROGRESS: phase-1-intake complete` — after all intake reads return.
 - `PROGRESS: phase-2-prompts preparing <N> worker prompts` — at the start of Phase 2, before any `Write` to the assigned prompt paths.
-- `PROGRESS: phase-3-team-create <adapter-specific-status>` — after selected-adapter setup is recorded in team-state. The stable phase id is retained for artifact compatibility.
+- `PROGRESS: phase-3-team-create <adapter-specific-status>` — after selected-adapter setup is recorded in team-state. The stable phase id is retained for artifact compatibility. When the first dispatch writes the implicit-team marker, that dispatch command records the line.
 - `PROGRESS: phase-4-dispatch worker=<role> model=<model>` — once per worker, immediately before `dispatch_worker`. `<role>` is the **roster** role, exactly as team-state's `workers[].role` records it (`Claude worker`, `Codex worker`) — the checkpoint is matched against that entry, so a phase-specific functional label (`Claude verifier`, `Codex executor`) names no roster worker and fails the check. Only `claude-worker`-style hyphenation of the same roster role is also accepted.
 - `PROGRESS: phase-5-poll pending=<n> done=<m>` — emitted when entering the wait and when the pending attempts or terminal outcomes change. A host wait returning without a worker state change does not create a new checkpoint.
-- `PROGRESS: phase-5-collect worker=<role> status=<terminal-status>` — once per worker, immediately after the result file is verified. `<role>` is the roster role, same rule as `phase-4-dispatch` above.
+- `PROGRESS: phase-5-collect worker=<role> status=<terminal-status>` — once per worker, immediately after the result file is verified. `<role>` is the roster role, same rule as `phase-4-dispatch` above. `team await` (cmux-pane run only) and `worker-dispatch` record it for the dispatches they settle.
 - `PROGRESS: phase-5-stage stage=<N> title=<title> steps=<count>` — `implementation` only, immediately before the Executor's `phase-4-dispatch` line, after parsing the approved plan's Stage Map and this run's `**Stage for this implementation run:**` anchor. `<title>` is the stage's Stage Map title and `<count>` is its `stepwiseExecution` row count, both read from the approved plan — this is the line that tells the user WHICH plan stage this run executes. The numbering keeps the line sorted where the work happens — the stage runs in Phase 5.
 - `PROGRESS: phase-5-stage-complete stage=<N> steps=<done>/<count>` — `implementation` only, immediately after the Executor result is verified and its `### Stage Carry Evidence` block is parsed, before the verifier dispatch. `<done>` counts the block's `stepResults[]` rows whose `status` is `done` — read from the emitted block, never recomputed from git. Omitted when the Executor ends without carry evidence (`FAIL` or a non-result); the user then learns the outcome from `phase-5-collect status=<terminal-status>`.
 - `PROGRESS: phase-5.5-convergence round=<N> queue=<count>` — at the start of each convergence round (Phase 5.5).
 - `PROGRESS: phase-5.6-critic provider=<provider> gaps=<n>` — after the critic result is collected (Phase 5.6, opt-in; the critic dispatch itself fires concurrently with the first 5.5 reverify round). Omitted when `convergence.critic.enabled == false`.
-- `PROGRESS: phase-batch-cleanup panes=<n>` — immediately after cleaning up the previous batch's panes, at each batch boundary (① just before the first `phase-5.5-convergence` round ② just before the `phase-6-synthesis` report-writer dispatch). `<n>` is the number of panes closed at that boundary — the panes of dispatches this run recorded and that have since finished — read from the `okstra team reclaim --project-root <dir> --run-manifest <path> --dry-run` pass taken immediately before the closing pass, never estimated. A pane the harness opened for its own teammate carries no recorded id, so it is not counted and not closed. Expose only the counts and NEVER expose a raw `paneId` or worker handle. Just before the first batch (analysis-worker dispatch) there is nothing to clean up, so it is a no-op and the marker is omitted.
-- `PROGRESS: phase-6-synthesis dispatching report-writer-worker` — at the start of Phase 6.
-- `PROGRESS: phase-5.5.9-plan-verify round=<N> items=<count>` — immediately before dispatching each plan-body verification round (`implementation-planning` only; see [plan-body-verification](./plan-body-verification.md) §"Round protocol"). Each round is a worker batch like any other, so round 2 and later MUST be preceded by a `phase-batch-cleanup` line reclaiming the previous round's verifiers. The numbering keeps this line sorted where the work happens — after Phase 6, because the round verifies the drafted plan body.
+- `PROGRESS: phase-batch-cleanup panes=<n>` — immediately after cleaning up the previous batch's panes, at each batch boundary (① just before the first `phase-5.5-convergence` round ② just before the `phase-6-synthesis` report-writer dispatch). `<n>` is the number of panes closed at that boundary — the panes of dispatches this run recorded and that have since finished — counted by `okstra team reclaim --project-root <dir> --run-manifest <path>` as the panes that pass closed, never estimated; no `--dry-run` pass is needed to learn it. A pane the harness opened for its own teammate carries no recorded id, so it is not counted and not closed. Expose only the counts and NEVER expose a raw `paneId` or worker handle. Just before the first batch (analysis-worker dispatch) there is nothing to clean up, so it is a no-op and the marker is omitted.
+- `PROGRESS: phase-6-synthesis dispatching report-writer-worker` — at the start of Phase 6. `team dispatch` (cmux-pane run only) and `worker-dispatch` record it on the first report-writer dispatch; on any other backend a `team dispatch` run appends it with `lead-progress append`.
+- `PROGRESS: phase-5.5.9-plan-verify round=<N> items=<count>` — immediately before dispatching each plan-body verification round (`implementation-planning` only; see `plan-body-verification` (the absolute path in **Okstra Runtime Resources**) §"Round protocol"). Each round is a worker batch like any other, so round 2 and later MUST be preceded by a `phase-batch-cleanup` line reclaiming the previous round's verifiers. The numbering keeps this line sorted where the work happens — after Phase 6, because the round verifies the drafted plan body.
 - `PROGRESS: user-confirm <C-NNN> <the question, one line>` — immediately before asking the user about anything that would otherwise become an open `Blocks=approval` row (see "User confirmation before an approval blocker" below). Not tied to a phase: it fires wherever the blocker surfaces. `<C-NNN>` is the id the row will carry, so the answer and the row can be matched afterwards.
-- `PROGRESS: phase-7-persist updating manifests` — at the start of Phase 7.
+- `PROGRESS: phase-7-persist updating manifests` — at the start of Phase 7. `okstra report-finalize` records it.
 - `PROGRESS: phase-7-teardown shutting-down-workers` — only after usage collection and user approval, immediately before `shutdown_workers`; omitted when no cleanup resource exists or the user keeps it.
 - `PROGRESS: complete final-report=<relative-path>` — final summary line, after all persistence.
 
@@ -291,7 +302,7 @@ The sequence is fixed:
 4. On an answer — record the raw text in the row's `userInput`, set `status: answered` and `userConfirmation: asked-and-answered`, and apply the selected disposition in this run.
 5. Only when asking fails does the row stay open: `asked-awaiting` when the user has not answered, `deferred-no-interactive-session` when this run has no user to ask.
 
-For report contract v3 `implementation-planning`, record active approval decisions only through `okstra approval-decision`; report assembly derives each report row's status, resolution, and backtraces from that lead-owned ledger plus the activity ledger. Classify a user-owned selection as `user-decision`, a surviving non-correctness majority disagreement as `noncritical-dissent`, and a cited path/symbol mismatch, `P-Req-*` coverage mismatch, or independent Requirement Coverage blocker as `correctness-critical`. `select` is limited to `user-decision`. `accept-risk` is available to all three classifications: it ends the gate, keeps the DISAGREE votes and the clarification row as evidence, and later stages read that record. `request-revision` / `reject` are available to all three and still withhold the next phase. Contract v2 remains read-only compatible; do not create a new v2 report. **Enforced:** `scripts/okstra_ctl/approval_decisions.py` rejects an invalid option/disposition combination at the moment the decision is opened or resolved, so a classification that does not admit the disposition never reaches the ledger. The backtraces are not re-derived afterwards — they are produced by assembly (next paragraph), which is why the lead has no hand-written path to them. `validators/validate-run.py` `_validate_v3_approval_context` checks the one claim assembly cannot see: an `approved` frontmatter published against a row that still blocks progress.
+For report contract v3 `implementation-planning`, record active approval decisions only through `okstra approval-decision`; report assembly derives each report row's status, resolution, and backtraces from that lead-owned ledger plus the activity ledger. Classify a user-owned selection as `user-decision`, a surviving non-correctness majority disagreement as `noncritical-dissent`, and a cited path/symbol mismatch, `P-Req-*` coverage mismatch, or independent Requirement Coverage blocker as `correctness-critical`. `select` is limited to `user-decision`. `accept-risk` is available to all three classifications: it ends the gate, keeps the DISAGREE votes and the clarification row as evidence, and later stages read that record. `request-revision` / `reject` are available to all three and still withhold the next phase. Contract v2 remains read-only compatible; do not create a new v2 report. **Enforced:** `scripts/okstra_ctl/approval_decisions.py` rejects an invalid option/disposition combination at the moment the decision is opened or resolved, so a classification that does not admit the disposition never reaches the ledger. The backtraces are not re-derived afterwards — they are produced by assembly (next paragraph), which is why the lead has no hand-written path to them. `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_v3_approval_context` checks the one claim assembly cannot see: an `approved` frontmatter published against a row that still blocks progress.
 
 The approval state transitions are fixed:
 
@@ -301,7 +312,7 @@ The approval state transitions are fixed:
 
 Do not move `answered` back to `open` because a check failed. The user's choice stands. Record the failed check on the row; later stages still see the DISAGREE votes.
 
-`open` blocks until the user judges. `answered` with `select` / `accept-risk` / `answer`, `resolved`, and `obsolete` do not block approval or the next phase. `request-revision` and `reject` still withhold the next phase until this report's `supersessionLedger` records that the answer was incorporated (`superseded` or `no-dependent-statement`). `accept-risk` does not require re-verification `AGREE`. The worker votes stay on the plan item so a later stage can still see the dissent. **Enforced:** `scripts/okstra_ctl/clarification_items.py` `row_blocks_progress`, `validators/validate-run.py` `_user_accepted_plan_item_ids`.
+`open` blocks until the user judges. `answered` with `select` / `accept-risk` / `answer`, `resolved`, and `obsolete` do not block approval or the next phase. `request-revision` and `reject` still withhold the next phase until this report's `supersessionLedger` records that the answer was incorporated (`superseded` or `no-dependent-statement`). `accept-risk` does not require re-verification `AGREE`. The worker votes stay on the plan item so a later stage can still see the dissent. **Enforced:** `scripts/okstra_ctl/clarification_items.py` `row_blocks_progress`, `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_user_accepted_plan_item_ids`.
 
 When a terminal row preserves a pre-correction dissent classification, keep superseded votes in `state/plan-body-verification-implementation-planning-<seq>.json`. Activities that implement or check the decision record the exact `C-NNN` in `clarificationRefs` and the affected `P-*` identifiers in `planItemIds`. Report assembly verifies that every resolution `checkRefs` value names an existing activity and derives each plan item's `clarificationRefs`; the lead never copies those references into `approvalContext`. A corrected coverage-only blocker keeps its `C-NNN` in the non-blocking Requirement Coverage row's `decisionRefs`. An `obsolete` row is invalid while its disagreement or coverage blocker remains active in the current plan. **Enforced at assembly, not after it:** `scripts/okstra_ctl/report_assembly.py` `_clarification_row` refuses a resolution whose `checkRefs` is empty, names an activity that does not exist, or names one whose `clarificationRefs` omits this `C-NNN`; `_attach_plan_backlinks` derives every plan item's `clarificationRefs` from the activity ledger, so a hand-copied reference has nowhere to enter. Nothing recomputes these links afterwards — assembly failing is the whole check.
 
@@ -326,7 +337,7 @@ The table below documents those prep-time seed values **for reference only** —
 | Lead role | opus | -- | runtime-specific role label; orchestration + convergence supervision + final-report review/approval |
 | Report writer worker | sonnet | report-writer-worker | common + role + duty contracts composed per invocation; `native-session` execution |
 | Claude worker | opus | claude-worker | common + role + duty contracts composed per invocation; `native-session` execution |
-| Codex worker | gpt-6-sol | codex-worker | duty + task instructions composed per invocation; deterministic `worker-dispatch` execution |
+| Codex worker | gpt-6.1-sol | codex-worker | duty + task instructions composed per invocation; deterministic `worker-dispatch` execution |
 | Antigravity worker | gemini-3.1-pro | antigravity-worker | duty + task instructions composed per invocation; deterministic `worker-dispatch` execution |
 
 Each analysis assignment follows its recorded `runner`. `runner=native-session` uses the host's native subagent primitive after `host-native-spec-link-gate`. `runner=cli-wrapper` follows the planned execution surface after `core-pre-dispatch` verification: `okstra team dispatch` when `terminalBackend` is `cmux-pane`, otherwise the deterministic `okstra worker-dispatch` process boundary. No LLM transport wrapper sits in front of a provider CLI.
@@ -378,7 +389,9 @@ After context-loader completes, read **only the compact intake files below** in
 **Doctrine lazy reads (BLOCKING — read at the round, not at Phase 1):**
 
 - [convergence](./convergence.md) — read the common procedure with the bounded command below before the first `PROGRESS: phase-5.5-convergence` line of any run that runs a convergence round.
-- [plan-body-verification](./plan-body-verification.md) — read the common procedure with the bounded command in the Phase 6 sub-step before the first `PROGRESS: phase-5.5.9-plan-verify` line.
+- `plan-body-verification` (the absolute path in **Okstra Runtime Resources**) — read the common procedure with the bounded command in the Phase 6 sub-step before the first `PROGRESS: phase-5.5.9-plan-verify` line.
+
+For a run frozen before the phase-package migration, a missing `prompts/lead/plan-body-verification.md` pointer resolves within the asset root containing this lead contract. Identify its unique `okstra_ctl` package at `scripts/okstra_ctl`, `python/okstra_ctl`, or `lib/python/okstra_ctl` by `__init__.py`, then read `phases/implementation_planning/instructions/plan-body-verification.md` inside that package at the original Phase 6 sub-step. Preserve the bounded read and the `phase-5.5.9-plan-verify` checkpoint order below. If the package is ambiguous or the resource is missing, stop and report it; do not search another installation or rewrite frozen profiles, manifests, prompts or run context. The mapping is checked by `scripts/okstra_ctl/phases/implementation_planning/tests/test_instruction_assets.py`; the existing entry guard checks read timing by the unchanged basename.
 
 Both stay out of the Phase 1 baseline for the token reason above, and neither is optional at its round: together they carry more than half of this contract family's MUST clauses, so a round dispatched without the read is a round run from memory. **Enforced:** `validators/validate_session_conformance.py` `_ENTRY_GUARD_READS` requires each read — a `Read` call or a shell command naming the file — inside this run's window and before that checkpoint. The requirement is conditioned on the checkpoint actually appearing, so a run that holds no such round is never asked for it.
 
@@ -406,7 +419,9 @@ checks the emitted common procedure. The same entry-guard read trace applies.
 
 **Implementation profile lazy reading discipline (BLOCKING — applies only when `task_type == "implementation"`):**
 
-The `implementation` profile's thin core (`prompts/profiles/implementation.md`) is intentionally minimal so the Phase 1 baseline stays small. Three sidecar files carry the bulk of the rules and MUST be read at the listed phase — do NOT pre-load them at Phase 1. The sidecar list and each one's `Read at` phase live in that profile's "Lazy section pointers" table, which arrives in the Phase 1 intake via `analysis-profile.md`, so it is already in context whenever this discipline applies.
+The `implementation` profile's thin core (`scripts/okstra_ctl/phases/implementation/profile.md`) is intentionally minimal so the Phase 1 baseline stays small. Three sidecar files carry the bulk of the rules and MUST be read at the listed phase — do NOT pre-load them at Phase 1. The sidecar list and each one's `Read at` phase live in that profile's "Lazy section pointers" table, which arrives in the Phase 1 intake via `analysis-profile.md`, so it is already in context whenever this discipline applies.
+
+For a run frozen before the phase-package migration, resolve a missing `prompts/profiles/_implementation-*.md` pointer within the asset root containing this lead contract. That root has one `okstra_ctl` package at `scripts/okstra_ctl`, `python/okstra_ctl`, or `lib/python/okstra_ctl`, identified by its `__init__.py`. Read `phases/implementation/instructions/<same-basename>` inside that package at the original `Read at` phase. If no unique package or requested file exists, stop and report the missing resource. Keep the frozen `analysis-profile.md` unchanged and do not search another installation. New runs carry resolved instruction paths. The path mapping is checked by `scripts/okstra_ctl/phases/implementation/tests/test_assets.py`; the entry guard below checks the recorded read timing.
 
 **Entry guard (BLOCKING).** Before transitioning into Phase 5 or Phase 6 for an `implementation` run, lead MUST load the sidecar(s) whose `Read at` (per that table) matches the entering phase — either a single `Read` tool call, or a shell command naming that file (`cat`, `sed -n`), since some hosts steer file reads to the shell. If lead enters the phase without that load recorded in the selected adapter's conformance evidence/event source, phase entry is refused — lead writes a `contract-violation` to the run-level errors log with `--message "implementation-sidecar-not-loaded"` and stops. Re-entry requires the sidecar Read first. **Enforcement:** the Phase 7 validator (`validate_session_conformance.py`) verifies post-hoc that all three sidecar loads exist in the selected adapter's declared source within this run's window, and that they precede the `phase-6-synthesis` / `phase-7-persist` checkpoints respectively.
 
@@ -446,7 +461,7 @@ For `improvement-discovery`, Lead records `## Primary Pass Assignments` in the P
 2. Verify the run manifest's `leadRuntime`, `leadAdapter`, dispatch backend, concurrency metadata, and artifact paths.
 3. Execute the adapter's pre-dispatch setup without substituting another adapter's primitive.
 4. Persist the setup outcome in team-state using the existing fields required by that backend.
-5. Emit the canonical `PROGRESS: phase-3-team-create <adapter-specific-status>` checkpoint. The phase id remains stable for artifact compatibility; only the adapter-owned verb phrase varies.
+5. Emit the canonical `PROGRESS: phase-3-team-create <adapter-specific-status>` checkpoint. The phase id remains stable for artifact compatibility; only the adapter-owned verb phrase varies. When the implicit-team marker is written by the first `team dispatch` / `worker-dispatch`, that command records the line and prints it; emit it from there.
 
 **Enforced:** `validators/validate_session_conformance.py` `_check_progress_checkpoints` requires the `phase-3-team-create` checkpoint once any worker was dispatched, and `validate-run.py` `validate_team_state` reads the setup outcome this phase persists.
 
@@ -552,54 +567,9 @@ All categories must appear in the final synthesis. Do not omit contested or work
 
 If only one worker result is usable: reduced-confidence synthesis. If evidence is missing: say `I don't know`. If no meaningful worker differences: say so explicitly.
 
-### Phase 6 sub-step: Plan-body verification (implementation-planning only, BLOCKING)
-
-After the Report writer worker narrative is reviewed, **if** `task_type == "implementation-planning"` **and** `task-manifest.json` `convergence.planBodyVerification.enabled == true` (default), the lead MUST run the plan-body verification sequence on the consolidated plan body before declaring Phase 6 complete and entering Phase 7.
-
-This is a Phase 6 sub-step — it does NOT introduce a new top-level lifecycle phase; the lead operating-phase model (Phase 1 Intake → Phase 7 Persist, labels in the "Quick Reference" table above as the single source of truth) is preserved. The round's outcome is read from the final report's `### 5.5.9 Plan Body Verification` section and `implementationPlanning.planBodyVerification` in its data.json — it is not a separate lifecycle phase identifier.
-
-**REQUIRED RESOURCE:** Read the common procedure of [plan-body-verification](./plan-body-verification.md) for the round protocol, plan-item ID scheme (`P-Dir-1` for selected-direction; `P-Opt-*` for legacy candidate comparison; then `P-Step-*` / `P-Dep-*` / `P-Val-*` / `P-Rb-*` / `P-Req-*` / `P-Prep-*`), verdict semantics (`AGREE` / `DISAGREE(a-f)` / `SUPPLEMENT`), classification rules, gate-result resolution, and state-path authority. Read the state-file schema only when diagnosing state or projection validation. For `P-Dir-1`, compare `directionRealization` with `selectedDirectionRef` and its snapshot: verify the core mechanism, architecture boundaries, planning invariants, and any hidden direction change.
-
-Read from the resolved runtime resource path, replacing `<plan-body-contract-path>`
-with that resource's absolute path. This prints the complete common procedure and
-its conditional reading table, stopping before reference examples:
-
-```sh
-awk '/^## Reference material$/ {exit} {print}' '<plan-body-contract-path>'
-```
-
-Follow the conditional reading table for later rounds and validation failures.
-The command keeps the filename in the read trace used by
-`validators/validate_session_conformance.py` `_ENTRY_GUARD_READS`.
-The bounded output is checked by
-`tests/contract/test_contract_examples_execute.py::test_plan_body_common_read_keeps_gate_rules`.
-
-Distinct from Phase 5.5 finding convergence:
-
-- Phase 5.5 reconciles worker **findings** (F-*) from independent analysis.
-- This sub-step reconciles the **consolidated plan body** (P-*) authored by the Report writer worker.
-- The two rounds use disjoint queues and separate state files — see [plan-body-verification](./plan-body-verification.md) "MUTUAL EXCLUSION (BLOCKING)".
-
-Lead's responsibilities in this sub-step (in order):
-
-For a new `implementation-planning` run, the fixed order is initial verification → one planner self-fix → targeted re-verification → lead decision or immediate user confirmation. The initial verification is round 1 and the targeted re-verification is round 2. A second automatic self-fix is a contract violation. When `okstra plan-items prepare` reports `"gating": false` (one-stage `no-design-inputs` plan), skip the self-fix loop and the sweep batch: extraction and round 1 still run, then go to the user gate. Two-or-more stages, a PREP item, or non-empty `designPreparation.items` keep `gating: true` and the full order.
-
-1. Build the queue with `okstra plan-items prepare --narrative <report-writer-narrative.md> --run-manifest <run-manifest>`, place the output of `okstra plan-items prompt --run-manifest <run-manifest>` verbatim in every verifier prompt, then run `okstra plan-items validate-prepared --narrative <report-writer-narrative.md> --run-manifest <run-manifest>`. Python resolves the one convergence-owned state path from that run identity. The lead MUST NOT summarise, select, omit, reorder, or renumber the queue. Each prompt uses the compact subject plus the lossless payload, and asks every item:
-
-   ```text
-   What concrete false-positive input, failure ordering, or omitted dependency
-   would make this plan item incorrect even if its happy path succeeds?
-   ```
-
-   An `AGREE` response records the considered counterexample and exclusion reason in its note; unverified external material is `verification-error`, not `DISAGREE`.
-2. Dispatch a single plan-body reverify round to every analyser worker in the roster (`claude`, `codex`, and `antigravity` when opted in). `Report writer worker` is NOT a participant in this round.
-3. Record each verifier Markdown result through `okstra plan-items apply-verdicts --state <plan-body-verification.json> --result <worker-id>=<result.md> --round <N>`. Python validates every submitted `P-*` identifier against the current convergence state and overwrites only that round's verdicts. Then resolve the gate result to one of `passed` / `passed-with-dissent` / `blocked-by-disagreement` / `aborted-non-result`.
-4. After `okstra plan-verify` succeeds, run `okstra plan-items complete-round --state <plan-body-verification.json> --run-manifest <current-run-manifest.json> --round <N>`. Python reads the current worker assignments, atomically appends the convergence-owned history, and updates its nested final projection. This state is the only plan-verification input report assembly reads.
-5. Record every *in-scope execution* `majority-disagree` decision through `okstra approval-decision`; record its plan and clarification links only on activities. Do not promote `observed` / `deferred` / `record` items, and do not append `clarificationItems[]` directly.
-6. Run report assembly after the final plan-body state, approval ledger, design snapshot, activity ledger, and team state are complete. Assembly writes `implementationPlanning.planBodyVerification` and derived clarification rows while publishing `data.json` once.
-7. Publish the report record `frontmatter.approved` field as `false`. There is no in-body `- [ ] Approved` marker line — approval lives only in the record (see [plan-body-verification](./plan-body-verification.md) §"Round protocol" step 9). The user may set it to `true` (via `--approve` or the in-session wizard) when the gate is `passed` / `passed-with-dissent`, or under `blocked-by-disagreement` once every remaining `Blocks=approval` row is user-proceeded (`accept-risk` / `select` / `answer`); `aborted-non-result` still withholds approval. **Enforced:** run-prep (`scripts/okstra_ctl/run.py` `_validate_approved_plan` / `_blocking_gate_survives_user_decision`) fail-closes an `approved: true` plan whose blocking gate carries no user disposition, and `validators/validate-run.py` `_validate_plan_body_gate_recompute` fails a gate value upgraded past what the recorded votes support. Manually flipping a blocked gate to passing is a contract violation.
+### Phase 6 sub-step: Plan-body verification (implementation-planning only)
 
-If `convergence.planBodyVerification.enabled == false` (set by `--no-plan-verification` or by `okstra config set plan-verification off`), the entire sub-step is skipped and the top-of-report Approval marker is rendered unconditionally (legacy behaviour). This opt-out is intended for fast iteration only and is not recommended for handoff-ready plans.
+For `implementation-planning`, follow the Phase 6 plan-body verification sub-step in the selected phase profile before entering Phase 7. The phase profile owns the enablement gate, round protocol, and approval publication rules.
 
 ## Phase 7: Artifact persistence and validator handoff
 
@@ -674,6 +644,7 @@ The run-level error log lives at `<runDir>/logs/errors-<task-type>-<seq>.jsonl`.
 | Injecting `[Required reading]` into lightweight reverify prompts | Lightweight reverify forbids re-reading source materials — see [convergence](./convergence.md) "Reverify prompt: required-reading suppression" |
 | Letting `convergence.maxRounds` default to 2 for `requirements-discovery` | Resolve effective default to `1` for discovery and put it in the grouped input |
 | Issuing serial Read calls in Phase 1 | The intake files are independent — issue all Read calls in a single message (parallel) |
+| Running `agent-prompt materialize`, `jobs`, or a jobs-file dispatcher once per `runner=cli-wrapper` worker of a batch | One `okstra agent-prompt materialize --project-root <dir> --run-manifest <path> --batch <file> --jobs-out <jobs-file>` call per batch, chained with the dispatcher the execution surface selects (`okstra team dispatch` on `cmux-pane`, `okstra worker-dispatch` otherwise) and `--jobs-file <jobs-file>`. Native-session rows still dispatch one host call per row — see [convergence](./convergence.md) "Invocation materialization gate" |
 | Flagging an adapter-shortened dispatch prompt as "incomplete" because it omits host-loaded material | The Worker Preamble pointer and core inputs remain mandatory; the selected adapter may omit duplicate host-loaded definitions |
 | Waiting silently after `dispatch_worker` returns without a completed worker artifact | A dispatch acknowledgement is not completion — call `await_workers` and enforce the selected adapter's liveness policy |
 | Re-sending a finding absent from the persisted round plan | Dispatch exactly the engine-returned `findingIds`; see [convergence](./convergence.md) "Re-verification Dispatch" |

package/runtime/prompts/lead/phase-routing.md

@@ -16,3 +16,67 @@ Allowed targets:
 - `done`
 
 `finalVerification.routingRecommendation` is an **object** with exactly two fields — `target`, one value from the Allowed targets list, and `rationale`, the sentence tying that choice to the verdict and the blocker list. Free routing prose is not the field; a target named only in the prose does not route the task, because Phase 7 projects `workflow.nextRecommendedPhase` from `target` alone. `final-verification` re-runs this phase on the same head and is for exactly one situation: every remaining blocker is an environment or configuration fault whose cause this report already names — a `qaCommands` entry pointing at a path that no longer exists, a missing credential, a stale fixture — so nothing in the code, the plan, or the selected direction is being re-decided. Name the repair in the `rationale`. When any blocker needs a code, plan, or direction change, route to the phase that owns that change instead; routing a defect you have not diagnosed back into this phase re-runs the verification that already failed. Both `release-handoff` forms are allowed ONLY when the verdict is release-ready — `accepted`, or `conditional-accept` with every condition declaring `blocksReleaseHandoff: false`. Either verification scope may route there: release-handoff opens one PR per stage, so a release-ready `single-stage` run is the evidence for that stage's PR, and `release-handoff(stage-group)` is only a scope qualifier that projects onto the same phase. `done` ends the lifecycle here. Enforcement: `schemas/final-report-v2.0.schema.json` rejects a `target` outside the enum, a missing `rationale`, and a string in place of the object; `validators/validate-run.py` rejects a missing `target` and a verdict that is not release-ready routed to either `release-handoff` form (naming the condition ids that block it).
+
+## release-handoff
+
+- if any cited verdict is `blocked`, a `conditional-accept` carrying a condition that blocks release, or any other token (including ambiguous phrasing like "looks good"), the run MUST end immediately with status `blocked` and a routing recommendation back to `error-analysis` or `implementation-planning`. Do NOT prompt the user; Do NOT run any git command.
+
+- **Routing recommendation**: explicit `done` token, since release-handoff is the terminal lifecycle phase. If the run ended in `skip` or `cancel`, or delivered only some of the selected stages, the recommendation MUST state which stages still need a PR and that re-entry into release-handoff is appropriate.
+
+1. **Entry-gate audit** — the report cites, for every stage it delivered, that stage's final-verification report path and the literal `Verdict Token` row with a release-ready value. If any is missing, or a `conditional-accept` stage's PR body omits its conditions, the run is invalid and MUST be re-routed to `final-verification`.
+
+Enforcement boundary: `scripts/okstra_ctl/release_gate.py` `release_handoff_allowed` rejects non-release-ready verification evidence, and `scripts/okstra_ctl/phases/release_handoff/operations.py` `_require_eligible` blocks ineligible stages. The lead performs the routing and report-completeness judgement through the phase-transition checklist in [the lead contract](./okstra-lead-contract.md); these code checks do not choose its next destination.
+
+## technical-verification
+
+Route only to `implementation-option-selection`, with one matching phase-continuation follow-up. The next comparison consumes this report through `--clarification-response` and authors fresh feasibility votes.
+
+Enforcement: `technicalVerification.routing.nextTaskType` and phase-continuation constraints in the report schema; `scripts/okstra_ctl/report_routing.py` checks the routing value during publication and run validation.
+
+## implementation-option-selection
+
+When no candidate is valid and explicit eligible technical facts remain, route to `technical-verification` to collect experimental evidence. Keep `rankedOptions` empty and `recommendedOptionId` null. `validate_blocked_answer_channel` rejects this route while user decisions remain unresolved or no safe, explicitly classified technical fact is available. Historical blocked reports can be supplied explicitly without rewriting their verdict.
+
+With valid options set routing to `pending-direction-selection`; without a valid option use `blocked`.
+
+In `candidate-comparison`, keep `preselectedDirection` null and do not route directly to `implementation-planning`. In `preselected-validation`, emit exactly one validated option, an empty `candidateAudit`, a cited `preselectedDirection`, and routing `implementation-planning`.
+
+## requirements-discovery
+
+determine whether `error-analysis` or `implementation-option-selection` is the next safe step. Direct `implementation-planning` or `implementation` handoff is never a valid routing target — implementation requires direction selection followed by an approved `implementation-planning` report
+
+The lead owns the final routing decision and safe resume guidance. The phase supplies request classification, rejection criteria, missing evidence and dependency facts. The report schemas constrain `requirementsDiscovery.routing.nextTaskType`; common `report_routing.fanout_routing_errors` checks each packet destination.
+
+## error-analysis
+
+Allowed targets:
+
+- `implementation-option-selection`
+- `error-analysis`
+
+If the cause is credible, recommend `implementation-option-selection` with the verified evidence; if the cause is still unclear, recommend another `error-analysis` run with the next diagnostic. The lead's Phase Routing settles the next phase.
+
+A route to `implementation-option-selection` requires a credible leading cause referenced by `routing.leadingCauseId` and `begin-option-selection` as the direction. A route back to `error-analysis` requires the sharp next diagnostic and `continue-investigation` as the direction.
+
+The selected target is recorded in `errorAnalysis.routing.nextTaskType`. `schemas/final-report-v2.0.schema.json` and `schemas/final-report-v3.0.schema.json` constrain the target values. `okstra_ctl.phases.error_analysis.validation` checks the cause reference, matching verdict directions, and the single phase-continuation row. Common `okstra_ctl.next_phase` projects that selected target without choosing a destination.
+
+## improvement-discovery
+
+Both branches: Direction `routing`; Next Step "ask the user to select K candidates (see the ## 5.9 table)".
+
+- `## 3. Recommended Next Steps` first entry summarises per-candidate routing and proposes new task-key names of the form `<task-group>/imp-<Cand-ID>`
+
+### Candidate conversion
+
+- Each candidate the user picks becomes a new okstra task. Suggested task-key: `<task-group>/imp-<Cand-ID>`.
+- The candidate row's Recommended next-phase determines which `--task-type` to launch with.
+
+## implementation
+
+Pick `final-verification` when this stage's plan items landed and validation passed; `error-analysis` when a failure's cause is not understood; `implementation-planning` when the approved plan itself no longer fits the evidence; `implementation` when work remains inside this stage and the next run is a fix run.
+
+For the `selected-direction` plan branch: A direction change routes to `implementation-option-selection`; a detail-only plan correction routes to `implementation-planning`.
+
+For the legacy candidate-comparison branch: Any deviation MUST be justified in the final report AND routed to a new `implementation-planning` run; never silently expand scope.
+
+Enforcement boundary: the lead applies these semantic distinctions through the phase-transition checklist in [the lead contract](./okstra-lead-contract.md). `tests/contract/test_prompt_fragment_ownership.py` preserves the decision rules at this canonical location; it checks instruction ownership, not the correctness of an individual model judgement.