okstra 0.186.7 → 0.187.0

package/docs/architecture.md

@@ -18,7 +18,7 @@ Its core capabilities at a glance are:
 - **Single python authority**: All prepare wiring—resolving profiles/workers/models, computing paths, rendering, and central record_start—is concentrated in a single function, [`okstra_ctl.run.prepare_task_bundle()`](../scripts/okstra_ctl/run.py). `okstra.sh` and the `okstra-run` skill are thin callers of that same function and do not pass state through environment variables. Task identity, paths, and workflow state are recalculated from authoritative on-disk files every time.
 - **Host-aware handoff**: Claude Code, Codex, Antigravity, Grok, and Kimi can keep their current native session as the lead. The standalone compatibility launcher still starts a new `claude` process by default, while the external adapter uses registered CLI wrappers. Every path consumes the same `prepare_task_bundle` outputs.
 - **Required team contract**: The `Required workers:` block in each phase profile is authoritative for the roster. General analysis phases use Claude/Codex analysers plus a report writer by default, while Antigravity, Grok, and Kimi are included only when allowed by both the profile and `--workers`. Lead-oriented phases such as `release-handoff` have separate rosters.
-- **User-home install + project-local task bundles**: One `npx okstra@latest install` command installs the runtime (`~/.okstra/{lib/python, bin, templates, prompts}`) and installs public skills to `~/.agents/skills/` by default. If `~/.claude` exists, it also installs Claude skills and six worker agent definitions (`~/.claude/agents/*-worker.md`). Only user entry-point skills are exposed in the skill list; lead/support operating contracts are installed as runtime resources under `~/.okstra/prompts/` and are not discoverable as skills. Global conversation memory is stored separately from projects under `~/.okstra/memory-book/`. Task bundles and discovery metadata are stored under `.okstra/` in the target project. **In addition, `<PROJECT_ROOT>/.claude/settings.local.json` is provisioned as a symlink to `~/.okstra/templates/settings.local.json`** (`okstra setup` or `okstra-ctl` prepare manages it idempotently; if a regular file already existed, it is preserved as `.bak.<timestamp>` before replacement).
+- **User-home install + project-local task bundles**: One `npx okstra@latest install` command installs the runtime (`~/.okstra/{lib/python, bin, templates, prompts}`) and installs public skills to `~/.agents/skills/` by default. If `~/.claude` exists, it also installs Claude skills and six worker agent definitions (`~/.claude/agents/*-worker.md`). Only user entry-point skills are exposed in the skill list; lead/support operating contracts are installed as runtime resources under `~/.okstra/prompts/` and are not discoverable as skills. Global conversation memory is stored separately from projects under `~/.okstra/memory-book/`. Task bundles and discovery metadata are stored under `.okstra/` in the target project. **In addition, `<PROJECT_ROOT>/.claude/settings.local.json` is provisioned as a symlink to `~/.okstra/templates/settings.local.json`** (`okstra setup` and the prepare path manage it idempotently; if a regular file already existed, it is preserved as `.bak.<timestamp>` before replacement).
 - **Resume and clarification**: Supports resuming the same task and responding to follow-up questions from the lead through `--task-key`, `--resume-clarification`, and `--clarification-response`.
 - **Dual-audience derived views and telemetry**: For schema v2, derives the full reading copy Markdown (on demand) and task-specific human-facing HTML independently from the same v2 data.json. Schema v1 and quick Markdown reports keep their compatibility renderer. Worker error sidecars, wrapper log sidecars, and token-usage/cost accounting remain separate audit inputs.
 
@@ -85,7 +85,7 @@ okstra's prepare responsibilities are consolidated in a single Python entry poin
 - Resolves task-brief / clarification-response paths (cwd first → PROJECT_ROOT fallback)
 - Computes the stable task root and all paths/sequences inside a per-task mutex (`~/.okstra/.locks/<task-key>.lock`), then persists them to `<run-dir>/manifests/run-context-<seq>.json`
 - Persists user input to `<run-dir>/manifests/run-inputs-<seq>.json`
-- Renders the instruction set (`analysis-profile.md`, `analysis-packet.md`, `analysis-material.md`, `task-brief.md`, `reference-expectations.md`, `final-report-template.md`, `final-report-schema.json`, optional `clarification-response.md`, optional `directive.txt`, final-verification-only `verification-target.md`, canonical `lead-execution-prompt.md`, and its Claude-named compatibility alias) and writes a run prompt snapshot
+- Renders the instruction set (`analysis-profile.md`, `analysis-packet.md`, `analysis-material.md`, `task-brief.md`, `reference-expectations.md`, `final-report-template.md`, `final-report-schema.json`, optional `clarification-response.md`, optional `directive.txt`, final-verification-only `verification-target.md`) and writes the lead prompt to `runs/<task-type>/prompts/lead-execution-prompt-<task-type>-<seq>.md` alongside its `.meta.json` invocation record
 - Updates `task-manifest.json`, `task-index.md`, `run-manifest-*.json`, `history/timeline.json`, and `discovery/{latest-task,task-catalog}.json`
 - Writes a preassigned Claude session ID and `sessions/claude-resume-*.sh` (unless `--render-only` is used)
 - Records record_start in the central indexes (`~/.okstra/{active,recent}.jsonl`, `projects/<id>/{index.jsonl, meta.json}`)
@@ -126,7 +126,7 @@ Runtime entry points are consolidated in Python packages. Bash and skills only c
 - [`okstra_ctl.workflow`](../scripts/okstra_ctl/workflow.py) — phase rules (PHASE_ALLOWED_OUTPUTS / PHASE_FORBIDDEN_ACTIONS).
 - [`okstra_ctl.material`](../scripts/okstra_ctl/material.py) — `analysis-material.md` body + related-tasks builder.
 - [`okstra_ctl.session`](../scripts/okstra_ctl/session.py) · [`okstra_ctl.seeding`](../scripts/okstra_ctl/seeding.py) — Claude session ID / resume command / installation validation / runtime settings.
-- [`okstra_ctl.{ids,index,invocation,jsonl,project_meta,reconcile,resolver,sequence,batch,backfill,listing,locks,tmux}`](../scripts/okstra_ctl/) — existing central-index (`~/.okstra`) modules.
+- [`okstra_ctl.{ids,index,invocation,jsonl,project_meta,reconcile,sequence,backfill,listing,locks}`](../scripts/okstra_ctl/) — existing central-index (`~/.okstra`) modules.
 - [`okstra_project.{resolver,state}`](../scripts/okstra_project/) — PROJECT_ROOT resolution + project.json upsert + task-catalog/manifest reader.
 - [`okstra_ctl.manager_cli`](../scripts/okstra_ctl/manager_cli.py), [`manager_store`](../scripts/okstra_ctl/manager_store.py), [`manager_sync`](../scripts/okstra_ctl/manager_sync.py), [`manager_launch`](../scripts/okstra_ctl/manager_launch.py), [`manager_paths`](../scripts/okstra_ctl/manager_paths.py) — cross-project manager state, one-way project snapshot sync, and child launch packet/context creation for `okstra manager`.
 
@@ -134,7 +134,6 @@ Runtime entry points are consolidated in Python packages. Bash and skills only c
 
 - [`scripts/okstra.sh`](../scripts/okstra.sh) — standalone compatibility launcher: CLI parsing / interactive prompt / `prepare_task_bundle` invocation / default `exec claude`. In-host Claude Code, Codex, and Antigravity runs use `okstra-run` and keep their current native session.
 - [`scripts/lib/okstra/{cli,globals,interactive,project-resolver,usage}.sh`](../scripts/lib/okstra/) — CLI/interactive support only; contains no artifact-generation logic.
-- [`scripts/okstra-ctl.sh`](../scripts/okstra-ctl.sh) + [`scripts/lib/okstra-ctl/`](../scripts/lib/okstra-ctl/) — central control-center CLI (list / show / open / rerun / reconcile / etc.).
 
 ### Runtime assets (templates + lead resources)
 
