okstra 0.174.0 → 0.176.0

package/runtime/skills/okstra-inspect/facets/status.md

@@ -18,8 +18,7 @@ Read `.okstra/discovery/task-catalog.json`. The catalog is the authoritative sou
 | `currentStatus` | task-level status |
 | `currentPhase` | lifecycle current phase |
 | `currentPhaseState` | lifecycle phase state |
-| `nextRecommendedPhase` | next recommended phase |
-| `routingStatus` | routing decision status |
+| `nextRecommendedPhase` | next-phase pointer — an **object** `{phase, status, rationale}`, never a string. `status` is `ready` / `pending` / `blocked` / `terminal`. The lead writes `phase` only under `ready`, but that is an authoring rule, not a constraint the struct enforces — `prepare` lowers a `ready` pointer to `pending` and keeps its `phase`, so a non-`ready` pointer that still names a phase is a normal state to read. Decide launchability from `status` alone. Render `phase` (or `--` when it is empty) — never the object itself. |
 | `awaitingApproval` | whether awaiting approval |
 | `latestRunStatus` | latest run status |
 | `latestReportPath` | latest report path |
@@ -29,9 +28,9 @@ Read `.okstra/discovery/task-catalog.json`. The catalog is the authoritative sou
 
 Sort by `updatedAt` desc, then `taskKey`.
 
