okstra 0.202.0 → 0.204.0

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

@@ -8,7 +8,7 @@ description: |
 
 Cross-task roll-up: collect every catalog task's run results (optionally scoped to one task-group) and summarize them together. The `rollup` CLI does all deterministic aggregation — counts, time sums, error tallies, status/category/phase distributions. You resolve scope, call it, render the table, and synthesize the prose digest from the report files. **Never recompute totals or re-tally by hand** — the CLI is the SSOT for the numbers.
 
-This skill is read-only. It never mutates task artifacts.
+The skill itself writes nothing. `okstra rollup` resolves every catalog task by task-key, and that lookup self-heals a finished implementation phase. When a task's current phase is `implementation`, that lookup appends a `done` row to `runs/implementation-planning/consumers.jsonl` for each stage whose carry file is complete but has no settled row, and when every stage of the latest plan has a `done` row and a pass-grade carry it marks the phase completed in `task-manifest.json` (`workflow`, `phaseOutcome.implementation`) and refreshes that task's catalog entry. Nothing else is written.
 
 ## Step 0: Preflight
 
@@ -56,15 +56,15 @@ Convert each returned `ms` label to `HH:MM:SS` (zero-pad; never show raw ms). CP
 **workStatus:** done 1 · in-progress 1   **category:** bugfix 1 · feature 1
 ```
 
-Render `Report` as `✓` when the corresponding `Task N report path` is non-empty, else `—`. Use the numbered fixed labels and total labels verbatim; do not re-count tasks.
+Render `Report` as `✓` when the corresponding `Task N report path` holds a path, else `—`. An absent path prints as `-`. Use the numbered fixed labels and total labels verbatim; do not re-count tasks.
 
 ## Step 4: Synthesize the digest (the summary)
 
 This is the skill's value-add over a bare table. When the user asked to "summarize"/"digest"/"organize" (the common case), produce a short cross-task narrative:
 
-1. For each task with a non-empty `reportPath` whose file exists under `<projectRoot>/<reportPath>`, read it and write a 1–2 line summary of what it accomplished and its recommended next step.
-2. Above the per-task lines, write a 2–4 sentence group-level synthesis: what was delivered across the group, where the open work sits (use `byWorkStatus`/`byCurrentPhase`), and any error hot-spots (tasks with high `errorCount`).
-3. Cite each per-task claim with the report path as `<reportPath>` so the reader can open it.
+1. For each task whose `Task N report path` is not `-` and whose file exists under `<projectRoot>/<Task N report path>`, read it and write a 1–2 line summary of what it accomplished and its recommended next step.
+2. Above the per-task lines, write a 2–4 sentence group-level synthesis: what was delivered across the group, where the open work sits (use the `Work status N name/count` and `Current phase N name/count` lines), and any error hot-spots (tasks with a high `Task N errors`).
+3. Cite each per-task claim with its `Task N report path` value so the reader can open it.
 
 For tasks with no report, state the current phase/workStatus instead of inventing a summary — do not read non-report artifacts to fill the gap.
 

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

@@ -32,10 +32,10 @@ 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. 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.
+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 스텝 남음`, or `Step 11/11 · 마지막 단계` on the final screen; the suffix is Korean whatever the report language). **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: ...",
+{ "ok": false, "error": "approved plan §1 has 1 unresolved `Blocks=approval` row(s); ...",
   "current": { "step": "approved_plan", "kind": "text", "label": "..." } }
 ```
 
@@ -61,7 +61,7 @@ The final `confirm` step is a normal `pick` step with three options — `Proceed
 
 Never invent additional questions. **Never drop, hide, merge, reorder, or truncate** a `pick` / `pick_group` option — relay every `options[]` entry, including entries that carry a `(default)` / `(recommended)` suffix. Do not collapse a multi-option pick into a "recommended + Enter directly / Other" shortlist. The wizard's arrays are the complete authoritative choice sets, regardless of the current host UI's usual option limit. The run-prompt recommendation rule (1–2 recommendations + Enter directly) shapes the **option set** only for prompts this skill authors itself, never for wizard-provided options — you may not add, drop, or reorder a wizard option to produce a shortlist. It does not excuse you from recommending: before relaying a wizard step whose answer turns on something readable (the carried report, the sidecar the user already wrote, the prior Stage Map), read it, put what you found in the question body, and name which of the wizard's own options you recommend and why. Relaying a step with no context and no recommendation hands the whole question back to the user — see the lifecycle core contract "Asking the user (BLOCKING)".
 
-**One recommendation, shown in one place, and it is option 1.** The option carrying `recommended: true` is what this run computed, and the wizard already placed it first — append ` (추천)` to that option's label when you render it, and to no other. A checkbox step (`multi: true`) may flag several leading options: they are the recommended set, rendered the same way. Your prose recommendation names one of the flagged options. If you believe a different option is right, do not quietly recommend it in prose while the flagged one still reads as recommended on screen: say you disagree, name both, and let the user pick. When no option carries the flag, the run computed nothing for this step — recommend one from what you read and mark that one, and do not present the first option as a default just because it is first. **Enforced:** `scripts/okstra_ctl/wizard/state.py` `Prompt.__post_init__` refuses a step whose free-input option is not last, whose single-select recommendation is not exactly one option placed first (a checkbox step's recommended options must be its leading run), or that marks the free-input / abort escape as a recommendation.
+**One recommendation, shown in one place, and it is option 1.** The option carrying `recommended: true` is what this run computed, and the wizard already placed it first — except on model-selection steps (`role-models:*`, `role-model:*`), which keep provider display order, so the flagged model may sit anywhere in the list. Append ` (추천)` to that option's label when you render it, and to no other. A checkbox step (`multi: true`) may flag several leading options: they are the recommended set, rendered the same way. Your prose recommendation names one of the flagged options. If you believe a different option is right, do not quietly recommend it in prose while the flagged one still reads as recommended on screen: say you disagree, name both, and let the user pick. When no option carries the flag, the run computed nothing for this step — recommend one from what you read and mark that one, and do not present the first option as a default just because it is first. **Enforced:** `scripts/okstra_ctl/wizard/state.py` `Prompt.__post_init__` refuses a step whose free-input option is not last, whose single-select recommendation is not exactly one option, whose recommendation is not placed first on a single-select step or is not the leading run on a checkbox step (both position checks are skipped on `role-models:*` / `role-model:*` steps), or that marks the free-input / abort escape as a recommendation.
 
 ## Step 1: Preflight
 
