okstra 0.179.2 → 0.183.2

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

@@ -1,193 +1,164 @@
 ---
 name: okstra-user-response
 description: >-
-  Use this to answer an okstra task's open clarification questions in-session, without hand-editing any file. The tell is a request to respond to an okstra run's clarification items or its approval gate — "answer okstra", "I'll answer the questions", "clarification response", "user response", "approve and move on". This skill lists tasks whose latest report still has open clarification blockers, then walks the open C-ids one at a time — each rewritten as a self-contained question with background, its options with their impact plus "Enter directly" — echoes the collected answers back for an explicit "confirmed" acknowledgement, optionally records approval, and writes the `user-responses/` sidecar via `okstra user-response write`. NOT for starting a run (okstra-run), inspecting a finished task (okstra-inspect), or generating a brief (okstra-brief-gen). The skill never picks an answer — it builds the option board and transcribes what the user decides.
+  Use this to answer an okstra task's open clarification questions in-session without hand-editing a report or sidecar. It projects the available tasks and one report as fixed text, asks one question at a time, confirms the user's exact answers, and publishes only the user-owned user-responses sidecar through a typed transaction. NOT for starting a run, inspecting a finished task, or generating a brief.
 ---
 
 # OKSTRA User Response
 
-Single entry point for answering the clarification questions an okstra run left behind (the open `C-*` rows under the final report's `## 1. Clarification Items`) **in-session**, and recording those answers as a `runs/<type>/user-responses/` sidecar. The next `/okstra-run` auto-attaches this sidecar via `--clarification-response`.
+Use this skill for open `C-*` clarification items and explicit plan decisions. The user alone selects or writes every answer. Never infer an answer or approval.
 
-**Core principle — the skill never picks an answer for the user.** It builds the option board — background, a self-contained question, the report's options with their impact, `Enter directly` — and the user alone picks from it; every `value` is what the user chose or typed. It never calls `write` until the user has explicitly confirmed.
+The model-facing commands are fixed text reads and typed transaction writes:
 
-**Second principle — one question at a time.** Never batch two clarification items into one question, and never dump the whole open list at the user. Ask item 1, transcribe the answer, then ask item 2.
-
-| Sub-command | What it does |
+| Command | Purpose |
 |---|---|
-| `list` | List tasks that still have approval-open clarification, newest report first. |
-| `show` | Expand one report's open `C-*` rows (statement + options + contextRefs). |
-| `write` | Record the collected answers (+ optional approval) as a `user-responses/` sidecar. |
+| `user-response list-view` | Show tasks that still await user input. |
+| `user-response show-view` | Show questions, choices, resolved context, and current response state. |
+| `user-response begin` | Open a sidecar transaction for one report identity. |
+| `user-response answer` | Add or replace one validated clarification answer. |
+| `user-response plan-decision` | Record an explicit plan decision in the transaction. |
+| `user-response legacy-report-authoring` | Record legacy report-authoring permission for report contract 2.0 only. |
+| `user-response finalize` | Atomically merge and publish the user-owned sidecar. |
 
-## Step 0: Preflight (shared)
+Do not use the automation-oriented `list` or `show` commands. Do not open a report record to select fields. The fixed views provide every value this skill may use.
 
-Before anything:
+## Step 0: Preflight
 
 <!-- BEGIN FRAGMENT: bash-invocation-rule -->
 Run one Bash tool call, starting with the literal token `okstra` (never wrapped in `if`/`eval`/`export`/`$(...)`/`VAR=...`/`||`/`&&`/`npx` — a non-literal leading token defeats the `Bash(okstra:*)` permission match):
 <!-- END FRAGMENT: bash-invocation-rule -->
 
 ```bash
-okstra preflight --runtime claude-code --json
+okstra preflight --runtime claude-code
 ```
 
-Branch on the stdout JSON:
-- `ok: true` → carry `projectRoot` and `projectId` as literal strings; they are the base for every step below.
-- `ok: false` → this project has no okstra setup. Tell the user: "this project has no okstra setup. Run `/okstra-setup` first." Then stop. If the user pointed at a specific project directory, re-run targeting it: `okstra preflight --runtime claude-code --cwd <that-dir> --json` (`--cwd` is the sanctioned way to target a project — a leading `cd` would break the permission match); only if that **also** returns `ok:false` do you stop.
+On `Okstra preflight: failed`, show `Reason` and `Recovery`, then stop. On `Okstra preflight: ready`, carry the fixed `Project root` and `Project ID` lines as literal values.
 
 <!-- BEGIN FRAGMENT: preflight-outdated-cli -->
 If the call fails with `unknown command: preflight`, the `okstra` binary on PATH predates this skill — tell the user to update it (`npm i -g okstra@latest`), then stop (`/okstra-setup` does not update the binary).
 <!-- END FRAGMENT: preflight-outdated-cli -->
 
-Then resolve the okstra home once (the `list` sub-command needs it):
+Resolve the installed home:
 
 ```bash
 okstra paths --field home
 ```
 
-Paste the printed path literally into `--home` below.
-
 <!-- BEGIN FRAGMENT: python-bootstrap-note -->
 Every subsequent `okstra <subcmd>` call self-bootstraps its Python path, so this skill never needs `okstra paths --shell` / `export PYTHONPATH=...`.
 <!-- END FRAGMENT: python-bootstrap-note -->
 
-## Step 1: List awaiting tasks → picker
+## Step 1: Select a task from the fixed list view
 
 ```bash
-okstra user-response list --home <resolved-home> --project <projectId> --limit 3
+okstra user-response list-view --home <resolved-home> --project <projectId> --limit 3
 ```
 
-Returns a JSON array (latest report mtime first); each entry:
-`{taskKey, taskType, seq, reportPath, reportMtime, openBlockerCount, openApprovalCount, unreadable}`. `openBlockerCount` counts every open row that still owes the user an answer (`Blocks` = `approval` or `next-phase`); `openApprovalCount` is the `approval`-only subset that gates the frontmatter `approved` flip.
+The view gives `Task key`, `Task type`, `Report`, open-item counts, and readability status. If the count is zero, answer `No task has open clarification items.` and stop. Do not continue with an unreadable entry.
 
-- Empty array → answer `No task has open clarification items.` and stop.
-- Otherwise present a **3-option picker**: the top recommendations from the list (each shown as `taskKey (taskType, <openBlockerCount> open items)`), and the **final option is always "Enter directly"** — where the user pastes a `reportPath` or a `task-key` directly (for a task not in the top-3 window).
-- An entry with `unreadable: true` means its `## 1. Clarification Items` heading exists but drifted from the expected format. Flag it as `⚠ §1 format drift — the CLI could not parse its items` and do not proceed on it until the report is regenerated; do not fabricate rows for it.
+Present up to three task choices. The final picker option is `Enter directly`, where the user may provide a report path or task key.
 
-Carry the chosen entry's `reportPath` and `taskKey` forward.
-
-## Step 2: Fetch the open rows (data only — ask nothing yet)
+## Step 2: Read the fixed report view
 
 ```bash
-okstra user-response show --report <reportPath>
+okstra user-response show-view --report <reportPath> --project-root <projectRoot>
 ```
 
-Returns `{reportPath, rows: [{id, kind, blocks, status, statement, expectedForm, options, contextRefs, resolvedRefs}]}`.
-
-Each entry of `options[]` is `{role, answer, rationale, scopeImpact, addedWork, directionChange, disposition}`. `role` is `recommended` for exactly one entry and `alternative` for the rest; `scopeImpact` is a token list drawn from `in-repo` / `cross-repo` / `new-schema` / `deferrable`; `addedWork` and `directionChange` are one sentence each. Activity-contract v1 approval options also carry the gate action in `disposition`. A legacy schema-v1 report has nowhere to record impact or a gate action, so those fields arrive empty — the CLI reconstructs only the answers from the report's `Expected form` cell.
-
-`resolvedRefs` is `[{ref, definition}]` — the CLI has already looked up what each record coordinate (`RB-002`, `FU-001`) means in the report record; `definition` is `null` when the record has no such row, when the citation is a section number (`§4.7`, leftover from an older report), or when the citation is a `path:line` pointer.
-
-This call is a **data fetch, not a presentation step**. Do not print `rows` at the user, and do not paste a raw `statement` as a question — a `statement` like `Rewrite RB-002 rollback (see §4.7)` is meaningless on its own, which is the whole reason this skill exists. Announce only the count and the plan:
-
-> `<N>` open items — I'll go through them one at a time.
+The view contains the report identity, contract version, every open clarification question, its expected form, its current response and disposition, its options, approval context, plan option candidates, current plan decision, and resolved context. It is the only report-information source for this skill.
 
-Step 3 then turns exactly one row at a time into a question.
+Each entry in `options[]` corresponds to `{role, answer, rationale, scopeImpact, addedWork, directionChange, disposition}`. Put the `recommended` option first and suffix its label with `(Recommended)`. Then put the alternatives in view order and finish with `Enter directly`.
 
-## Step 3: Ask one item at a time (loop)
+Contract 3.0 options also expose `reach` and `scopeEffects`. Contract 3.0 approval-blocking rows expose `approvalContext`. Present those values exactly as the view prints them.
 
-Walk the open rows in report order. **One item per `AskUserQuestion` call** — never batch two items into one call, and never pre-announce the items still to come. Ask, transcribe, move on. Head each item with its position and what it is holding up:
+Each option description uses all three impact axes in this order:
 
-> **[2/5] C-014** — blocks: approval gate
+> `<rationale>` — Scope: `<scopeImpact>` · Added work: `<addedWork>` · Direction: `<directionChange>`
 
-### 3a. Background first (plain text, above the picker)
+When an axis says `not stated in the report`, repeat that text. Do not infer missing impact. The skill must **never invent it**.
 
-`AskUserQuestion` carries one sentence of question, so the background goes in the message text right before the call. Write these three blocks, **3–6 lines total** — enough that someone who never read the report can answer:
+## Step 3: Ask one clarification at a time
 
-1. **Situation** — what the run was doing when it stopped at this item, in the user's own domain terms.
-2. **What is undecided** — the actual fork, with every internal token expanded inline from `resolvedRefs[].definition`; the user must never need to know what `RB-002` is to answer. Say what is stuck right now in plain words: `blocks: approval` → the approval gate stays shut and `implementation` cannot start; `blocks: next-phase` → the next phase cannot begin.
-3. **What changes with your answer** — what each direction actually causes downstream.
+For each item that still needs an answer, show its position, ID, blocking effect, question, expected form, and resolved context. Use one single-select question per clarification.
 
-Where the background comes from — in this order:
+Use the displayed values to confirm the user's choice. Do not copy a predefined option's answer, disposition, reach, or scope effects into command arguments. The typed command resolves those report-owned fields from its option number.
 
-- `resolvedRefs[].definition`, which is already resolved and needs no file read;
-- when a `definition` is `null`, or the three blocks would otherwise be empty, **Read** the report record (the `.data.json` at `reportPath`) and take the cited row's `statement` / `summary` / `item` from there. Do not open the full reading copy to chase a `§` number — that number is not a record coordinate;
-- **never invent it.** If the report genuinely does not say why, write `The report states nothing beyond the statement itself.` and go straight to the question. Fabricated background corrupts the answer it collects.
-
-Close the background with the raw source on one line, so the mapping back to the report stays visible:
-
-> Source: `C-014` — "<raw statement>"
-
-### 3b. The picker — the report's options plus `Enter directly`
-
-One `AskUserQuestion` (single-select). Fill the slots from `options[]` in array order — the `role: recommended` entry first with its label suffixed `(Recommended)`, then the `alternative` entries — and always close with `Enter directly` as the last option. Never mark anything but the `recommended` entry as recommended.
-
-Each `label` is that option's `answer`, kept to the answer itself (1–5 words). Each `description` carries the rationale followed by the three impact axes, in this fixed order:
+| User action | Value | Disposition |
+|---|---|---|
+| Selects an option | that option's `answer` | that option's `disposition` |
+| Enters an answer | the user's text verbatim | `answer` |
+| Asks for the item to be presented again | the user's request verbatim | `reframe` |
 
-> `<rationale>` — Scope: `<scopeImpact, comma-joined>` · Added work: `<addedWork>` · Direction: `<directionChange>`
+Copy `kind` from the view. A `reframe` does not satisfy the gate. If the user asks what an item means, explain only from the view and ask the same item again.
 
-The three axes answer three different questions: how far the choice reaches, what new work it creates, and what it overturns. Never fold them into one phrase — whichever is easiest to write ends up standing in for the other two, and the user weighs a scope change as though it were free. That is the failure this board exists to prevent.
+## Step 4: Confirm the complete response
 
-When an axis is empty — a schema-v1 report has nowhere to record impact — write `not stated in the report` for that axis. Do not infer it, and do not read the code to reconstruct it. A guessed side effect is worse than a stated gap, because the user cannot tell the two apart.
+Echo each clarification ID, kind, disposition, value, and rationale. Include any explicit plan decision or legacy report-authoring decision. Ask:
 
-When `options[]` carries more than three entries, keep the recommended one plus the two alternatives whose `scopeImpact` differs most from it, and say in the background text how many you left out. When it carries exactly two, the picker has three options in total — do not pad it with an invented third.
+> Record it as shown above? Reply `confirmed` to publish the sidecar.
 
-### 3c. Transcribe the decision, then move on
+Do not start a transaction until the user clearly confirms. If the user changes an item, show the complete response again and reconfirm.
 
-Record one entry — `{id, kind, value, rationale?, disposition}`, `kind` copied from the row `show` returned:
+## Step 5: Begin the typed transaction
 
-| The user picks | `value` | `disposition` |
-|---|---|---|
-| One of the `options[]` entries | that option's `answer` text, not its short label | that option's `disposition` (`answer` only when absent on a legacy option) |
-| `Enter directly` → their own answer | the user's utterance verbatim (rationale into `rationale`) | `answer` |
-| Free text asking for the item to be re-asked | what the user wants re-asked, verbatim (empty → the raw statement) | `reframe` |
+```bash
+okstra user-response begin --report <reportPath> --task-key <taskKey>
+```
 
-A reframe is not an answer, so it does not satisfy the approval gate.
+Carry the returned opaque `transaction` value exactly. Do not decode it or inspect its state file.
 
-If the user replies with a question instead of an answer ("what does this mean?"), record nothing: **Read** the report record for the cited row id from `contextRefs[]`, explain it in plain language, and re-ask the same item with the same options. Explain only — **do not resolve it for them**; the decision goes back to the user.
+For a predefined option, pass only its one-based number from the fixed view:
 
-Echo one line per finished item (`[2/5] C-014 → answer: 60s`), then ask the next one. Do not summarize the whole set until Step 4.
+```bash
+okstra user-response answer --transaction <transaction> --clarification-id <C-NNN> --kind <kind> --option-number <N>
+```
 
-## Step 4: Echo the full sidecar back → explicit "confirmed" gate
+Every value, rationale, and reason body file must be a regular file under `<projectRoot>/.okstra/tmp/user-response/`; do not use an external file or a symbolic link. For a direct user answer, write the exact value there. Write the rationale to a separate Markdown file only when present. Then run:
 
-Once the loop has covered every open item, **before** calling `write`, **echo back** everything collected (each `id`, `disposition`, `value`, `rationale` if present, and the approval decision from Step 5 below) to the user as-is. Then ask for explicit confirmation:
+```bash
+okstra user-response answer --transaction <transaction> --clarification-id <C-NNN> --kind <kind> --disposition <disposition> --value-file <value.md> [--rationale-file <rationale.md>]
+```
 
-> Record it as shown above? (Reply `confirmed` to write the sidecar.)
+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.
 
-- **Never call `write`** until the user says `confirmed` (or gives clear approval).
-- If the user changes any item, show the echo-back again with the changed value and re-confirm.
-- Every `value` must be what the user picked or typed, never a wording you settled on for them — this gate guarantees that.
+## Step 6: Record an explicit decision when present
 
-## Step 5: (Optional) Record the plan decision
+When the user explicitly approved a plan:
 
-Record a decision alongside the answers only when the user stated one outright. Never infer it from the tone of the conversation.
+```bash
+okstra user-response plan-decision --transaction <transaction> --status approved [--implementation-option <name>]
+```
 
-Approval also requires that the report's approval-blocking clarification items are **all filled with an answer**:
+For `revision-requested` or `rejected`, write the user's reason verbatim to a Markdown file in that same temporary directory and pass it:
 
-```
---plan-decision '{"status":"approved","implementationOption":"<the option the user chose>"}'
+```bash
+okstra user-response plan-decision --transaction <transaction> --status <revision-requested|rejected> --reason-file <reason.md>
 ```
 
-If any approval-target item is not filled with an answer, or is a reframe/hold, do not approve — tell the user the gate is still open.
+Never infer a plan decision from the user's tone.
 
-A user who turns the plan down gets the same treatment, and the reason is mandatory — the next planning run reads it to know what to change:
+Only for a report whose fixed view says `Report contract: 2.0`, an explicit legacy report-authoring decision may be recorded. A reason file in that same temporary directory is always required:
 
+```bash
+okstra user-response legacy-report-authoring --transaction <transaction> --status <approved|denied> --reason-file <reason.md>
 ```
---plan-decision '{"status":"rejected","reason":"<the user's own words>"}'
-```
-
-Use `revision-requested` instead of `rejected` when the user wants the same plan reworked rather than dropped. Either way, quote the user's reason; do not summarise it into your own.
 
-## Step 6: Write the sidecar
+Report contract 3.0 rejects this command because report inputs have separate owners.
 
-Run only after the user has confirmed the echo-back with "confirmed":
+## Step 7: Finalize once
 
 ```bash
-okstra user-response write --report <reportPath> --answers '<answers-json>' --plan-decision '<plan-decision-json>' --task-key <taskKey>
+okstra user-response finalize --transaction <transaction>
 ```
 
-- `--answers` = the JSON array of `{id, kind, value, rationale?, disposition}` objects collected in Step 3.
-- `--plan-decision` is attached only when recording a decision in Step 5 (otherwise omit it).
-- `--task-key` is the value carried forward from Step 1/2.
-- Report the path from the returned JSON `{sidecar: <path>}` to the user. (`write` merges items when a sidecar already exists — the same `id` is overwritten with the new value.)
-
-## Step 7: Self-describing next-step guidance
+Only `finalize` publishes the sidecar. Report the returned `sidecar` path. A retry with the same transaction returns the same published result.
 
-Leave the following in the final output as-is:
+Leave this guidance in the final answer:
 
-> This answer was recorded in the `user-responses/` sidecar (`<sidecar path>`). Re-running this task's `<task-type>` with `/okstra-run` auto-attaches this answer (if you approved all approval-blocking items, the next phase is `implementation`).
+> This answer was recorded in the `user-responses/` sidecar (`<sidecar path>`). Re-running this task with `/okstra-run` attaches the answer to the next eligible phase.
 
-## Output Rules (shared)
+## Output rules
 
-- Keep responses concise and in the language the user is using, unless they ask otherwise.
-- Give path guidance host-relative (`~/.okstra/...` or relative to the `projectRoot` preflight returned). Use repo paths only when pointing at a code source.
-- This skill never hand-edits a rendered report (`runs/*/reports/*.md` / `*.data.json`). Writing the `user-responses/` sidecar goes only through the `okstra user-response write` CLI.
+- Keep responses in the user's language.
+- Never edit a rendered report, report record, approval ledger, lead events, team state, convergence state, or report-writer narrative.
+- Never edit a `user-responses/` sidecar directly. Publish it only with `user-response finalize`.
+- Never create or parse structured state for these commands. Pass scalar arguments and Markdown body files only.

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

@@ -1,37 +1,47 @@
 # Report Writer Prompt Preamble (canonical)
 
-This file is the audience-specific contract for `report-writer`. Read it end-to-end. Before work, also read the shared file named by `**Worker Error Contract Path:**`; error rules live only there.
+This file is the audience-specific contract for `report-writer`. Read it and the shared Worker Error Contract end-to-end.
+
+## Output ownership
+
+Write only the report narrative Markdown at `**Result Path:**`, the pointer record at `**Worker Result Path:**`, and the reading audit at `**Audit sidecar path:**`.
+
+The report narrative Markdown contains the task judgment, plan, summaries, and user explanation. It must not write or patch `final-report-*.data.json`, the approval decision ledger, activity ledger, team state, convergence state, or design-preparation input.
+
+The following fields belong to other owners and must not appear in the narrative: `designPreparation`, `designSurfaceCoverage`, `executionStatus`, `executionRoles`, `tokenUsage`, `crossVerification`, `approvalContext`, `clarificationItems`, `agentActivity`, and `planBodyVerification`.
+
+Do not pre-fill a future round, future gate, usage value, activity identifier, or resolution. Report assembly derives those values after their owner input exists.
 
 ## Required reading
 
-Read every input enumerated by the Phase 6 dispatch end-to-end: task/analysis inputs, worker results, convergence state, the instruction-set-local `final-report-template.md`, and the task-type excerpt `final-report-schema.json`. Do not pull the full repository template or schema when the scoped instruction-set copies are provided.
+Read every path listed under `## Inputs` end-to-end. Full context is available for synthesis, but read access does not transfer write ownership. Preserve supplied technical meaning and do not invent missing evidence.
+
+Write the audit sidecar before synthesis with one `- PROGRESS: <stage> <ISO-8601-UTC>` line and the required reading confirmation. Valid stages are `started`, `required-reading-complete`, `synthesis-start`, `narrative-write-start`, and `write-result-start`.
 
-Write Reading Confirmation to `**Audit sidecar path:**`, not the rendered final report. Resolve `.okstra/**` paths against `**Project Root:**`.
+## Narrative format
 
-Write `- PROGRESS: <stage> <ISO-8601-UTC>` there before reading and at least every five minutes while pending. The only valid report-writer stages are `started`, `required-reading-complete`, `synthesis-start`, `data-json-write-start`, `render-start`, and `write-result-start`.
+The narrative is not free-form Markdown. A narrative file is the line `# OKSTRA Report Narrative`, then lines of exactly three shapes and nothing else:
 
-## Report authoring handoff
+- `- **Humanised Field Name**` — one field. Nest a child field by indenting two more spaces.
+- `- Item <N>` — one array entry, numbered `1..N` with no gaps.
+- `> value` — one scalar. Repeat the line for a multi-line value. Write `> _none_` for null, an empty object, or an empty array.
 
-- Author the data.json at `**Result Path:**` and the audit file at `**Audit sidecar path:**`.
-- Follow the task-type schema excerpt and Phase 6 report-writer contract. Do not perform independent analysis, edit source code, or load implementation coding-preflight resources.
-- Do not invoke `okstra render-final-report`. The full reading copy is rendered on demand.
-- Preserve source item IDs, convergence classifications, round history, and unresolved dissent; do not recompute them from intuition.
-- Every `clarificationItems[]` row you leave `status: open` with `blocks: approval` carries `origin` and `userConfirmation`. `origin` is `worker-finding` only when an analyser or verifier reached it on its own evidence — when the lead's dispatch prompt told you to raise it, it is `lead-directed`, whatever the workers then agreed. `userConfirmation` is what the lead reports having done about it (`asked-and-answered` / `asked-awaiting` / `deferred-no-interactive-session`); if the dispatch does not say, write `asked-awaiting` and name the gap in your return message rather than guessing. An open approval blocker stops the whole task, so a row that misreports where it came from costs a re-run. **Enforced:** `validators/validate-run.py` `_validate_open_approval_blocker_provenance`.
+Blank lines are ignored. **Every other line is rejected**, including Markdown headings (`#`, `##`, `###`), a pipe table written at column 0, code fences, bare paragraphs, JSON, YAML, and JSON Pointer. A heading or table that belongs in the reader's report is written as the text of a `> ` value, never as a narrative line of its own.
 
-## Anchor headers
+Follow the task-specific schema order and write the prose in English.
 
-The generated prompt selects this file through `**Worker Preamble Path:**` and includes `**Worker Error Contract Path:**`, `**Audit sidecar path:**`, error paths, and read scope. It never includes `**Coding preflight pack:**`.
+### Top-level fields you may author
 
-The adjacent v2 prompt metadata supplies `participantRef`, `roleExecutionRef`, `executionLabel`, `invocationRef`, and `attempt`. Copy those values into report and audit identity fields without deriving them from the provider or model. Legacy v1 `workerId` is a read-only compatibility projection and is not written into v2 artifacts.
+These are the only names allowed at the top level:
 
-## Return message to the lead
+`Analysis Common`, `Change Impact Analysis`, `Error Analysis`, `Feature Analysis`, `Final Verdict`, `Final Verification`, `Follow Up Tasks`, `Human Summary`, `Implementation`, `Implementation Option Selection`, `Implementation Planning`, `Improvement Discovery`, `Project Analysis`, `Rationale`, `Recommended Next Steps`, `Release Handoff`, `Requirements Discovery`, `Summary`, `Ticket Coverage`, `Verdict Card`
 
-Begin the inline return with the exact `**Model:** Report writer worker, <modelExecutionValue>` line from the prompt, followed by the artifact status. Never invent or abbreviate the model.
+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.
 
-## Writing style
+## Pointer record
 
-Use concise reader-facing prose. Prefer tables when several items share a shape; reserve bullets for short standalone statements.
+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.
 
-**Author the data.json in English, whatever `**Report Language:**` says.** That header is not an instruction to write in that language — it names the language the *human HTML* renders in, and you copy its value verbatim into `data.json.meta.reportLanguage`. The data.json is the English SSOT every later phase, validator and agent reads. When the value is not `en`, Phase 7 dispatches a separate translator worker that writes a sidecar the HTML renderer overlays; you never author that sidecar and never write a second language into the data.json.
+## Failure handling
 
-Authoring the data.json in the reader's language is rejected before anything derives from it: `okstra report-translate check-source` fails the run when Korean exceeds 20% of its prose, and the same gate runs again inside `validate-run`. The cost of getting this wrong is a full rewrite, so decide it once, up front.
+If a required narrative fact is missing or contradictory, record the report-writer error and stop. If report assembly later reports another owner, do not edit that owner's input; return the failure to the named owner.

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

@@ -63,6 +63,7 @@
   {% for row in items %}
   {% set is_closed = row.status in ['resolved', 'obsolete'] %}
   {% set approval_context = row.approvalContext | default(None) %}
+  {% set resolution = row.resolution | default(None) %}
   {% set options = row.options | default([]) %}
   <article class="clarification-item" id="id-{{ row.id }}" data-response-id="{{ row.id }}" data-kind="{{ row.kind }}" data-status="{{ row.status }}">
     <p class="eyebrow">{{ row.id }} · {{ row.kind }}</p>
@@ -72,9 +73,10 @@
     <div class="approval-context" data-approval-classification="{{ approval_context.classification }}">
       <p class="eyebrow">{{ approval_context.classification }}</p>
       <p><strong>{{ t('tasks.implementation-planning.unblock-condition') }}</strong> {{ approval_context.unblockCondition | inline_code }}</p>
-      <p><strong>{{ t('tasks.implementation-planning.agent-evidence') }}</strong>
-        {% for activity_id in approval_context.activityIds %}<a href="#id-{{ activity_id }}">{{ activity_id }}</a>{% if not loop.last %}, {% endif %}{% endfor %}
-      </p>
+      {% set check_refs = resolution.checkRefs if resolution else approval_context.activityIds | default([]) %}
+      {% if check_refs %}<p><strong>{{ t('tasks.implementation-planning.agent-evidence') }}</strong>
+        {% for activity_id in check_refs %}<a href="#id-{{ activity_id }}">{{ activity_id }}</a>{% if not loop.last %}, {% endif %}{% endfor %}
+      </p>{% endif %}
     </div>
     {% endif %}
     {% if options %}
@@ -85,7 +87,7 @@
         {% if option.disposition | default(None) %}<p class="clarification-option-disposition"><code>{{ option.disposition }}</code></p>{% endif %}
         <p class="clarification-option-rationale">{{ option.rationale }}</p>
         <dl class="clarification-option-impact">
-          <dt>{{ t('macros.forms.scope-impact') }}</dt><dd>{{ option.scopeImpact | join(', ') }}</dd>
+          <dt>{{ t('macros.forms.scope-impact') }}</dt><dd>{% if option.reach | default(None) %}{{ option.reach }}{% if option.scopeEffects | default([]) %}, {{ option.scopeEffects | join(', ') }}{% endif %}{% else %}{{ option.scopeImpact | join(', ') }}{% endif %}</dd>
           <dt>{{ t('macros.forms.added-work') }}</dt><dd>{{ option.addedWork }}</dd>
           <dt>{{ t('macros.forms.direction-change') }}</dt><dd>{{ option.directionChange }}</dd>
         </dl>

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

@@ -200,10 +200,10 @@ Stage 3           ██████░░░░
 **Solution**: <…>
 
 <!-- Everything below this line is transcribed from the planning report the CLI
-     resolved — `okstra stage-map <task-key> --json` carries each stage's
-     `acceptance` / `exitContract` / `sliceValue` and the task-level
-     `rollbackStrategy` / `validationChecklist` / `dependencyMigrationRisk`
-     rows. Transcribe those rows; do not re-summarise the report body. -->
+     resolved — `okstra stage-map <task-key> --text` carries fixed `Stages` and
+     `Planning` count/name/value rows for each stage's acceptance, exit contract,
+     slice value, and the task-level rollback, validation, and migration-risk
+     fields. Transcribe those rows; do not re-summarise the report body. -->
 
 **Work Breakdown**:
 

package/runtime/templates/worker-error-contract.md

@@ -1,6 +1,6 @@
 # Worker Error Contract (canonical)
 
-This audience-neutral file is the single source of truth for every initial worker's error path, sidecar schema, and write protocol. Read it end-to-end from `**Worker Error Contract Path:**` before work.
+This audience-neutral file is the single source of truth for every initial worker's error path and typed write command. Read it end-to-end from `**Worker Error Contract Path:**` before work.
 
 ## Error reporting
 
@@ -12,44 +12,32 @@ Record a tool call only when its failure blocked the step you intended. A non-ze
 
 If the non-zero exit changed nothing about what you could do next, it is normal. When in doubt, record the real blocker: under-recording a real blocker is worse than one noisy entry.
 
-If the sidecar does not exist when a real failure occurs, create `{"schemaVersion": 1, "errors": []}` and append one entry.
-
-### Entry schema
-
-```json
-{
-  "ts": "<ISO 8601 UTC>",
-  "phase": "<current okstra phase>",
-  "errorType": "tool-failure",
-  "command": "<failed command/tool signature>",
-  "commandKind": "bash | tool:Read | tool:Edit | mcp | ...",
-  "exitCode": null,
-  "durationMs": null,
-  "message": "<one-line human summary>",
-  "stderrExcerpt": null,
-  "context": {
-    "cause": "sandbox-denied | service-unavailable | auth-failed | unknown",
-    "causeEvidence": {
-      "targetProbe": "<command + raw output proving the target's state>",
-      "controlProbe": "<command + raw output proving another target is reachable>"
-    }
-  }
-}
+For each real failure, invoke this typed command. Replace only the angle-bracket values supplied by the dispatch prompt or observed from the failed call. Do not create a JSON file or pass JSON text.
+
+```bash
+okstra error-log append-observed \
+  --out <absolute-errors-log-path> \
+  --task-key <task-key> --phase <phase> \
+  --agent <assigned-agent> --agent-role worker --model <assigned-model> \
+  --error-type tool-failure --command-file <failed-command-file> \
+  --command-kind <command-kind> --message-file <message-markdown-file> \
+  --cause sandbox-denied \
+  --evidence-file targetProbe=<target-probe-file> \
+  --evidence-file controlProbe=<control-probe-file>
 ```
 
-`context` and both `cause` fields are optional; omit `context` entirely (`null`) when there is nothing to add.
+For a cause other than `sandbox-denied`, replace the cause value and omit both `--evidence-file` arguments unless you observed the required probes. Put any free-form message or probe output in the supplied Markdown file rather than relying on shell quoting.
 
 ### Rules
 
-- Do not add `source`, `recordedAt`, `agent`, `agentRole`, `model`, or `taskKey`; the lead supplies them when merging the sidecar.
-- The sidecar accepts only `errorType: "tool-failure"`. CLI wrappers write `cli-failure` directly to the run log; the lead records `contract-violation`.
-- To record a block (sandbox/permission) as the cause, submit `context.cause = "sandbox-denied"` together with both probes in `context.causeEvidence`. Without the probes, leave `cause` as `unknown` — and then keep `message` to what you observed (`connection refused`, `1045 access denied`), not what you infer. A block asserted in `message` prose is rejected exactly like one asserted in `cause`, so "sandbox blocked it" with `cause: unknown` fails the write too. Failing to reach a target and the target being down are not the same fact — never assert the former without checking. Only `sandbox-denied` requires evidence; `service-unavailable` and `auth-failed` do not. Each probe is stored truncated to 256 bytes, so lead with the decisive command and its output.
+- Use only `--error-type tool-failure`. CLI wrappers write `cli-failure` directly to the run log; the lead records `contract-violation`.
+- To record a block (sandbox/permission) as the cause, pass `--cause sandbox-denied` together with both `--evidence-file targetProbe=<target-probe-file>` and `--evidence-file controlProbe=<control-probe-file>`. Without the probes, pass `--cause unknown` — and then keep the `--message-file` content to what you observed (`connection refused`, `1045 access denied`), not what you infer. A block asserted in message prose is rejected exactly like one asserted in the cause. Failing to reach a target and the target being down are not the same fact. Only `sandbox-denied` requires evidence; `service-unavailable` and `auth-failed` do not. Each probe is stored truncated to 256 bytes, so lead with the decisive command and its output.
 - [Guideline] Put raw output in `stderrExcerpt` verbatim. Never merge several commands' output into one line, summarize it, or elide it with `...`. Once the host, port, and errno are gone, the cause cannot be recovered later.
 - Continue after recording unless the failure makes the task impossible.
 
 ### Path extraction (BLOCKING)
 
-Extract `**Errors log path:**` and `**Errors sidecar path:**` verbatim from the dispatch prompt. If either is absent, return the worker-specific `<SENTINEL_PREFIX>_ERRORS_PATH_MISSING` sentinel and stop. Never synthesize a path from a run-directory pattern.
+Extract `**Errors log path:**` verbatim from the dispatch prompt. If it is absent, return the worker-specific `<SENTINEL_PREFIX>_ERRORS_PATH_MISSING` sentinel and stop. Never synthesize a path from a run-directory pattern.
 
 ## Path anchoring