-The overview table is intentionally narrow so it renders cleanly in a terminal. Only six columns are shown; for any task that needs a closer look (phase state, routing, approval gate, last run status, resume path, etc.) tell the user to run `/okstra-inspect status <task-key>` for the detail view in `status.2`.
+The overview table is intentionally narrow so it renders cleanly in a terminal. Only six columns are shown; for any task that needs a closer look (phase state, the pointer's status and rationale, approval gate, last run status, resume path, etc.) tell the user to run `/okstra-inspect status <task-key>` for the detail view in `status.2`.
 
-If `awaitingApproval` is true OR `routingStatus == "pending"`, append a `*` to the `Next` cell and explain the marker once below the table.
+The `Next` cell is `nextRecommendedPhase.phase`, or `--` when that string is empty. If `awaitingApproval` is true OR `nextRecommendedPhase.status` is anything other than `ready`, append a `*` to the cell and explain the marker once below the table — an unset or non-`ready` pointer means no next run is launchable yet.
 
 ```markdown
 ## okstra Status — <project-id>
@@ -39,9 +38,9 @@ If `awaitingApproval` is true OR `routingStatus == "pending"`, append a `*` to t
 | # | Task Key | Category | Phase | workStatus | Next |
 |---|----------|----------|-------|------------|------|
 | 1 | proj:group:id | bugfix | error-analysis | in-progress | implementation-planning |
-| 2 | proj:group:id2 | feature | requirements-discovery | done | pending-routing-decision* |
+| 2 | proj:group:id2 | feature | requirements-discovery | done | --* |
 
-`*` = awaiting user approval or pending routing decision. Run `/okstra-inspect status <task-key>` for details.
+`*` = awaiting user approval, or the next-phase pointer is not `ready`. Run `/okstra-inspect status <task-key>` for details.
 ```
 
 ### status.2 — Specific task status
@@ -52,7 +51,9 @@ Given a specific `task-key` or `task-group + task-id`:
 2. If necessary, read `.okstra/tasks/<task-group>/<task-id>/task-manifest.json` directly.
 3. If you need the latest run information, read `history/timeline.json` along with the latest run manifest.
 
-Required fields: `taskKey`, `taskType`, `workCategory`, `currentStatus`, `latestRunStatus`, `workflow.{currentPhase, currentPhaseState, phaseStates, lastCompletedPhase, nextRecommendedPhase, awaitingApproval, routingStatus, lastSafeCheckpoint}`, `workStatus`, `workStatusUpdatedAt`, `workStatusNote`, `latestReportPath`, `latestResumeCommandPath`, `historyTimelinePath`.
+Required fields: `taskKey`, `taskType`, `workCategory`, `currentStatus`, `latestRunStatus`, `workflow.{currentPhase, currentPhaseState, phaseStates, lastCompletedPhase, nextRecommendedPhase, awaitingApproval, lastSafeCheckpoint}`, `workStatus`, `workStatusUpdatedAt`, `workStatusNote`, `latestReportPath`, `latestResumeCommandPath`, `historyTimelinePath`.
+
+`workflow.nextRecommendedPhase` is the `{phase, status, rationale}` object described in `status.1` — read its three fields, do not print it whole. A `task-manifest.json` written before the object existed still holds a bare string there; `scripts/okstra_ctl/next_phase.py::promote` is what turns that string into the object, and every CLI-projected surface you can read instead (`task-catalog.json`, `okstra rollup`, `okstra recap`) has already applied it. Prefer those over a raw manifest rather than promoting a legacy string yourself.
 
 ```markdown
 ## okstra Task Status — <task-key>
@@ -61,9 +62,8 @@ Required fields: `taskKey`, `taskType`, `workCategory`, `currentStatus`, `latest
 - Current phase: `<phase>`
 - Current phase state: `<phase-state>`
 - Last completed phase: `<phase-or-->`
-- Next recommended phase: `<phase>`
+- Next phase pointer: `<phase-or-->` (`<status>`) — `<rationale-or-->`
 - Awaiting approval: `<yes|no>`
-- Routing status: `<routing-status>`
 - Task status: `<task-status>`
 - Latest run status: `<run-status>`
 - Latest report: `<relative-path-or-->`
@@ -95,9 +95,11 @@ The status response always includes one of:
 
 1. **Resume current run** — if `latestResumeCommandPath` exists, display that path.
 2. **Restart current phase** — task can be re-run with the same `task-key` and current `taskType`.
-3. **Start next phase** — if `workflow.nextRecommendedPhase` is one of `error-analysis`, `implementation-planning`, `implementation`, `final-verification`, `release-handoff`, that phase is proposed. If `nextRecommendedPhase` is `pending-release-handoff`, surface as verdict-gated and propose `release-handoff` only when the cited verdict is `accepted`.
-4. **Need more information** — if `nextRecommendedPhase` is `pending-routing-decision` or `routingStatus` is `pending`.
-5. **Task complete (terminal)** — if `nextRecommendedPhase` is `done-or-follow-up`, the task lifecycle has reached its terminal signal. This is **not** a "next phase" — do not propose a new okstra run. Surface the latest report and ask the user whether any follow-up task should be opened separately.
+Branches 3–5 are decided by `workflow.nextRecommendedPhase.status` alone — one status, one branch, no other field consulted:
+
+3. **Start next phase** — `status` is `ready`. Propose `nextRecommendedPhase.phase` as the next run's `--task-type` and quote its `rationale` as the reason. This is the only status under which a named phase may be launched, so it is the only branch that proposes a run. A `ready` pointer to `release-handoff` already implies an `accepted` final-verification verdict (the report validator refuses that routing target otherwise), so do not re-gate it here.
+4. **Need more information** — `status` is `pending` (the last run did not settle where this task goes next) or `blocked` (it did settle, and the answer is that something outside the run has to change first). Neither proposes a run, and a leftover `phase` name does not change that — `prepare` keeps the name when it lowers a pointer to `pending`, so read `status`, not the emptiness of `phase`. Show the `rationale`, and for `blocked` state what it names as the obstacle. The way forward is a fresh brief, a clarification response, or a re-run of the current phase — not a next-phase launch.
+5. **Task complete (terminal)** — `status` is `terminal`: the task lifecycle ends here. This is **not** a "next phase" — do not propose a new okstra run. Surface the latest report and ask the user whether any follow-up task should be opened separately.
 
 ### status.4 — Update workStatus (write)
 
@@ -135,7 +137,7 @@ Confirm in Korean (the block below shows the message shape only — render the a
 
 | Manifest state | Inferred display |
 |---|---|
-| `currentStatus == "completed"` AND `workflow.nextRecommendedPhase == "done-or-follow-up"` | `done` (inferred) |
+| `currentStatus == "completed"` AND `workflow.nextRecommendedPhase.status == "terminal"` | `done` (inferred) |
 | `currentStatus == "completed"` AND `workflow.currentPhaseState == "completed"` | `phase-done` (inferred) |
 | `currentStatus == "contract-violated"` OR `workflow.currentPhaseState == "blocked"` | `blocked` (inferred) |
 | anything else | `in-progress` (default) |

package/runtime/skills/okstra-rollup/SKILL.md

@@ -42,6 +42,7 @@ Omit `--task-group` for the whole project. The JSON shape (all durations are **r
 
 - `taskGroup` — the scope (`null` = whole project), `taskCount` — number of tasks.
 - `tasks[]` — per task: `taskKey, taskGroup, taskId, taskType, workCategory, workStatus, currentPhase, currentPhaseState, nextRecommendedPhase, latestRunStatus, updatedAt, reportPath, runCount, cpuSumMs, wallClockMs, errorCount`, plus `criticRuns, criticGapsProposed, criticGapsMerged, criticGapsRejected, criticGapsUnverified`.
+  - `nextRecommendedPhase` is an **object** `{phase, status, rationale}`, not a phase-name string. Anywhere you surface it, print `nextRecommendedPhase.phase` — or `--` when that string is empty, which is what `status` `pending` / `blocked` / `terminal` all produce. Never interpolate the object into a table cell or a sentence: it renders as a raw dict.
 - `totals` — `runs, cpuSumMs, wallClockMs, errors`, plus `byWorkStatus`, `byWorkCategory`, `byCurrentPhase`, `byTaskType` (each a `{value: count}` map), plus `critic` (`runsWithCritic, gapsProposed, gapsMerged, gapsRejected, gapsUnverified`).
 - The coverage critic is opt-in, so `totals.critic.runsWithCritic == 0` means it was never used — report that as "not used", never as a zero-yield result. When it IS non-zero, the merge rate (`gapsMerged / gapsProposed`) is what tells the user whether the pass earns its tokens; state it only when at least one run used it.
 

package/runtime/skills/okstra-run/SKILL.md

@@ -32,7 +32,7 @@ Every wizard call returns JSON. The two shapes you'll see:
             "progress": { "index": 5, "total": 11, "remaining": 6 } } }
 ```
 
-Every non-terminal `next` carries a `progress` object (`done` / `aborted` omit it). It holds `index` (1-based number of the **current screen**; pick_group counts as one screen), `total` (the wizard's forward estimate of the full screen count — may grow by a few when the user opens a branch, e.g. choosing *Customize* adds the model screen), `remaining` (`total − index`), and **`label`** — the ready-to-render marker the wizard already composed (e.g. `Step 10/11 · 1 step remaining`, or `Step 11/11 · final step` on the final screen). **Always suffix the rendered prompt with `progress.label` verbatim** — see Step 3. Do not recompute the marker or decide "final step" yourself; only the wizard knows whether more screens follow.
+Every non-terminal `next` carries a `progress` object (`done` / `aborted` omit it). It holds `index` (1-based number of the **current screen**; pick_group counts as one screen), `total` (the wizard's forward estimate of the full screen count — may grow by a few when the user opens a branch, e.g. role-add or extra role-model slots), `remaining` (`total − index`), and **`label`** — the ready-to-render marker the wizard already composed (e.g. `Step 10/11 · 1 step remaining`, or `Step 11/11 · final step` on the final screen). **Always suffix the rendered prompt with `progress.label` verbatim** — see Step 3. Do not recompute the marker or decide "final step" yourself; only the wizard knows whether more screens follow.
 
 ```json
 { "ok": false, "error": "approved plan has no APPROVED marker: ...",
@@ -179,14 +179,14 @@ Repeat until `next.kind == "done"` (or `"aborted"` — terminal cancel, see "How
 That is the entire interactive flow. The wizard handles:
 
 - new-vs-existing task split (remaining work — `workStatus != done` — top-3 newest recommendations + Enter directly), task-group / task-id slug validation (task-group offers the top-3 newest candidates combining recent task use + recent `.okstra/briefs/<group>/` creation activity + Enter directly; task-id offers the top-3 recent candidates from the same group + Enter directly),
-- task-type pick (3 recommendations — `nextRecommendedPhase` recommended / re-run the current phase / the lifecycle's next step — + Enter directly; Enter directly is validated against the full task-type whitelist in a follow-up `text` step),
+- task-type pick (3 options + Enter directly; Enter directly is validated against the full task-type whitelist in a follow-up `text` step). What fills those three depends on `workflow.nextRecommendedPhase` — an object `{phase, status, rationale}`, not a phase-name string. `status: ready` gives the classic trio: its `phase` marked recommended, re-run the current phase, the lifecycle's next step. Any other status contributes nothing at all, since both the recommended slot and the next-step slot derive from that phase — re-run the current phase becomes the first option and the remaining slots fill unlabelled from recently used task-types and then the whitelist. Never recover a phase name from a non-`ready` pointer and propose it yourself: prepare deliberately lowers the pointer to `pending` while its run is unfinished, and the missing recommendation is that signal,
 - brief path — **asked only for entry task-types (requirements-discovery / error-analysis / improvement-discovery / project-analysis / feature-analysis / change-impact-analysis)** (same-group `.okstra/briefs/<task-group>/**/*.md` candidates first, sorted by the newer of file-created/modified time and latest task-catalog use; direct input last; `Keep / Change` for existing entry tasks). `project-analysis`, `feature-analysis`, and `change-impact-analysis` are brief entry task types. A downstream lifecycle task-type auto carries in the manifest's brief, and when no registered brief exists a `brief_carry` 3-option prompt appears (recommend switching to entry / Enter directly / Abort). `release-handoff` has no brief step at all — prepare generates the input document that cites the verification report,
 - analysis-input sub-flow — `project-analysis` has no target or evidence step. `feature-analysis` runs `project_evidence_pick` / `project_evidence`, then `analysis_target_pick` / `analysis_target`; the target is required even when the user skips project evidence. `change-impact-analysis` runs `feature_evidence_pick` / `feature_evidence`, then `project_evidence_pick` / `project_evidence`. The evidence steps show accepted compatible reports first and retain direct-path entry; do not invent a different relation or reorder these steps,
 - base-ref pick + git rev-parse validation (skipped when reusing an active worktree),
-- `implementation`-only sub-flow: approved-plan path (frontmatter `approved: true` check) + stage pick (`auto` = the earliest incomplete stage whose dependencies are satisfied, or a specific stage number) + executor pick. When an approved plan is selected and a `## PLAN DECISION` sidecar carrying `Status: approved`, exported from the report — matching the plan on source-report·seq — is detected in that run's sibling `user-responses/`, the approve-confirm step expands to 3 options (`yes_apply` recommended: approve + apply the option as exported / `yes` approve only / `no` abort) — `yes_apply` validates the option against the plan's `optionCandidates` before applying it via the existing approval·option path,
+- `implementation`-only sub-flow: approved-plan path (frontmatter `approved: true` check) + stage pick (`auto` = the earliest incomplete stage whose dependencies are satisfied, or a specific stage number). Implementer slots use role-count / role-model like every other role (`executor` is only a compatibility alias for `implementer`). When an approved plan is selected and a `## PLAN DECISION` sidecar carrying `Status: approved`, exported from the report — matching the plan on source-report·seq — is detected in that run's sibling `user-responses/`, the approve-confirm step expands to 3 options (`yes_apply` recommended: approve + apply the option as exported / `yes` approve only / `no` abort) — `yes_apply` validates the option against the plan's `optionCandidates` before applying it via the existing approval·option path,
 - `release-handoff`-only sub-flow: after the approved plan auto-resolves, a `handoff_stage_pick` multi-select — choose an eligible stage bundle (stage-group) or the whole task (when an accepted whole-task verification report exists); the result goes out as render-args' `stages` key (csv, empty when whole-task),
-- `Use defaults / Customize` branch with profile-aware worker/model questions,
-- **resume-clarification (in-session equivalent)** — there is no separate mode or flag matching the shell's `okstra.sh --resume-clarification`; two steps of the standard flow carry out its substance. (1) `reuse_previous` (yes/no to reuse the previous run's settings — in `requirements-discovery` / `error-analysis` / `implementation-planning`, only when prior run-inputs exist): YES prefills workers·model·directive·related-tasks at once. (2) `clarification_pick`: if the **task-type's own** previous `final-report` exists it is auto-recommended as the carry-in input (falling back to the newest by mtime across all phases when absent), and the same run's `user-responses/` sidecar (answers the user filled in) is attached alongside. The chosen path is passed to prepare as `--clarification-response` — the user makes the sidecar via the report's `Export user response`, places it in `runs/<task-type>/user-responses/`, and re-runs the same phase,
+- launch selection after identity/worktree steps: leader session read-only (current-session) → role-count per static role (`min..max`, omit uses **recommended**, skip when `min == max`) → role-model `provider/model` per slot → min=0 roles only via role-add (default skip). The wizard does not fork on defaults-vs-customize, does not show a provider roster multi-pick, and does not offer a separate implementer-provider pick. Dynamic verifiers are not chosen at launch. `--workers` is compatibility-only, not a launch picker. Repeated `--role-count` / `--role-model` tokens on `renderArgv` are intentional,
+- **resume-clarification (in-session equivalent)** — there is no separate mode or flag matching the shell's `okstra.sh --resume-clarification`; two steps of the standard flow carry out its substance. (1) `reuse_previous` (yes/no to reuse the previous run's settings — in `requirements-discovery` / `error-analysis` / `implementation-planning`, only when prior run-inputs exist): YES prefills role-count·role-model·directive·related-tasks at once. (2) `clarification_pick`: if the **task-type's own** previous `final-report` exists it is auto-recommended as the carry-in input (falling back to the newest by mtime across all phases when absent), and the same run's `user-responses/` sidecar (answers the user filled in) is attached alongside. The chosen path is passed to prepare as `--clarification-response` — the user makes the sidecar via the report's `Export user response`, places it in `runs/<task-type>/user-responses/`, and re-runs the same phase,
 - **re-verification scope (`reverify_scope_pick`, `implementation-planning` clarification re-runs only)** — asked right before `confirm`, and **only when the re-run is narrowable** (every answered `C-NNN` traces back to a stage in the prior report). 3 options: `auto` (recommended — leave it to the lead's `okstra incremental-scope` decision) / `full` (re-verify every stage) / Enter directly (a stage-number CSV, validated against the prior report's Stage Map). The answer goes out as `--reverify-scope` and reaches the lead prompt as the `REVERIFY_SCOPE_MODE` / `REVERIFY_SCOPE_STAGES` tokens; it shapes that CLI's inputs rather than replacing the decision. When the re-run is not narrowable the step does not appear — full is already fixed, and the confirmation block's `reverify-scope` line says which answered id broke the link,
 - `release-handoff` PR template override + persist scope,
 - final `Proceed / Edit` confirmation; on `Edit` the wizard asks which step to rewind to and clears every later answer.
@@ -220,9 +220,9 @@ When `next.kind == "done"`, fetch the public wizard outcome:
 okstra wizard outcome --state-file /var/folders/.../okstra-wizard.AbCd.json
 ```
 
-Output: `{ok: true, outcome: {renderArgs: {...}, orchestration: {chainStages: "..."}, persistActions: [...], confirmationText: "..."}}`.
+Output: `{ok: true, outcome: {renderArgv: ["--lead-runtime", "...", ...], renderArgs: {...}, orchestration: {chainStages: "..."}, persistActions: [...], confirmationText: "..."}}`.
 
-`renderArgs` holds only flags `okstra render-bundle` accepts, which is what makes the pass-everything rule below safe. `orchestration` holds signals this skill acts on itself — never pass its entries to `render-bundle`.
+`renderArgv` is the canonical ordered `okstra render-bundle` argument list. Pass its tokens verbatim and in order. Repeated `--role-count` and `--role-model` flags are intentional. `renderArgs` is a compatibility and inspection view only; do not reconstruct an invocation from it. `orchestration` holds signals this skill acts on itself — never pass its entries to `render-bundle`.
 
 Run every `outcome.persistActions[]` entry BEFORE `render-bundle`. The only supported action is:
 
@@ -243,19 +243,19 @@ Before rendering the next phase's bundle — and between worker rounds within a
 
 Before you ask the user for any approval, clarification, or decision after workers have been dispatched, run the same reclaim first: `$HOME/.okstra/bin/okstra-trace-cleanup.sh --list --run-dir "<RUN_DIR>" [--keep report-writer-worker]` to count the panes, then the same command without `--list` to close them, emit `PROGRESS: phase-gate-cleanup panes=<n>`, and `TaskStop` each completed worker. A `TaskStop` by itself idles the task but leaves the pane open — the `trace-cleanup` call is what actually closes it. This keeps a user gate from being shown while finished worker panes remain; in-flight workers and an in-flight report writer are preserved.
 
-Build the `okstra render-bundle` invocation from `outcome.renderArgs`, passing each key as `--<key>` and the value verbatim (including empty strings — they are intentional `use phase default` markers).
+Build the `okstra render-bundle` invocation from `outcome.renderArgv`, passing every token verbatim and in order (including empty strings — they are intentional `use phase default` markers).
 
-Analysis sidetracks therefore forward wizard-owned entries such as `--analysis-target "<args.analysis-target>"` and `--evidence-inputs "<args.evidence-inputs>"` when those keys are present. These are examples of the generic mapping rule, not a separate hard-coded argument list.
+Analysis sidetracks therefore forward wizard-owned tokens such as `--analysis-target "<value>"` and `--evidence-inputs "<value>"` when they are present. These are examples of the verbatim token rule, not a separate hard-coded argument list.
 
-Step 3's empty-answer and escaping rules apply verbatim: every flag whose value is the empty string MUST still be passed explicitly as `--<key> ""` (e.g. `--workers ""`, `--directive ""`) — `render-bundle` distinguishes "flag absent" from "flag present with empty value", and the wizard's intent is always the latter.
+Step 3's empty-answer and escaping rules apply verbatim: every flag in `renderArgv` whose following value is the empty string MUST still be passed explicitly (e.g. `--workers ""`, `--directive ""`) — `render-bundle` distinguishes "flag absent" from "flag present with empty value", and the wizard's intent is always the latter.
 
-Add `--lead-runtime <host-runtime>` from Step 1. Pass every `outcome.renderArgs` entry exactly once; do not enumerate a fixed provider list in this skill because the wizard and provider registry own those keys. If `renderArgs` ever contains `lead-runtime`, replace it with the Step 1 host value rather than emitting the flag twice.
+`renderArgv` already contains exactly one `--lead-runtime <host-runtime>` pair. Do not add or replace it. Do not enumerate a fixed provider list in this skill because the wizard and role model pool own the ordered tokens.
 
 ```bash
 okstra render-bundle \
-  --lead-runtime <host-runtime> \
-  --<first-renderArgs-key> "<first-renderArgs-value>" \
-  --<each-remaining-renderArgs-key> "<corresponding-value>"
+  <outcome.renderArgv token 1> \
+  <outcome.renderArgv token 2> \
+  <each remaining outcome.renderArgv token in order>
 ```
 
 `render-bundle` auto-supplies `--workspace-root` and forces `--render-only`. Stdout prints `okstra task root:`, `okstra instruction-set:`, `okstra run manifest:`, and the full rendered lead prompt. Parse the labelled lines for `TASK_ROOT`, `INSTRUCTION_SET_PATH`, and `RUN_MANIFEST_PATH`. Also watch for an optional `okstra concurrent-run stages:` label line — present only when a concurrent run is detected (see "Concurrent-run detection branch" below).

package/runtime/templates/implementation-worker-preamble.md

@@ -29,24 +29,9 @@ When `**Evidence ledger:** required-v1` is present, append one canonical row to
 
 Every file citation in the result MUST use backticks, a line suffix, and the same project-relative path its ledger row carries — for example `src/config/env.ts:1-22`. A bare filename (`env.ts:1-22`) does not match its row and fails exactly like a file you never opened, however many times you cited the full path earlier. A cited path without a matching ledger row fails Phase 7 in `validators/validate-run.py` `validate_worker_results_audit()`. Do not add a row for a file you did not open.
 
-## Anchor headers
-
-Every initial implementation prompt begins with these generated common anchors in this exact order, before its implementation-specific body:
-
-1. `**Project Root:** <absolute-path>`
-2. `**Prompt History Path:** <project-relative-path>`
-3. `**Result Path:** <project-relative-path>`
-4. `Assigned worker prompt history path: <absolute-path>`
-5. `**Worker Preamble Path:** <absolute-path>`
-6. `**Worker Error Contract Path:** <absolute-path>`
-7. `**Coding preflight pack:** <absolute-path>`
-8. `**Evidence ledger:** required-v1`
-9. `**Evidence citations:** <rule>` — the ledger-row and citation-path rule of §"Evidence read ledger", restated inline so it is in front of you before your first citation.
-10. `**Errors log path:** <absolute-path>`
-11. `**Errors sidecar path:** <absolute-path>`
-12. `**Read scope:** <allowlist>`
-
-The implementation body additionally carries `**Worktree:**` and its role-sidecar inputs. Do not synthesize any missing path.
+## Injected paths
+
+Use the path headers in the dispatch prompt exactly as written, including `**Coding preflight pack:**` and `**Worktree:**` when present. Do not synthesize any missing path.
 
 ## Return message to the lead
 

package/runtime/templates/project-docs/task-index.template.md

@@ -36,7 +36,6 @@ taskType: "{{FM_TASK_TYPE}}"
 - Last Completed Phase: `{{WORKFLOW_LAST_COMPLETED_PHASE}}`
 - Next Recommended Phase: `{{WORKFLOW_NEXT_RECOMMENDED_PHASE}}`
 - Awaiting Approval: `{{WORKFLOW_AWAITING_APPROVAL}}`
-- Routing Status: `{{WORKFLOW_ROUTING_STATUS}}`
 - Fix cycles: {{FIX_CYCLES_SUMMARY}}
 
 ## Phase States

package/runtime/templates/report-writer-prompt-preamble.md

@@ -22,6 +22,8 @@ Write `- PROGRESS: <stage> <ISO-8601-UTC>` there before reading and at least eve
 
 The generated prompt selects this file through `**Worker Preamble Path:**` and includes `**Worker Error Contract Path:**`, `**Audit sidecar path:**`, error paths, and read scope. It never includes `**Coding preflight pack:**`.
 
+The adjacent v2 prompt metadata supplies `participantRef`, `roleExecutionRef`, `executionLabel`, `invocationRef`, and `attempt`. Copy those values into report and audit identity fields without deriving them from the provider or model. Legacy v1 `workerId` is a read-only compatibility projection and is not written into v2 artifacts.
+
 ## Return message to the lead
 
 Begin the inline return with the exact `**Model:** Report writer worker, <modelExecutionValue>` line from the prompt, followed by the artifact status. Never invent or abbreviate the model.

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

@@ -25,7 +25,7 @@ schema-version: {{ schemaVersion | yaml_scalar }}
   is a non-authoritative index of `finalVerdict`, which §Final Verdict already
   carries in full.
 -#}
-{{ md_claim("schemaVersion", "meta", "frontmatter", "header", "humanSummary", "verdictCard") }}
+{{ md_claim("schemaVersion", "meta", "frontmatter", "header", "humanSummary", "verdictCard", "executionRoles", "executionIdentityVersion") }}
 
 # {{ frontmatter.title }}
 
@@ -44,6 +44,12 @@ schema-version: {{ schemaVersion | yaml_scalar }}
 - Rationale IDs: {{ finalVerdict.rationaleRowIds | join(", ") }}
 - Blocking IDs: {{ aiBlockingIds | join(", ") if aiBlockingIds else "none" }}
 - Next step: {{ finalVerdict.nextStep }}
+{% if executionIdentityVersion == 2 %}
+
+## Execution Roles
+
+{{ executionRolesTable }}
+{% endif %}
 
 ## Decision Context
 

package/runtime/templates/reports/html/base.template.html

@@ -21,6 +21,27 @@
     </dl>
     <p class="lede">{{ humanSummary.headline | inline_code }}</p>
     <p>{{ humanSummary.outcome | inline_code }}</p>
+    {% if executionRoles %}
+    <section data-report-section="execution-roles">
+      <h2>{{ t('base.execution-roles') }}</h2>
+      <table>
+        <thead><tr>
+          <th scope="col">{{ t('base.role') }}</th>
+          <th scope="col">{{ t('base.execution-label') }}</th>
+          <th scope="col">{{ t('base.status') }}</th>
+        </tr></thead>
+        <tbody>
+          {% for row in executionRoles %}
+          <tr>
+            <td>{{ row.role }}</td>
+            <td><code>{{ row.executionLabel }}</code></td>
+            <td>{{ row.status }}</td>
+          </tr>
+          {% endfor %}
+        </tbody>
+      </table>
+    </section>
+    {% endif %}
   </header>
   <main id="main-content" data-report-role="human-main">
     {% block human_content %}{% endblock %}

package/runtime/templates/reports/html/i18n/en.json

@@ -96,6 +96,10 @@
     "skip-to-report-content": "Skip to report content",
     "contents": "Contents",
     "task": "Task",
+    "execution-roles": "Execution roles",
+    "role": "Role",
+    "execution-label": "Execution label",
+    "status": "Status",
     "task-key": "Task key",
     "written": "Written",
     "elapsed": "Elapsed",

package/runtime/templates/reports/html/i18n/ko.json

@@ -96,6 +96,10 @@
     "skip-to-report-content": "리포트 본문으로 건너뛰기",
     "contents": "목차",
     "task": "태스크",
+    "execution-roles": "실행 역할",
+    "role": "역할",
+    "execution-label": "실행 표지",
+    "status": "상태",
     "task-key": "태스크 키",
     "written": "작성",
     "elapsed": "소요 시간",

package/runtime/templates/reports/html/macros/forms.html

@@ -63,6 +63,7 @@
   {% for row in items %}
   {% set is_closed = row.status in ['resolved', 'obsolete'] %}
   {% set approval_context = row.approvalContext | default(None) %}
+  {% set options = row.options | default([]) %}
   <article class="clarification-item" id="id-{{ row.id }}" data-response-id="{{ row.id }}" data-kind="{{ row.kind }}" data-status="{{ row.status }}">
     <p class="eyebrow">{{ row.id }} · {{ row.kind }}</p>
     {{ row.statement | paragraphs }}
@@ -76,9 +77,9 @@
       </p>
     </div>
     {% endif %}
-    {% if row.options %}
+    {% if options %}
     <ol class="clarification-options">
-      {% for option in row.options %}
+      {% for option in options %}
       <li class="clarification-option{% if option.role == 'recommended' %} is-recommended{% endif %}">
         <p class="clarification-option-answer">{{ option.answer }}{% if option.role == 'recommended' %} <span class="badge">{{ t('macros.forms.recommended') }}</span>{% endif %}</p>
         {% if option.disposition | default(None) %}<p class="clarification-option-disposition"><code>{{ option.disposition }}</code></p>{% endif %}
@@ -93,10 +94,10 @@
     </ol>
     {% endif %}
     <label for="response-{{ row.id }}">{{ t('macros.forms.your-answer-to-id') | replace('{id}', row.id) }}</label>
-    {% if row.kind == 'decision' and approval_context and row.options %}
+    {% if row.kind == 'decision' and approval_context and options %}
     <select id="response-{{ row.id }}" data-response-id="{{ row.id }}"{% if is_closed %} disabled{% endif %}>
       <option value="">{{ t('macros.forms.choose-one') }}</option>
-      {% for option in row.options %}<option value="{{ option.answer }}" data-disposition="{{ option.disposition }}"{% if option.role == 'recommended' %} data-recommended="true"{% endif %}{% if row.userInput | default('') == option.answer %} selected{% endif %}>{{ option.answer }}</option>{% endfor %}
+      {% for option in options %}<option value="{{ option.answer }}" data-disposition="{{ option.disposition | default('') }}"{% if option.role == 'recommended' %} data-recommended="true"{% endif %}{% if row.userInput | default('') == option.answer %} selected{% endif %}>{{ option.answer }}</option>{% endfor %}
     </select>
     {% else %}
     <textarea id="response-{{ row.id }}" data-response-id="{{ row.id }}" rows="4"{% if is_closed %} disabled{% endif %}>{{ row.userInput | default('') }}</textarea>

package/runtime/templates/reports/html/tasks/final-verification.template.html

@@ -41,6 +41,6 @@
 <section data-report-section="release-route">
   <h2>{{ t('tasks.final-verification.release-path') }}</h2>
   {{ render_narrative(narrative.releaseReadiness, "finalVerification.userNarrative.releaseReadiness") }}
-  {% if releaseAllowed %}<p>{{ final.routingRecommendation | inline_code }}</p>{% else %}<p>{{ t('tasks.final-verification.the-current-verdict-does-not-allow-release-h') }}</p>{% endif %}
+  {% if releaseAllowed %}<p><strong><code>{{ final.routingRecommendation.target }}</code></strong> — {{ final.routingRecommendation.rationale | inline_code }}</p>{% else %}<p>{{ t('tasks.final-verification.the-current-verdict-does-not-allow-release-h') }}</p>{% endif %}
 </section>
 {% endblock %}

package/runtime/templates/reports/html/tasks/implementation.template.html

@@ -53,6 +53,6 @@
 
 <section data-report-section="next-step" data-report-field="implementation.routingRecommendation">
   <h2>{{ t('tasks.implementation.next-step') }}</h2>
-  <p>{{ implementation.routingRecommendation | inline_code }}</p>
+  <p><strong><code>{{ implementation.routingRecommendation.target }}</code></strong> — {{ implementation.routingRecommendation.rationale | inline_code }}</p>
 </section>
 {% endblock %}

package/runtime/templates/worker-prompt-preamble.md

@@ -2,6 +2,8 @@
 
 This file is the audience-specific contract for initial `analysis` workers. Read it end-to-end from the path selected by the dispatch prompt. Before doing work, also read the shared file named by `**Worker Error Contract Path:**`; that file is the only source for error-sidecar rules.
 
+Your identity is the stored role execution (`executionLabel`). Canonical roles are `leader`, `analyser`, `critic`, `designer`, `planner`, `implementer`, `verifier`, `report-writer`, and `translator`. `lead` and `executor` are compatibility aliases only.
+
 ## Required reading
 
 Read `analysis-packet.md`, the primary compact input, end-to-end. Source files named as fallback/evidence paths are read only when a finding needs to verify a citation, fill a packet gap, or resolve ambiguity. Do not read `final-report-template.md` or `final-report-schema.json`; analysis workers produce findings, not the final report.
@@ -23,34 +25,15 @@ Every file citation in the result MUST use backticks, a line suffix, and the sam
 
 ## Evidence command ledger
 
-Append one canonical JSON row to the audit sidecar for each command that produced or verified a conclusion:
-
-- Evidence command: {"command":"npm run check","cwd":"<project-root>","exitCode":0,"outputSummary":"all checks passed"}
-
-Do not record commands used only to explore, including `rg`, `ls`, and file-opening commands. Do not record environment variable values, tokens, credentials, or authorization headers. `okstra worker-audit-check` rejects malformed command rows and rows containing potential sensitive material through `okstra_ctl.worker_audit_ledger`.
+Follow the `**Evidence commands:**` header in the dispatch prompt. That header is the worker-facing rule.
 
-## Anchor headers (lead-injected, BLOCKING)
+## Injected paths
 
-Every initial analysis prompt begins with these generated anchors in this exact order, before any other content:
-
-1. `**Project Root:** <absolute-path>`
-2. `**Prompt History Path:** <project-relative-path>`
-3. `**Result Path:** <project-relative-path>`
-4. `**Audit sidecar path:** <absolute-path>` — the generated audit destination; write the sidecar here and never synthesize a `runs/<task-type>/...` path.
-5. `Assigned worker prompt history path: <absolute-path>`
-6. `**Worker Preamble Path:** <absolute-path>` — selects this analysis preamble.
-7. `**Worker Error Contract Path:** <absolute-path>` — shared by every initial audience.
-8. `**Evidence ledger:** required-v1`
-9. `**Evidence citations:** <rule>` — the ledger-row and citation-path rule of §"Evidence read ledger", restated inline so it is in front of you before your first citation.
-10. `**Errors log path:** <absolute-path>`
-11. `**Errors sidecar path:** <absolute-path>`
-12. `**Read scope:** <allowlist>`
-
-`final-verification` additionally carries its six verification-target anchors. `improvement-discovery` carries `**Phase 1.5 Grilling Log:**`. Reverify prompts are lightweight and do not use this preamble.
+Use the path headers in the dispatch prompt exactly as written. Do not synthesize a missing path from a run-directory pattern. `final-verification` may carry verification-target headers. `improvement-discovery` may carry `**Phase 1.5 Grilling Log:**`. Treat extra generated headers the same way. Reverify prompts are lightweight and do not use this preamble.
 
 ## Worker output sections
 
-Every analysis result starts with YAML frontmatter containing the task identity and `workerId`, followed by a header with the actual `**Model:**` value. Then emit these sections in exact order:
+Every analysis result starts with YAML frontmatter containing the task identity, `participantRef`, `roleExecutionRef`, `executionLabel`, `invocationRef`, and `attempt`, followed by a header with the actual `**Model:**` value. Copy these execution fields from the generated prompt metadata; do not derive them from the provider or model name. Legacy v1 prompts may expose only `workerId`, which is a read-only compatibility projection and must not be written into a v2 result. Then emit these sections in exact order:
 
 1. Findings
 2. Missing Information or Assumptions
@@ -61,18 +44,6 @@ Every analysis result starts with YAML frontmatter containing the task identity
 
 Every item has a worker-local ID and file:line evidence where code evidence exists. Sections 1–5 are the common core: feasibility, requirement interpretation, hidden assumptions, alternatives, and execution risk. Section 6 is the only legal home for specialization and is not consensus input.
 
-### Selected-direction planning ownership
-
-For `implementation-planning` with `selected-direction.json`, sections 1–5 read that snapshot and the original requirements, then assess only its realization into files, interfaces, stages, validation, rollback, bidirectional requirement links, and `direction-invalidated` evidence. Direction selection remains upstream of this prompt.
-
-### Legacy candidate-comparison ownership
-
-For an implementation-planning compatibility rerun without the snapshot, sections 1–5 retain candidate comparison, trade-off, recommendation, and `P-Opt-*` evidence.
-
-### Ticket Tagging
-
-For `requirements-discovery`, `error-analysis`, and `implementation-planning`, tag every section 1–5 item with its related ticket. Use `Issue / Ticket`, fall back to Task ID, then `unknown`; comma-separate multiple tickets.
-
 ## Return message to the lead
 
 Begin the inline return with the model identity copied verbatim from the `**Model:** <Role>, <modelExecutionValue>` line in the prompt, followed by the status summary. Never invent or abbreviate the model.

package/runtime/validators/lib/fixtures.sh

@@ -138,6 +138,7 @@ prompt_path.write_text(
             f"{target_worker_id}-errors.json",
             f"Assigned worker prompt history path: {prompt_relative}",
             "**Prompt Delivery Mode:** eager-include",
+            f"**Model:** Fixture worker, {target_worker.get('modelExecutionValue', '')}",
             f"- Primary analysis packet: `{analysis_packet_path}`",
             "",
             "# Initial Analysis Prompt",
@@ -222,7 +223,7 @@ for worker in team_state.get("workers", []):
     worker["reason"] = reason_by_worker_id.get(worker_id, "Validation fixture not used")
 
     prompt_relative = str(worker.get("promptPath", "")).strip()
-    if prompt_relative and worker_id != omitted_worker_id:
+    if prompt_relative:
         prompt_path = project_root / prompt_relative
         prompt_path.parent.mkdir(parents=True, exist_ok=True)
         prompt_lines = [
@@ -232,6 +233,7 @@ for worker in team_state.get("workers", []):
             f"{worker_id}-errors.json",
             f"Assigned worker prompt history path: {prompt_relative}",
             "**Prompt Delivery Mode:** eager-include",
+            f"**Model:** Fixture worker, {worker.get('modelExecutionValue', '')}",
         ]
         if worker_id != "report-writer":
             prompt_lines.append(
@@ -570,6 +572,7 @@ if WORKSPACE_ROOT:
         AgentInstructionSource,
         AgentInvocationRequest,
         agent_model_assignment_from_payload,
+        invocation_execution_identity_from_manifest,
         prepare_agent_invocation,
     )
     from okstra_ctl.dispatch_state import (
@@ -602,7 +605,7 @@ if WORKSPACE_ROOT:
     contract = run_manifest["agentContract"]
     reservation_root = project_root / contract["invocationReservationRootPath"]
     for worker in team_state.get("workers", []):
-        if not isinstance(worker, dict) or worker.get("status") != "completed":
+        if not isinstance(worker, dict):
             continue
         worker_id = str(worker.get("workerId") or "").strip()
         prompt_relative = str(worker.get("promptPath") or "").strip()
@@ -615,18 +618,37 @@ if WORKSPACE_ROOT:
         assignment_ref = f"initial/{worker_id}"
         invocation_id = f"validation-fixture-{worker_id}"
         invocation_prompt = reservation_root / f"{invocation_id}.prompt.md"
+        audience = (
+            "report-writer" if worker_id == "report-writer"
+            else analysis_audience
+        )
+        assignment = agent_model_assignment_from_payload(
+            assignments[assignment_ref]
+        )
+        identity = invocation_execution_identity_from_manifest(
+            run_manifest,
+            assignment=assignment,
+            assignment_ref=assignment_ref,
+            duty_id=audience,
+        )
+        identity_args = {
+            "participant_ref": (
+                identity.participant_ref if identity is not None else None
+            ),
+            "role_execution_ref": (
+                identity.role_execution_ref if identity is not None else None
+            ),
+            "duty_id": identity.duty_id if identity is not None else None,
+            "invocation_ref": invocation_id if identity is not None else None,
+            "attempt": 1,
+        }
         prepared = prepare_agent_invocation(AgentInvocationRequest(
             invocation_id=invocation_id,
-            worker_id=worker_id,
-            audience=(
-                "report-writer" if worker_id == "report-writer"
-                else analysis_audience
-            ),
+            worker_id=worker_id if identity is None else None,
+            audience=audience,
             assignment_ref=assignment_ref,
             purpose=None,
-            assignment=agent_model_assignment_from_payload(
-                assignments[assignment_ref]
-            ),
+            assignment=assignment,
             instruction=AgentInstruction(
                 anchor_lines=(),
                 body=source_prompt.read_text(encoding="utf-8"),
@@ -642,6 +664,7 @@ if WORKSPACE_ROOT:
                 invocation_prompt.name + ".meta.json"
             ),
             dispatch_kind="validation-fixture",
+            **identity_args,
         ))
         dispatch = record_verified_agent_dispatch(
             project_root=project_root,
@@ -653,11 +676,21 @@ if WORKSPACE_ROOT:
                 else "core-pre-dispatch"
             ),
         )
-        link_agent_dispatch_result(
-            project_root=project_root,
-            run_manifest_path=run_manifest_path,
-            dispatch_id=dispatch["dispatchId"],
-            result_path=project_root / result_relative,
-        )
+        if worker.get("status") == "completed":
+            link_agent_dispatch_result(
+                project_root=project_root,
+                run_manifest_path=run_manifest_path,
+                dispatch_id=dispatch["dispatchId"],
+                result_path=project_root / result_relative,
+            )
+
+# Preserve the workflow's historical missing-prompt negative after the v2
+# invocation record has captured the prompt bytes that were actually sent.
+for worker in team_state.get("workers", []):
+    if isinstance(worker, dict) and worker.get("workerId") == omitted_worker_id:
+        omitted_prompt = str(worker.get("promptPath") or "").strip()
+        if omitted_prompt:
+            (project_root / omitted_prompt).unlink(missing_ok=True)
+        break
 PY
 }