okstra 0.189.3 → 0.190.0

package/docs/for-ai/skills/okstra-chat.md

@@ -25,10 +25,10 @@ okstra chat ack --room <name> --as <display> --through <id>
 
 Display names are typed. The CLI does not generate them.
 
-Unread is the inbox after the read cursor minus messages whose `from` equals `--as`. It does not move the cursor. `inbox` and `log` keep those messages. Rows are `id @from YYYY-MM-DD HH:MM body`. A reply inserts `↑parentId` after the time. Recipient is not on the line.
+Unread is the inbox after the read cursor minus messages whose `from` equals `--as`. It does not move the cursor. `inbox` and `log` keep those messages. Rows are `id @from YYYY-MM-DD HH:MM body`. A reply inserts `↑parentId` after the time. Recipient is not on the line. A body with several lines continues on rows indented by two spaces; those rows carry no id.
 
-`send --to` may equal `--as`. `--to` and `--reply-to` are exactly one. `--body` and `--body-file` are exactly one. A reply inherits `to` from the parent. `members` is the full roster.
+`send --to` may equal `--as`. `--to` and `--reply-to` are exactly one. `--body` and `--body-file` are exactly one; either may hold several lines, and only an all-blank body is rejected. A reply inherits `to` from the parent. `members` is the full roster. `ack --through` rejects an id behind the current cursor. `.` and `..` are reserved names. A stale `.lock` (dead owner pid, or older than 5 s) is reclaimed by the next writer.
 
-The skill picker is `all` plus `members` minus the current display name. Skill send and reply use `--body`, not `--body-file`. After showing unread rows, the skill runs `ack --through` with the last unread id unless the output is `no unread`. The Step 3 menu is send, unread, inbox, log, reply, done. Reply takes a free-input id and body; there is no recipient picker and no `okstra chat reply` subcommand.
+The skill picker is `all` plus `members` minus the current display name. Skill send and reply use `--body`, not `--body-file`. Before joining an existing room the skill runs `members`; if the typed display name is already listed, it asks whether this session is already in the room under that name (a re-entry after context loss) and, if so, continues with `--as` without joining. After showing unread rows, the skill runs `ack --through` with the id of the last row that starts with an id, unless the output is `no unread`. The Step 3 menu is send, unread, inbox, log, reply, done. Reply takes a free-input id and body; there is no recipient picker and no `okstra chat reply` subcommand.
 
 Read the fixed text rows. Do not parse JSON.

package/docs/for-ai/skills/okstra-inspect.md

@@ -33,7 +33,7 @@ No sub-command writes outside this machine.
 | `errors` | aggregate task error logs into a timestamped markdown report | generates report |
 | `error-zip` | build an anonymized zip of cross-project error logs | generates zip |
 | `run-audit` | check every run's artifacts against progress invariants — catches a run that ended wrong without ever logging a failure | read |
-| `recap` | summarize a task's before/after runs and record Q&A | appends `recap-log.jsonl` |
+| `recap` | summarize a task's before/after runs, or a task-group's per-brief status and latest conclusions, and record Q&A | appends `recap-log.jsonl` (task `recap/`, group `.recap/`) |
 
 ## Preflight
 
@@ -225,12 +225,22 @@ okstra model-io recap-input --project-root <projectRoot> --task-ref <task-key>
 
 Use the emitted `Run count` and repeated `Transition` fields in order. Do not parse recap JSON or open recap state files directly.
 
+Group scope — when the user names a task-group, or the bare token resolves only via `taskGroup`:
+
+```bash
+okstra model-io recap-input --project-root <projectRoot> --task-group <task-group>
+```
+
+The projection joins the group's briefs (start order, `waits for` edges), the catalog / task-manifests (real status, progress, run count, next phase, report), and the group document's Task Memory (headline, decisions, watch-outs, follow-ups). Read `Brief count` / `Task count` / `Next in group`, then the repeated `Queue entry` and `Task` blocks. Run-count / time / error totals belong to `okstra-rollup`.
+
 record:
 
 ```bash
 okstra recap record <task-key> --project-root <projectRoot> --kind <summary|qa> --mode <artifact|code> --question "<question>" --answer "<summary>" --citation "<path:line>"
 ```
 
+In group scope, `--task-group <task-group>` replaces `<task-key>` and the line lands at `.okstra/tasks/<task-group>/.recap/recap-log.jsonl`. `recap note` has no group form.
+
 Enter code mode only when the user explicitly requests it, such as "including the diff" or "the code changes too". Entering recap alone does not read the code diff.
 
 ## Output rules

package/docs/for-ai/skills/okstra-rollup.md

@@ -28,6 +28,7 @@ Use it when:
 Do not use it when:
 
 - A single task's report/time/errors/recap → `okstra-inspect` (report / time / errors / recap facet).
+- "Where does the group stand" — which briefs are done / in progress / not started, what is next, each task's latest conclusion → `okstra-inspect` recap facet with `--task-group`. rollup keeps the numbers (runs, time, errors) and the cross-task digest.
 - A forward-looking work plan (a client-facing schedule of non-done tasks) → `okstra-schedule-gen`. rollup is **retrospective**, collecting past run results; schedule is **forward-looking**, planning future work.
 - Actual phase execution → `okstra-run`.
 

package/docs/for-ai/skills/okstra-run.md

@@ -4,7 +4,7 @@
 
 - Skill source: [`skills/okstra-run/SKILL.md`](../../../skills/okstra-run/SKILL.md)
 - wizard CLI wrapper: [`src/commands/execute/wizard.mjs`](../../../src/commands/execute/wizard.mjs)
-- wizard state machine: [`scripts/okstra_ctl/wizard.py`](../../../scripts/okstra_ctl/wizard.py)
+- wizard state machine: [`scripts/okstra_ctl/wizard/`](../../../scripts/okstra_ctl/wizard/)
 - render-bundle CLI: [`src/commands/execute/render-bundle.mjs`](../../../src/commands/execute/render-bundle.mjs)
 - prepare entrypoint: [`scripts/okstra_ctl/run.py`](../../../scripts/okstra_ctl/run.py)
 
@@ -14,7 +14,7 @@
 
 Single authority:
 
-- Question order, branching, validation: `scripts/okstra_ctl/wizard.py`
+- Question order: `scripts/okstra_ctl/wizard/registry.py` (`STEPS`); branching: `engine.py`; per-step validation: `steps_*.py`
 - task bundle materialization: `prepare_task_bundle()`
 - Skill document: thin prompt-relay loop
 
@@ -109,12 +109,13 @@ Important: never trim, hide, or restructure the wizard-provided options into a "
 
 ## brief candidate ordering
 
-The brief selection for entry phases (`requirements-discovery`, `error-analysis`, `improvement-discovery`) is handled by the wizard.
+The brief selection is handled by the wizard. A new task is asked for its brief right after task-group and **before** the task-type; an existing task is asked only on an entry phase (`requirements-discovery`, `error-analysis`, `improvement-discovery`, `project-analysis`, `feature-analysis`, `change-impact-analysis`).
 
 - task-group candidates are shown newest-first by combining recent task-catalog use with the recent brief creation/modification times under `.okstra/briefs/<group>/`.
 - brief file candidates are chosen from within the selected group's `.okstra/briefs/<task-group>/**/*.md`.
 - The brief-file sort key is `max(file created/modified time, task-catalog updatedAt of the task that used this brief)`.
 - direct input is always last.