@@ -168,13 +168,13 @@ okstra wizard init \
   --available-function <each-additional-function-in-the-effective-intersection>
 ```
 
-Output: the same `{ok, next}` JSON described above. The first `next` is always `step: "task_pick"`.
+Output: the same `{ok, next}` JSON described above. The first `next` is `step: "report_language"` when `.okstra/project.json` has no `reportLanguage` value; otherwise it is `step: "task_pick"`, except that when the brand-new option is the only `task_pick` choice, `init` answers it itself and the first `next` is the task-group step.
 
 ## Step 3: Run the prompt loop
 
 Repeat until `next.kind == "done"` (or `"aborted"` — terminal cancel, see "How the wizard talks to you"):
 
-1. **Render** the prompt according to `next.interaction.kind` using the relay rules above. For a native kind, invoke the `function` string from that same `interactions` entry — the Claude Code picker, the Grok picker, and the Codex picker are different names, and substituting one for another is a relay-contract failure. **Always append the progress marker to the rendered question label**: suffix it with ` (<next.progress.label>)` — render `progress.label` exactly as the wizard sent it, never recompute it. Example: label `Step 8/11 · 3 steps remaining` → `Select a model (Step 8/11 · 3 steps remaining)`. Re-prompts after `ok: false` reuse `current.progress.label` the same way. The progress marker is presentation-only — never send it back to the wizard as part of an answer. **The rendered question is the last thing you emit in that turn.** Every host streams assistant text in emission order, so an echo, a restatement, a rationale, or a status line emitted after the question call renders *below* the picker and pushes the question away from where the user answers. Say whatever you need to say before the call, then call and stop.
+1. **Render** the prompt according to `next.interaction.kind` using the relay rules above. For a native kind, invoke the `function` string from that same `interactions` entry — the Claude Code picker, the Grok picker, and the Codex picker are different names, and substituting one for another is a relay-contract failure. **Always append the progress marker to the rendered question label**: suffix it with ` (<next.progress.label>)` — render `progress.label` exactly as the wizard sent it, never recompute it. Example: label `Step 8/11 · 앞으로 3 스텝 남음` → `Select a model (Step 8/11 · 앞으로 3 스텝 남음)`. Re-prompts after `ok: false` reuse `current.progress.label` the same way. The progress marker is presentation-only — never send it back to the wizard as part of an answer. **The rendered question is the last thing you emit in that turn.** Every host streams assistant text in emission order, so an echo, a restatement, a rationale, or a status line emitted after the question call renders *below* the picker and pushes the question away from where the user answers. Say whatever you need to say before the call, then call and stop.
    **One pending interaction per wizard state.** For native interactions, display the question and options only through the selected question tool, not as a second text list. An asynchronous acknowledgement such as `{accepted: true}` means the question is pending, not answered. Wait for the actual user reply; do not repeat the tool call or fetch and render the same step again while waiting. If ending the turn while awaiting a reply, do not restate the question in the final message. Re-prompt only on explicit user edits or a validation error after submitting an actual answer. This is a lead relay instruction; wizard state validation does not deduplicate host UI emissions.
 2. **Submit** the answer — call `okstra wizard step` with the literal state-file path from Step 2 and the literal user answer (no shell variables, no `$(...)`):
    ```bash
@@ -186,7 +186,7 @@ Repeat until `next.kind == "done"` (or `"aborted"` — terminal cancel, see "How
    ```bash
    okstra wizard step --state-file /var/folders/.../okstra-wizard.AbCd.json --answer ""
    ```
-   Omitting `--answer` entirely is forbidden. The wizard interprets a missing `--answer` flag as "re-emit the current prompt" (a `get-current-prompt` style no-op), not as "submit empty" — so dropping the flag will loop the same prompt forever. Submitting `--answer ""` is the only way to advance past an intentionally-blank step (e.g. "use phase default").
+   Omitting `--answer` entirely is forbidden. The wizard does not read a missing `--answer` flag as "submit empty": without `--answer` or `--no-submit`, `wizard step` returns `ok: false` naming `--answer` and exits 2, and the step is not submitted. Submitting `--answer ""` is the only way to advance past an intentionally-blank step (e.g. "use phase default").
 
    **Escaping rule**: if the literal answer contains `"`, escape each occurrence as `\"` inside the double-quoted argument. Empty values must still be `--answer ""` — the flag itself is mandatory, even when the value is empty.
 
@@ -204,9 +204,9 @@ That is the entire interactive flow. The wizard handles:
 - 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). 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),
+- `release-handoff`-only sub-flow: after the approved plan auto-resolves, a `handoff_stage_pick` multi-select — choose the eligible stages to open a PR for, one PR per stage; the result goes out as render-args' `stages` key (csv; empty takes every eligible stage),
 - launch selection after identity/worktree steps: one screen per static role, in profile order. A role that can run several instances (`max > 1`) is a checkbox step `role-models:<role>` (`multi: true`) — the number of models checked is the number of instances, there is no separate count question; the label states the profile range and recommended count, every executable candidate is listed on that one screen (defaults first, the recommended set flagged), and when the list exceeds the host's native checkbox limit the runtime either splits it into several checkbox questions on one `pick_group` screen (interaction plan `native-group`; the question steps are `role-models:<role>#1`, `#2`, … and the answer is one JSON object keyed by them, each value a CSV) when the host's native question group holds every option, or returns the interaction plan `numbered-multi` — render the whole list, never a shortlist or pages. An optional role (`min = 0`, e.g. critic) carries a `추가 안 함` row. A fixed single role (`min = max = 1`, e.g. report-writer) is a single pick `role-model:<role>:1`, and a role capped at one model (`max = 1`, e.g. critic) is a single pick on its `role-models:<role>` step; both split the same way when they exceed the native option limit — the tabs are checkbox questions, the answer is the same keyed JSON object, and the wizard rejects a screen whose tabs together name more than one value. current-session lead is this session and is listed on the confirmation summary, not as a wizard step. 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,
