okstra 0.201.3 → 0.204.0

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):
 
@@ -140,6 +142,15 @@ Then create the file — paste the literal `projectRoot` from Step 2 and the lit
 okstra setup --yes --project-root /abs/path/to/projectRoot --project-id my-project-id
 ```
 
+`okstra setup` also refreshes the okstra-managed citation-guidance block in
+`<PROJECT_ROOT>/CLAUDE.md` and `AGENTS.md` when those files already exist (it never
+creates them). The block tells agents not to carry okstra-internal references — report
+section numbers, `C-NNN` clarification ids, run/stage ids, `.okstra/...` paths — into
+writing that is not an okstra report, where the reader cannot resolve them. The command
+reports the files it touched in its JSON `citationGuidance` array; a failure there is a
+`warning:` line, not a non-zero exit. Tell the user which guidance files were updated so
+they can review the appended block.
+
 ## Step 3.5 (optional): project customisation
 
 The built-in defaults work for most projects — skip straight to Step 4

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

@@ -0,0 +1,109 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>{{TITLE}}</title>
+<style>
+:root {
+  --bg: #f7f7f5;
+  --panel: #ffffff;
+  --text: #1f2328;
+  --muted: #5f6670;
+  --line: #d9dbde;
+  --planned: #6e7781;
+  --missing: #9a6700;
+  --running: #0969da;
+  --done: #1a7f37;
+  --blocked: #cf222e;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #111418;
+    --panel: #1a1f25;
+    --text: #e6e8eb;
+    --muted: #9aa3ad;
+    --line: #2f363e;
+    --planned: #8b949e;
+    --missing: #d29922;
+    --running: #58a6ff;
+    --done: #3fb950;
+    --blocked: #f85149;
+  }
+}
+* { box-sizing: border-box; }
+body {
+  margin: 0;
+  background: var(--bg);
+  color: var(--text);
+  font: 14px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", "Apple SD Gothic Neo", "Noto Sans KR", sans-serif;
+}
+main { max-width: 1200px; margin: 0 auto; padding: 24px 16px 48px; }
+header h1 { margin: 0 0 4px; font-size: 22px; }
+.meta { color: var(--muted); font-size: 13px; }
+section { margin-top: 28px; }
+h2 { font-size: 17px; margin: 0 0 10px; }
+h3 { font-size: 15px; margin: 0; }
+.panel {
+  background: var(--panel);
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  padding: 16px;
+  margin-bottom: 16px;
+}
+.tiles { display: grid; grid-template-columns: repeat(auto-fit, minmax(120px, 1fr)); gap: 10px; }
+.tile { background: var(--panel); border: 1px solid var(--line); border-radius: 8px; padding: 10px 12px; }
+.tile .count { font-size: 24px; font-weight: 600; }
+.tile .label { color: var(--muted); font-size: 12px; text-transform: uppercase; letter-spacing: 0.04em; }
+.scroll { overflow-x: auto; }
+table { width: 100%; border-collapse: collapse; }
+th, td { text-align: left; padding: 7px 10px; border-bottom: 1px solid var(--line); vertical-align: top; }
+th { color: var(--muted); font-weight: 600; font-size: 12px; white-space: nowrap; }
+.wrap { display: inline-block; min-width: 220px; }
+code.id { white-space: nowrap; word-break: normal; }
+code { font: 12px/1.4 ui-monospace, SFMono-Regular, Menlo, monospace; word-break: break-all; }
+.chip {
+  display: inline-block;
+  padding: 1px 8px;
+  border-radius: 999px;
+  border: 1px solid currentColor;
+  font-size: 12px;
+  white-space: nowrap;
+}
+.chip.planned { color: var(--planned); }
+.chip.missing { color: var(--missing); }
+.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; }
+details { margin-top: 10px; }
+summary { cursor: pointer; color: var(--muted); }
+ul.plain { margin: 6px 0 0; padding-left: 18px; }
+.empty { color: var(--muted); }
+a { color: var(--running); }
+</style>
+</head>
+<body>
+<main>
+<header>
+<h1>{{TITLE}}</h1>
+<div class="meta">{{META}}</div>
+</header>
+<section>
+<h2>Summary</h2>
+{{SUMMARY}}
+</section>
+<section>
+<h2>Projects</h2>
+{{PROJECTS}}
+</section>
+<section>
+<h2>Manager tasks</h2>
+{{TASKS}}
+</section>
+</main>
+</body>
+</html>

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",
@@ -371,6 +367,8 @@
     "final-verification": {
       "verification-verdict": "Verification verdict",
       "result-per-requirement": "Result per requirement",
+      "requirement": "Requirement",
+      "evidence": "Evidence",
       "what-the-change-added": "What the change added",
       "traced-to": "Serves",
       "callers": "Callers",
@@ -650,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": "실패",
@@ -371,6 +367,8 @@
     "final-verification": {
       "verification-verdict": "검증 판정",
       "result-per-requirement": "요구사항별 결과",
+      "requirement": "요구사항",
+      "evidence": "근거",
       "what-the-change-added": "이 변경이 추가한 것",
       "traced-to": "봉사하는 요구사항",
       "callers": "호출자",
@@ -650,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/final-verification.template.html

@@ -1,6 +1,5 @@
 {% extends "html/base.template.html" %}
 {% from "html/macros/layout.html" import narrative as render_narrative, row_key %}
-{% from "html/macros/visualizations.html" import figure %}
 
 {% block human_content %}
 <section data-report-section="verification-verdict">
@@ -22,7 +21,8 @@
 <section data-report-section="requirement-results" data-report-field="finalVerification.validationEvidence">
   <h2>{{ t('tasks.final-verification.result-per-requirement') }}</h2>
   {{ render_narrative(narrative.coverageExplanation, "finalVerification.userNarrative.coverageExplanation") }}
-  {{ figure(coverageFigure, anchor_nodes=true) }}
+  <div class="table-scroll"><table><thead><tr><th>{{ t('macros.layout.id') }}</th><th>{{ t('tasks.final-verification.requirement') }}</th><th>{{ t('macros.layout.status') }}</th><th>{{ t('tasks.final-verification.evidence') }}</th></tr></thead>
+  <tbody>{% for row in final.validationEvidence %}<tr id="id-{{ row.id }}"><td>{{ row.id | inline_code }}</td><td>{{ row.requirement | inline_code }}</td><td><span class="status status-{{ row.status }}">{{ row.status }}</span></td><td>{{ row.artifact | inline_code }}</td></tr>{% endfor %}</tbody></table></div>
 </section>
 
 <section data-report-section="added-surface" data-report-field="finalVerification.addedSurfaceAudit">

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.

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

@@ -0,0 +1,36 @@
+# Translator Prompt Preamble (canonical)
+
+This file is the audience-specific contract for `translator`. Read it and the shared Worker Error Contract end-to-end. The task instructions in this prompt own this run's commands, paths, and target language; this file owns how you translate and what you may write.
+
+## Output ownership
+
+Write only the translations file at `**Result Path:**`, the completion pointer at `**Worker Result Path:**`, and the reading audit at `**Audit sidecar path:**`. The publish command named in the task instructions owns the sidecar the renderer overlays; do not write that file yourself.
+
+Never edit the report record, the narrative Markdown, the rendered HTML, or any project source file.
+
+Never add, remove, or re-order the `T-NNN` items relative to the work list you were given. Never translate a value the work list did not offer you: its absence is deliberate, because the renderer reads those values as machinery and a translated copy breaks the page silently.
+
+Never return the translated text inline. The file on disk is the artifact; your return message names the paths and the verification result.
+
+## Required reading
+
+Read the complete work list before translating any item, continuing in chunks when it is long. A partial read produces a partial sidecar, and the items you never saw render in the source language with no error raised.
+
+## How to translate
+
+Judge every term on whether the translation or the original carries the meaning faster to a working developer in the target language, and pick that one. The goal is a reader who understands the report sooner, not a document with no English left in it.
+
+- **Never touch**: code identifiers, file paths, CLI commands and flags, model names, commit SHAs, URLs, and anything already inside backticks. Reproduce them character for character.
+- **Keep the English word** when that is what developers in the target language actually say. Forcing a native coinage onto `commit`, `worktree`, `merge`, `lint`, `diff`, `stage`, `rollback` or `PR` makes the sentence *slower* to read, not more local.
+- **Translate the explanation.** Connective prose — why something matters, what a reader should do, what a finding means — is where the translation earns its place. Carry the meaning, not the word order.
+- **Do not translate literally.** A word-for-word rendering that is technically correct and unreadable has failed. Say what the sentence means the way a developer would say it.
+- **Gloss on first use, once.** When a technical term does need translating, write it as `<translation>(<English>)` the first time it appears in the document, then use the translation alone. Never gloss the same term twice.
+- **One claim per sentence.** Where the English stacks four clauses behind em-dashes, split it. The reader gains nothing from the original's punctuation.
+- **Match the register.** A verdict line is terse; a rationale paragraph is explanatory. Do not inflate a three-word cell into a sentence, or compress a paragraph into a fragment.
+- **Leave it out when you cannot do it justice.** An omitted item renders in the source language, which is a correct fallback. A confident mistranslation is not.
+
+## Failure handling
+
+A failing verification check means a pointer resolves nowhere — you altered or invented one. Fix the translation and run the check again; do not return while it fails.
+
+Record your own tool failures through the file named by `**Worker Error Contract Path:**`.

package/runtime/validators/checks/validate-assets-01.py

@@ -22,15 +22,14 @@ def check(source_path: Path, target_path: Path) -> None:
         errors.append(f"build-output asset does not match source: {target_path}")
 
 
-# 1. Worker agent files: agents/workers/*-worker.md -> runtime/agents/workers/*-worker.md
-#
-workers_source = agents_source_root / "workers"
-workers_target = runtime_root / "agents" / "workers"
-if not workers_source.is_dir():
-    errors.append(f"missing agents/workers source directory: {workers_source}")
+# 1. Agent contracts: agents/common.json + agents/roles/* + agents/operations/*
+#    -> runtime/agents/*. 호스트 전역 에이전트 정의는 더 이상 없다(ADR-0017).
+if not agents_source_root.is_dir():
+    errors.append(f"missing agents source directory: {agents_source_root}")
 else:
-    for source_path in sorted(workers_source.glob("*.md")):
-        check(source_path, workers_target / source_path.name)
+    for source_path in sorted(agents_source_root.rglob("*.json")):
+        relative = source_path.relative_to(agents_source_root)
+        check(source_path, runtime_root / "agents" / relative)
 
 # 2. Lead contract + internal lead resources: prompts/lead/* + prompts/coding-preflight/*
 #    -> runtime/prompts/*. These ship as runtime resources (okstra install copies