okstra 0.180.0 → 0.183.2

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

@@ -58,29 +58,37 @@ running the legacy `okstra-install.sh` — that path is dev-only.
 ## Step 2: Resolve PROJECT_ROOT
 
 ```bash
-okstra check-project --json
+okstra preflight
 ```
 
-Parse the JSON from stdout. The shape is `{ok, projectRoot, projectJsonPath, projectId, stage?}`.
+Read the fixed `Okstra preflight`, `Project root`, `Project JSON`, `Project ID`,
+`Reason`, and `Recovery` lines.
 
-- `ok: true` → carry `projectRoot` 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:
+- `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:
 
   ```bash
-  okstra check-project --cwd /abs/path/from/user --json
+  okstra preflight --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 JSON `reason` field to the user verbatim and follow the recovery it names (typically `okstra doctor` to diagnose, then `okstra ensure-installed` or re-running the Step 1 install). `reason` is the SSOT — do not hand-enumerate stage causes.
+- `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` to diagnose, then `okstra ensure-installed` or re-running the Step 1 install). `Reason` is the SSOT — do not hand-enumerate stage causes.
 
-## Step 3: Inspect or create `project.json`
+## Step 3: Project metadata setup
 
-Use the `Read` tool on the literal absolute path `<projectRoot>/.okstra/project.json` (substitute the literal `projectRoot` value parsed in Step 2). If `Read` errors with "file does not exist", treat that as the "create" branch below; otherwise the file exists and you can inspect its contents inline.
+Render the existing project metadata with the purpose-specific view. Paste the
+literal `projectRoot` value parsed in Step 2:
 
-If the file exists, surface its `projectId`/`projectRoot` and ask whether to
-keep or overwrite. Default is to keep — okstra refuses to change `projectId`
-on an existing project (see `okstra_project.resolver.upsert_project_json`),
-so overwriting requires manually deleting the file first.
+```bash
+okstra model-io project-context --project-root /abs/path/to/projectRoot
+```
+
+If the command reports that project metadata is missing, treat that as the
+"create" branch below. Otherwise, surface the rendered `Project ID` and
+`Project root`, then ask whether to keep or overwrite. Default is to keep —
+okstra refuses to change `projectId` on an existing project (see
+`okstra_project.resolver.upsert_project_json`), so overwriting requires
+manually deleting the file first.
 
 If the file does NOT exist, ask via `AskUserQuestion`:
 

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

@@ -1,6 +1,6 @@
 # Optional project configuration (okstra-setup)
 
-Read this only when the user asks to customise one of the areas below after
+Use this reference only when the user asks to customise one of the areas below after
 `project.json` exists. The built-in defaults work for most projects — none of
 these sections is required for a working setup.
 
@@ -189,7 +189,7 @@ okstra config set pr-template-path "<typed-path>" --scope <project|global>
 ```
 
 The command validates the value (global rejects relative paths) and writes
-atomically. Surface its stdout JSON. If the user chose `Later`, tell them
+atomically. Surface its fixed text result. If the user chose `Later`, tell them
 they can register later via the same `okstra config set` command or the
 per-run override prompt during the next release-handoff run.
 

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

@@ -17,11 +17,11 @@ Read-only project usage snapshot. The CLI owns every sum; never re-add rows.
 Run one literal Bash call:
 
 ```bash
-okstra preflight --runtime claude-code --json
+okstra preflight --runtime claude-code
 ```
 
-On `ok:true`, carry `projectRoot`. On `ok:false`, tell the user to run `/okstra-setup` first
-and stop.
+On `Okstra preflight: ready`, carry the fixed `Project root` line. On
+`Okstra preflight: failed`, show `Reason` and `Recovery`, then stop.
 
 <!-- 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).
@@ -37,7 +37,7 @@ If the call fails with `unknown command: preflight`, the `okstra` binary on PATH
 ## Step 2: Fetch once
 
 ```bash
-okstra usage-report --days 30 --project-root <projectRoot> --json
+okstra usage-report --days 30 --project-root <projectRoot> --text
 ```
 
 Replace `30` only with the resolved positive integer. Do not wrap the command in
@@ -45,23 +45,23 @@ Replace `30` only with the resolved positive integer. Do not wrap the command in
 
 ## Step 3: Render
 
-If `ok:false`, report `stage` and `reason`, then stop. If `runs.total == 0`, say
+If `Status` is `error`, report `Failure stage` and `Failure reason`, then stop. If `Runs total` is `0`, say
 `No okstra usage found in the last N days.`, omit the table, and continue to Step 4.
 
-Otherwise, render `byTaskType` in returned order:
+Otherwise, render the numbered `Task type N ...` fixed fields in returned order:
 
 | Task type | Runs | Coverage | Raw tokens | Billable | Cost | CPU | Wall |
 |---|---:|---:|---:|---:|---:|---:|---:|
 
-- `Coverage` = returned `collectedRuns/runs`; never calculate a new aggregate.
+- `Coverage` = returned `Task type N collection rate`; never divide or calculate a new aggregate.
 - Format tokens with K/M suffixes, milliseconds as zero-padded `HH:MM:SS`, and
   USD to two decimals. For tokens, use one decimal at `>= 1,000` (`K`) and
   `>= 1,000,000` (`M`), trimming a trailing `.0`; below 1,000 render the integer.
-- Render the `totals` object as the final bold row.
+- Render the fixed total labels as the final bold row.
 - Never treat unavailable usage as collected zero usage.
 
 ## Step 4: Diagnostics
 
-- Render non-zero `unavailable` and `warnings` counts after the Step 3 output.
-- If `unmatchedModels` is non-empty, mark Cost with `*` when the table exists and
+- Render non-zero numbered `Unavailable N` and `Warning N` fields after the Step 3 output.
+- If numbered `Unmatched model N name` fields exist, mark Cost with `*` when the table exists and
   always say known-price cost excludes those exact model names.

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

@@ -20,7 +20,23 @@ Write the audit sidecar before synthesis with one `- PROGRESS: <stage> <ISO-8601
 
 ## Narrative format
 
-Start with `# OKSTRA Report Narrative`. Encode fields as nested Markdown list entries using `- **Humanised Field Name**`; use `- Item N` for array entries and `> value` for scalar or multiline values. Follow the task-specific schema order and write the prose in English. JSON, YAML, JSON Pointer, and fenced JSON are not narrative syntax.
+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:
+
+- `- **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.
+
+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.
+
+Follow the task-specific schema order and write the prose in English.
+
+### Top-level fields you may author
+
+These are the only names allowed at the top level:
+
+`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`
+
+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.
 
 ## Pointer record
 

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