+- for a new task the following task-type pick offers entry phases only, and its recommended slot is the selected brief's `Recommended next phase:` line (fallback `requirements-discovery`).
 
 ## confirm step
 
@@ -124,7 +125,7 @@ When `next.step == "confirm"`, first fetch the confirmation summary.
 okstra wizard confirmation --state-file /tmp/okstra-wizard/state.json
 ```
 
-Show `text` to the user, then render the Proceed/Edit/Abort picker. `Edit` rewinds the wizard to an earlier step.
+Show `text` to the user, then render the Proceed/Edit/Abort picker as the final output of that turn — the rendered question is the last thing you emit in that turn, and text emitted after the call renders below the picker. `Edit` rewinds the wizard to an earlier step.
 
 ## outcome and render-bundle
 

package/docs/for-ai/skills/okstra-user-response.md

@@ -26,7 +26,7 @@ The legacy `list` and `show` JSON commands remain for automation compatibility.
 ## Flow
 
 1. Run `okstra preflight --runtime <host-runtime>` for the current harness. On `Okstra preflight: failed`, show `Reason` and `Recovery`, then stop. On `Okstra preflight: ready`, carry `Project root`, `Project ID`, `Runtime`, and `Relay contract`, then run `okstra paths --field home`.
-2. Read the relay `Wizard interaction relay` JSON. When `native-single` is available and the option count fits `nativeLimits`, call `interactions.native-single.function` (`AskUserQuestion` / `ask_user_question` / `request_user_input` from that field). Do not print a numbered list in chat while the native tool is available. Otherwise render a numbered Markdown list. Do not substitute one host function name for another. Copy the view's `Picker:` `- Label:` / `Description:` pairs into that function in that order. Do not rebuild labels from the `Options:` dump. `--option-number` is the 1-based `Option N:` index, which is the same order as `Picker:`. The HTML report's `<select>` uses the same `option.answer` values. Pass only the `list-view` `Picker:` rows, the report `Picker:` rows, or the two confirmation labels. Do not append `Enter directly`. Claude Other, Grok `z`, and Codex's free-form row are `Enters an answer`; on a numbered list, so is a next message that is not a listed label or its 1-based number. Do not ask a second question for the custom value.
+2. Read the relay `Wizard interaction relay` JSON. When `native-single` is available and the option count fits `nativeLimits`, call `interactions.native-single.function` (`AskUserQuestion` / `ask_user_question` / `request_user_input` from that field). Do not print a numbered list in chat while the native tool is available. Emit the question as the last thing in that turn; text emitted after the call renders below the question. Otherwise render a numbered Markdown list. Do not substitute one host function name for another. Copy the view's `Picker:` `- Label:` / `Description:` pairs into that function in that order. Do not rebuild labels from the `Options:` dump. `--option-number` is the 1-based `Option N:` index, which is the same order as `Picker:`. The HTML report's `<select>` uses the same `option.answer` values. Pass only the `list-view` `Picker:` rows, the report `Picker:` rows, or the two confirmation labels. Do not append `Enter directly`. Claude Other, Grok `z`, and Codex's free-form row are `Enters an answer`; on a numbered list, so is a next message that is not a listed label or its 1-based number. Do not ask a second question for the custom value.
 3. Select a task from `list-view` through that host picker. A host free-text row or unmatched next message is the report path or task key.
 4. Read only `show-view --report <reportPath> --project-root <projectRoot>` for report facts. The view also prints `Why asked`, `Linked plan items`, and `Cited artifacts`.
 5. Read every cited `path:line` under the project root and every linked plan-item definition before asking. Do not search beyond that list. Investigation explains; it never changes `options[]`.

package/docs/project-structure-overview.md

@@ -202,7 +202,7 @@ The Module column below is where the command's behaviour lives — a `src/` modu
 | `spawn-followups`, `error-log` | `scripts/okstra-spawn-followups.py`, `scripts/okstra-error-log.py` | Follow-up task bundle creation and run error-log append helpers |
 | `memory` | `src/commands/memory/memory.mts` | Store/find global conversation memory under `~/.okstra/memory-book` |
 | `pr` | `src/commands/pr/pr.mts` | `okstra pr <template\|branches\|gen>` — PR body template store under `~/.okstra/template/pr/` (bundled fallback `src/commands/pr/default.md`), base-branch recommendation, and a fixed-text generation bundle for the okstra-pr-gen skill. `--json` preserves the template + `<base>..HEAD` commits + `<base>...HEAD` diffstat machine contract. Git-only; no project registration required |
-| `recap` | `scripts/okstra_ctl/recap.py` | `okstra recap <assemble\|record\|note>` Node wrapper backing the okstra-inspect `recap` facet — `assemble` is a read-only phase-transition summary, `record` appends one line to `recap/recap-log.jsonl`, and `note` writes an agent-authored note under `notes/` and prints the `--clarification-response` argument for a follow-up run |
+| `recap` | `scripts/okstra_ctl/recap.py` | `okstra recap <assemble\|record\|note>` Node wrapper backing the okstra-inspect `recap` facet — `assemble` is a read-only phase-transition summary for a task or, with `--task-group`, the group's start order plus each task's latest conclusion; `record` appends one line to `recap/recap-log.jsonl` (task) or `.okstra/tasks/<group>/.recap/recap-log.jsonl` (`--task-group`); `note` writes an agent-authored note under `notes/` and prints the `--clarification-response` argument for a follow-up run |
 | `stage-map` | `scripts/okstra_ctl/stage_map_cli.py` | `okstra stage-map <task-key>` — exposes a task's implementation-planning Stage Map as JSON (`stages[].{stage_number,title,depends_on,step_count}` + consumer-state-based `doneStages[]`). If there is no Stage Map, `stages: []`. The read-side basis from which `okstra-schedule-gen` derives stage units and dependency closure |
 | `design-prep` | `scripts/okstra_ctl/design_prep.py` | `okstra design-prep <list\|show\|write>` thin shim into `scripts/okstra_ctl/design_prep.py` — queries (`list`/`show`) the design items that implementation-planning pre-authored with AI, and records the user-confirmed responses as an append-only sidecar under `design-prep-inputs/` (`write`, `--confirmed` required). It never modifies the report snapshot |
 | `rollup` | `scripts/okstra_ctl/rollup.py` | Read-only roll-up; `--text` is the fixed model projection and machine mode remains JSON |
@@ -262,7 +262,7 @@ Important modules:
 | `consumers.py` | Append-only `consumers.jsonl` writer + reader — records which `implementation` runs consumed which `implementation-planning` stage |
 | `implementation_outcome.py` | Artifact-derived reconstruction of the implementation phase outcome — reads `runs/implementation/carry/stage-<N>.json` + `consumers.jsonl` + the approved Stage Map to derive `phaseOutcome.implementation`, and when every stage has pass-grade carry evidence it raises `workflow.nextRecommendedPhase.status` to `ready` (keeping the `contract-violated` audit information). It never picks the phase — `phase` is left as the last stage's report routing settled it, and the status is raised only while `phase` is non-empty |
 | `paths.py` | Path/sequence computation for task/run artifacts (including recap directory/log paths) |
-| `recap.py` | deterministic backend for the okstra-inspect `recap` facet — `assemble` builds the cross-run phase transitions from the timeline overlaid with each run-manifest's current facts (`timeline_runs.py`), `record` append-only writes a summary/Q&A to `<task-root>/recap/recap-log.jsonl` (other task artifacts unchanged) |
+| `recap.py` | deterministic backend for the okstra-inspect `recap` facet — `assemble` builds the cross-run phase transitions from the timeline overlaid with each run-manifest's current facts (`timeline_runs.py`); `assemble_group_recap` joins a task-group's briefs (start order, `group_context.group_queue`), catalog task-manifests (status, run count, next phase, report), and the group document's Task Memory (each task's conclusion); `record` append-only writes a summary/Q&A to `<task-root>/recap/recap-log.jsonl` or `.okstra/tasks/<group>/.recap/recap-log.jsonl` (other artifacts unchanged) |
 | `timeline_runs.py` | read-side overlay of a `history/timeline.json` entry with its run-manifest's current facts (`current_run_facts`) — the entry is a prepare-time snapshot (`status`, `workflowSnapshot`, reserved `reportRecordPath`) and `validate-run` writes the end state to the run-manifest only; a run whose `validation.status` is `not-run` projects no report path. Shared by `recap.py` and the `history-input` / overview projections in `model_io/renderers.py` |
 | `render.py` | task manifest, run manifest, timeline, task index, discovery, team-state, prompt/template render |
 | `group_context.py` | task-group context document (`.okstra/briefs/<task-group>/group-context.md`): the skeleton writer behind `okstra group-context init` (template `templates/reports/group-context.template.md`), `validate_group_context` (four required sections, no template placeholder left, directory slug matches the frontmatter `task-group`) that `validators/validate-brief.py` dispatches to on frontmatter `type: group-context`, and the path helpers `run.py` uses to validate the file at preflight and copy it to `instruction-set/task-group-context.md` for the analysis packet's `## Task-Group Context` section |
