okstra 0.166.1 → 0.167.0

package/README.md

@@ -225,7 +225,7 @@ Major workflow changes added to `main` after 0.8.0:
 
 - **Automatic isolated worktrees for every task type** — During preparation, `okstra-ctl` runs `git worktree add ~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>` once per task key to create an isolated working tree and a `<work-category-namespace>/<task-id-segment>` branch (for example, `feature/dev-9436` or `fix/dev-7311`). The user chooses the base ref with `--base-ref`, using the same choices as the release-handoff PR base picker: `main`, `dev`, `staging`, `preprod`, `prod`, or a custom value. It is required in the first phase; the okstra-run skill collects it through `AskUserQuestion`, while non-interactive callers must pass `--base-ref` explicitly. Later **non-`implementation`** phases for the same task key (`requirements-discovery` → `error-analysis` → `implementation-planning` → `final-verification` → `release-handoff`) reuse the same path and branch. `implementation` runs are **stage-isolated**: each run executes one stage in its own `.../<task>/stage-<N>/` worktree on a `<work-category-namespace>/<task>-s<N>` branch, so independent stages with `depends-on (none)` can run concurrently without sharing a tree. The registry reserves both task keys and **stage keys** with flock. Provisioning is skipped when the caller is already in another worktree or project_root is not a Git repository; stage isolation degrades to a flat path in those cases. Manual cleanup: `git worktree remove <path>` → `git branch -D <branch>` plus release/removal of the registry entry. Details: [`docs/architecture.md`](docs/architecture.md), in the *Task type* section, and [`docs/cli.md#--executor`](docs/cli.md#--executor).
 - **`release-handoff` lifecycle phase** — runs immediately after `final-verification` returns `verdict=accepted`. The current Okstra lead drafts the candidate messages and PR body inline, then uses the selected host adapter's user-prompt operation for the delivery choices. Only the Git/GitHub CLI commands selected through those menus are run. Force pushes, direct pushes to the base branch, hook bypasses (`--no-verify`), and release publication (`gh release`, `npm publish`, and similar commands) are prohibited. This phase does not edit source code. Profile: [`prompts/profiles/release-handoff.md`](prompts/profiles/release-handoff.md).
-- **Configurable PR body template** (release-handoff) — PR bodies are populated from a Markdown template selected in this order: one-time override (`--pr-template-path` or the okstra-run Step 6 prompt) → `prTemplatePath` in `<project_root>/.okstra/project.json` → `prTemplatePath` in `~/.okstra/config.json` → the skill default at `~/.claude/skills/templates/prd/pr-body.template.md`. Register a template with `okstra config set pr-template-path <path> [--scope project|global]`; project scope accepts a path relative to the project root, while global scope requires an absolute path or a path beginning with `~/`. `okstra config get pr-template-path --scope all` prints every scoped value and the effective winner. The default template contains `## Summary`, `## Changes`, `## Test plan`, and `## Linked issues`, plus HTML comment guidance that the lead removes immediately before PR creation.
+- **Configurable PR body template** (release-handoff) — PR bodies are populated from a Markdown template selected in this order: one-time override (`--pr-template-path` or the okstra-run Step 6 prompt) → `prTemplatePath` in `<project_root>/.okstra/project.json` → `prTemplatePath` in `~/.okstra/config.json` → the skill default at `~/.claude/skills/templates/pr/pr-body.template.md`. Register a template with `okstra config set pr-template-path <path> [--scope project|global]`; project scope accepts a path relative to the project root, while global scope requires an absolute path or a path beginning with `~/`. `okstra config get pr-template-path --scope all` prints every scoped value and the effective winner. The default template contains `## Summary`, `## Changes`, `## Test plan`, and `## Linked issues`, plus HTML comment guidance that the lead removes immediately before PR creation.
 - **Profile worker-roster validation** — `--workers <csv>` and the okstra-run Step 6 worker prompt accept only the worker IDs declared in the selected profile's `Required workers:` block. Requesting a worker absent from the profile—for example, `codex` or `antigravity` for `release-handoff`—fails with a clear error, and the interactive prompt shows only workers accepted by that profile.
 - **Host-aware lead adapters** — `okstra-run` resolves the current harness through the same dynamic host registry used by the terminal front door. Claude Code, Codex, Antigravity, Grok, and Kimi keep their matching provider assignment native; `external` remains the explicit all-CLI host. Host and provider are separate axes, and every non-native worker assignment uses its provider's registered CLI wrapper. `leadAssignment` and every `workerAssignments[]` row record provider, model, and `runner`. `okstra codex-run` and `okstra codex-dispatch` remain low-level artifact/dispatch commands.
 - **Multi-stage `implementation-planning` / `implementation`** — `implementation-planning` always produces a Stage Map and N stage sections. Each stage has no more than six steps, and stages with `depends-on (none)` can be implemented concurrently in separate `implementation` runs. Each `implementation` invocation runs a single stage, selected with `--stage <auto|N>`, and creates an evidence sidecar at `carry/stage-<N>.json` for automatic carry-in to the next stage. The `implementation-planning` run directory accumulates `consumers.jsonl` reverse links that record which run consumed each stage.

package/docs/cli.md

@@ -130,7 +130,7 @@ For standard values and phase-specific responsibilities, see [Task type](#--task
   - `out-of-scope`: optional.
   - `candidate-cap`: 1–12; default 8.
 - Output: the `## 5.9 Improvement Candidates` table with 11 columns: Cand ID / Lens / Title / Scope / Severity / Effort / Consensus / Source workers / Recommended next-phase / Expected behavior after / Evidence.
-- Verdict Token: `candidates-ready` / `no-candidates` / `blocked`.
+- Verdict Token: `analysis-complete` / `analysis-partial` / `blocked` — the shared analysis enum, which is what `schemas/final-report-v2.0.schema.json` admits. Finding no candidates is not a verdict: the run stays `analysis-complete` and records an empty candidate set with a `no-candidate` row per lens. (`candidates-ready` / `no-candidates` appear only in a schema-v1 legacy report's `## 7. Final Verdict`.)
 - Routing: there is no automatic spin-off. The user selects candidates and starts each under a new task ID with `requirements-discovery`, `implementation-planning`, or `error-analysis`.
 - Workers: claude + codex + antigravity + report-writer are all required.
 - Primary-pass assignment: selected analyser instances are enumerated in `requiredWorkerRoles` order, then the lead rotates the primary pass across the resolved priority lenses. Provider/model names do not affect the order, and every analyser still covers every resolved lens after its primary pass.

package/docs/pr-template-usage.md

@@ -19,8 +19,8 @@ If the file named in any of the 4 steps does not exist, it fails immediately wit
 
 ## 2. Default candidate paths
 
-1. `$OKSTRA_SKILLS_DIR/templates/prd/pr-body.template.md` — only when the `OKSTRA_SKILLS_DIR` environment variable is set.
-2. `~/.claude/skills/templates/prd/pr-body.template.md` — the standard location `npx okstra install` installs to.
+1. `$OKSTRA_SKILLS_DIR/templates/pr/pr-body.template.md` — only when the `OKSTRA_SKILLS_DIR` environment variable is set.
+2. `~/.claude/skills/templates/pr/pr-body.template.md` — the standard location `npx okstra install` installs to.
 
 The candidates are tried in priority order, and if all are absent it ends with an explicit error as follows.
 
@@ -28,7 +28,7 @@ The candidates are tried in priority order, and if all are absent it ends with a
 
 ## 3. The original inside the source repository
 
-- [`templates/prd/pr-body.template.md`](../templates/prd/pr-body.template.md) — the original that `npx okstra install` copies to the §2 default location. To change the copy, edit this file and install again.
+- [`templates/pr/pr-body.template.md`](../templates/pr/pr-body.template.md) — the original that `npx okstra install` copies to the §2 default location. To change the copy, edit this file and install again.
 
 ## 4. Configuration commands — persistence
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.166.1",
+  "version": "0.167.0",
   "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.166.1",
-  "builtAt": "2026-08-11T12:28:22.915Z",
+  "package": "0.167.0",
+  "builtAt": "2026-08-12T03:32:48.888Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/prompts/profiles/_implementation-executor.md

@@ -63,7 +63,7 @@ persisted prompt lacks the heading `Coding-conventions preflight`
 
 ## Stage execution contract (this run owns one stage)
 
-- **Sidecar evidence writer (BLOCKING).** When this stage's Stage Validation `post` commands all succeed, the Executor MUST emit a JSON object with **exactly** these fields (spec `docs/superpowers/specs/2026-05-20-implementation-planning-multi-stage-design.md` §3.2), as a fenced ```json``` block in the worker result under the heading `### Stage Carry Evidence`, and the lead MUST persist it to `runs/<impl-task-key>/carry/stage-<N>.json`. The schema is inlined here because a CLI-wrapper executor runs in its own process and never receives a native worker definition — a carry emitted with an ad-hoc shape (`stage`/`files`/`validation`) is a `contract-violated` gap the lead must rewrite by hand:
+- **Sidecar evidence writer (BLOCKING).** You emit the evidence; you do NOT write the file. `carry/stage-<N>.json` sits inside your task scope, so nothing stops your tools from creating it — but the lead's post-stage persistence is what writes it, and only on a non-`FAIL` verdict. Your own gate passes before the verifier's, so a file you write exists exactly when the verdict may still withhold it: the lead then refuses to overwrite, the report says the sidecar was withheld, and the disk disagrees with the record. Emit the block and stop. When this stage's Stage Validation `post` commands all succeed, the Executor MUST emit a JSON object with **exactly** these fields (spec `docs/superpowers/specs/2026-05-20-implementation-planning-multi-stage-design.md` §3.2), as a fenced ```json``` block in the worker result under the heading `### Stage Carry Evidence`, and the lead MUST persist it to `runs/<impl-task-key>/carry/stage-<N>.json`. The schema is inlined here because a CLI-wrapper executor runs in its own process and never receives a native worker definition — a carry emitted with an ad-hoc shape (`stage`/`files`/`validation`) is a `contract-violated` gap the lead must rewrite by hand:
 
   ```json
   {

package/runtime/prompts/profiles/improvement-discovery.md

@@ -54,7 +54,7 @@
   - v1 legacy branch: when validating or rerendering an existing schema-v1 report, preserve its `## 5.9 Improvement Candidates` table and legacy Markdown contract; do not rewrite that historical data into v2 implicitly.
   - the `## 5.9 Improvement Candidates` table populated with rows that obey the 11-column schema from `validators/validate_improvement_report.py` (Cand ID `I-NNN`, Lens from whitelist, Title, Scope ⊆ scan-scope, Severity, Effort, Consensus, Source workers `<worker>:<id>` from {claude, codex, antigravity}, Recommended next-phase ∈ {requirements-discovery, implementation-planning, error-analysis}, Expected behavior after, Evidence as path:line list). `Expected behavior after` states, in one observable sentence, what becomes different once the candidate is applied — it is the seed of the downstream brief's `EB-NNN` / `EO-NNN`. A candidate you cannot write this cell for is a preference, not a finding: drop it rather than filling the cell with a restatement of the title.
   - `Consensus` cells in `## 5.9 Improvement Candidates` use the table enum exactly: `full`, `partial`, `contested`, `worker-unique`. Map convergence's `full-consensus` / `partial-consensus` labels to `full` / `partial` before writing the table.
-  - `## 7. Final Verdict` Verdict Token ∈ {`candidates-ready`, `no-candidates`, `blocked`}; Direction `routing`; Next Step "ask the user to select K candidates (see the ## 5.9 table)"
+  - Verdict Token — **branch-specific, and the two branches do not share a vocabulary.** On the current v2 branch use the shared analysis enum: `analysis-complete` when every resolved lens was examined, `analysis-partial` when one could not be, `blocked` when the scan itself could not run. `schemas/final-report-v2.0.schema.json` admits only those three for `verdictCard.verdictToken` / `finalVerdict.verdictToken`, so a v2 report carrying `candidates-ready` fails Phase 7. **Finding no candidates is not a verdict**: it is an empty `candidates[]` plus a `lensCoverage[]` row per lens with `status: no-candidate` and its evidence-backed rationale — the verdict stays `analysis-complete`. `candidates-ready` / `no-candidates` belong to the v1 legacy `## 7. Final Verdict` Markdown alone, where `validators/validate_improvement_report.py` enforces them. 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>`
   - author the shared schema-v2 report fields plus `improvementDiscovery.candidates[]`, `improvementDiscovery.lensCoverage[]`, `improvementDiscovery.selectionLimit`, and `improvementDiscovery.userNarrative` in data.json. `candidates[]` carries the same 11 logical fields described above; `lensCoverage[]` records either candidate IDs or an evidence-backed no-candidate rationale for every resolved lens. `schemas/final-report-v2.0.schema.json` and `validators/validate_improvement_report.py` enforce this contract. The renderers independently derive AI handoff Markdown and human HTML; never author a free-form report.
 - Clarification request policy (phase-specific addenda — shared policy is in `_common-contract.md`):

package/runtime/python/okstra_ctl/adapters/hosts/antigravity/relay.md

@@ -77,7 +77,7 @@ Render every numbered item as its option label followed by its description verba
 | `read_artifacts` | Read the manifest-provided paths through the current Antigravity host file interface. |
 | `write_artifact` | Write only core-authorized `.okstra/` artifacts and preserve their schemas. |
 | `prompt_user` | Ask through the current host text/question interface and stop at approval gates until an explicit answer arrives. |
-| `dispatch_worker` | Dispatch every `runner=native-session` Antigravity assignment through the current host. Dispatch every `runner=cli-wrapper` assignment through its registered provider wrapper. |
+| `dispatch_worker` | Dispatch every `runner=native-session` Antigravity assignment through the current host. Dispatch every `runner=cli-wrapper` assignment through its registered provider wrapper. **Not in a cmux run:** when the run manifest's `terminalBackend` is `cmux-pane`, `prompts/lead/adapters/cmux.md` overrides this row — start every worker with `okstra team dispatch`, this host's native path included, so okstra owns the panes and the user can watch the work. |
 | `await_workers` | Await native host workers through the host primitive and CLI workers through their status sidecars, then verify terminal state and Result Paths. |
 | `redispatch_worker` | Start a fresh native worker or CLI wrapper attempt according to the persisted assignment and record the supplied dispatch kind. |
 | `shutdown_workers` | Perform host or process cleanup only for resources owned by this run. |

package/runtime/python/okstra_ctl/adapters/hosts/claude-code/relay.md

@@ -136,7 +136,7 @@ For a `host-text` mapping, render each numbered item as its option label followe
 | `read_artifacts` | Use the host file-read primitive and preserve the core contract's read order. |
 | `write_artifact` | Use the host file-write primitive only for paths authorized by the active lifecycle phase. |
 | `prompt_user` | Use the native question tool for approvals and clarifications; do not infer an answer from silence. |
-| `dispatch_worker` | Dispatch each assignment through `Agent(name: "<role>", run_in_background: true)` without `team_name`; use an in-process worker for `runner=native-session` and the assigned provider's wrapper worker for `runner=cli-wrapper`. |
+| `dispatch_worker` | Dispatch each assignment through `Agent(name: "<role>", run_in_background: true)` without `team_name`; use an in-process worker for `runner=native-session` and the assigned provider's wrapper worker for `runner=cli-wrapper`. **Not in a cmux run:** when the run manifest's `terminalBackend` is `cmux-pane`, `prompts/lead/adapters/cmux.md` overrides this row — start every worker with `okstra team dispatch`, this host's native path included, so okstra owns the panes and the user can watch the work. |
 | `await_workers` | Arm one background shell poll for the pending Result Paths; the spawn acknowledgement is not completion. |
 | `redispatch_worker` | Dispatch a fresh `Agent(...)` session with the same prompt plus the core reverify/retry reason. |
 | `shutdown_workers` | For each confirmed-complete worker selected for cleanup, send `SendMessage(to: <name>, message: { type: "shutdown_request" })` to idle the roster member **and** call `TaskStop(task_id: "<name>")` to stop its background task. Both are required; neither subsumes the other. |

package/runtime/python/okstra_ctl/adapters/hosts/codex/relay.md

@@ -77,7 +77,7 @@ Render every numbered item as its option label followed by its description verba
 | `read_artifacts` | Read the manifest-provided paths through the current host's file interface. |
 | `write_artifact` | Write only core-authorized `.okstra/` artifacts and preserve their schemas. |
 | `prompt_user` | Ask through the host text/question interface and stop at approval gates until an explicit answer arrives. |
-| `dispatch_worker` | Dispatch every `runner=native-session` assignment with the current Codex host's native worker/session primitive. Pass only `runner=cli-wrapper` assignments to `okstra codex-dispatch --project-root <root> --run-manifest <path> --workers <ids>`; use `--dry-run` first when the core requires a dispatch preview. |
+| `dispatch_worker` | Dispatch every `runner=native-session` assignment with the current Codex host's native worker/session primitive. Pass only `runner=cli-wrapper` assignments to `okstra codex-dispatch --project-root <root> --run-manifest <path> --workers <ids>`; use `--dry-run` first when the core requires a dispatch preview. **Not in a cmux run:** when the run manifest's `terminalBackend` is `cmux-pane`, `prompts/lead/adapters/cmux.md` overrides this row — start every worker with `okstra team dispatch`, this host's native path included, so okstra owns the panes and the user can watch the work. |
 | `await_workers` | Await native host workers through the host primitive and CLI workers through synchronous dispatch, then verify team-state terminal records and Result Paths for both. |
 | `redispatch_worker` | Start a fresh native worker or `okstra codex-dispatch` attempt according to the persisted assignment's `runner`, and record the retry/reverify dispatch kind. |
 | `shutdown_workers` | Perform process cleanup when a wrapper remains live; otherwise this operation is a no-op recorded in state. |

package/runtime/python/okstra_ctl/adapters/hosts/external/relay.md

@@ -77,7 +77,7 @@ Render every numbered item as its option label followed by its description verba
 | `read_artifacts` | Read the manifest-provided paths through the current host's file or shell interface. |
 | `write_artifact` | Write only core-authorized `.okstra/` artifacts and preserve their schemas. |
 | `prompt_user` | Ask through the host text/question interface and require an explicit approval or clarification response. |
-| `dispatch_worker` | Run `okstra team dispatch --project-root <root> --run-manifest <path>`; use `--dry-run` first when the core requires a dispatch preview. |
+| `dispatch_worker` | Run `okstra team dispatch --project-root <root> --run-manifest <path>`; use `--dry-run` first when the core requires a dispatch preview. **Not in a cmux run:** when the run manifest's `terminalBackend` is `cmux-pane`, `prompts/lead/adapters/cmux.md` overrides this row — start every worker with `okstra team dispatch`, this host's native path included, so okstra owns the panes and the user can watch the work. |
 | `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. |

package/runtime/python/okstra_ctl/adapters/hosts/grok/relay.md

@@ -76,7 +76,7 @@ Render every numbered item as its option label followed by its description verba
 | `read_artifacts` | Read the manifest-provided paths through the current Grok host file interface. |
 | `write_artifact` | Write only core-authorized `.okstra/` artifacts and preserve their schemas. |
 | `prompt_user` | Ask through the current host text interface and wait for an explicit answer. |
-| `dispatch_worker` | Follow each persisted assignment's `runner` and use the common host dispatch boundary. |
+| `dispatch_worker` | Follow each persisted assignment's `runner` and use the common host dispatch boundary. **Not in a cmux run:** when the run manifest's `terminalBackend` is `cmux-pane`, `prompts/lead/adapters/cmux.md` overrides this row — start every worker with `okstra team dispatch`, this host's native path included, so okstra owns the panes and the user can watch the work. |
 | `await_workers` | Await through the selected common dispatch backend, then verify terminal state and Result Paths. |
 | `redispatch_worker` | Start a fresh attempt from the persisted assignment and record the supplied dispatch kind. |
 | `shutdown_workers` | Clean up only host or process resources owned by this run. |

package/runtime/python/okstra_ctl/adapters/hosts/kimi/relay.md

@@ -76,7 +76,7 @@ Render every numbered item as its option label followed by its description verba
 | `read_artifacts` | Read the manifest-provided paths through the current Kimi host file interface. |
 | `write_artifact` | Write only core-authorized `.okstra/` artifacts and preserve their schemas. |
 | `prompt_user` | Ask through the current host text interface and wait for an explicit answer. |
-| `dispatch_worker` | Follow each persisted assignment's `runner` and use the common host dispatch boundary. |
+| `dispatch_worker` | Follow each persisted assignment's `runner` and use the common host dispatch boundary. **Not in a cmux run:** when the run manifest's `terminalBackend` is `cmux-pane`, `prompts/lead/adapters/cmux.md` overrides this row — start every worker with `okstra team dispatch`, this host's native path included, so okstra owns the panes and the user can watch the work. |
 | `await_workers` | Await through the selected common dispatch backend, then verify terminal state and Result Paths. |
 | `redispatch_worker` | Start a fresh attempt from the persisted assignment and record the supplied dispatch kind. |
 | `shutdown_workers` | Clean up only host or process resources owned by this run. |

package/runtime/python/okstra_ctl/analysis_packet.py

@@ -44,7 +44,13 @@ PROFILE_SECTIONS = (
     "Non-goals",
 )
 WORKER_PROFILE_SECTIONS_BY_TASK_TYPE = {
+    # `Brief consumption` carries the reporter-confirmation rules — do not infer an
+    # unconfirmed `intent-check:` / `conversion-block:`, carry it forward as a
+    # blocker instead. Those bind the analysis worker, and the packet is the only
+    # profile text a worker receives, so a phase that omits the section ships a
+    # worker that can turn an unconfirmed intent into a settled requirement.
     "requirements-discovery": (
+        "Brief consumption",
         "Worker discovery procedure",
     ),
     "error-analysis": (
@@ -52,6 +58,7 @@ WORKER_PROFILE_SECTIONS_BY_TASK_TYPE = {
         "Worker diagnosis procedure",
     ),
     "implementation-planning": (
+        "Brief consumption",
         "Worker planning procedure",
         "Pre-planning context exploration",
         "Design principles applied when scoring options",
@@ -60,7 +67,13 @@ WORKER_PROFILE_SECTIONS_BY_TASK_TYPE = {
         "Worker verification procedure",
     ),
     "improvement-discovery": (
+        "Brief consumption",
         "Worker candidate procedure",
+        # Every analyser examines every resolved lens but leads with its own, and
+        # keeps duplicate / conflicting relations. Held only in the lead's profile,
+        # the workers converge on the same easy lens and the cross-check thins out
+        # while the aggregate still looks complete.
+        "Worker diversity rule",
     ),
 }
 CLARIFICATION_SECTIONS = (

package/runtime/python/okstra_ctl/consumers.py

@@ -27,6 +27,11 @@ CONSUMERS_FILENAME = "consumers.jsonl"
 # carrying a confirmed regression as complete.
 STAGE_LIFECYCLE_STATUSES = ("started", "done", "failed")
 
+# The lead has already ruled on a stage whose last row is one of these — `done`
+# closed it, `failed` deliberately did not. Neither may be re-derived from disk:
+# closing a stage is the lead's verdict gate, not a file's existence.
+_LEAD_SETTLED_STATUSES = ("done", "failed")
+
 
 @dataclass(frozen=True)
 class StageConsumerState:
@@ -308,16 +313,29 @@ def _carry_dir(plan_run_root: Path) -> Path:
 def backfill_done_from_carry(plan_run_root: Path) -> int:
     """Recover missing `done` rows from carry sidecars (carry is SSOT).
 
-    For every `runs/implementation/carry/stage-<N>.json` that is complete and
-    not already recorded as `done` in consumers.jsonl, append a `done` row with
-    the head commit read from the carry. Returns the number of rows recovered.
-    Stages with no carry or an unfinished carry are skipped, so the dependency
-    gate still legitimately blocks genuinely-unstarted stages."""
+    Recovers the crash window between the lead writing the carry file and
+    appending the `done` row: for every `runs/implementation/carry/stage-<N>.json`
+    that is complete and whose stage has no terminal row yet, append a `done` row
+    with the head commit read from the carry. Returns the number of rows
+    recovered. Stages with no carry or an unfinished carry are skipped, so the
+    dependency gate still legitimately blocks genuinely-unstarted stages.
+
+    A stage the lead has already ruled on is never re-derived from disk. That
+    includes `failed`: the executor emits its carry evidence when its own Tier 1/2
+    validation passes, which happens BEFORE the verifier's gate, so a carry file
+    exists for exactly the runs where the verifier then returned `FAIL`. Reading
+    the file as completion would promote a stage carrying a confirmed regression
+    to `done` and let its dependents proceed — and it would contradict this
+    module's own rule that a stage's position is its last lifecycle row."""
     carry_dir = _carry_dir(plan_run_root)
     if not carry_dir.is_dir():
         return 0
     existing = read_consumers(plan_run_root)
-    done_stages = {r.get("stage") for r in existing if r.get("status") == "done"}
+    settled_stages = {
+        stage
+        for stage, status in last_lifecycle_status_by_stage(existing).items()
+        if status in _LEAD_SETTLED_STATUSES
+    }
     key_by_stage: Dict[Any, str] = {}
     fallback_key = ""
     for r in existing:
@@ -335,7 +353,7 @@ def backfill_done_from_carry(plan_run_root: Path) -> int:
         if not isinstance(carry, dict):
             continue
         stage = _carry_stage_number(carry, cf.name)
-        if stage is None or stage in done_stages:
+        if stage is None or stage in settled_stages:
             continue
         if not _carry_is_complete(carry):
             continue
@@ -358,6 +376,6 @@ def backfill_done_from_carry(plan_run_root: Path) -> int:
             carry_path=carry_path,
             source="carry-backfill",
         )
-        done_stages.add(stage)
+        settled_stages.add(stage)
         recovered += 1
     return recovered

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -31,6 +31,7 @@ from .dispatch_state import (
     transition_worker_status as _transition_worker_status,
     string_list as _string_list,
     string_value as _string_value,
+    TEARDOWN_BEFORE_TERMINAL_REASON,
     utc_now as _utc_now,
     validate_dispatch_prompts as _validate_dispatch_prompts,
     worker_jobs_from_file as _worker_jobs_from_file,
@@ -231,6 +232,7 @@ def await_dispatches(
     timeout_seconds: int | None = None,
     heartbeat_seconds: int = 30,
 ) -> int:
+    _correct_teardown_marked_dispatches(plan)
     deadline = time.monotonic() + timeout_seconds if timeout_seconds is not None else None
     last_heartbeat = 0.0
     while True:
@@ -643,6 +645,35 @@ def _outcome_from_completed(handle: WorkerHandle) -> WorkerOutcome:
     )
 
 
+def _correct_teardown_marked_dispatches(plan: DispatchPlan) -> None:
+    """Let the wrapper's own exit settle a record teardown wrote off.
+
+    `okstra team teardown` marks every non-terminal dispatch `error` — right for a
+    worker it killed, wrong for one that had already exited while its record was
+    still `running`, which happens when the lead awaited by polling artifacts
+    instead of `team await` (the component that transitions the record). The run
+    then reports `error` for workers whose wrapper exited 0 with every output in
+    place, and nothing could undo it: teardown's `error` drops the record out of
+    the running set this function's caller scans, so a later await never saw it.
+
+    Only a success is corrected, and only from process-level evidence — the
+    wrapper's terminal status plus its exit code, judged by the same
+    `_outcome_from_status` path every other dispatch goes through. A non-zero exit
+    or a missing output stays an error, and no retry is spawned: teardown has
+    already taken the panes, so re-running here would start work nobody is
+    watching.
+    """
+    for record in _teardown_marked_dispatches(plan.team_state_path):
+        status_path = _optional_path(record.get("statusSidecarPath"))
+        status = read_wrapper_status(status_path) if status_path else None
+        if status is None or not status.is_terminal:
+            continue
+        outcome = _outcome_from_status(record, status)
+        if outcome.returncode != 0 or outcome.missing_completion_paths or outcome.timeout:
+            continue
+        _finish_record(plan, record, outcome)
+
+
 def _advance_running_dispatches(plan: DispatchPlan, records: Sequence[Mapping[str, Any]]) -> None:
     for record in records:
         status_path = _optional_path(record.get("statusSidecarPath"))
@@ -811,6 +842,22 @@ def _update_dispatch_status(
     _write_json(team_state_path, payload)
 
 
+def _teardown_marked_dispatches(team_state_path: Path) -> list[Mapping[str, Any]]:
+    """Records `okstra team teardown` wrote off, matched by its own reason string
+    so a genuine dispatch error is never mistaken for one."""
+    payload = _load_json_object(team_state_path, "team-state")
+    dispatches = payload.get("workerDispatches")
+    if not isinstance(dispatches, list):
+        return []
+    return [
+        record
+        for record in dispatches
+        if isinstance(record, dict)
+        and record.get("status") == "error"
+        and _string_value(record.get("reason")) == TEARDOWN_BEFORE_TERMINAL_REASON
+    ]
+
+
 def _running_dispatches(team_state_path: Path) -> list[Mapping[str, Any]]:
     payload = _load_json_object(team_state_path, "team-state")
     dispatches = payload.get("workerDispatches")

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -58,6 +58,12 @@ def detect_terminal_backend() -> str:
 LIVENESS_AUDIT_HEARTBEAT = "audit-heartbeat"
 LIVENESS_WRAPPER_STATUS = "wrapper-status"
 
+# `okstra team teardown` stamps this on a dispatch it wrote off, and a later
+# `okstra team await` matches it to tell those apart from a genuine dispatch
+# error before letting the wrapper's own exit settle them. Two sides of one fact,
+# so the string lives here rather than in whichever module wrote it first.
+TEARDOWN_BEFORE_TERMINAL_REASON = "teardown before terminal status"
+
 # The worktree argument grants the wrapper `--add-dir` write access outside
 # project-root. Only the phases whose workers mutate a stage worktree get it;
 # analysis phases write their artifacts under project-root (see the contract in

package/runtime/python/okstra_ctl/pr_template.py

@@ -6,7 +6,7 @@ release-handoff 단계에서 lead 가 PR 본문을 작성할 때 사용하는
     1. per-run override (okstra-run Step 6 에서 입력)
     2. project: <project_root>/.okstra/project.json 의 ``prTemplatePath``
     3. global:  ~/.okstra/config.json 의 ``prTemplatePath``
-    4. default: ``$OKSTRA_HOME/templates/prd/pr-body.template.md`` (구버전
+    4. default: ``$OKSTRA_HOME/templates/pr/pr-body.template.md`` (구버전
        ``~/.claude/skills/...`` 후보는 backward-compat 로 유지)
 
 경로는 절대경로 또는 ``~`` 시작 경로를 권장한다. 상대경로일 경우 project

package/runtime/python/okstra_ctl/team.py

@@ -19,6 +19,7 @@ from . import tmux
 from .adapters.dispatch import provider_worker_wrappers
 from .adapters.dispatch.cmux import dispatch_port_for_terminal_backend
 from .application.dispatch_assignments import dispatch_assignments
+from .dispatch_state import TEARDOWN_BEFORE_TERMINAL_REASON
 from .dispatch_core import (
     BACKEND_CMUX_PANE,
     BACKEND_TMUX_PANE,
@@ -256,7 +257,7 @@ def _mark_teardown_errors(team_state_path: Path) -> None:
     for record in payload.get("workerDispatches", []):
         if isinstance(record, dict) and record.get("status") not in _TERMINAL_STATUSES:
             record["status"] = "error"
-            record["reason"] = "teardown before terminal status"
+            record["reason"] = TEARDOWN_BEFORE_TERMINAL_REASON
     _write_json(team_state_path, payload)
 
 

package/runtime/python/okstra_ctl/worker_audit_ledger.py

@@ -55,6 +55,12 @@ def _looks_like_file_path(path: str) -> bool:
         return False
     if re.fullmatch(r"[0-9a-fA-F]{7,64}", path):
         return False
+    # A dotted name is the usual filename signal, and an IPv4 literal is dots and
+    # digits too. `127.0.0.1:13306` in a Read-only command log is a host and port —
+    # the worker cannot record an Evidence read of it, so reading it as a citation
+    # fails the run over something it has no way to satisfy.
+    if re.fullmatch(r"\d{1,3}(?:\.\d{1,3}){3}", path):
+        return False
     return (
         "/" in path
         or "." in Path(path).name

package/runtime/schemas/final-report-v2.0.schema.json

@@ -726,9 +726,10 @@
       "type": "object",
       "description": "RENDER_IF taskType == release-handoff. §5.6 deliverables.",
       "required": [
-        "sourceVerificationReport",
+        "handoffScope",
         "featureBranchState",
         "userSelections",
+        "localCheckoutOutcome",
         "executedCommands",
         "commitList",
         "mergeConflictProbe",
@@ -737,6 +738,37 @@
         "userNarrative"
       ],
       "additionalProperties": false,
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "handoffScope": {
+                "properties": {
+                  "mode": {
+                    "const": "stage-group"
+                  }
+                },
+                "required": [
+                  "mode"
+                ]
+              }
+            },
+            "required": [
+              "handoffScope"
+            ]
+          },
+          "then": {
+            "required": [
+              "sourceVerificationReports"
+            ]
+          },
+          "else": {
+            "required": [
+              "sourceVerificationReport"
+            ]
+          }
+        }
+      ],
       "properties": {
         "handoffScope": {
           "type": "object",
@@ -761,11 +793,25 @@
             },
             "collectorBranch": {
               "type": "string"
+            },
+            "mergeCommits": {
+              "type": "array",
+              "description": "Assemble's merge commit SHAs, in the order the stages were merged into the collector branch. Without them the collector branch's contents cannot be traced back to the stages that produced them once the branch moves on.",
+              "items": {
+                "type": "string",
+                "minLength": 7
+              }
+            },
+            "dependencyClosureVerdict": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Whether the selected stages are closed under their dependencies, and on what basis. A stage-group PR that ships a stage without its predecessor is the failure this records."
             }
           }
         },
         "sourceVerificationReport": {
           "type": "object",
+          "description": "whole-task mode: the one final-verification report this handoff ships. Required unless handoffScope.mode is stage-group.",
           "required": [
             "path",
             "verdictTokenQuote"
@@ -782,6 +828,59 @@
             }
           }
         },
+        "sourceVerificationReports": {
+          "type": "array",
+          "description": "stage-group mode: one row per selected stage, because that handoff ships several verified stages and a single report path cannot say which stage each verdict belongs to.",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": [
+              "stage",
+              "path",
+              "verdictTokenQuote"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "stage": {
+                "type": "integer",
+                "minimum": 1
+              },
+              "path": {
+                "type": "string",
+                "minLength": 1
+              },
+              "verdictTokenQuote": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          }
+        },
+        "localCheckoutOutcome": {
+          "type": "object",
+          "description": "What the `local checkout` action did, including when it was not taken. `removedWorktree` is the command's own field: a non-empty path means the okstra worktree was removed, an empty string means it was already gone and the branch survived. Recording a removal that did not happen is the error this shape exists to prevent.",
+          "required": [
+            "status"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "status": {
+              "enum": [
+                "not-run",
+                "checked-out"
+              ]
+            },
+            "branch": {
+              "type": "string"
+            },
+            "mainWorktreePath": {
+              "type": "string"
+            },
+            "removedWorktree": {
+              "type": "string"
+            }
+          }
+        },
         "featureBranchState": {
           "type": "object",
           "required": [
@@ -835,7 +934,9 @@
               ]
             },
             "h3": {
+              "description": "The PR title/body confirmation. `not-run` when H1 was `local checkout` or `skip` — those routes never reach the question, and inventing an answer for a question that was never asked is the failure this value prevents.",
               "enum": [
+                "not-run",
                 "use as-is",
                 "edit then proceed",
                 "cancel"

package/runtime/skills/okstra-setup/references/project-config.md

@@ -155,7 +155,7 @@ overwriting silently.
 ## D. Project PR body template (release-handoff)
 
 `release-handoff` fills the PR body from a template — by default
-`~/.okstra/templates/prd/pr-body.template.md`. Most projects want their own
+`~/.okstra/templates/pr/pr-body.template.md`. Most projects want their own
 (e.g. `.github/PULL_REQUEST_TEMPLATE.md`). Pre-registration during setup is
 opt-in; the same prompt is offered again on the first `release-handoff` run,
 so deferring (`Later`) is safe.

package/runtime/templates/reports/final-report.template.md

@@ -544,13 +544,22 @@ Carried-forward plan items retain their prior verdicts verbatim; each such item
 - Mode: `{{ releaseHandoff.handoffScope.mode | mdcell }}`
 {% if releaseHandoff.handoffScope.stages %}- Stages: {{ releaseHandoff.handoffScope.stages | join(', ') | mdcell }}
 {% endif %}{% if releaseHandoff.handoffScope.collectorBranch %}- Collector branch: `{{ releaseHandoff.handoffScope.collectorBranch | mdcell }}`
+{% endif %}{% if releaseHandoff.handoffScope.mergeCommits %}- Assemble merge commits: {{ releaseHandoff.handoffScope.mergeCommits | join(', ') | mdcell }}
+{% endif %}{% if releaseHandoff.handoffScope.dependencyClosureVerdict %}- Dependency closure: {{ releaseHandoff.handoffScope.dependencyClosureVerdict | mdcell }}
 {% endif %}
 {% endif %}
 ### 5.6.1 Source Verification Report
-
+{% if releaseHandoff.sourceVerificationReports %}
+| Stage | Report path (project-relative) | Quoted `Verdict Token` row |
+|-------|--------------------------------|----------------------------|
+{% for row in releaseHandoff.sourceVerificationReports -%}
+| {{ row.stage | mdcell }} | `{{ row.path | mdcell }}` | {{ row.verdictTokenQuote | mdcell }} |
+{% endfor %}
+{%- else %}
 - Path (project-relative): `{{ releaseHandoff.sourceVerificationReport.path }}`
 - Quoted `Verdict Token` row from that report's `## 7.` table:
   > {{ releaseHandoff.sourceVerificationReport.verdictTokenQuote | mdquote(2) }}
+{% endif %}
 
 ### 5.6.2 Feature Branch & Working-Tree State{% if t("releaseHandoff.branchStateAside") != "captured at run start" %} ({{ t("releaseHandoff.branchStateAside") }}){% endif %}
 
@@ -571,7 +580,7 @@ Carried-forward plan items retain their prior verdicts verbatim; each such item
 {% endif %}
 | H2 | {{ t("releaseHandoff.h2Body") }} | `{{ (releaseHandoff.userSelections.h2 or t("releaseHandoff.h2DefaultLabel")) | mdcell }}` | {{ t("releaseHandoff.h2OptionsLabel") }} |
 | H2b | Merge conflict probe | `{{ (releaseHandoff.userSelections.h2b or releaseHandoff.mergeConflictProbe.kind) | mdcell }}` | `not-run` / `clean` / `proceed anyway` / `change base branch` / `cancel` |
-| H3 | {{ t("releaseHandoff.h3Body") }} | `{{ releaseHandoff.userSelections.h3 | mdcell }}` | `use as-is` / `edit then proceed` / `cancel` |
+| H3 | {{ t("releaseHandoff.h3Body") }} | `{{ releaseHandoff.userSelections.h3 | mdcell }}` | `not-run` / `use as-is` / `edit then proceed` / `cancel` |
 
 ### 5.6.4 Executed Commands
 
@@ -623,6 +632,12 @@ Carried-forward plan items retain their prior verdicts verbatim; each such item
 
 {{ releaseHandoff.routingRecommendation }}
 
+### 5.6.9 Local Checkout Outcome
+
+- Status: `{{ releaseHandoff.localCheckoutOutcome.status | mdcell }}`
+{% if releaseHandoff.localCheckoutOutcome.status == 'checked-out' %}- Checked out `{{ releaseHandoff.localCheckoutOutcome.branch | mdcell }}` into `{{ releaseHandoff.localCheckoutOutcome.mainWorktreePath | mdcell }}`
+- okstra worktree: {% if releaseHandoff.localCheckoutOutcome.removedWorktree %}`{{ releaseHandoff.localCheckoutOutcome.removedWorktree | mdcell }}` removed{% else %}none removed — already torn down, so the branch survived{% endif %}
+{% endif %}
 {% endif %}
 {% if header.taskType == 'implementation' %}
 ## 5.7 Implementation Deliverables

package/runtime/templates/reports/html/tasks/release-handoff.template.html

@@ -39,7 +39,8 @@
   <h2>{{ t('tasks.release-handoff.commits-delivered') }}</h2>
   {% if handoff.commitList is mapping %}<p>{{ t('tasks.release-handoff.there-are-no-commits') }}</p>{% else %}
   <table><thead><tr><th>{{ t('tasks.release-handoff.commit') }}</th><th>{{ t('tasks.release-handoff.subject') }}</th><th>{{ t('tasks.release-handoff.files') }}</th></tr></thead><tbody>{% for row in handoff.commitList %}<tr>{{ row_key(pairs=[("SHA", row.shortSha), ("Order", loop.index)]) }}<td>{{ row.subject | inline_code }}</td><td>{% for file in row.files %}<code>{{ file }}</code>{% if not loop.last %} {% endif %}{% endfor %}</td></tr>{% endfor %}</tbody></table>{% endif %}
-  <p data-report-field="releaseHandoff.sourceVerificationReport"><strong>{{ t('tasks.release-handoff.the-verification-report-this-rests-on') }}</strong> — <code>{{ handoff.sourceVerificationReport.path }}</code> · {{ handoff.sourceVerificationReport.verdictTokenQuote | inline_code }}</p>
+  {% if handoff.sourceVerificationReports %}<p data-report-field="releaseHandoff.sourceVerificationReports"><strong>{{ t('tasks.release-handoff.the-verification-report-this-rests-on') }}</strong>{% for row in handoff.sourceVerificationReports %} — stage {{ row.stage }}: <code>{{ row.path }}</code> · {{ row.verdictTokenQuote | inline_code }}{% endfor %}</p>
+  {% else %}<p data-report-field="releaseHandoff.sourceVerificationReport"><strong>{{ t('tasks.release-handoff.the-verification-report-this-rests-on') }}</strong> — <code>{{ handoff.sourceVerificationReport.path }}</code> · {{ handoff.sourceVerificationReport.verdictTokenQuote | inline_code }}</p>{% endif %}
 </section>
 
 <section data-report-section="next-action">

package/runtime/validators/validate-run.py

@@ -693,6 +693,58 @@ def _is_legal_concurrent_run_skip(
     )
 
 
+def _validate_cmux_workers_were_dispatched_by_okstra(
+    team_state: dict,
+    workers: list,
+    dispatched_statuses: set[str],
+    failures: list[str],
+) -> None:
+    """Under cmux, okstra owns the worker panes — so it must have started them.
+
+    `prompts/lead/adapters/cmux.md` overrides the host relay's worker-dispatch
+    mapping: every lead goes through `okstra team dispatch`, a Claude Code lead
+    included. A lead that follows its own relay instead and starts the worker
+    in-process gets no pane, and the user cannot see the work — which is the whole
+    point of the adapter owning them.
+
+    The tell is the absent record, not the backend: `okstra team` appends a
+    `workerDispatches[]` row for every worker it starts, and an in-process worker
+    leaves none. Backend alone cannot separate the two, because a pane dispatch
+    that degrades legitimately records `backendType: cli-wrapper`
+    (`dispatch_core._dispatch_record`). A worker that was never attempted has no
+    row either, so only attempted statuses are checked.
+    """
+    adapter = team_state.get("leadAdapter")
+    if not isinstance(adapter, dict):
+        return
+    if str(adapter.get("name", "")).strip() != "cmux":
+        return
+    recorded = {
+        str(row.get("workerId", "")).strip()
+        for row in team_state.get("workerDispatches") or []
+        if isinstance(row, dict)
+    }
+    missing = []
+    for worker in workers:
+        if not isinstance(worker, dict):
+            continue
+        if str(worker.get("status", "")).strip() not in dispatched_statuses:
+            continue
+        worker_id = str(worker.get("workerId", "")).strip()
+        if worker_id and worker_id not in recorded:
+            missing.append(worker_id)
+    if missing:
+        failures.append(
+            "team-state.workerDispatches has no record for "
+            f"{', '.join(sorted(missing))} in a cmux run — those workers ran "
+            "without okstra starting them, so they had no pane and the user "
+            "could not watch the work. Under cmux every lead dispatches through "
+            "`okstra team dispatch`, a Claude Code lead included "
+            "(prompts/lead/adapters/cmux.md); the host relay's in-process "
+            "`Agent(...)` mapping does not apply to this run."
+        )
+
+
 def validate_team_state(
     team_state: dict,
     project_root: Path,
@@ -777,6 +829,10 @@ def validate_team_state(
                         f"Found: `{tc_status}`."
                     )
 
+    _validate_cmux_workers_were_dispatched_by_okstra(
+        team_state, workers, dispatched_statuses, failures
+    )
+
     by_role: dict[str, dict] = {}
     for worker in workers:
         if not isinstance(worker, dict):