@@ -153,7 +152,7 @@ Runtime entry points are consolidated in Python packages. Bash and skills only c
 - [`prompts/lead/okstra-lead-contract.md`](../prompts/lead/okstra-lead-contract.md) is the runtime-neutral lifecycle core: phase boundaries, artifacts, convergence, report ownership, and persistence semantics.
 - `prompts/lead/adapters/claude-code.md`, `prompts/lead/adapters/codex.md`, `prompts/lead/adapters/antigravity.md`, and `prompts/lead/adapters/external.md` map the same semantic operations to one selected host runtime. The generated launch prompt exposes the core path plus exactly one adapter path.
 - `prompts/lead/adapters/cmux.md` is selected by environment rather than by runtime: when the run manifest's `terminalBackend` is `cmux-pane`, every lead runtime resolves to it and dispatches through `okstra team`, because okstra owns the worker panes on that path instead of the host. It overrides only the adapter and the dispatch mode; the lead's agent, role, and session accounting still come from its own runtime.
-- Runtime metadata and role assignments are persisted separately, but the lead provider is derived from the host: Claude Code maps to Claude, Codex maps to Codex, and Antigravity CLI maps to Antigravity. New runs persist `hostRuntime`, `leadAssignment`, and `workerAssignments[]`; each assignment records its provider, model, execution value, and resolved `native-session` or `cli-wrapper` runner. `lead-execution-prompt.md` is canonical, while `claude-execution-prompt.md` is a byte-identical compatibility alias for historical consumers.
+- Runtime metadata and role assignments are persisted separately, but the lead provider is derived from the host: Claude Code maps to Claude, Codex maps to Codex, and Antigravity CLI maps to Antigravity. New runs persist `hostRuntime`, `leadAssignment`, and `workerAssignments[]`; each assignment records its provider, model, execution value, and resolved `native-session` or `cli-wrapper` runner. `lead-execution-prompt.md` is canonical: one file per run at `runs/<task-type>/prompts/lead-execution-prompt-<task-type>-<seq>.md`. No Claude-named copy is written — `resources.claudeExecutionPromptPath` in the run manifest is a key alias that resolves to that same file for historical consumers.
 - Host and provider registries remain separate: the active registered host owns the native lead session, while non-native providers run through their registered CLI wrappers.
 - [`skills/okstra-setup/SKILL.md`](../skills/okstra-setup/SKILL.md) — **first-run bootstrap**. Runs `okstra install` and creates `project.json`.
 - [`skills/okstra-run/SKILL.md`](../skills/okstra-run/SKILL.md) — host-aware in-session entry point that starts an okstra task in the current registered host session and calls `prepare_task_bundle` directly.
@@ -272,7 +271,7 @@ The following environment variables are read only as user settings, not for stat
 - `OKSTRA_HOME` — overrides the central directory location (default `~/.okstra`).
 - `OKSTRA_DEFAULT_LEAD_MODEL`, `OKSTRA_DEFAULT_CLAUDE_MODEL`, `OKSTRA_DEFAULT_CODEX_MODEL`, `OKSTRA_DEFAULT_ANTIGRAVITY_MODEL`, `OKSTRA_DEFAULT_REPORT_WRITER_MODEL` — model defaults.
 - `OKSTRA_TOOL_NAME`, `OKSTRA_COMMAND_NAME` — display names in usage output.
-- `OKSTRA_RUN_SEQ_OVERRIDE` — run-sequence override forced by okstra-ctl rerun / test hooks (per-process).
+- `OKSTRA_RUN_SEQ_OVERRIDE` — run-sequence override forced by test hooks (per-process).
 
 Other variables such as `PROJECT_ID`, `TASK_GROUP`, `RUN_*`, `FINAL_*`, and `CLAUDE_*` are not exported and do not leak into child processes.
 
@@ -298,12 +297,12 @@ The legacy standalone shell path remains Claude-specific:
 
 Kimi and Grok implement this same lead contract. Their provider roles remain `lead`, `analyser`, and `critic`; they do not gain executor, verifier, or report-writer roles from being lead-capable hosts.
 
-Both modes create identical artifacts (task-manifest, run-manifest, timeline, instruction set, and central-index registration), so subsequent `okstra-ctl` commands (list / show / rerun / reconcile) operate consistently without distinguishing between them.
+Both modes create identical artifacts (task-manifest, run-manifest, timeline, instruction set, and central-index registration), so the run-index consumers (`okstra run-audit`, `okstra error-zip`) operate consistently without distinguishing between them.
 - The handed-off native host acts as the Okstra lead, responsible for orchestration and final synthesis.
 - The default worker policy remains Claude + Codex analysis and a Claude report writer. Antigravity, Grok, and Kimi are profile-gated optional assignments; Grok and Kimi are read-only analyser/critic providers.
 - The lead assigns worker responsibilities and makes the final judgment after reading the task bundle.
 - okstra Claude assets installed in the user home (`~/.claude/skills`, `~/.claude/agents`) instruct Claude to dispatch workers through `Agent(name: ...)`; workers automatically join the session's implicit team.
-- **Team lifecycle (Claude Code v2.1.178+)**: v2.1.178 removed the `TeamCreate` / `TeamDelete` tools and the `team_name` parameter from `Agent(...)`. When `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` (seeded into `settings.json` by `okstra install`), one implicit team per session is created automatically at startup. In Phase 3, the lead does not call a team-creation tool. It records only the `teamName` audit label and `teamCreate: { attempted: false, status: "implicit", splitPane: <true-if-TMUX-is-set> }`, then dispatches workers through `Agent(name: "<role>-worker", run_in_background: true)` (without team_name). Split-pane teammates appear when `$TMUX` is set and `teammateMode: auto`; outside tmux they run in-process, and both modes are valid. At run end, after Phase 7 token accounting, the lead checks for remaining tmux panes and asks whether to clean up worker teammates only for split-pane runs. If approved, `okstra-team-reconcile.sh` marks dead-pane stale-active members inactive and sends each completed teammate a `SendMessage` shutdown_request. There is no tool for deleting the implicit team; it disappears when the session ends. If the user keeps the teammates, they remain in the FleetView roster and the lead tells the user to remove them through Teams/FleetView (see *Run-end teammate teardown* in `prompts/profiles/_common-contract.md`). Phase 7 token accounting locates worker sessions by top-level `agentName` or nested `subagents/agent-a<name>-<hash>.jsonl` filenames when `teamCreate.status` is `implicit`/`skipped`/`error`.
+- **Team lifecycle (Claude Code v2.1.178+)**: v2.1.178 removed the `TeamCreate` / `TeamDelete` tools and the `team_name` parameter from `Agent(...)`. When `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` (seeded into `settings.json` by `okstra install`), one implicit team per session is created automatically at startup. In Phase 3, the lead does not call a team-creation tool. It records only the `teamName` audit label and `teamCreate: { attempted: false, status: "implicit" }`, then dispatches workers through `Agent(name: "<role>-worker", run_in_background: true)` (without team_name). Teammates run in-process. At run end, after Phase 7 token accounting, the lead asks whether to clean up worker teammates. If approved, it sends each completed teammate a `SendMessage` shutdown_request. There is no tool for deleting the implicit team; it disappears when the session ends. If the user keeps the teammates, they remain in the FleetView roster and the lead tells the user to remove them through Teams/FleetView. Phase 7 token accounting locates worker sessions by top-level `agentName` or nested `subagents/agent-a<name>-<hash>.jsonl` filenames when `teamCreate.status` is `implicit`/`skipped`/`error`.
 
 ## Lead prompt contract
 
@@ -322,7 +321,7 @@ The standard `okstra` workflow applies the following team contract consistently
 - The current host-native provider owns the synthesis-only lead session: Claude on Claude Code, Codex on Codex.
 - Every selected worker comes from the profile roster and provider capability registry. The default analysis policy remains Claude + Codex + a report writer; Antigravity, Grok, and Kimi are attempted only when the profile and resolved roster include them.
 - `Report writer worker` focuses on report structure and evidence organization, while the host-native lead remains the final synthesis owner. Claude is the default report-writer provider; Codex may be selected explicitly.