@@ -287,7 +287,19 @@ Important modules:
 | `design_snapshot.py` | Builds the design-surface-detector-owned snapshot from the report narrative — reproducible design surfaces plus conservative `PREP-NNN` preparation items (delegates surface detection to `design_surfaces.py`) |
 | `report_markdown.py` | Schema-ordered Markdown serialisation of a data.json subtree for the full reading copy — headings, tables for uniform row sets, prose for narrative fields; field order read from the schema, not from the mapping |
 | `final_report_paths.py`, `report_view_artifacts.py` | Path-helper SSOT for the final-report markdown/data.json pair and the generated view artifacts (HTML view, user-responses directory) |
-| `wizard.py` | `okstra-run` prompt state machine; user-facing Korean strings live in `prompts/wizard/prompts.ko.json` |
+| `wizard/` | `okstra-run` prompt state machine as a package; user-facing Korean strings live in `prompts/wizard/prompts.ko.json`. Modules import only the modules listed before them (`tests/contract/test_no_import_cycles.py`): |
+| `wizard/ids.py` | constants, `S_*` step ids, pick tokens, multi-tab prompt groups |
+| `wizard/state.py` | `WizardState` / `Prompt` / `Option` / `Step` dataclasses, v1 provider-selection → v2 conversion, state predicates |
+| `wizard/prompts.py` | `prompts.ko.json` loader and placeholder interpolation (`_p`, `_msg`, `_static_options`) |
+| `wizard/sources.py` | helpers that read `.okstra` history, reports, profiles and git worktrees to suggest values |
+| `wizard/roles.py` | role-instance selection loop (`next_role_prompt`) and its validation / rewind |
+| `wizard/statefile.py` | `load_state_file` / `save_state_file` and the v2 companion-file lookup |
+| `wizard/steps_identity.py`, `steps_analysis.py`, `steps_plan.py`, `steps_options.py`, `steps_roles.py` | build/submit pairs per step cluster: task identity + brief + base ref; analysis inputs + design prep; approved plan + stage + handoff + reverify scope; directive / related tasks / clarification / pr template ("optional cached pick" seam); executor / critic / workers / per-role model picks |
+| `wizard/confirmation.py` | `confirmation_block` and the confirm step |
+| `wizard/registry.py` | the ordered `STEPS` literal (order is question order), `STEP_BY_ID`, `_reset_from`, and the steps that rewind the registry (edit target, brief carry) |
+| `wizard/engine.py` | public API — `init_state`, `next_prompt`, `submit`, progress / simulation, host interaction payloads |
+| `wizard/render.py` | `render_args`, `render_role_args`, `wizard_outcome` |
+| `wizard/cli.py`, `wizard/__main__.py` | `okstra wizard` argparse entrypoint (`main`); `python3 -m okstra_ctl.wizard` |
 | `wizard_stage_intent.py` | stage-related intent projection of the `okstra-run` wizard output — normalizes whole-task (`__whole_task__`) vs single/multi stage selection into render-args (`resolve_wizard_stage_intent`) |
 | `index.py`, `jsonl.py`, `reconcile.py`, `listing.py`, `backfill.py` | `~/.okstra` run index and history operations — `record_start` (index.py) writes a run's start; the end is closed either by `settle_run_row` (reconcile.py, records a verdict the caller already knows — used by `validate-run.py`) or by `reconcile_home` (infers one from disk — used by `run._reconcile_prior_runs` as the backstop for runs that died before validation) |
 | `run_index_row.py` | single reference point for creating / slimming / hydrating a `~/.okstra` run-index row — runId SSOT, preserves projectId raw |
@@ -346,7 +358,7 @@ Important modules:
 | `plan_derivations.py` | the supersession sweep `_common-contract.md` requires an author to do by hand — extracts the symbols, paths, and ids an answered clarification names and reports every plan string that mentions one. Advisory: it locates candidates and never judges which are now false |
 | `scope_provenance.py` | single source of truth for the scope-provenance grammar every phase-emitted requirement must declare, shared by `validators/validate-run.py` and `validators/validate_fanout.py` so the planning report and fan-out packets cannot drift |
 | `worker_artifact_paths.py` | canonical worker artifact path derivation (e.g. `audit_sidecar_rel` inserts `-audit-` after the first `-worker-` token), so dispatch and validation agree on non-canonical-path rejection |