+- **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` / `project-analysis` / `feature-analysis` / `change-impact-analysis`, only when prior run-inputs exist): YES prefills role-count·role-model·directive·related-tasks at once (and, for the analysis types, the target and evidence inputs). (2) `clarification_pick`: a `revision-requested` analysis report for the selected analysis type is recommended first; otherwise the **task-type's own** previous `final-report` is auto-recommended as the carry-in input (for `technical-verification`, the `implementation-option-selection` report), falling back to the newest by mtime across all phases when absent — except for `implementation-planning` and `technical-verification`, which get no cross-phase fallback. The approved plan is never recommended here. 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` when the re-run is narrowable **or** an answered `C-NNN` traces to no stage. When every answered id traces to a stage: 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). When an id is unlinked, `auto` is omitted and the user names stages or picks `full`; that unlinked id does not freeze the run at full. 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. The confirmation block's `reverify-scope` line names unlinked ids as needing stage numbers, not as a forced full re-run,
 - `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.
@@ -271,7 +271,7 @@ Before invoking it, follow the active host relay's execution-permission guidance
 
 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 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.
+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 ""`) — the wizard's intent is always "flag present with empty value", even where prepare's default happens to be the same empty value.
 
 `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.
 
@@ -299,9 +299,9 @@ Do not continue from the rendered prompt if this command fails. This record
 associates the current-session lead with a verified invocation specification;
 it does not claim that the host exposed or attested the delivered prompt bytes.
 
-The python function underneath is mutex-protected (`~/.okstra/.locks/<task-key>.lock`), writes `run-context-*.json` + `run-inputs-*.json` + all manifests + discovery files, and registers the run in `~/.okstra/recent.jsonl` with status `prepared`.
+The python function underneath allocates the run sequence number and writes `run-context-*.json` under the per-task lock (`~/.okstra/.locks/<task-key>.lock`), then writes `run-inputs-*.json` + all manifests + discovery files outside that lock, and registers the run in `~/.okstra/recent.jsonl` with status `prepared` under the central `~/.okstra/.lock` (a registration failure is reported on stderr and does not fail prepare).
 
-**Enforced:** the same `tests-js/wizard.test.mjs` cases cover the argv this step passes through — `orderedRenderArgv` preserves the Python role selection bytes and repeated role order, so an empty value dropped here changes the rendered bundle and the golden comparison fails.
+**Not enforced:** `tests-js/wizard.test.mjs` pins the argv the wizard produces (`orderedRenderArgv` preserves the Python role selection bytes and repeated role order), not the argv you pass. Prepare's parser defaults most flags to `""` (e.g. `--directive`), so a dropped empty value is indistinguishable from its default and nothing rejects it — passing every token verbatim is on you.
 
 You can delete the literal state-file path after this point — its job is done. Invoke `command rm` with the literal path (e.g. `command rm /var/folders/.../okstra-wizard.AbCd.json`), not a shell variable. `command` is what keeps a `rm='rm -i'` alias from turning this into a confirmation prompt nobody is there to answer.
 
@@ -462,9 +462,28 @@ The three branches that end or pause the queue — "Next stage not yet ready", "
 
 Do not read the wizard state file directly. `okstra wizard outcome` exposes any release-handoff PR template write as `outcome.persistActions[]`; execute those actions before `render-bundle`.
 
+## Comparison material for a direction choice
+
+When the user has to choose an implementation direction — a finished `implementation-option-selection` run with routing `pending-direction-selection`, or the planning wizard's `selected_direction_pick` step — and asks for material comparing the directions, build it from the report record, not from memory or a hand read of the JSON:
+
+```bash
+~/.okstra/bin/okstra option-comparison --report <final-report-implementation-option-selection-NNN.data.json>
+```
+
+At `selected_direction_pick` the report path is the option value. The command prints JSON; every number in the reply comes from it. Use the recorded `weightedScore` as printed; do not recompute it. Write the reply in the user's language, in this order:
+
+1. **Lead-in** — one or two sentences on what the directions share and the axes they split on, drawn from `narrative.comparisonOverview` and each option's `coreMechanism`.
+2. **Score table** — a Markdown table: one row per `criteria[]` entry in order, a weight column, one column per option (`<id> <short name>`), and a last row with each option's `weightedScore`. Write each criterion as its identifier with a translation in the user's language, e.g. `requirement-fit(요구사항 부합)`.
+3. **Coverage and blockers** — one line per option, or one line when they agree: `coverage.verdict`, the `coverage.requirementIds` it covers, and the `safetyBlockers` and `unresolvedFeasibilityFacts` counts.
+4. **Feasibility votes** — a Markdown table: one row per option, one column per `workers[]` entry, each cell that worker's `votes[<worker>].verdict`.
+5. **Per direction** — one paragraph per option, recommended first and marked as recommended, with its `weightedScore`: what it does (`coreMechanism`), the criteria that carry its score (its high scores on heavy weights), and its main cost, taken from its low `scoreRationales` and the `counterevidence` of its votes. Name a worker who voted `not-feasible` or `uncertain` and give that worker's `rationale`.
+6. **Remaining steps** — restate `nextStep`: where the direction is chosen (the HTML report's direction-selection Export saved under `user-responses/`) and how planning then picks it up.
+
+The layout is guidance for the reply. Nothing checks the reply text; the command guarantees only the numbers.
+
 ## Concurrency
 
-- `prepare_task_bundle` serializes per-task via `~/.okstra/.locks/<task-key>.lock`. Concurrent skill invocations on the same task wait; different tasks proceed in parallel.
+- `prepare_task_bundle` takes the per-task lock `~/.okstra/.locks/<task-key>.lock` only while it allocates the run sequence number and writes the run-context file; concurrent invocations on the same task wait for that step and get distinct sequence numbers, and the rest of prepare is not serialized by it. Different tasks proceed in parallel.
 - Each wizard run owns its own state file (one per `okstra wizard new-state-file`); two parallel skill invocations do not collide.
 - The skill must NOT call `okstra.sh` (or any other bash entrypoint) that would re-implement the orchestration. The wizard + `render-bundle` is the single authority.
 

package/runtime/skills/okstra-schedule-gen/SKILL.md

@@ -52,7 +52,7 @@ restated a table that sat directly above or below them.
 
 ## Audience & authority (READ FIRST — drives everything below)
 
-**The schedule is shared with people who do not run okstra.** It is the team's work-plan document, not a record of a run. The body names neither the tool nor its vocabulary — `okstra`, `task-group`, `task-key`, `taskType`, a run's phase names — and the validator refuses a body that does. The title is the work's name, the one metadata line is `> 작성일 <YYYY-MM-DD> · 대상 저장소 <repo>`, and At a Glance identifies each task by name rather than by task-id. That extends to paths: a plan often puts its own scaffolding under the run's working tree — `.okstra/…`, or the `qa/…` scratch it holds — and those are places the reader cannot open and does not own. Name the artefact instead ("계약 캡처 도구", "위반 대장") and keep the path out. Real repository paths — `package.json`, `src/**`, `eval/**`, `.github/workflows/**` — are content and stay.
+**The schedule is shared with people who do not run okstra.** It is the team's work-plan document, not a record of a run. The body names neither the tool nor its vocabulary — `okstra`, `task-group`, `task-key`, `taskType`, a run's phase names. The validator refuses prose that names `okstra`, `task-group`, `task-key`, or `taskType` outside inline code; it does not check phase names or backticked tokens. The title is the work's name, the one metadata line is `> 작성일 <YYYY-MM-DD> · 대상 저장소 <repo>`, and At a Glance identifies each task by name rather than by task-id. That extends to paths: a plan often puts its own scaffolding under the run's working tree — `.okstra/…`, or the `qa/…` scratch it holds — and those are places the reader cannot open and does not own. Name the artefact instead ("계약 캡처 도구", "위반 대장") and keep the path out. Real repository paths — `package.json`, `src/**`, `eval/**`, `.github/workflows/**` — are content and stay.
 
 **The schedule is a client-facing work plan.** It assumes the team has all permissions and can proceed without further approval. Even when the underlying per-task reports flag blocking items, missing approvals, or "items requiring user confirmation", **the schedule MUST NOT surface them** — those belong in the internal report. Never emit a decision checklist, a `#### Items requiring user confirmation` sub-section, `Done`/`Ready?`/`Blocking Decisions` columns, or checkbox lists; "Status" reflects work phase only.
 
@@ -64,13 +64,13 @@ restated a table that sat directly above or below them.
 
 **The schedule must be self-contained.** Opaque codes pulled from internal reports (`FC-5`, `UC-12`, `M1`, decision-item letters, …) must not appear unresolved. Choose one per identifier: **Form A** (≤3 codes) — replace the code inline with a 5–20 character one-line description of the item; **Form B** (≥4 recurring codes) — keep the codes and emit a `## Glossary` table as the last section resolving every one. Decision-item letters (`A1`, `B2`, …) are approval items and may not appear at all. TASK-IDs listed in `## At a Glance` need neither.
 
-**Enforced:** `validators/validate-schedule.py` `_validate_format` rejects a schedule body carrying a blocking/approval item, and `_check_self_contained_identifiers` rejects a decision-item code and an unresolved opaque identifier that neither Form A nor a `## Glossary` row resolves.
+**Enforced:** `validators/validate-schedule.py` `_validate_format` rejects a `## Consolidated User Decision Checklist` heading, a `#### 사용자 확인 필요 항목` heading, and any checkbox item; it does not detect other approval content such as `Done`/`Ready?`/`Blocking Decisions` columns or an approval-request sentence. `_check_self_contained_identifiers` rejects a decision-item code and an unresolved opaque identifier that neither Form A nor a `## Glossary` row resolves.
 
 ## Contract SSOT — template + validator
 
-The installed template `~/.okstra/templates/reports/schedule.template.md` is the **byte-for-byte SSOT** for the output shape: frontmatter, top header block, the mandatory `##` heading list and order, per-task `Item / Detail` field labels and sub-section order, table column shapes, the ASCII Gantt format (relative day axis, plain fence, bar-only rows), the dependency-graph shapes, and the optional `## Glossary` gate. **Read the template before writing the schedule and follow it exactly** — do not re-derive section shapes from memory. Headings and field labels stay English literals regardless of the source-report language; body prose is Korean. When a section has no data, render its heading with `_none_` — never delete or reorder headings. Never emit mermaid or any graph DSL.
+The installed template `~/.okstra/templates/reports/schedule.template.md` is the **byte-for-byte SSOT** for the output shape: frontmatter, top header block, the mandatory `##` heading list and order, per-task `Item / Detail` field labels and sub-section order, table column shapes, the ASCII Gantt format (relative day axis, plain fence, bar-only rows), the dependency-graph shapes, and the optional `## Glossary` gate. **Read the template before writing the schedule and follow it exactly** — do not re-derive section shapes from memory. Headings and field labels stay English literals regardless of the source-report language; body prose is Korean. When a section has no data, render its heading with `_none_` — never delete or reorder headings, except `## Task Dependency Graph`, which is omitted when no task depends on another (Step 5). Never emit mermaid or any graph DSL.
 
-`~/.okstra/lib/validators/validate-schedule.py` is the enforcement for all of the above (heading order, field labels, controlled vocabulary — e.g. `Med-High` is the canonical risk form — forbidden translations, checkbox bans, Gantt fence rules, unresolved-code detection). The Step 4 ambiguous-classification rationale line is the one rule the validator does not yet enforce — emit it yourself.
+`~/.okstra/lib/validators/validate-schedule.py` enforces most of the above (heading order, field labels, controlled vocabulary — e.g. `Med-High` is the canonical risk form — forbidden translations, checkbox bans, Gantt fence rules, unresolved-code detection). It treats `## Task Dependency Graph` and `## Gantt Chart` as optional, and it does not refuse a risk, cross-task, or next-actions section (Step 4 bans them). The Step 4 ambiguous-classification rationale line is not enforced either — emit it yourself.
 
 One computation rule the template scaffold cannot carry inline:
 
@@ -175,7 +175,7 @@ Do not render `sliceValue` — it argues why the plan sliced the work this way,
 
 When the source is a Stage Map, the Gantt bars are selected stages. A row is labelled `Stage <n>` when exactly one task is scheduled, and `<TASK-ID> Stage <n>` when more than one is. Spell the stage out — `S1` costs the reader a lookup and saves five characters. A row is a label and a bar and nothing else: no `days=` annotation (the Work Breakdown owns those numbers, and the validator compares the bar against that column), and no per-row `! crit` / `est` markers, which distinguish nothing when every row carries them. One line above the fence states the column unit and what `█` and `░` mean — that is the whole legend, because those two glyphs are the only notation left. Split the task effort range proportionally by `step_count`; round every stage except the last to 0.5 day and let the last stage absorb the remainder. Cross-stage dependency annotations follow `depends_on`. Already-done and non-selected stages never get a bar. A task tagged `[NEEDS-PLANNING]` contributes no bars.
 
-**Bar geometry is checked, not decorative.** One column is half a day: a bar runs `lower / 0.5` filled cells `█` then `(upper - lower) / 0.5` open cells `░`. A bar drawn to any other width is a validation error, as is an axis whose last tick overshoots the scheduled work by 5 days or more.
+**Bar geometry is checked, not decorative.** One column is half a day: a bar runs `lower / 0.5` filled cells `█` then `(upper - lower) / 0.5` open cells `░`. A bar drawn to any other width is a validation error, as is an axis whose last tick overshoots the scheduled work by more than 5 days.
 
 **Every controlled code the schedule prints must be defined on the page.** The template's `### Priority & Risk Scale` resolves `P0`–`P3` and `Very Low`–`High`; the validator requires that subsection and both header literals. Stage labels are spelled out for the same reason — Gantt rows read `Stage 3`, and `Depends On` cells read `None` / `Stage 2` / `Stage 1 (done)` rather than a bare number the reader has to match against the Stage column of the same table. A reader who never saw the source report cannot rank `P0` against `P1`, calibrate `High`, or expand `S3`; those are opaque codes wearing a friendlier shape.
 
@@ -229,13 +229,18 @@ When you do skip, insert in the section's position exactly: `> _Gantt Chart skip
 3. **Run the deterministic gate first.** Execute `python3 ~/.okstra/lib/validators/validate-schedule.py <draft> --selection-json <selection>`. Do not dispatch the narrative verifier when this exits non-zero.
 4. **Run the independent LLM verifier second.** Only after the deterministic gate passes, create
    `.okstra/agent-invocations/schedule-verification/<invocation-id>.instructions.md` containing the draft,
-   selection JSON, and checks below, but none of the lead's reasoning. Materialize its sibling `.prompt.md`
-   with `okstra agent-prompt materialize`, `--purpose schedule-verification`,
-   `--audience schedule-verifier`, the current host runtime, the selected provider, and
-   `--model-role analyser`. Run `okstra agent-prompt verify` against the returned `metadataPath` before
-   dispatch. A native host call receives the verified prompt body and `hostModelValue`; a deterministic
-   provider process runs `okstra worker-dispatch` with the prompt path and `modelExecutionValue`. These
-   values are not interchangeable.
+   selection JSON, and checks below, but none of the lead's reasoning. Ask the runtime what this operation
+   runs — `okstra agent-prompt resolve-operation --operation schedule-verification` prints the duty, the
+   verifier count, and each slot's provider and model; the contract owns them, so do not choose a role or
+   provider here. Materialize its sibling `.prompt.md` with
+   `okstra agent-prompt materialize`, `--purpose schedule-verification`, `--audience <dutyId>`, the
+   current host runtime, and that slot's `--provider` and `--model <modelRef>`. Run
+   `okstra agent-prompt verify` against the returned `metadataPath` before dispatch. A native host call receives the verified prompt body and `hostModelValue`; a deterministic
+   provider process runs the provider wrapper
+   `~/.okstra/bin/okstra-<provider>-exec.sh <projectRoot> <modelExecutionValue> <prompt-path>`
+   (`okstra worker-dispatch` dispatches only a run manifest's assignments, not a standalone prompt). The
+   wrapper records the provider's output in the prompt path with `.md` replaced by `.log`. These values are
+   not interchangeable.
    The verifier returns `pass` plus concrete findings. Give it these checks:
    - **Executable ordering** — stage sequence, `Depends On`, and Gantt bar positions tell the same story; nothing depends on something scheduled after it.
    - **Arithmetic** — the Work Breakdown `Days` column sums to the At a Glance `Days` cell and to the `Effort sum` line.
@@ -262,7 +267,7 @@ Reached only after both Step 5.5 gates return `pass`. Promote the verified same
 .okstra/tasks/<task-group-segment>/schedule/<task-group-segment>-plan-<YYYY-MM-DD_HH-MM-SS>.md
 ```
 
-`<task-group-segment>` comes from the manifest's `taskGroupPathSegment` verbatim. Timestamp is current local time. Auto-create the parent directory. Never overwrite an existing file — on a same-second collision append `-2`, `-3`, ….
+`<task-group-segment>` is the parent directory name of the `Task root` that `okstra stage-map` printed in Step 3, used verbatim. Timestamp is current local time. Auto-create the parent directory. Never overwrite an existing file — on a same-second collision append `-2`, `-3`, ….
 
 ### Step 7: Self-validate before reporting completion
 
@@ -301,7 +306,7 @@ Reached only after both Step 5.5 gates return `pass`. Promote the verified same
 | either validation gate still fails after two revisions | Final file not written; report residual findings to the user |
 | `task-group` matches no tasks | "That task-group could not be found." and stop |
 | Catalog and manifest disagree on `workStatus` | Manifest wins (catalog may be stale) |
-| task-group casing / punctuation variants | Normalise both sides (lowercase + strip non-`[a-z0-9]`), compare against `taskGroupPathSegment` only; use the manifest's segment verbatim for path output |
+| task-group casing / punctuation variants | `schedule-input` matches them: it lowercases the argument and the group part of each catalog task key and drops every non-alphanumeric character (Unicode letters and digits stay); use the Step 6 segment verbatim for path output |
 
 ## Output Rules
 

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

@@ -96,18 +96,19 @@ targets; follow the host's permission mechanism if either remains blocked.
 okstra preflight --runtime <host-runtime>
 ```
 
-Read the fixed `Okstra preflight`, `Project root`, `Project JSON`, `Project ID`,
-`Reason`, and `Recovery` lines.
+Read the fixed `Okstra preflight` line. On `Okstra preflight: ready` the output
+carries `Project ID` and `Project root`; on `Okstra preflight: failed` it carries
+`Stage`, `Reason`, and `Recovery`, and no `Project root` line.
 
-- `Ok: true` → carry `Project root` as a literal absolute string and paste it into every subsequent command in this skill.
-- `Ok: false`, `Stage: resolve` → ask the user (`AskUserQuestion`, free text) for an absolute project root and rerun as a separate Bash tool call with the literal absolute path:
+- `Okstra preflight: ready` → carry `Project root` as a literal absolute string and paste it into every subsequent command in this skill.
+- `Okstra preflight: failed`, `Stage: resolve` → ask the user (`AskUserQuestion`, free text) for an absolute project root and rerun as a separate Bash tool call with the literal absolute path:
 
   ```bash
   okstra preflight --runtime <host-runtime> --cwd /abs/path/from/user
   ```
 
-- `Ok: false`, `Stage: project_json_missing` → proceed to Step 3 (this is the normal create path).
-- `Ok: false`, any other `Stage` (`python`, `parse`, `project_json_invalid`) → show the fixed `Reason` line to the user verbatim and follow the `Recovery` line (typically `okstra doctor --runtime <host-runtime>` to diagnose, then `okstra ensure-installed --runtime <host-runtime>` or re-running the Step 1 install). `Reason` is the SSOT — do not hand-enumerate stage causes.
+- `Okstra preflight: failed`, `Stage: project_json_missing` → proceed to Step 3 (this is the normal create path). The project root appears only inside the `Reason` path (`<root>/.okstra/project.json not found — ...`); take the root from that path.
+- `Okstra preflight: failed`, any other `Stage` (`install`, `helper_scripts_missing`, `python`, `parse`, `project_json_invalid`, `runtime_readiness`) → show the fixed `Reason` line to the user verbatim and follow the `Recovery` line (typically `okstra doctor --runtime <host-runtime>` to diagnose, then `okstra ensure-installed --runtime <host-runtime>` or re-running the Step 1 install). `Reason` is the SSOT — do not hand-enumerate stage causes.
 
 ## Step 3: Project metadata setup
 
@@ -129,10 +130,11 @@ If the file does NOT exist, ask via `AskUserQuestion`:
 
 - **Question**: `"Project id for okstra (e.g. INV-1234, my-app, okstra)"`
 - **Validate**: the answer must be non-empty AND contain at least one
-  alphanumeric character. Re-ask on empty input — `okstra setup --yes`
-  with no `--project-id` exits 1 with
-  `error: --project-id is required (no existing project.json, not a TTY)`,
-  so passing the user's empty answer through is a silent failure path.
+  alphanumeric character. Re-ask on empty input — `okstra setup` exits 1
+  on an empty `--project-id` value or an id with no alphanumeric character,
+  and `okstra setup --yes` with no `--project-id` and no existing
+  `project.json` exits 1 with
+  `error: --project-id is required (no existing project.json, not a TTY)`.
 
 Then create the file — paste the literal `projectRoot` from Step 2 and the literal `projectId` from the user's answer (no shell variables):
 

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

@@ -81,8 +81,9 @@ form only. Representative denied tokens: `--fix` / `--write` (formatters),
 (`_DENIED_LITERAL_TOKENS` / `_DENIED_SUBSTRINGS` plus the dynamic
 `npm install` and `INSTA_UPDATE=` checks) — do not re-enumerate it here.
 
-Encountering a denied token aborts the verifier with status
-`contract-violated`; re-declare the command in check-only form to recover
+A declared denied token makes okstra refuse to prepare an `implementation`
+or `final-verification` run, with an error naming the token (other task types
+do not read `qaCommands`); re-declare the command in check-only form to recover
 (e.g. swap `prettier --write` → `prettier --check`).
 
 The field is preserved across the runtime's auto-upserts of `project.json`, so
@@ -134,7 +135,7 @@ and `validators/validate-run.py::_validate_conformance`.
 
 ## C. Project-local Claude settings symlink and workspace trust
 
-`okstra setup` (and `okstra run` on its first invocation per project)
+`okstra setup` (and every `okstra run` prepare that is not render-only)
 provisions `<PROJECT_ROOT>/.claude/settings.local.json` as a symlink to
 `~/.okstra/templates/settings.local.json`. The template contains the Bash
 permission rules required for the codex/antigravity worker wrappers:
@@ -159,9 +160,9 @@ If a non-symlink `.claude/settings.local.json` already exists, setup backs it
 up to `.claude/settings.local.json.bak.<timestamp>` before installing the
 symlink — surface that to the user so they can merge project-specific rules
 back (the symlinked template is okstra-owned and refreshed on okstra updates).
-To opt out (advanced): replace the symlink with a regular file; okstra will
-back it up as `.bak.<timestamp>` on its next setup call rather than
-overwriting silently.
+There is no persistent opt-out: a regular file or foreign symlink put in
+its place is backed up as `.bak.<timestamp>` and replaced with the symlink on
+the next `okstra setup` or run prepare.
 
 ## D. Project PR body template (release-handoff)
 

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

@@ -10,7 +10,7 @@ description: >-
 
 # OKSTRA Usage
 
-Read-only project usage snapshot. The CLI owns every sum; never re-add rows.
+Project usage snapshot. The skill itself writes nothing. `okstra usage-report` resolves every catalog task by task-key, and that lookup self-heals a finished implementation phase. When a task's current phase is `implementation`, that lookup appends a `done` row to `runs/implementation-planning/consumers.jsonl` for each stage whose carry file is complete but has no settled row, and when every stage of the latest plan has a `done` row and a pass-grade carry it marks the phase completed in `task-manifest.json` (`workflow`, `phaseOutcome.implementation`) and refreshes that task's catalog entry. Nothing else is written. The CLI owns every sum; never re-add rows.
 
 ## Step 0: Preflight
 

package/runtime/skills/okstra-user-response/SKILL.md

@@ -156,7 +156,7 @@ Every value, rationale, and reason body file must be a regular file under `<proj
 okstra user-response answer --transaction <transaction> --clarification-id <C-NNN> --kind <kind> --disposition <disposition> --value-file <value.md> [--rationale-file <rationale.md>]
 ```
 
-The two answer forms are mutually exclusive. The command validates that the clarification ID and kind exist and remain open in the selected report. Repeating the same answer command is safe.
+The two answer forms are mutually exclusive. The command validates that the clarification ID exists once in the selected report, that its kind matches, and that its status is `open` or `answered` — an item answered in an earlier response can be answered again. Within one transaction, a repeated answer for the same ID replaces the earlier one, so repeating the same command is safe.
 
 ## Step 6: Record an explicit decision when present
 

package/runtime/templates/manager/view.template.html

@@ -75,6 +75,7 @@ code { font: 12px/1.4 ui-monospace, SFMono-Regular, Menlo, monospace; word-break
 .chip.running { color: var(--running); }
 .chip.done { color: var(--done); }
 .chip.blocked { color: var(--blocked); }
+.chip.unlinked { color: var(--missing); }
 .task-head { display: flex; flex-wrap: wrap; gap: 8px 16px; align-items: baseline; margin-bottom: 8px; }
 .counts { display: flex; flex-wrap: wrap; gap: 6px; }
 .hint { color: var(--muted); font-size: 12px; margin: 6px 0 12px; }

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

@@ -42,6 +42,14 @@ The synthesis packet's Authoring Contract names which of these are **required**
 
 Any other top-level name is rejected however reasonable it reads — a section title copied out of a lead procedure document (`Clarification Response Carried In`, `Stage Map`, `Rollback Strategy`) is a heading in that document, not a top-level field here. Nested names come from the task's block in `schemas/final-report-v3.0.schema.json`; when a name is refused, the parser's message lists the names allowed at that exact position, so correct against that list rather than guessing a second time.
 
+**Implementation-planning direction branch.** A selected-direction narrative carries `selectedDirectionRef` and `directionRealization`; the `P-Dir-1` verifier checks that realization against the selected core mechanism, architecture boundaries, planning invariants, and any hidden direction change. A legacy candidate-comparison narrative retains `P-Opt-*` option comparison semantics. These are plan-body judgments, not frontmatter fields owned by the writer. Four `directionRealization` fields — `coreMechanism`, `architectureBoundaries`, `planningInvariants`, `userConstraints` — are verbatim copies of the selected-direction snapshot and report assembly overwrites them from that snapshot at publication: do not paraphrase them; spend the writing on the fields the writer actually owns (`fileStructure` and the other realization fields).
+
+**Implementation-option-selection comparison.** Candidate details remain direction-level and must not claim planning precision:
+
+```json
+{"candidateDetailBoundary":{"expectedChangeAreas":"direction-level-only","expectedVerification":"direction-level-signals-only","forbidden":["exact-file-lists","stage-lists","test-commands"]}}
+```
+
 ## Pointer record
 
 The pointer record names the project-relative narrative path and audit sidecar path. It does not contain the narrative, worker result corpus, or any machine-owned ledger.

package/runtime/templates/reports/brief.template.md

@@ -34,10 +34,15 @@ candidate-cap: 8                                 # codebase-scan only: 1..12, de
 
 <!-- author guidance — strip out at fill-in time:
 Paste each source separately and as-is. No paraphrasing, summarizing, or
-restructuring. Format conversion (e.g. Jira ADF → Markdown) is allowed and
-must be annotated in the header meta. Heading was originally
-"Source Material (verbatim — do not modify)" — the parenthetical is a
-reviewer note, not body text.
+restructuring. Length is never a reason to excerpt: capture the record in
+full — for a ticket that means title, body, every comment, status, labels,
+assignee and linked/child issue references, not the body alone. Format
+conversion (e.g. Jira ADF -> Markdown) is allowed and must be annotated in
+the header meta. Anything the fetch could not deliver (a truncated body, an
+attachment returned as a link, an opaque embed node) gets a
+`conversion-block:` row in Open Questions naming what is missing. Heading was
+originally "Source Material (verbatim — do not modify)" — the parenthetical
+is a reviewer note, not body text.
 -->
 
 ### Source 1 — <type: file | linear | jira | github | notion | url | user-input>
@@ -145,6 +150,11 @@ than downstream. -->
 
 ## Constraints
 
+<!-- Author guidance: this section also records what the source asked for and
+this task deliberately leaves out. One bullet per dropped item, written as
+`out of scope: <the source's item> — <why>`. Dropping a source requirement
+without that line is indistinguishable from overlooking it. -->
+
 <Deadlines, compatibility, technical/operational limits. Use _(none)_ if
 none.>
 

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

@@ -57,10 +57,6 @@
       "brief": "Brief",
       "clarification": "Your answer"
     },
-    "handoffMode": {
-      "whole-task": "Whole task",
-      "stage-group": "Selected stages"
-    },
     "workerStatus": {
       "completed": "Completed",
       "error": "Failed",
@@ -652,6 +648,11 @@
       "handoff-scope": "Handoff scope",
       "the-behaviour-you-chose": "The behaviour you chose",
       "handoff-mode": "Handoff mode",
+      "stages-shipped": "Stages shipped:",
+      "release-base": "Release base:",
+      "stage": "Stage",
+      "pr-head": "PR head branch",
+      "pr-base": "PR base branch",
       "conflict-check": "Conflict check",
       "pr-body": "PR Body",
       "branch-and-pr": "Branch and PR",

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

@@ -57,10 +57,6 @@
       "brief": "브리프",
       "clarification": "사용자 답변"
     },
-    "handoffMode": {
-      "whole-task": "태스크 전체",
-      "stage-group": "선택한 stage"
-    },
     "workerStatus": {
       "completed": "완료",
       "error": "실패",
@@ -652,6 +648,11 @@
       "handoff-scope": "인계 범위",
       "the-behaviour-you-chose": "선택한 동작",
       "handoff-mode": "인계 방식",
+      "stages-shipped": "내보낸 stage:",
+      "release-base": "릴리스 base:",
+      "stage": "stage",
+      "pr-head": "PR head 브랜치",
+      "pr-base": "PR base 브랜치",
       "conflict-check": "충돌 확인",
       "pr-body": "PR 본문",
       "branch-and-pr": "브랜치와 PR",

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

@@ -12,7 +12,10 @@
 {% if handoff.get("handoffScope") %}
 <section data-report-section="handoff-scope" data-report-field="releaseHandoff.handoffScope">
   <h2>{{ t('tasks.release-handoff.handoff-scope') }}</h2>
-  <p><strong>{{ handoff.handoffScope.mode | enum_label("handoffMode") }}</strong>{% if handoff.handoffScope.get("stages") %} — stages {{ handoff.handoffScope.stages | join(", ") }}{% endif %}{% if handoff.handoffScope.get("collectorBranch") %} · Collector branch <code>{{ handoff.handoffScope.collectorBranch }}</code>{% endif %}</p>
+  <p><strong>{{ t('tasks.release-handoff.stages-shipped') }}</strong> {{ handoff.handoffScope.stages | join(", ") }} · {{ t('tasks.release-handoff.release-base') }} <code>{{ handoff.handoffScope.releaseBase }}</code></p>
+  {% if handoff.handoffScope.get("stagePlan") %}
+  <table><thead><tr><th>{{ t('tasks.release-handoff.stage') }}</th><th>{{ t('tasks.release-handoff.pr-head') }}</th><th>{{ t('tasks.release-handoff.pr-base') }}</th></tr></thead><tbody>{% for row in handoff.handoffScope.stagePlan %}<tr><td>{{ row.stage }}</td><td><code>{{ row.headBranch }}</code></td><td><code>{{ row.baseBranch }}</code> ({{ row.baseKind }})</td></tr>{% endfor %}</tbody></table>
+  {% endif %}
 </section>
 {% endif %}
 
@@ -25,22 +28,22 @@
   <h2>{{ t('tasks.release-handoff.branch-and-pr') }}</h2>
   {{ render_narrative(narrative.branchAndPrExplanation, "releaseHandoff.userNarrative.branchAndPrExplanation") }}
   <p><strong>{{ t('tasks.release-handoff.branch') }}</strong> {{ handoff.featureBranchState.branchName }}</p>
-  <p data-report-field="releaseHandoff.pullRequestOutcome"><strong>{{ t('tasks.release-handoff.pr-result') }}</strong> {{ handoff.pullRequestOutcome.kind }}{% if prUrl %} · <a href="{{ prUrl }}" rel="noopener noreferrer">{{ t('tasks.release-handoff.pull-request-open') }}</a>{% endif %}</p>
+  <ul data-report-field="releaseHandoff.pullRequestOutcomes">{% for row in prOutcomes %}<li><strong>{{ t('tasks.release-handoff.pr-result') }}</strong> stage {{ row.stage }} — {{ row.kind }}{% if row.get("baseBranch") %} → <code>{{ row.baseBranch }}</code>{% endif %}{% if row.get("url") %} · <a href="{{ row.url }}" rel="noopener noreferrer">{{ t('tasks.release-handoff.pull-request-open') }}</a>{% endif %}{% if row.get("reason") %} · {{ row.reason }}{% endif %}</li>{% endfor %}</ul>
 </section>
 
 <section data-report-section="conflicts" data-report-field="releaseHandoff.mergeConflictProbe">
   <h2>{{ t('tasks.release-handoff.conflict-verdict') }}</h2>
   {{ render_narrative(narrative.conflictExplanation, "releaseHandoff.userNarrative.conflictExplanation") }}
   {{ summary_card(handoff.mergeConflictProbe.kind, t('tasks.release-handoff.base-branch') ~ " " ~ (handoff.mergeConflictProbe.baseBranch | default('not-run'))) }}
+  {% if handoff.mergeConflictProbe.get("conflictingStages") %}<p>{{ t('tasks.release-handoff.stage') }} {{ handoff.mergeConflictProbe.conflictingStages | join(", ") }}</p>{% endif %}
   {% if handoff.mergeConflictProbe.get("conflictingPaths") %}<ul>{% for path in handoff.mergeConflictProbe.conflictingPaths %}<li>{{ path }}</li>{% endfor %}</ul>{% endif %}
 </section>
 
 <section data-report-section="delivered-commits" data-report-field="releaseHandoff.commitList">
   <h2>{{ t('tasks.release-handoff.commits-delivered') }}</h2>
   {% if handoff.commitList is mapping %}<p>{{ t('tasks.release-handoff.there-are-no-commits') }}</p>{% else %}
-  <table><thead><tr><th>{{ t('tasks.release-handoff.commit') }}</th><th>{{ t('tasks.release-handoff.subject') }}</th><th>{{ t('tasks.release-handoff.files') }}</th></tr></thead><tbody>{% for row in handoff.commitList %}<tr>{{ row_key(pairs=[(t('macros.layout.sha'), row.shortSha), (t('macros.layout.order'), loop.index)]) }}<td>{{ row.subject | inline_code }}</td><td>{{ file_paths(row.files) }}</td></tr>{% endfor %}</tbody></table>{% endif %}
-  {% if handoff.get("sourceVerificationReports") %}<p data-report-field="releaseHandoff.sourceVerificationReports"><strong>{{ t('tasks.release-handoff.the-verification-report-this-rests-on') }}</strong>{% for row in handoff.sourceVerificationReports %} — stage {{ row.stage }}: <code>{{ row.path }}</code> · {{ row.verdictTokenQuote | inline_code }}{% endfor %}</p>
-  {% else %}<p data-report-field="releaseHandoff.sourceVerificationReport"><strong>{{ t('tasks.release-handoff.the-verification-report-this-rests-on') }}</strong> — <code>{{ handoff.sourceVerificationReport.path }}</code> · {{ handoff.sourceVerificationReport.verdictTokenQuote | inline_code }}</p>{% endif %}
+  <table><thead><tr><th>{{ t('tasks.release-handoff.stage') }}</th><th>{{ t('tasks.release-handoff.commit') }}</th><th>{{ t('tasks.release-handoff.subject') }}</th><th>{{ t('tasks.release-handoff.files') }}</th></tr></thead><tbody>{% for row in handoff.commitList %}<tr><td>{{ row.get("stage", "") }}</td>{{ row_key(pairs=[(t('macros.layout.sha'), row.shortSha), (t('macros.layout.order'), loop.index)]) }}<td>{{ row.subject | inline_code }}</td><td>{{ file_paths(row.files) }}</td></tr>{% endfor %}</tbody></table>{% endif %}
+  <p data-report-field="releaseHandoff.sourceVerificationReports"><strong>{{ t('tasks.release-handoff.the-verification-report-this-rests-on') }}</strong>{% for row in handoff.sourceVerificationReports %} — stage {{ row.stage }}: <code>{{ row.path }}</code> · {{ row.verdictTokenQuote | inline_code }}{% endfor %}</p>
 </section>
 
 <section data-report-section="next-action">

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

@@ -239,7 +239,7 @@
       "allowedOptions": "Allowed options"
     },
     "h1Body": "Which action should run?",
-    "h2Body": "PR base branch (when H1 = `push + PR`)",
+    "h2Body": "Release base branch (when H1 = `push + PR`)",
     "h3Body": "How should the PR title/body draft be handled?",
     "h2DefaultLabel": "(n/a)",
     "h2OptionsLabel": "staging / preprod / main / user input",

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

@@ -6,7 +6,7 @@
 {{ s.section("releaseHandoff.handoffScope", "Handoff Scope") }}
 {{ s.section("releaseHandoff.userSelections", "User Selections") }}
 {{ s.section("releaseHandoff.featureBranchState", "Feature Branch State") }}
-{{ s.section("releaseHandoff.pullRequestOutcome", "Pull Request Outcome") }}
+{{ s.section("releaseHandoff.pullRequestOutcomes", "Pull Request Outcomes") }}
 {{ s.section("releaseHandoff.mergeConflictProbe", "Merge Conflict Probe") }}
 {{ s.section("releaseHandoff.executedCommands", "Executed Commands") }}
 {{ s.section("releaseHandoff.routingRecommendation", "Routing Recommendation") }}

package/runtime/templates/reports/release-handoff-input.template.md

@@ -25,8 +25,7 @@ taskType: "{{FM_TASK_TYPE}}"
 
 ## Source Verification Report
 
-- Mode: `{{HANDOFF_MODE}}`
-- Stages: `{{HANDOFF_STAGES}}`
+- Stages: `{{HANDOFF_STAGES}}` — one PR per stage.
 - Reports (one row per cited `final-verification` final-report; the verdict must be release-ready).
   **Enforced:** `validators/validate-run.py` routes through
   `okstra_ctl.release_gate.release_handoff_allowed`, which passes `accepted` and
@@ -47,11 +46,14 @@ taskType: "{{FM_TASK_TYPE}}"
 - Existing implementation commits (`git log --oneline <base>..HEAD`):
 - Existing PR for this head, if any (`gh pr list --head <branch> --state open --json url --jq '.[0].url'`):
 
-## Candidate PR Base Branches
+## Candidate Release Base Branches
+
+The user picks ONE release base for the whole run. Each stage's own PR base is then derived from its `depends-on` by `okstra handoff pr-plan`: a stage with no live dependency targets the release base, a stage with one targets that stage's branch (a stacked PR), and a stage with several targets a branch merging them.
 
 - Default options offered to the user: `staging` | `preprod` | `prod` | `main` | `dev` | custom input
 - Repo-specific preference, if known (e.g. `main` is the integration branch):
 - Branches that are off-limits as a base in this repo (security / freeze rules):
+- Merge order the stack implies (merge a stage's PR only after its base PR):
 
 ## PR Draft Inputs
 
@@ -69,7 +71,7 @@ taskType: "{{FM_TASK_TYPE}}"
 ## User-Selection Defaults (advisory only — the user still chooses interactively)
 
 - Suggested action (Q1): `local checkout` | `push + PR` | `skip`
-- Suggested base (Q2): one of the candidate base branches above
+- Suggested release base (Q2): one of the candidate base branches above
 - Suggested message handling (Q3): `use as-is` | `edit then proceed`
 
 > These suggestions help the lead phrase its `AskUserQuestion` prompts. They are NOT pre-approvals — every mutating command still requires an explicit user pick at run time.