-- Model defaults are provider and functional-role policy. Fallbacks include Claude lead/analyser=`opus`, Codex lead/analyser=`gpt-5.6-sol`, Claude report writer=`sonnet`, Antigravity=`gemini-3.1-pro`, Grok analyser=`grok-4.6`, and Kimi analyser=`kimi-k2.7-code`. Selectable catalog models may be assigned to every role.
+- Model defaults are provider and functional-role policy. Fallbacks include Claude lead/analyser=`opus`, Codex lead/analyser=`gpt-5.6-sol`, Claude report writer=`sonnet`, Antigravity=`gemini-3.1-pro`, Grok analyser=`grok-4.6`, and Kimi analyser=`kimi-k3`. Selectable catalog models may be assigned to every role.
 - Before the final judgment, each required role in the current run's worker roster must have either a result or an explicit terminal status (`completed`, `timeout`, `error`, `not-run`).
 - Every attempted worker (`completed`, `timeout`, `error`) must have an assigned worker prompt history file under the current run's `prompts/` directory.
 - Worker timing begins at the atomic transition to `in-progress`, which records `workers[].startedAt` in `team-state.json`; prompt creation time is not a dispatch proxy. `okstra worker-state transition` and both dispatch adapters share `dispatch_state.transition_worker_status`, while `okstra worker-liveness --team-state ... --worker ...` reads that timestamp as the launch-grace authority for both probe kinds — the in-process audit sidecar is reused on re-dispatch, so only `startedAt` separates the previous attempt's last heartbeat from this dispatch's silence.
@@ -352,7 +351,7 @@ The complete artifact lifecycle is: worker results → Round 0 grouping → redu
 
 Cross-verification does not mean that worker A reviews worker B's entire result. Round 0 records multi-source agreement immediately, and the reducer asks independent analyser instances to vote only on single-source or still-unresolved findings selected in the persisted queue. The report writer is never a voter. It organizes the validated result, while the later plan-body round verifies the consolidated `P-*` plan items rather than reopening the `F-*` finding queue.
 
-The lead writes the grouped input, then advances it through the internal admin CLI operations `okstra convergence seed`, `plan-round`, `apply-round`, optional `apply-critic-gaps`, `finalize`, and `validate`. For worker W, each generated dispatch excludes findings originating from W; resolved findings leave the queue permanently. Lightweight reverify receives only its current persisted batch and embedded evidence, not the original analysis packet, profile, brief, or instruction set. Its prompt carries an exact task type and active-phase forbidden-actions block; dispatch validates those phase anchors, and the run validator rejects a recorded phase-boundary violation. Terminal worker non-results and completed per-finding `UNVERIFIABLE` responses become `verification-error`; the engine never fabricates a `DISAGREE` vote. The report writer does not vote and consumes the validated terminal convergence state and every analysis-worker result as read context. Under report contract v3 it writes only the narrative Markdown, a pointer, and its audit sidecar. Approval decisions, activity, execution, convergence, design preparation, and plan-body verification remain in their single-owner inputs. Phase 7 validates those inputs and atomically publishes `data.json` once. The full reading copy is rendered on demand. Newly finalized convergence output is schema v1.3; under the compatibility path, valid historical final schema versions v1.0, v1.1, or v1.2 are reused and consumed without rewrite.
+The lead writes the grouped input, then advances it through the internal admin CLI operations `okstra convergence seed`, `plan-round`, `apply-round`, optional `apply-critic-gaps`, `finalize`, and `validate`. For worker W, each generated dispatch excludes findings originating from W; resolved findings leave the queue permanently. Lightweight reverify receives only its current persisted batch and embedded evidence, not the original analysis packet, profile, brief, or instruction set. Its prompt carries an exact task type and active-phase forbidden-actions block; dispatch validates those phase anchors, and the run validator rejects a recorded phase-boundary violation. Terminal worker non-results and completed per-finding `UNVERIFIABLE` responses become `verification-error`; the engine never fabricates a `DISAGREE` vote. The report writer does not vote and consumes the validated terminal convergence state and every analysis-worker result as read context. Under report contract v3 it writes only the narrative Markdown, a pointer, and its audit sidecar. Approval decisions, activity, execution, convergence, design preparation, and plan-body verification remain in their single-owner inputs. Phase 7 validates those inputs and atomically publishes `data.json` once. The full reading copy is rendered on demand. Newly finalized convergence output is schema v1.4; under the compatibility path, valid historical final schema versions v1.0, v1.1, v1.2, or v1.3 are reused and consumed without rewrite.
 
 Coverage critic and plan-body verification remain separate from finding convergence. The critic audits the integrated Round 0 analysis, while implementation-planning's plan-body gate validates the later report draft through its own `P-*` queue and state file. Neither path changes the engine's `F-*` queue.
 