-| `report_finalize.py` | Phase 7 post-report sequence **SSOT** — runs `check-source` → `token-usage` → `render-views` → `spawn-followups` → `validate-run` in that load-bearing order. A non-zero exit still runs every later check through `validate-run` and names the earliest failure; `teardown-stages` is skipped when any earlier step failed. Both lead paths converge here: the Codex adapter calls it in-process (`codex_dispatch`), a Claude-led run reaches it through `okstra report-finalize`. Neither reimplements the sequence |
+| `report_finalize.py` | Phase 7 post-report sequence **SSOT** — runs `check-source` → `token-usage` → `render-views` → `spawn-followups` → `validate-run` → `record-group-memory` → `teardown-stages` in that load-bearing order. A non-zero exit still runs every later check through `validate-run` and names the earliest failure; `record-group-memory` (this run's conclusion into the task-group's `group-context.md`, plus `nextInGroup` for the closeout) and `teardown-stages` are skipped when any earlier step failed. Both lead paths converge here: the Codex adapter calls it in-process (`codex_dispatch`), a Claude-led run reaches it through `okstra report-finalize`. Neither reimplements the sequence |
 | `wrapper_status.py` | worker wrapper status sidecar reader — the host-side reader of the sidecar `worker_runner.py` writes. `is_terminal` is the one question it answers for the dispatch record and the pane reclaim: does `stage` read `exited` |
 | `worker_runner.py` | runs one worker CLI and records what happened — shared by every provider entrypoint. Owns the `selectors` pump over the child's streams, the stream-arrival idle watchdog (`killpg` on breach), the run-wide progress cap on the log copy, and the status sidecar's whole life. A run that dies after launch still closes its sidecar, so `worker_liveness` never reads a dead worker as running |
 | `session_transcript.py` | worker session transcript — one line per event (time, speaker, body) with a run-wide progress-line cap (`LOG_LINE_CAP`, elision notice) so a single-file dispatch's tool echo cannot dominate the project's `.okstra/` bytes; the fixed shape lets a later lead write share the same file |
@@ -358,7 +370,7 @@ Important modules:
 | `task_target.py` | shared helper resolving `task-key → (task_root, project_root)` (`resolve_task_root`) |
 | `contract_graph.py`, `contract_graph_cli.py` | runtime-contract graph loader + cross-reference/dependency-closure validator and its `okstra contract-check --root <dir> (--profile\|--operation)` CLI boundary. Loads the agent contract schemas (`common`/`role`/`duty`/`profile`/`operation`), validates known role capabilities, and reports the dependency closure with per-file `path`/`schemaVersion`/`sha256`; an invalid contract raises `ContractGraphError` |
 | `json_boundary.py` | strict JSON persistence boundaries for okstra-owned artifacts — a sealed `ExternalJsonSource` (validated producer + path) is the only way owned JSON is read, and `JsonBoundaryError` names artifact / reason / path when a write cannot satisfy its contract; the SSOT that keeps the model out of internal JSON key/path authorship |
-| `fixed_text.py` | shared scalar-line format for the model-facing fixed-text projections — `scalar` neutralises complex values and control characters, `line` renders one static-labelled Markdown list row, and `value_lines` losslessly flattens a JSON-shaped value into fixed name/order/value rows |
+| `fixed_text.py` | shared scalar-line format for the model-facing fixed-text projections — `scalar` neutralises complex values and control characters (backticks escaped for the code span `line` wraps it in), `block` projects a prose body outside any code span with its backticks intact, `line` renders one static-labelled Markdown list row, and `value_lines` losslessly flattens a JSON-shaped value into fixed name/order/value rows |
 | `model_io_cli.py`, `model_io/` | renders purpose-scoped fixed Markdown input from okstra-owned JSON for the model boundary — resolves the current run/project through the run manifest (`validated_run_authority`, `canonical_run_state_artifact`) and emits only each command's allow-listed fields in fixed order instead of expanding arbitrary nested objects. `model_io_cli.py` is the argparse surface only; inside the package, `references` resolves paths and reads JSON, `lines` turns an already-read mapping into fixed Markdown and opens nothing, and `renderers` composes the two into one function per command |
 
 > `i18n.py` (the final-report i18n dictionary loader + Jinja2 lookup) is an intentionally undocumented internal helper — it is a render helper that users and contributors do not need to know about in the canonical docs, so it is excluded from the module map.

package/docs/task-process/README.md

@@ -53,7 +53,7 @@ Launch selection is role slots and model refs, not a provider roster. The wizard
 | Concern | Source of truth |
 |---|---|
 | okstra-run skill procedure | [`skills/okstra-run/SKILL.md`](../../skills/okstra-run/SKILL.md) |
-| wizard state machine | [`scripts/okstra_ctl/wizard.py`](../../scripts/okstra_ctl/wizard.py) |
+| wizard state machine | [`scripts/okstra_ctl/wizard/`](../../scripts/okstra_ctl/wizard/) |
 | wizard prompt text | [`prompts/wizard/prompts.ko.json`](../../prompts/wizard/prompts.ko.json) |
 | render-bundle Node shim | [`src/commands/execute/render-bundle.mjs`](../../src/commands/execute/render-bundle.mjs) |
 | single entrypoint for bundle creation | [`scripts/okstra_ctl/run.py`](../../scripts/okstra_ctl/run.py) |

package/docs/task-process/error-analysis.md

@@ -37,7 +37,7 @@ Launch selection uses role slots and model refs only: current-session lead is th
 ```mermaid
 sequenceDiagram
     participant Skill as okstra-run
-    participant Wizard as wizard.py
+    participant Wizard as okstra_ctl.wizard
     participant Run as prepare_task_bundle
     participant WT as worktree/provision.py
     participant Art as artifacts
@@ -99,5 +99,5 @@ What is prohibited is source edit, refactor, fix attempt, implementation design
 - [`prompts/profiles/error-analysis.md`](../../prompts/profiles/error-analysis.md)
 - [`templates/reports/error-analysis-input.template.md`](../../templates/reports/error-analysis-input.template.md)
 - [`scripts/okstra_ctl/workflow.py`](../../scripts/okstra_ctl/workflow.py)
-- [`scripts/okstra_ctl/wizard.py`](../../scripts/okstra_ctl/wizard.py)
+- [`scripts/okstra_ctl/wizard/`](../../scripts/okstra_ctl/wizard/)
 - [`prompts/lead/okstra-lead-contract.md`](../../prompts/lead/okstra-lead-contract.md)

package/docs/task-process/final-verification.md

@@ -172,7 +172,7 @@ The stage merge of whole-task mode is a runtime-owned integration step that prep
 
 - [`prompts/profiles/final-verification.md`](../../prompts/profiles/final-verification.md)
 - [`templates/reports/final-verification-input.template.md`](../../templates/reports/final-verification-input.template.md)
-- [`scripts/okstra_ctl/wizard.py`](../../scripts/okstra_ctl/wizard.py)
+- [`scripts/okstra_ctl/wizard/`](../../scripts/okstra_ctl/wizard/)
 - [`scripts/okstra_ctl/run.py`](../../scripts/okstra_ctl/run.py)
 - [`scripts/okstra_ctl/workflow.py`](../../scripts/okstra_ctl/workflow.py)
 - [`scripts/okstra_ctl/render.py`](../../scripts/okstra_ctl/render.py)

package/docs/task-process/implementation.md

@@ -220,7 +220,7 @@ This phase does not declare final acceptance. It says only ready for final-verif
 - [`prompts/profiles/implementation.md`](../../prompts/profiles/implementation.md)
 - [`templates/reports/implementation-input.template.md`](../../templates/reports/implementation-input.template.md)
 - [`scripts/okstra_ctl/run.py`](../../scripts/okstra_ctl/run.py)
-- [`scripts/okstra_ctl/wizard.py`](../../scripts/okstra_ctl/wizard.py)
+- [`scripts/okstra_ctl/wizard/`](../../scripts/okstra_ctl/wizard/)
 - [`validators/validate-implementation-plan-stages.py`](../../validators/validate-implementation-plan-stages.py)
 - [`scripts/okstra_ctl/qa_commands.py`](../../scripts/okstra_ctl/qa_commands.py)
 - [`prompts/lead/okstra-lead-contract.md`](../../prompts/lead/okstra-lead-contract.md)

package/docs/task-process/release-handoff.md

@@ -14,7 +14,7 @@
 
 ## 1. Purpose
 
-`release-handoff` is the terminal phase that pushes an already-committed implementation result with an `accepted` verdict, or hands it off as a PR. whole-task mode packages the verified task branch as-is. stage-group mode can assemble the selected stages into a collector branch and bundle them into a single PR, and the merge commit created here is produced only by `okstra handoff assemble`.
+`release-handoff` is the terminal phase that pushes an already-committed implementation result with a release-ready verdict, or hands it off as a PR. whole-task mode packages the verified task branch as-is. stage-group mode can assemble the selected stages into a collector branch and bundle them into a single PR, and the merge commit created here is produced only by `okstra handoff assemble`.
 
 This phase has no worker dispatch. It does not use a provider or report-writer roster; the host-native Okstra lead performs git/gh inspection, user questions, the PR draft, and the final report inline.
 
@@ -89,13 +89,15 @@ flowchart TD
 Before asking the user whether to push/PR, the lead confirms the following.
 
 - The `## Source Verification Report` of the input document (`release-handoff-input.md`) generated by prepare contains the mode (`HANDOFF_MODE`) and the cited report table. The brief is the input of the entry phase, so it does not exist in release-handoff — the user's stage selection finishes before prepare via the wizard `handoff_stage_pick` or the CLI `--stages`.
-- In whole-task mode, the cited report must be `verificationScope=whole-task` and `Verdict Token = accepted`.
-- In stage-group mode, each cited single-stage report must be `Verdict Token = accepted`, and prepare / `okstra handoff assemble` re-enforce the Stage Lifecycle Snapshot-based eligibility and dependency closure.
+- In whole-task mode, the latest verification execution must have passed validation and carry a release-ready `verificationScope=whole-task` report. A newer unfinished, broken, or blocked execution prevents fallback to an older success. The lead compares the delivery branch tip with the captured verification commit at entry and before push.
+- In stage-group mode, each cited single-stage report must be the latest validated execution for that stage and must match the recorded implementation commit. Prepare and `okstra handoff assemble` re-check this evidence and the dependency closure. A new implementation start or completion invalidates the earlier approval.
 - The working tree is clean.
 - The current branch is not a base branch such as `main`, `master`, `prod`, `preprod`, `staging`, or `dev`.
 - The `<base>..HEAD` commit range is non-empty.
 
-`conditional-accept`, `blocked`, and vague-sentence verdicts are all immediate-termination targets.
+`accepted` is release-ready. `conditional-accept` is release-ready only when its non-empty condition list explicitly sets every `blocksReleaseHandoff` to `false`; those conditions remain in the generated input and PR body. `blocked`, missing conditions, and ambiguous verdicts stop delivery. `okstra_ctl.release_gate.release_handoff_allowed` owns this rule.
+
+Verification targets are preserved per execution under the run's state directory. Old records without provable task/stage/commit evidence require re-verification; they are not rewritten. The checks are enforced by `okstra_ctl.handoff_verification`, `consumers.verified_accepted_stages`, and the handoff regression tests.
 
 ## 5. lead-only execution flow
 
@@ -139,7 +141,7 @@ In stage-group mode, `local checkout` is not offered. After choosing `push + PR`
 ```mermaid
 flowchart TD
     PushPR[push + PR selected] --> Fetch[git fetch origin chosen-base]
-    Fetch --> MergeTree[git merge-tree --write-tree --merge-base<br/>origin/base HEAD origin/base]
+    Fetch --> MergeTree[git merge-tree --write-tree<br/>handoff-branch origin/base]
     MergeTree --> Conflict{conflict?}
     Conflict -->|no| Draft[show PR draft]
     Conflict -->|yes| Ask[ask proceed/change base/cancel]
@@ -214,7 +216,7 @@ A failed `git push` must not be retried with weaker safeguards. When a failure s
 - [`prompts/profiles/release-handoff.md`](../../prompts/profiles/release-handoff.md)
 - [`templates/reports/release-handoff-input.template.md`](../../templates/reports/release-handoff-input.template.md)
 - [`skills/okstra-run/SKILL.md`](../../skills/okstra-run/SKILL.md)
-- [`scripts/okstra_ctl/wizard.py`](../../scripts/okstra_ctl/wizard.py)
+- [`scripts/okstra_ctl/wizard/`](../../scripts/okstra_ctl/wizard/)
 - [`scripts/okstra_ctl/run.py`](../../scripts/okstra_ctl/run.py)
 - [`scripts/okstra_ctl/pr_template.py`](../../scripts/okstra_ctl/pr_template.py)
 - [`src/commands/lifecycle/config.mjs`](../../src/commands/lifecycle/config.mjs)

package/docs/task-process/requirements-discovery.md

@@ -106,7 +106,7 @@ Non-goals are source edit, plan authoring, build, and deployment.
 ## 6. Code reviewed
 
 - [`skills/okstra-run/SKILL.md`](../../skills/okstra-run/SKILL.md)
-- [`scripts/okstra_ctl/wizard.py`](../../scripts/okstra_ctl/wizard.py)
+- [`scripts/okstra_ctl/wizard/`](../../scripts/okstra_ctl/wizard/)
 - [`scripts/okstra_ctl/run.py`](../../scripts/okstra_ctl/run.py)
 - [`scripts/okstra_ctl/workflow.py`](../../scripts/okstra_ctl/workflow.py)
 - [`prompts/profiles/requirements-discovery.md`](../../prompts/profiles/requirements-discovery.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.189.3",
+  "version": "0.190.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.189.3",
-  "builtAt": "2026-09-05T22:53:00.281Z",
+  "package": "0.190.0",
+  "builtAt": "2026-09-08T19:21:43.911Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/workers/claude-worker.md

@@ -88,6 +88,8 @@ After your `Write` to the assigned worker-results file (path provided by Lead as
 3. Do NOT rewrite the worker-results file with `Write` more than once. If a correction is genuinely required, perform a single `Edit` and then return immediately.
 4. The only exception is recording a `tool-failure` with the typed error-log command when a post-Write failure is itself the failure being reported — return immediately after that command.
 
+**Enforced:** `validators/validate-run.py` `validate_team_state` fails a run whose worker carries a terminal status with no saved result file at its assigned Result Path (and no saved prompt history at its assigned prompt path).
+
 If you find yourself thinking "let me double-check section 3" or "I should read one more file to be safer" after the Write succeeded — stop. Convergence (Phase 5.5) and the Report writer worker (Phase 6) will reconcile gaps across all three workers; over-investing in single-worker depth at the expense of returning quickly is a net loss for the run.
 
 ## Error reporting
@@ -122,3 +124,5 @@ When this run's `task_type` is `implementation` and you are acting as the **Exec
 Emit this as a fenced ```json``` block in your worker result under the heading `### Stage Carry Evidence`. The host-native Okstra lead is responsible for persisting the block as `runs/<impl-task-key>/carry/stage-<N>.json` — you do not write the file yourself.
 
 This applies only when `task_type` is `implementation`. For other task types, skip this block entirely.