@@ -417,7 +416,7 @@ On the first run, it writes the four fields `projectId`, `projectRoot`, `created
 
 `reviewRulePacks` (optional, an array of absolute paths, default empty) declares the project's own review rule packs — the review standard a phase reads before it judges a plan or a diff, such as a team's PR-review skill. A pack used to reach a run only when the task brief cited its exact path, so whether the team standard applied depended on who wrote the brief; a declaration here applies to every run in the project, and the two channels are a union. It is read by [`scripts/okstra_project/resolver.py`](../scripts/okstra_project/resolver.py) `resolve_review_rule_packs`, which drops a relative entry — a worker's cwd is a worktree, where a relative path names a different file — and falls back to "none declared" on an unreadable or malformed `project.json`. Three phases consume it: `implementation-planning` (plan away the findings before code exists), the implementation executor's coding-conventions preflight, and the static review passes of the implementation verifier and `final-verification`. **Enforced:** `okstra doctor --phase <phase>` fails the `review rule packs` check when a declared path is not a readable file ([`scripts/okstra_ctl/doctor.py`](../scripts/okstra_ctl/doctor.py) `_review_rule_pack_check`), because a stale path otherwise costs the whole pack in silence. Whether a pack that *does* resolve was actually read stays the phase's own `project-review-rules:` record — no machine check reads a worker's reasoning.
 
-The authoritative source for `okstra-ctl` reindex/backfill also changed under the new model. Previously it sourced `examples/projects/*.conf.sh`; it now scans `~/.okstra/projects/<projectId>/meta.json` (the mirror of the project.json information produced by record_start) to restore (projectId, projectRoot) mappings. The `OKSTRA_PROJECT_DEFINITION_DIR_OVERRIDE` environment variable has also been retired.
+The authoritative source for reindex/backfill also changed under the new model. Previously it sourced `examples/projects/*.conf.sh`; it now scans `~/.okstra/projects/<projectId>/meta.json` (the mirror of the project.json information produced by record_start) to restore (projectId, projectRoot) mappings. The `OKSTRA_PROJECT_DEFINITION_DIR_OVERRIDE` environment variable has also been retired.
 
 ## Artifact-home rule
 
@@ -447,14 +446,14 @@ Selection rules:
 
 Each task type enforces phase-specific allowed and forbidden actions. A run creates only the artifacts for its own task type and does not advance to the next phase. The next phase always begins with a new `okstra.sh` execution.
 
-The fourth column is the `workflow.nextRecommendedPhase` pointer Phase 7 leaves behind. The pointer is an object `{phase, status, rationale}`; `status` is `ready`, `pending`, `blocked`, or `terminal`, and `phase` names a phase only under `ready`. Phase 7 does not decide the route — it projects the pointer from the report's own routing field (`scripts/okstra_ctl/next_phase.py::project`), named per row below. The authoring rule for the field is stated once, in the Phase 6 checklist of [`prompts/lead/report-writer.md`](../prompts/lead/report-writer.md); this table describes the outcome, not the rule.
+The fourth column is the `workflow.nextRecommendedPhase` pointer Phase 7 leaves behind. The pointer is an object `{phase, status, rationale}`; `status` is `ready`, `pending`, `blocked`, or `terminal`, and `phase` names a phase only under `ready`. Phase 7 does not decide the route — it projects the pointer, `rationale` included, from the report's own routing field (`scripts/okstra_ctl/next_phase.py::project`), named per row below. Nothing else reaches the pointer: the value already in the manifest is the previous run's, and the projection does not consult it. The rule for authoring that field is stated once, in the Phase 6 checklist of [`prompts/lead/report-writer.md`](../prompts/lead/report-writer.md); this table describes the outcome, not the rule.
 
 | task type | Purpose | Core artifacts | Next-phase pointer after Phase 7 | Code changes allowed? |
 |---|---|---|---|---|
 | `requirements-discovery` | Classify the request as bugfix, feature, refactor, ops, or improvement, then route it to a safe next phase | work category, routing decision, missing-input list, clarification requests | from `requirementsDiscovery.routing.nextTaskType`: `ready` at `error-analysis` or `implementation-option-selection`; `pending` when the run settles on neither | No |
 | `error-analysis` | Analyze the symptoms, causes, and reproduction gaps of a reported error/incident based on evidence | symptom/trigger summary, root-cause hypotheses, reproduction gap, validation path | from `errorAnalysis.routing.nextTaskType`: `ready` at `implementation-option-selection` after a credible cause, or at `error-analysis` for continued investigation | No |
 | `implementation-option-selection` | Compare or validate implementation directions before detailed planning | up to three ranked directions, per-direction `coveragePercent` and `scopePrecisionPercent`, rejected-candidate audit, separate `DIRECTION SELECTION` response | from the `implementationOptionSelection.routing` string enum: `ready` at `implementation-planning` once a direction is confirmed, `pending` on `pending-direction-selection`, `blocked` on `blocked` | No (strictly read-only; source edits, builds, tests, migrations, and deploys are prohibited) |
-| `implementation-planning` | Expand one selected direction into an executable plan without changing its mechanism or architecture boundary | selected-direction snapshot/reference, direction realization, affected-file list, Stage Map, validation/rollback, exact plan coverage, YAML frontmatter `approved: false`, **§5.5.9 Plan Body Verification**. Existing plans without `planningContract: selected-direction` retain the legacy option-candidate and `implementation-option:` contract | from `implementationPlanning.outcome`: `ready` at `implementation` on `plan-ready` (the plan still needs its separate approval before that run starts), `ready` at `implementation-option-selection` on `direction-invalidated` | No |
+| `implementation-planning` | Expand one selected direction into an executable plan without changing its mechanism or architecture boundary | selected-direction snapshot/reference, direction realization, affected-file list, Stage Map, validation/rollback, exact plan coverage, YAML frontmatter `approved: false`, **§5.5.9 Plan Body Verification**. Existing plans without `planningContract: selected-direction` retain the legacy option-candidate and `implementation-option:` contract | from `implementationPlanning.outcome`: `ready` at `implementation` on `plan-ready` or on a candidate-comparison plan with no `outcome` (the plan still needs its separate approval before that run starts), `ready` at `implementation-option-selection` on `direction-invalidated` | No |
 | `implementation` | Modify source code according to the approved `implementation-planning` final report. **One run executes exactly one stage** (selected with `--stage <auto\|N>`) | commit list, diff summary, out-of-plan edits block, validation/TDD evidence, rollback verification, verifier results (Antigravity/Codex/Claude), `carry/stage-<N>.json` evidence sidecar | from `implementation.routingRecommendation.target`: `ready` at that phase — `final-verification` on a clean stage, otherwise `error-analysis`, `implementation-planning`, or `implementation` | Yes (limited to the approved plan's file list; `git push`/publish/deploy/real migration prohibited) |
 | `final-verification` | Check completed work for residual defects and regression risk, then make a release judgment | acceptance verdict, residual risk, follow-up routing (`error-analysis`/`implementation-option-selection`/`implementation-planning`/`release-handoff`) | from `finalVerification.routingRecommendation.target`: `ready` at that value — `release-handoff` only on an `accepted` verdict, otherwise the phase owning the defect (cause, selected direction, or detailed plan). `release-handoff(stage-group)` is a scope qualifier on the same phase, so it projects to `release-handoff`. `done` becomes `terminal` | No (read-only tests only) |
 | `release-handoff` | Deliver `accepted` changes as a commit, push, or PR according to the user's chosen method | user menu responses (H1 action / H2 PR base / H3 message handling), executed git/gh command log, commit SHA list, PR URL | always `terminal` — the lifecycle ends here and this report has no routing field Phase 7 projects from | Yes—but execute **only the mutating commands selected by the user in the menu**. `git push --force*`, direct push to the base branch, `--no-verify`, `gh release`, and publish/deploy are prohibited. The source code itself must not be changed; package the existing `implementation` diff unchanged. |
@@ -465,7 +464,7 @@ The fourth column is the `workflow.nextRecommendedPhase` pointer Phase 7 leaves
 Common constraints:
 
 - Every phase except `implementation` prohibits source-code edits, builds, migrations, deployments, and other state-mutating commands (`final-verification` allows read-only test commands only). `implementation` permits edits/commits only within the file list of the approved plan; `git push`, publish, deploy, real migration, and third-party write APIs remain prohibited.
-- **Isolated worktree for pre-implementation non-implementation phases (BLOCKING)**: The first pre-implementation non-implementation phase prepare creates a task-key `git worktree` through `okstra-ctl`. Pre-implementation non-implementation phases reuse the task-key worktree: `requirements-discovery` → `error-analysis` → `implementation-option-selection` → `implementation-planning` use the same worktree and branch for the same task key. `implementation` does not reuse this task-key worktree; implementation uses a dedicated stage-specific worktree and branch for every stage/run, as described in the next item. The task-key worktree lives at `~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>/` (special characters such as `/` and `:` in segments are normalized to `-`), and the branch is named `<work-category-namespace>/<task-id-segment>` (for example, `feature/dev-9436` or `fix/dev-7311`). The namespace is derived from work_category (`feature`·`improvement`→`feature/`, `bugfix`→`fix/`, `refactor`→`refactor/`, `ops`→`ops/`, unspecified→`task/`). The work_category itself is resolved by `work_categories.resolve_work_category` as **explicit `--work-category` → the classification recorded in `task-manifest.json` → `feature`**, so the `task/` fallback is only reached when a task has no recorded classification at all; a run that omits the flag still inherits the namespace `requirements-discovery` classified. The base ref is the commit selected by the user's `--base-ref` during the first phase's prepare. `~/.okstra/worktrees/registry.json` (guarded by flock) globally manages task-key → path/branch mappings to prevent path and branch collisions during concurrent runs. Configured sync directories are linked from the main worktree as symlinks to provide filesystem continuity across task checkouts (the sync list can be overridden by `worktreeSyncDirs` in `project.json` or the `OKSTRA_WORKTREE_SYNC_DIRS` environment variable; an empty array disables syncing). This sync does not expand the okstra context/write boundary. Provisioning is skipped when the caller is already inside another worktree or project_root is not a Git repository, and the executor works directly from project_root. The worktree is not automatically deleted after a run; it is the authoritative artifact for later phases, PR authoring, and rollback verification. Manual cleanup: `git -C <main-worktree> worktree remove <path>` → `git -C <main-worktree> branch -D <branch>` + remove the registry entry. See the *Task worktree* block in `prompts/profiles/implementation.md` and the *Task worktree (BLOCKING for every task-type)* section in `prompts/lead/okstra-lead-contract.md` for details.
+- **Isolated worktree for pre-implementation non-implementation phases (BLOCKING)**: The first pre-implementation non-implementation phase prepare creates a task-key `git worktree`. Pre-implementation non-implementation phases reuse the task-key worktree: `requirements-discovery` → `error-analysis` → `implementation-option-selection` → `implementation-planning` use the same worktree and branch for the same task key. `implementation` does not reuse this task-key worktree; implementation uses a dedicated stage-specific worktree and branch for every stage/run, as described in the next item. The task-key worktree lives at `~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>/` (special characters such as `/` and `:` in segments are normalized to `-`), and the branch is named `<work-category-namespace>/<task-id-segment>` (for example, `feature/dev-9436` or `fix/dev-7311`). The namespace is derived from work_category (`feature`·`improvement`→`feature/`, `bugfix`→`fix/`, `refactor`→`refactor/`, `ops`→`ops/`, unspecified→`task/`). The work_category itself is resolved by `work_categories.resolve_work_category` as **explicit `--work-category` → the classification recorded in `task-manifest.json` → `feature`**, so the `task/` fallback is only reached when a task has no recorded classification at all; a run that omits the flag still inherits the namespace `requirements-discovery` classified. The base ref is the commit selected by the user's `--base-ref` during the first phase's prepare. `~/.okstra/worktrees/registry.json` (guarded by flock) globally manages task-key → path/branch mappings to prevent path and branch collisions during concurrent runs. Configured sync directories are linked from the main worktree as symlinks to provide filesystem continuity across task checkouts (the sync list can be overridden by `worktreeSyncDirs` in `project.json` or the `OKSTRA_WORKTREE_SYNC_DIRS` environment variable; an empty array disables syncing). This sync does not expand the okstra context/write boundary. Provisioning is skipped when the caller is already inside another worktree or project_root is not a Git repository, and the executor works directly from project_root. The worktree is not automatically deleted after a run; it is the authoritative artifact for later phases, PR authoring, and rollback verification. Manual cleanup: `git -C <main-worktree> worktree remove <path>` → `git -C <main-worktree> branch -D <branch>` + remove the registry entry. See the *Task worktree* block in `prompts/profiles/implementation.md` and the *Task worktree (BLOCKING for every task-type)* section in `prompts/lead/okstra-lead-contract.md` for details.
 - **Isolated implementation-stage worktrees (concurrent parallelism)**: The task-key worktree above is the model for `requirements-discovery` through `implementation-planning`. `implementation` tasks use **stage isolation**: **one run = one stage**, and every run receives an isolated worktree at `.../<task-id-segment>/stage-<N>/` (branch `<work-category-namespace>/<task-id-segment>-s<N>`). The registry reserves task keys and **stage keys** (`<task-key>#stage-<N>`) together under flock. The Stage Lifecycle Snapshot reads `done`/`started` entries in `consumers.jsonl`, carry-sidecar backfills, and reserved registry stages together, and removes them from the ready set (occupancy SSOT = registry). Thus, if the user starts two `implementation` runs simultaneously, they proceed on different independent stages without collision. Base selection: independent = common anchor (HEAD fixed at entry to the first stage); single dependency = predecessor's done commit; multiple dependencies = task worktree HEAD only if every predecessor is an ancestor (`git merge-base --is-ancestor`; otherwise `PrepareError`). The cost-aware-design ready-set batch has been retired because each stage needs an isolated branch and reserving two stage keys on one branch creates a branch-uniqueness collision, so it offers no benefit: sequential work uses the next run after a stage is done, and concurrent work uses separate runs, at equivalent cost. Select a stage with `--stage <auto|N>` or the wizard's `stage_pick`. The wizard's `stage_pick` is a multiselect that labels each stage with its state (`mark_done`/`mark_active`/`mark_ready`/`mark_blocked`), topologically sorts the dependency closure of the selection with Kahn's algorithm (`stage_targets.order_stage_closure`), and exports it as the `chain-stages` CSV in render-args. The `okstra-run` SKILL consumes this queue and sequentially executes N single-stage runs in dependency order as an unattended chain, advancing only after checking the Phase 6 `done` row for each stage. This is an orchestration layer only; the **one run = one stage** isolation invariant of the wizard and prepare remains unchanged. Not only worktrees but also **run artifacts (reports, state, worker results, manifests) are isolated per stage under `runs/implementation/stage-<N>/`**, so reports and state from two concurrently running stages do not mix. In contrast, `consumers.jsonl` and the worktree registry remain at the task-type root (`runs/implementation/`) because they are shared coordination sources of truth across stages.
 - **Isolation of single-stage final-verification run artifacts (concurrent parallelism)**: Single-stage `final-verification` (`--stage <N>`) also isolates run artifacts under `runs/final-verification/stage-<N>/`, like implementation, with independent sequences per stage, and appends `-fv-s<N>` to the team name. The `-fv-` delimiter prevents collisions with the same stage's implementation team (`-s<N>`) and with the default whole-task verification name. Thus, final-verification for multiple stages can run concurrently without mixing state, worker results, reports, or teams. It does not create a new worktree; it reuses the corresponding implementation stage worktree from the registry read-only and therefore does not reserve a registry stage key. The `-fv-s<N>` suffix on the `teamName` label is only for audit/display distinction. The actual team is the per-session implicit team (`session-<leadSid>`), so the pre-v2.1.178 hard failure caused by a `TeamCreate` name collision no longer occurs. Whole-task verification (empty stage value) retains the existing flat `runs/final-verification/` structure.
 - **Final-verification target acquisition seam**: `stage_targets.acquire_final_verification_target()` accepts semantic task identity, the approved plan, the normalized Stage Map, and `stage: int | None`; it derives ledger, registry, worktree, Git, and integration facts behind one task-key `worktree_provision_mutex`. Single-stage acquisition is read-only and whole-task acquisition integrates and tears down completed stage worktrees. `run.py` remains the adapter that converts CLI values, builds render-context fields, computes the diff summary, and writes the target snapshot. The container keeps using the locked `resolve_and_integrate_whole_task()` interface; both interfaces share an internal unlocked implementation so the acquisition path never re-enters the non-reentrant task-key mutex.
@@ -489,7 +488,7 @@ If a bug is discovered in artifacts after a task has completed release-handoff,
 - **Entry**: The okstra-run wizard detects reentry into an entry phase for a completed task and confirms it at the `fix_cycle_confirm` step. The CLI uses `--fix-cycle <yes|no>` (when omitted, nothing is recorded). `--fix-cycle yes` opens a cycle only if both guards pass: task type is an entry phase, and the manifest's `workflow.lastCompletedPhase` is `release-handoff`; a violation raises `PrepareError`. A task may have only one open cycle at a time.
 - **Attachment**: While a cycle is open, all runs for the same task attach to it as `run` rows even without a later `--fix-cycle` flag, and `fixCycleId` is recorded in run-manifest and timeline entries.
 - **Closure**: After a release-handoff run attaches to an open cycle and the manifest's `workflow.lastCompletedPhase` becomes `release-handoff`, the next prepare lazily appends a `closed` row.
-- **Consumers (all derived views)**: ① the `## Fix History` section of a later run's analysis-packet ② quotation in Task Continuity Notes from okstra-brief-gen ③ final-report `## 5.10 Fix History` (when run-manifest has `fixCycleId`, validator `_validate_fix_cycle` requires a `fixCycle` block in data.json) ④ a `fixCycles` summary in task-manifest plus a one-line entry in task-index / task-catalog. All four consumers read only derived views from `fix_cycles.summarize()` / `packet_summary()`.
+- **Consumers (all derived views)**: ① the `## Fix History` section of a later run's analysis-packet ② quotation in Task Continuity Notes from okstra-brief-gen ③ final-report `## 5.10 Fix History` ④ a `fixCycles` summary in task-manifest plus a one-line entry in task-index / task-catalog. All four consumers read only derived views from `fix_cycles.summarize()` / `packet_summary()`.
 
 ### release-handoff stage-group mode
 
@@ -820,8 +819,7 @@ Checking the following fields first makes it easy to determine the current posit
 - `workflow.currentPhaseState`
 - `workflow.phaseStates`
 - `workflow.lastCompletedPhase`
-- `workflow.nextRecommendedPhase` *(object `{phase, status, rationale}`; `status` is `ready` / `pending` / `blocked` / `terminal`. The lead writes `phase` only under `ready` — an authoring rule, not a constraint the struct enforces: `prepare` lowers a `ready` pointer to `pending` and keeps its `phase`, so a non-`ready` pointer that still names a phase is a normal manifest state. Read `status` to decide whether anything can be launched.)*
-- `workflow.nextRecommendedPhaseCorrection` *(present only when Phase 7 validation replaced the authored pointer — `{authored, applied}`, where `authored` is the pointer the lead wrote)*
+- `workflow.nextRecommendedPhase` *(object `{phase, status, rationale}`; `status` is `ready` / `pending` / `blocked` / `terminal`. `phase` is non-empty only under `ready` — a property of the projection, not a constraint the struct enforces: `prepare` lowers a `ready` pointer to `pending` and keeps its `phase`, so a non-`ready` pointer that still names a phase is a normal manifest state. Read `status` to decide whether anything can be launched.)*
 - `workflow.awaitingApproval`
 - `workflow.lastSafeCheckpoint`
 - `phaseOutcome`
@@ -918,10 +916,10 @@ Errors that occur while provider workers, the report writer, or the Okstra lead
 - The `.log` is an execution transcript containing wrapper/CLI output, not the original prompt. `okstra log-report` pairs it with the sibling persisted `.md` prompt and reports `transcriptBytes`, `promptBytes`, and their ratio separately. The compatibility fields `path`, `sizeBytes`, and `totalBytes` continue to mean transcript data, so existing consumers and transcript-size ordering remain stable.
 - **Run-wide cap on the progress copy in the log** (`_LOG_PROGRESS_LINE_CAP` in `scripts/okstra_ctl/worker_runner.py`): workers read their required inputs end-to-end per the Worker Preamble's *Reading rules*, so a single report read can dump 170KB+ into the log and observed sidecars reach 8MB. The runner archives the first 5000 progress lines of the run and replaces the rest with a `[okstra log-cap] N progress line(s) elided` marker, emitted every 500 elided lines so a reader tailing the log can see the run is still producing. The cap is run-wide rather than per-block because a block boundary is a provider's own vocabulary and the shared runner has none; the cost is that a very long run keeps its opening rather than a sample throughout, which the elision notices make visible. **Only the log copy is capped** — never the screen, and never the result stream, because a truncated tool echo costs detail while a truncated answer costs the whole post-mortem.
 - **Progress lands in the worker's own pane, not in a sibling tail pane.** The presentation is passed to the entrypoint as `--presentation live|quiet`; `live` is claimed only by a backend that opened a pane, and the default is `quiet`. Under `live` the runner renders each event into one readable row on the caller's own streams (`→ Bash: …` for a tool call, `  ← ok (N bytes)` for its result, `!! PERMISSION DENIED — <tool>: <reason>` for a refusal); thinking events are dropped. Under `quiet` progress is withheld and only the worker's closing text is printed, which is what a `cli-wrapper` dispatch on a machine with no pane surface needs. `scripts/okstra_ctl/domain/worker_stream.py` owns all three projections (`format_live`, `format_log`, `final_text`) as pure functions over *normalised* events — `Text`, `ToolCall`, `ToolResult`, `Denial`, `Result`. Providers do not share a wire format and this layer may not name one, so each adapter supplies the function that turns its own events into those, declared on `ExecCommand.normalise` beside the stream format it belongs to. Adding a provider whose stream is shaped differently is that one function; a provider that declares `stream-json` without one is failed by `tests/contract/test_provider_execution_contract.py`, which runs the schema each provider claims through its own normaliser and requires rows out.
-- **No okstra pane carries a tag any more, and the tag scan is gone with them.** Two writers disappeared at different times. The wrappers stopped splitting a `tail -F` sibling, so **nothing spawns a trace pane** and `@okstra_trace_run` / `@okstra_status` lost their writer — the operator watches the worker pane itself instead. Then the `tmux-pane` dispatch backend was removed, so `tmux.tag_pane` and `@okstra_worker_run` went with it: a worker now gets a cmux surface or a cli-wrapper subprocess, neither of which is a tmux pane okstra owns. `okstra-trace-cleanup.sh` therefore no longer scans tags at all, and the two modes that existed only for that scan were removed — `--reclaim-completed` (with the `okstra-subagent-reclaim.sh` entry that drove it from `SubagentStop` / `TaskCompleted`) and `--reap` (with its `SessionEnd` entry). Those hooks are gone from `templates/reports/settings.template.json`; `SessionEnd` now carries only `okstra-team-reconcile.sh --session-end`.
+- **No okstra pane carries a tag any more, and the tag scan is gone with them.** Two writers disappeared at different times. The wrappers stopped splitting a `tail -F` sibling, so **nothing spawns a trace pane** and `@okstra_trace_run` / `@okstra_status` lost their writer — the operator watches the worker pane itself instead. Then the pane-tagging dispatch backend was removed, so `@okstra_worker_run` went with it: a worker now gets a cmux surface or a cli-wrapper subprocess, and okstra tags neither. `okstra-trace-cleanup.sh` therefore no longer scans tags at all, and the two modes that existed only for that scan were removed — `--reclaim-completed` (with the `okstra-subagent-reclaim.sh` entry that drove it from `SubagentStop` / `TaskCompleted`) and `--reap` (with its `SessionEnd` entry). Both hooks are gone from `templates/reports/settings.template.json`, which now seeds only the `SessionStart(compact)` reminder.
 - **What cleanup does — okstra's own worker panes**: `okstra team reclaim --project-root <root> --run-manifest <path>` closes the cmux panes this run opened for its workers, and only those whose dispatch has reached a terminal status. The candidates are the `paneId` values recorded in `team-state.workerDispatches[]`, so nothing is discovered by scanning: a title sweep would be worse than nothing, because cmux labels its own agent surfaces with the same glyph the harness uses for a teammate pane and a sweep could close the lead (`team._reclaimable_panes`). A pane the harness opened for its own teammate (`runner: native-session`, which okstra's dispatcher refuses and hands to the host) carries no recorded id and is not okstra's to close. `--dry-run` prints the same `<paneId>\t<kind>` set without closing, which is how the lead counts before it closes. At every worker round boundary — after collecting that round's results and token usage, immediately before the next dispatch — the lead runs the counting pass, reports `PROGRESS: phase-batch-cleanup panes=<n>`, then runs the closing pass. Closing also gives the lead its width back: cmux hands freed width to a neighbour it picks, and that neighbour is not always the lead. See [ADR-0012](../.project-docs/adr/0012-pane-reclaim-scope.md).
 - **Cleanup survives compaction and precedes user gates**: A `SessionStart` hook with matcher `compact` (`okstra-compact-reminder.sh`, seeded in `settings.template.json`) fires after every `/compact` or auto-compaction. It reads `cwd` from the hook's stdin JSON and asks `pane_reclaim.in_flight_run_dirs` for that project's runs that still hold a non-terminal dispatch — the newest `team-state` per run directory decides, because sequences accumulate and an earlier round's `in-progress` rows stay on disk. If one exists it prints a factual reminder naming the run dir and the two-pass `okstra team reclaim` sequence, restoring the boundary/gate obligation that a compaction summary can otherwise drop. The hook never closes a pane itself; the closing stays with the lead, which holds the run manifest. The signal is the run directory rather than `~/.okstra/active.jsonl`: an in-session run is registered `prepared` (because `render-bundle` forces `--render-only`), `prepared` routes to `recent.jsonl` as terminal, and that ledger was measured empty while 310 runs sat in `recent.jsonl` — see [ADR-0011](../.project-docs/adr/0011-in-flight-run-source-of-truth.md). Separately, the lead runs the same two passes immediately before any user approval/clarification/decision gate (`PROGRESS: phase-gate-cleanup panes=<n>`). At every cleanup point the pane close and the task stop (`TaskStop`) are paired — a `TaskStop` alone idles the roster task and closes no pane.
-- **User confirmation at phase end**: At the final step of the run, the lead calls `okstra team teardown --project-root <root> --run-manifest <path> --dry-run` to show the panes this run recorded, then asks once whether to "close all and clean up teammates / keep them." Unlike the round boundary, teardown's set is every recorded pane regardless of status — the run is ending, so none is expected to continue — and it also writes off any dispatch that never reached a terminal status. If approved, the lead runs the same command without `--dry-run`, then uses `okstra-team-reconcile.sh` to mark dead-pane members inactive and sends each completed teammate a `SendMessage` shutdown_request (`TeamDelete` was removed in v2.1.178; the implicit team disappears with the session). A `cli-wrapper` run recorded no pane, so the command safely reports an empty set. The teammate step is determined by the existence of an on-disk team configuration whose `leadSessionId` matches (`~/.claude/teams/session-*/config.json`), not by `teamCreate.status`.
+- **User confirmation at phase end**: At the final step of the run, the lead calls `okstra team teardown --project-root <root> --run-manifest <path> --dry-run` to show the panes this run recorded, then asks once whether to "close all and clean up teammates / keep them." Unlike the round boundary, teardown's set is every recorded pane regardless of status — the run is ending, so none is expected to continue — and it also writes off any dispatch that never reached a terminal status. If approved, the lead runs the same command without `--dry-run`, then sends each completed teammate a `SendMessage` shutdown_request (`TeamDelete` was removed in v2.1.178; the implicit team disappears with the session). A `cli-wrapper` run recorded no pane, so the command safely reports an empty set.
 - Disk accumulation is handled by the `okstra-inspect logs` flow, which offers a read-only inventory and suggests cleanup commands for the user to copy and paste.
 
 ### Linked-worktree `.git/` write permissions
@@ -942,7 +940,7 @@ Tokens used in each run are collected from lead/worker session transcripts and w
 - CLI execution evidence and token attribution are independent. A wrapper `.status.json` proves `not-started`, `started`, `exited`, `timeout`, or `failed` and supplies the worker's collection window; only a matching transcript with a final token snapshot proves attributable usage. If a wrapper exited successfully but no attributable transcript exists, the worker remains `source: "unavailable"` with `cliExecutionStatus: "exited"` and a reason instead of becoming zero usage or being described as never invoked.
 - Records billable-equivalent token math and USD cost estimates. It applies Anthropic billing ratios (`cache_creation_5m=1.25x`, `cache_creation_1h=2.0x`, `cache_read=0.1x`, `output=5x`). When the transcript provides separate `usage.cache_creation.ephemeral_5m_input_tokens` / `ephemeral_1h_input_tokens` values, they are counted separately.
 - Pricing is centrally managed in `scripts/okstra_token_usage/pricing.py`. Update it when model prices change. Model IDs that fail price matching are exposed to the user in `usageSummary.unmatchedModels`, preventing silent-zero incidents.
-- Project-wide historical usage is exposed through the read-only `okstra usage-report` command (`src/commands/inspect/usage-report.mts` → `scripts/okstra_ctl/usage_report.py`) and the `okstra-usage` skill. It defaults to the whole current project's last 30 days and returns run coverage, raw and billable-equivalent tokens, known USD cost, CPU-sum milliseconds, and wall-clock milliseconds grouped by task type. Runs without usable Phase 7 usage are excluded from resource totals and reported through unavailable reason counts rather than treated as zero usage; unmatched model names remain visible when their tokens and time are included but their cost is not. Use `okstra-inspect` for one task's elapsed/context detail and `okstra-rollup` for task-group or project status/report digests.
+- Project-wide historical usage is exposed through the read-only `okstra usage-report` command (`scripts/okstra_ctl/usage_report.py`) and the `okstra-usage` skill. It defaults to the whole current project's last 30 days and returns run coverage, raw and billable-equivalent tokens, known USD cost, CPU-sum milliseconds, and wall-clock milliseconds grouped by task type. Runs without usable Phase 7 usage are excluded from resource totals and reported through unavailable reason counts rather than treated as zero usage; unmatched model names remain visible when their tokens and time are included but their cost is not. Use `okstra-inspect` for one task's elapsed/context detail and `okstra-rollup` for task-group or project status/report digests.
 - **Incremental scan cache (P6)**: To avoid rescanning session jsonl files, a per-file byte cursor and the extracted usage events before windowing are stored in `$OKSTRA_HOME/cache/token-usage/<transcript-dir>/<sessionId>.json` (`scripts/okstra_token_usage/cursor.py`). The run window (since/until) is reevaluated over events on every invocation, so even if a rerun narrows the window, the total matches a full scan. The cache is derived data; identifier mismatch, truncation, or corruption automatically falls back to a full rescan, and `okstra-token-usage.py --no-cache` forces a bypass.
 - **Phase timeline (P0 instrumentation)**: The collector extracts `PROGRESS: phase-*` checkpoint lines (see "Progress reporting" in prompts/lead/okstra-lead-contract.md) from the lead session jsonl scoped to the run window, and records them in team-state as a `phaseTimeline` block (`{source, phases: [{phase, firstAt, lastAt, markerCount, wallMsToNext}]}`) (`scripts/okstra_token_usage/collect.py :: phase_timeline`). This provides measurement points for per-phase wall-clock time within the run and is consumed by the "Per-run phase breakdown" in the `okstra-inspect` time facet. Runs without markers explicitly report that measurement is unavailable with `phases: []`.
 
@@ -951,13 +949,19 @@ Tokens used in each run are collected from lead/worker session transcripts and w
 Entry points that enforce whether phase artifacts may be published:
 
 - `validators/validate-workflow.sh` — integrated phase-contract validation.
-- `validators/validate-run.py` — version-aware run-level final-report contract. For schema v2 it validates the compact full reading copy heading order and rejects human-only fields in Markdown; task deliverables and cross-field rules are validated from data.json. For schema v1 it retains the Verdict Card, Index, numbered-section, Plan Body Verification, approval, and token-table checks. Both versions require rationale evidence, consistent task verdicts, worker-result audit sidecars, and phase-safe execution evidence.
+- `validators/validate-run.py` — run-level final-report contract, validated from `data.json`. Schema v2 and v3 reports are the only shapes a current run produces, and for those `validate_report` delegates straight to the data.json rules: heading order and human-only fields in the compact reading copy, task deliverables, and cross-field invariants. The Markdown body itself is no longer scanned — the Verdict Card / Index / numbered-section / token-table checks were display-title rules with no consumer (ADR-0024), and they sat behind a `schemaVersion` guard no current run reached. Below the delegation only one branch remains: the report file does not exist. Worker-result audit sidecars and phase-safe execution evidence are still required.
 - `validators/validate-report-views.py` — checks form-control placement in the self-contained HTML view, absence of external URLs, stale source digests, and Response ID parity (`C-*` ↔ HTML).
 - `validators/validate-brief.py` — enforces the brief schema (frontmatter, presence of `Reporter Confirmations`, root parent-id self rule, slug conventions, and so on). `bash validators/validate-brief.sh <brief.md>` is a thin wrapper.
 
 Each validator blocks the phase with a `contract-violated` exit code when a contract is breached. Violations are applied when the next phase executes, leaving prior artifacts unchanged.
 
-**Blocking failures vs advisories.** `validate-run.py` splits its findings into `validation.failures` and `validation.advisories` (both written to the run manifest and team state, and printed on stdout; advisories also go to stderr one per line). Only `failures` decide `validation.status`, so a run can pass while carrying advisories. The dividing line is whether a remedy still exists at Phase 7: a defect in the report is fixable by re-authoring and re-rendering, while a defect in what an *already-ended session* wrote down is not — the worker that would restate its citation and the lead pane that would emit its PROGRESS line are both gone, so the only remaining move is to void the phase, which blocks the next one without establishing that any conclusion in the report is wrong. Two surfaces are advisory today: the worker citation ledger (`okstra_ctl.worker_audit_ledger.worker_results_audit_findings` — a `path:line` citation with no matching Evidence read row; a missing or unreadable sidecar stays blocking) and the PROGRESS narration lines (`validators/validate_session_conformance.py` `SessionConformanceResult.advisories`; the user-confirmation cross-check stays blocking because it verifies a claim the report makes). **Enforced:** `tests/contract/test_worker_audit_check.py::test_an_unmatched_citation_is_advisory_and_a_missing_sidecar_is_not` and `tests/contract/test_validate_session_conformance.py::test_missing_checkpoints_are_advisory_not_blocking`.
+**Blocking failures vs advisories.** `validate-run.py` splits its findings into `validation.failures` and `validation.advisories` (both written to the run manifest and team state, and printed on stdout; advisories also go to stderr one per line). Only `failures` decide `validation.status`, so a run can pass while carrying advisories.
+
+The split is not made by the individual checks. Every check appends to one flat list, and immediately before the status is computed that list is partitioned by an allowlist: `partition()` in [`scripts/okstra_ctl/blocking_checks.py`](../scripts/okstra_ctl/blocking_checks.py), applied at [`validators/validate-run.py`](../validators/validate-run.py) just above `update_validation_metadata`. A failure blocks only if its message contains one of the registered substring fragments; everything else is moved into `validation.advisories`. **Advisory is the default, and a check does not choose its own grade** — a sub-validator that classified its own finding as an error (`worker_audit_ledger.worker_results_audit_findings`, `validate_session_conformance.SessionConformanceResult`) still ends up advisory unless its wording matches a registered fragment.
+
+The registration test is a sentence, not a severity feeling: **which consumer outside the validator breaks when this value is wrong?** Registered fragments name one — a renderer with no input (`final-report data.json is missing`), a gate whose result cannot be read (`conformance gate BLOCKING`, `self-mock gate BLOCKING:`), a release path opened on an unverified value (`final-verification report declares`, `` `verdict: FAIL` but `finalVerdict.verdictToken` is ``), a successor stage that cannot be prepared (`implementation run declares stage-`). Where the only reader is the validator itself or the report projection — a cross-reference link, an `Evidence checked:` line, a heading that reads differently — the finding is advisory by construction. ADR-0024 states the same rule from the other side: a display title is never a blocking reason.
+
+Fragments are substrings, so an over-broad fragment silently promotes neighbouring checks that happen to share a prefix. Each entry therefore carries a written consumer sentence next to it, and the fragment is chosen from a message string that actually exists. **Enforced:** `tests/contract/test_validate_run_conformance.py::test_every_blocking_fragment_is_producible` reconstructs every string expression in `validators/` and `scripts/okstra_ctl/` from the AST (excluding the allowlist module itself, so the check cannot pass by finding its own copy) and rejects a fragment no validator can emit; `::test_report_bookkeeping_failures_do_not_block` and `::test_a_broken_or_missing_artifact_still_blocks` pin the two sides of the partition.
 
 `contractValidation.status=failed` means the run artifact contract failed; it does not necessarily mean the implementation itself is incomplete. An implementation run derives `phaseOutcome.implementation` from `runs/implementation/carry/stage-<N>.json`, `runs/implementation-planning/consumers.jsonl`, and the approved Stage Map together. If every Stage Map stage has pass-grade carry evidence, it can retain the contract failure as audit information while raising `workflow.nextRecommendedPhase.status` to `ready`. It does not choose the phase: the reconciler's fact is that every stage finished, and the destination was already settled by the last stage's report routing, so it leaves `phase` untouched and raises the status only when `phase` is non-empty.
 
@@ -1003,34 +1007,31 @@ Each validator blocks the phase with a `contract-violated` exit code when a cont
 
 ---
 
-## okstra Control Center — Operating model / concurrency / environment variables
+## Run index — operating model / concurrency / environment variables
 
 ### Operating model
 
 - At startup, `okstra.sh` invokes the `record_start` hook once to record metadata and the invocation in the indexes.
-- Finalization is handled by lazy reconciliation invoked from every `okstra-ctl` entry point (inferred from the presence of `final-report-*.md` in the target project).
-- A batch rerun spawns one detached tmux session per target and returns immediately (fire-and-forget). The user connects to any session with the returned attach command.
-- The default spawn threshold is 10. Change it with `--max-spawn N` or `OKSTRA_CTL_MAX_SPAWN`.
+- **Finalization runs from two live invokers.** `record_start` writes the row when a run begins; nothing in the run's own path writes its end. Two mechanisms close it, and they are different in kind — one *records* a known verdict, the other *infers* one from disk.
+  - [`validators/validate-run.py::record_validation_in_central_index`](../validators/validate-run.py) — fires right after the validator writes team-state / run-manifest / task-manifest, and writes the verdict it just produced onto that one row via [`settle_run_row`](../scripts/okstra_ctl/reconcile.py). The row is matched on `executionManifestPath`, which is unique per run; `runDirRel` is not, because every run-seq of one task-type shares it. Recording rather than inferring is what makes re-validation come out right: `reconcile_recent` skips rows that are already terminal, so a run that failed, got fixed, and passed would otherwise stay `failed` in the index forever.
+  - [`okstra_ctl.run._reconcile_prior_runs`](../scripts/okstra_ctl/run.py) — fires after `record_start` succeeds and sweeps the project's other rows through [`reconcile_home`](../scripts/okstra_ctl/reconcile.py), which infers terminal status from final-report existence plus the run-manifest's `validation.status`. This is the backstop for runs that died before validation and so never reached the validator; those are closed by the 12-hour abort timeout. `reconcile_home` is the only entry point to that inference because `reconcile_active` (promote out of `active.jsonl`) and `reconcile_recent` (refresh a `prepared` row in place) must always run as a pair.
+  - Both are scoped to the run's `projectId`. An unscoped sweep would abort rows belonging to projects the invoking run has nothing to do with. Both are best-effort: a failure prints to stderr and never undoes the prepare or the validation verdict. Neither may be called while holding `central_lock` — both acquire it themselves and `flock` is not reentrant.
+  - Without a live invoker a row stayed `running` forever, and [`run_audit._never_ran`](../scripts/okstra_ctl/run_audit.py) reads such a row as a run that has not produced its report *yet*, skipping the report invariant entirely. `validators/validate-workflow.sh` asserts the settled row end-to-end after its validator step.
 - runId format: `<project-id>/<task-group>/<task-id>/<task-type>/r<run-seq>` (for example, `sample-project/payment/fail/error-analysis/r07`). Input supports prefix-substring matching.
 
 ### Concurrency control (two-level mutex)
 
-`okstra-ctl` and the `record_start` hook use two fcntl `LOCK_EX` locks with different scopes. Their responsibilities are separate, so no deadlock occurs even when both are held.
+The run index and the per-task prepare path use two fcntl `LOCK_EX` locks with different scopes. Their responsibilities are separate, so no deadlock occurs even when both are held.
 
 | Lock | Location | Scope | Held during | Purpose |
 |---|---|---|---|---|
-| central lock | `~/.okstra/.lock` | Global (index-wide) | Writes to `active.jsonl`/`recent.jsonl`/`projects/<id>/index.jsonl` by `record_start`; reconcile / reservation writes by ctl | Serializes read-modify-write operations on index jsonl files. Prevents concurrent record_start append and reconcile rotation from leaking into each other. |
-| task lock | `~/.okstra/.locks/<projectId>-<taskGroup>-<taskId>-<taskType>.lock` | Per task-key + task-type mutex | Entire sequence prediction + tmux spawn section of `okstra-ctl rerun` | Prevents simultaneous reruns of the same task from receiving the same run sequence and colliding on manifests/directories. Acquired outside the central lock, so reruns of different tasks do not block each other. |
-
-Acquisition order is always `task lock` → `central lock` (ctl rerun), or `central lock` alone (record_start, reconcile). The reverse order never occurs.
+| central lock | `~/.okstra/.lock` | Global (index-wide) | Writes to `active.jsonl`/`recent.jsonl`/`projects/<id>/index.jsonl` by `record_start`; reservation writes | Serializes read-modify-write operations on index jsonl files. Prevents a concurrent record_start append and a reconcile rotation from leaking into each other ([locks.central_lock](../scripts/okstra_ctl/locks.py)). |
+| task lock | `~/.okstra/.locks/<task-key>.lock` | Per task-key mutex | Sequence prediction and run-context writes during prepare | Prevents simultaneous prepares of the same task from receiving the same run sequence and colliding on manifests/directories. Acquired outside the central lock, so different tasks do not block each other ([run_context.task_mutex](../scripts/okstra_ctl/run_context.py)). |
 
-`task_lock_filename` normalizes each segment to an fs-safe slug, escapes `-` as `--`, and joins with `-`. This prevents tuples such as `('p','feature-8','email','x')` and `('p','feature','8-email','x')` from colliding on the same filename and unintentionally sharing a mutex ([scripts/okstra_ctl/locks.py](../scripts/okstra_ctl/locks.py)).
+Acquisition order is always `task lock` → `central lock` (prepare), or `central lock` alone (record_start). The reverse order never occurs.
 
 ### Environment variables
 
 - `OKSTRA_HOME`: overrides the central directory location (default `~/.okstra`).
-- `OKSTRA_CTL_MAX_SPAWN`: default threshold for concurrent rerun spawns.
-- `OKSTRA_CTL_SKIP_BACKFILL=1`: skips automatic backfill on first invocation.
-- `OKSTRA_CTL_SKIP_RECONCILE=1`: skips lazy reconciliation (for tests/debugging).
 - `OKSTRA_SKIP_INSTALL_CHECK=1`: skips installation-asset checks in `verify_installation` (for tests; workspace-existence validation remains enabled).
-- `OKSTRA_RUN_SEQ_OVERRIDE`: forces the run sequence used by okstra.sh during a rerun (injected automatically inside okstra-ctl).
+- `OKSTRA_RUN_SEQ_OVERRIDE`: forces the run sequence used by okstra.sh (test hooks only).