+
+**Enforced:** `scripts/okstra_ctl/implementation_outcome.py` `_load_carry` / `_carry_passed` read the persisted `carry/stage-<N>.json`; a stage with no carry block never reaches `done`, and `validators/validate_session_conformance.py` `_check_progress_checkpoints` requires the `phase-5-stage-complete` line the lead can only write by parsing this block.

package/runtime/bin/okstra-report-translate.py

@@ -50,7 +50,7 @@ from okstra_ctl.json_boundary import (  # noqa: E402
     load_owned_object_snapshot,
     write_owned_object_atomic,
 )
-from okstra_ctl.fixed_text import line, scalar  # noqa: E402
+from okstra_ctl.fixed_text import block, line  # noqa: E402
 from okstra_ctl.convergence import (  # noqa: E402
     ConvergenceContractError,
     RunArtifactAuthority,
@@ -189,10 +189,16 @@ def cmd_source(args: argparse.Namespace) -> int:
     print(line("Source digest", payload["sourceDataSha256"]), end="")
     print(line("String count", len(strings)), end="")
     for index, source in enumerate(strings.values(), 1):
-        print(f"\n## T-{index:03d}\n{scalar(source)}")
+        print(f"\n## T-{index:03d}\n{block(source)}")
     return 0
 
 
+def _translation_block(rows: list[str]) -> str:
+    # Markdown 의 `\`` 는 백틱 리터럴이고, 이전 `source` 출력이 본문 백틱을 그렇게
+    # 내보냈다. 렌더러는 Markdown 이스케이프를 모르므로 여기서 백틱으로 되돌린다.
+    return "\n".join(rows).strip().replace("\\`", "`")
+
+
 def _translation_blocks(path: Path) -> list[str]:
     text = path.read_text(encoding="utf-8")
     blocks: list[str] = []
@@ -200,7 +206,7 @@ def _translation_blocks(path: Path) -> list[str]:
     for row in text.splitlines():
         if row.startswith("## T-"):
             if current is not None:
-                blocks.append("\n".join(current).strip())
+                blocks.append(_translation_block(current))
             expected = f"## T-{len(blocks) + 1:03d}"
             if row != expected:
                 raise SystemExit(f"error: expected translation heading {expected}")
@@ -208,7 +214,7 @@ def _translation_blocks(path: Path) -> list[str]:
         elif current is not None:
             current.append(row)
     if current is not None:
-        blocks.append("\n".join(current).strip())
+        blocks.append(_translation_block(current))
     return blocks
 
 

package/runtime/prompts/launch.template.md

@@ -7,7 +7,7 @@
 
 **Enforced:** `validators/validate_session_conformance.py` reads the selected adapter's evidence within the run window and reports a missing checkpoint. Missing lines are advisories, not failures — by the time the validator runs the session that would have emitted the line has ended, so the finding records that the run is hard to follow, not that its work is wrong.
 
-Emit one `PROGRESS: <phase-id> <verb-phrase>` line as plain user-facing text at every checkpoint enumerated in the lifecycle core contract (`{{OKSTRA_LEAD_CONTRACT_PATH}}` "Progress reporting (BLOCKING)") — phase-1-intake start/complete, phase-2-prompts, phase-3-team-create, phase-4-dispatch (per worker), phase-5-collect (per worker), phase-5.5-convergence (per round), phase-6-synthesis, phase-7-persist, and final `complete`. One line per checkpoint, never batched, never replaced with prose. This is the only signal the user has during multi-minute silent windows.
+Emit one `PROGRESS: <phase-id> <verb-phrase>` line as plain user-facing text at every checkpoint enumerated in the lifecycle core contract (`{{OKSTRA_LEAD_CONTRACT_PATH}}` "Progress reporting (BLOCKING)") — phase-1-intake start/complete, phase-2-prompts, phase-3-team-create, phase-4-dispatch (per worker), phase-5-collect (per worker), phase-5.5-convergence (per round), phase-6-synthesis, phase-7-persist, and final `complete`. One line per checkpoint, never batched, never replaced with prose. This is the only signal the user has during multi-minute silent windows. Record each one with `okstra lead-progress append --project-root <dir> --run-manifest <path> --phase <phase-id>` and emit the `progressLine` it prints — that call is what puts the checkpoint where the validator reads it.
 
 When the run manifest declares `activityContractVersion: 1`, call `okstra agent-activity append` before each required activity boundary. Only after the structured append succeeds, emit the matching `PROGRESS:` line and the immediately following `ACTIVITY:` projection from the same fields. If the structured append fails, do not mark that boundary completed. Never reconstruct structured activity by parsing `ACTIVITY:` conversation text.
 
@@ -60,6 +60,10 @@ For every other task type:
 - Phase 7 `validate-run` failed → one line naming the blocking cause, then `/okstra-run` to re-run this phase. Only a failure matching the blocking allowlist (`okstra_ctl.blocking_checks`) reaches this row; every other finding was demoted to an advisory, printed as `validate-run: advisory — <finding>`, and the run passed. Name those advisories in one line and take the command from the matching pointer row above — an advisory is not a reason to re-run.
 - Otherwise → `/okstra-inspect status` for this task.
 
+Name every file in this reply as a markdown link — `[<what it is>](<path>)`, path inside the parentheses — so the user can open it. `reportPaths.markdown` in the `report-finalize` result already carries this run's report, report record, and team state that way. Commands stay in backticks.
+
+**Enforced:** `scripts/okstra_ctl/report_finalize.py` `closeout_command` applies this table to the run and returns the selected row as the result's `nextCommand`; the close is read from that value, not re-derived.
+
 Do not end the turn after the validator result. Task-qualified report paths and the same table live in the lifecycle core contract (`{{OKSTRA_LEAD_CONTRACT_PATH}}` "After persistence").
 
 {{TEAM_CREATION_GATE}}
@@ -106,7 +110,7 @@ Do not end the turn after the validator result. Task-qualified report paths and
 - Branch: `{{EXECUTOR_WORKTREE_BRANCH}}`
 - Base ref: `{{EXECUTOR_WORKTREE_BASE_REF}}`
 - Note: `{{EXECUTOR_WORKTREE_NOTE}}`
-- For any task-type with status `created` or `reused`, every role (lead, executor, verifier) MUST anchor reads and writes to the working tree path above — phase N inherits the working-tree state phase N-1 left behind. Verifiers read from the SAME path so they observe the exact diff produced by the Executor.
+- For any task-type with status `created` or `reused`, every role (lead, executor, verifier) MUST anchor reads and writes to the working tree path above — phase N inherits the working-tree state phase N-1 left behind. Verifiers read from the SAME path so they observe the exact diff produced by the Executor. Workers receive this path as the `**Worktree:**` anchor their own prompt carries; you do not restate it in a dispatch instruction, and you do not stop a dispatch over a prompt that lacks it. **Enforced:** `okstra_ctl.initial_prompt_materialization._worktree_anchor_lines` renders that anchor into every initial worker prompt whose run has a provisioned worktree, and `_anchor_predates_this_contract` republishes an older prompt that predates it the next time the run is dispatched.
 - Branch and path are globally reserved per task-key via `~/.okstra/worktrees/registry.json`; concurrent okstra runs on this machine cannot collide.
 - The worktree is preserved after every run (no automatic cleanup) and is reused by every subsequent phase of the same task-key. Manual cleanup when fully done: `git worktree remove <path>` → `git branch -D <branch>` + remove the task-key entry from the registry.
 - For status `skipped-in-worktree` or `skipped-not-git`, the run operates directly in `{{PROJECT_ROOT}}` and this section is informational only.
@@ -137,7 +141,7 @@ Do not end the turn after the validator result. Task-qualified report paths and
 
 ### Incremental re-verification (implementation-planning clarification re-runs only)
 
-The **default is full re-verification**. Narrow this re-run to the impacted stages only when the deterministic `okstra incremental-scope` CLI returns `mode == "incremental"`. When the wizard pin is `auto` and the CLI returns `mode == "incremental"`, do not upgrade to full — the CLI already applied the base-ref check, the dependency closure, and the cutoff. This procedure fires ONLY when this run's task-type is `implementation-planning` AND a prior final report exists for this task-key (its data.json at `runs/implementation-planning/reports/final-report-implementation-planning-<prev-seq>.data.json`, where `<prev-seq>` is the most recent prior implementation-planning run's seq). For every other task-type, ignore this block and re-verify normally. This branches on the CLI's `mode` output only — it does NOT re-implement the safety logic in the prompt.
+The **default is full re-verification**. Narrow this re-run to the impacted stages only when the deterministic `okstra incremental-scope` CLI returns `mode == "incremental"`. When the wizard pin is `auto` and the CLI returns `mode == "incremental"`, do not upgrade to full — the CLI already applied the base-ref check, the dependency closure, and the cutoff. This procedure fires ONLY when this run's task-type is `implementation-planning` AND a prior final report exists for this task-key (its data.json at `{{RUN_REPORTS_RELATIVE_PATH}}/final-report-implementation-planning-<prev-seq>.data.json`, where `<prev-seq>` is the most recent prior implementation-planning run's seq). For every other task-type, ignore this block and re-verify normally. This branches on the CLI's `mode` output only — it does NOT re-implement the safety logic in the prompt.
 
 0. **Honour the scope the user already pinned (not a judgement — an instruction).** The wizard asks for a re-verification scope whenever this re-run is narrowable or an answered id traces to no stage, and the answer arrives as two tokens: mode `{{REVERIFY_SCOPE_MODE}}`, stages `{{REVERIFY_SCOPE_STAGES}}`. Apply it before you form your own view:
    - `auto` — the user left the decision to this procedure. Run steps 1–7 exactly as written; nothing is pinned. If the CLI returns `mode == "incremental"`, keep it; do not upgrade to full.
@@ -154,7 +158,7 @@ The **default is full re-verification**. Narrow this re-run to the impacted stag
 3. **Call the CLI** (it is pure — same inputs always yield the same decision):
    ```
    okstra incremental-scope \
-     --prev-data runs/implementation-planning/reports/final-report-implementation-planning-<prev-seq>.data.json \
+     --prev-data {{RUN_REPORTS_RELATIVE_PATH}}/final-report-implementation-planning-<prev-seq>.data.json \
      --run-manifest {{RUN_MANIFEST_RELATIVE_PATH}} \
      --cur-base-sha {{EXECUTOR_WORKTREE_BASE_REF}} \
      --prev-base-sha <prior baseRef from step 2> \
@@ -170,7 +174,7 @@ The **default is full re-verification**. Narrow this re-run to the impacted stag
 7. **Merge carried-forward verdicts.** In `incremental` mode the report writer receives the carried stage rows as a packet source and is told, in its own authoring contract, to copy them unchanged — you do not repeat that instruction to it. After `okstra plan-items seed --narrative ... --state ...`, the lead runs:
    ```
    okstra incremental-carry \
-     --prev-data runs/implementation-planning/reports/final-report-implementation-planning-<prev-seq>.data.json \
+     --prev-data {{RUN_REPORTS_RELATIVE_PATH}}/final-report-implementation-planning-<prev-seq>.data.json \
      --cur-narrative <this run's report-writer narrative> \
      --state <this run's plan-body-verification state> \
      --prev-seq <prev-seq> \
@@ -180,3 +184,5 @@ The **default is full re-verification**. Narrow this re-run to the impacted stag
    A non-zero exit means the writer changed or omitted a carried stage, the item set drifted, or the stage scopes conflict. Fall back to **full** and re-verify every stage. The command writes only the convergence-owned plan state. It never patches the writer narrative or final `data.json`. `verdictCard` / `finalVerdict` are never carried.
 
    **Carry completeness (BLOCKING).** In incremental mode, this run's `planItems` MUST contain every plan-item id from the re-verified stages, each carried forward with its updated verdict. If re-verification concludes a plan item should be REMOVED, that is a signal the answer's blast radius is NOT local — abandon incremental and re-route to a FULL re-verification. The carry merge only ever ADDS prior items whose id is absent from this run; it cannot distinguish a legitimate deletion from an untouched carry, so it would resurrect a stale verdict.
+
+   **Enforced:** `scripts/okstra_ctl/incremental_carry.py` `_merge_stage_aware` performs the carry and exits non-zero when a re-verified stage's item set drifted from the prior run's `planItems`.

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

@@ -14,7 +14,7 @@ It overrides only the worker-dispatch portion of the selected host relay, not th
 | `leadRoleLabel` | `Okstra lead` |
 | `userPromptMode` | `host-text` |
 | `workerDispatchBackend` | `cmux-pane` |
-| `initialPromptDeliveryMode` | `lazy-path-reference` |
+| `initialPromptDeliveryMode` | `eager-include` |
 | `sessionAccounting` | unchanged — keep your own runtime's accounting |
 | `resumeMode` | `artifact-checkpoint` |
 | `teardownMode` | `pane-teardown` |
@@ -31,7 +31,7 @@ It overrides only the worker-dispatch portion of the selected host relay, not th
 | `await_workers` | Run `okstra team await --project-root <root> --run-manifest <path>` through the host's asynchronous shell facility. |
 | `redispatch_worker` | Create the core-specified fresh jobs file and dispatch it with a new `dispatchKind`; never reuse a live worker conversation. |
 | `shutdown_workers` | Run `okstra team teardown --project-root <root> --run-manifest <path>` only after the user-approved cleanup gate. |
-| `record_lead_event` | Append progress and activity records to the manifest-provided `leadEventsPath`. Emit the matching `PROGRESS:` line and, when an activity record is required, the immediately following `ACTIVITY:` line from the same structured fields. |
+| `record_lead_event` | Append progress and activity records to the manifest-provided `leadEventsPath`. Use `okstra lead-progress append --phase <phase-id>` for a checkpoint and `okstra agent-activity append --kind <kind>` for an activity record; both resolve the ledger path from the run manifest. Emit the matching `PROGRESS:` line — the command prints it as `progressLine` — and, when an activity record is required, the immediately following `ACTIVITY:` line from the same structured fields. |
 | `collect_usage` | Collect artifact/CLI-log-backed usage through the existing Okstra token-usage path; never substitute another runtime's session log. |
 
 An `implementation` run calls `dispatch_worker` twice: once for the Executor, then — after `await_workers` settles it — once for the verifiers. That second call's `--workers` list must omit the Executor's worker ID: it is materialized as the Executor on every dispatch, so a batch still carrying it is refused again. A verifier started beside the Executor observes base HEAD instead of the stage diff, so a single batch holding both is refused by `scripts/okstra_ctl/dispatch_core.py` `_validate_implementation_phase_order`, `--dry-run` included.
@@ -59,10 +59,7 @@ Use the screen to tell "still working" from "stuck", and to see at a glance whic
 - Worker completion is valid only from `workerDispatches[]`, terminal status sidecars, and required Result Paths. Pane creation alone is not completion.
 - Reverify uses a fresh jobs file at `runs/<task-type>/state/reverify-jobs-r<N>-<task-type>-<seq>.json`, sets `dispatchKind: "reverify-r<N>"`, and dispatches with `okstra team dispatch --project-root <root> --run-manifest <path> --dispatch-kind reverify-r<N> --jobs-file <jobs-file>`.
 - Report-writer uses a fresh one-job jobs file with `dispatchKind: "report-writer"` and the same schema, then dispatches through `okstra team dispatch --project-root <root> --run-manifest <path> --jobs-file <jobs-file>`.
-- A jobs file is `{"dispatchKind": "<kind>", "workers": [ … ]}` — the array key is `workers`, not `jobs`. Each entry follows the run manifest's identity version, and `scripts/okstra_ctl/dispatch_state.py` `worker_execution_identity` is the contract:
-  - **v2 entry** (`schemaVersion: "2.0"`, `executionIdentityVersion: 2`): carries `participantRef`, `roleExecutionRef`, `assignmentRef`, `executionLabel`, `dutyId`, `invocationRef`, a positive integer `attempt`, `provider`, `modelExecutionValue`, `role`, `promptPath`, `workerResultPath`, `invocationId`, `audience`, `promptMetadataPath`, `enforcementMode: "core-pre-dispatch"`, and a `digests` object holding `catalogDigest`, `assignmentDigest`, `dutyDigest`, `instructionDigest`, and `promptDigest`. Copy every identity, assignment and digest value from the prompt's `.meta.json` that the prompt materialization step wrote: its `roleExecutionRef` is the dispatched role's own execution (a reverify's `role-exec-verifier-<N>`), not the analyser's `sourceRoleExecutionRef` from the round plan. **Do not include `workerId`** — a v2 entry that carries it is refused as mixing v1 and v2 identity; the worker key is projected from `assignmentRef`. A missing required field is reported together with every other missing field of that entry (`_missing_required_strings` in `scripts/okstra_ctl/dispatch_state.py`).
-  - **v1 entry**: carries `workerId`, `provider`, `modelExecutionValue`, `role`, `promptPath`, and `workerResultPath`, and must carry none of the v2 identity fields.
-  - `resultPath` and `completionPaths` are advisory in both: dispatch derives them from the same rules the roster path uses, so a jobs file cannot disagree with a roster dispatch about which artifact is the result.
+- Generate v2 jobs files with `okstra agent-prompt jobs --project-root <root> --run-manifest <path> --dispatch-kind <kind> --metadata <prompt-meta.json> [--metadata <prompt-meta.json>] --out <jobs-file>`. Pass only the metadata paths for the core-planned batch. The command derives the `workers` array, canonical role execution, result headers, and five digests, and verifies them through the same consumer used at dispatch. Do not transcribe those fields. Identical output is reused; differing output is preserved and requires a new `--out` path. Existing v1 files remain readable by dispatch.
 - `workerResultPath` is the path the prompt tells the worker to write: the prompt's `**Result Path:**`, or `**Worker Result Path:**` for the report writer. `okstra team dispatch` refuses an entry whose value differs from that anchor, because the collector waits on `workerResultPath` while the worker writes where the anchor says. A reverify result is named `<worker-id>-worker-reverify-r<N>-<task-type>-<seq>.md`: the `-worker-` token is what the audit sidecar name inserts `-audit-` after (a name without it is refused with `worker result path has no canonical -worker- token`), and the round label is what keeps one round's file apart from the next. The report writer's `workerResultPath` is the roster's `resultPath` for `report-writer` and its `**Result Path:**` is the run manifest's `reportNarrativePath` — the report-writer materialization ([report-writer](../report-writer.md)) refuses any other pair. **Enforced:** `_validate_jobs_file_prompt_anchors` in `scripts/okstra_ctl/dispatch_state.py`, `_validate_report_writer_paths` in `scripts/okstra_ctl/agent/prompt_cli/materialize.py`.
 - `role` names the role execution's own role — `verifier` for reverify, `report-writer` for the report writer. It is not a per-round label: `dispatch_state.py` requires the entry's `role` to equal both the role execution's `role` and the duty's role, so a value like `worker-reverify-r<N>` is refused as `jobs file v2 identity does not match role execution authority`. The round lives in `dispatchKind` and in `invocationRef`. The report-writer completion paths include its narrative Markdown, worker-result pointer, and audit sidecar; they do not include the Phase 7 report record.
 - After either dispatch, run `okstra team await --project-root <root> --run-manifest <path>` before evaluating terminal status or completion paths.
@@ -70,5 +67,5 @@ Use the screen to tell "still working" from "stuck", and to see at a glance whic
 ## Completion, cleanup, and resume
 
 - Await through `okstra team await`; raw Result Path polling is forbidden for this backend.
-- Reclaim each round's panes at the round boundary through `okstra team teardown`, before the next round's dispatch. Finished workers leave their panes behind on purpose — the screen survives the process so you can still read a failure — so an unreclaimed round keeps shrinking the space the next one gets.
+- Reclaim terminal panes after each batch through `okstra team reclaim --project-root <root> --run-manifest <path>` before dispatching the next batch. Reserve `teardown` for run completion.
 - Resume from run artifacts and lead-events checkpoints. After usage collection, persistence, and the core user-approval gate, run `okstra team teardown --project-root <root> --run-manifest <path>` and tear down only Okstra-owned panes recorded for the run.

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

@@ -37,6 +37,8 @@ After reading `task-brief.md`, extract the frontmatter `reporter-confirmations`
 
 On `pending`, emit `REPORTER_CONFIRMATION_PENDING` and stop. Do not invoke `team-contract` or an analyser, and do not write a final report. Regenerate the brief with `okstra-brief-gen` Step 6.5 and prepare a fresh run. A missing field is a legacy brief and proceeds with the matrix's carried flags. Current-format invalid values are rejected during preparation.
 
+**Enforced:** `scripts/okstra_ctl/render.py` `_reporter_confirmation_status` reads the field at prepare time and carries the status into the rendered launch prompt; `validators/validate-brief.py` rejects an invalid value.
+
 ## Step 3: Use Run Input as the Run-State View
 
 Run Input is the only Phase 1 source for task identity, work category, workflow state, selected workers, model assignments, worker prompt paths, result paths, validator path, resume command, and configuration references.