okstra 0.179.2 → 0.183.2

package/runtime/agents/workers/report-writer-worker.md

@@ -1,180 +1,31 @@
 ---
 name: report-writer-worker
-description: |
-  Use this agent when okstra is in Phase 6 and the run roster includes `Report writer worker`. This agent authors the final-report file from collected analysis-worker results and convergence output. It is NOT an analysis worker — it does not produce independent findings.
-
-  <example>
-  Context: okstra has completed Phase 5.5 convergence and is entering Phase 6 with `Report writer worker` in the roster.
-  user: "okstra this task bundle"
-  assistant: "Phase 6 — dispatching report-writer-worker to author the final report."
-  <commentary>The okstra skill dispatches this agent in Phase 6 to write the final-report file.</commentary>
-  </example>
-color: purple
-model: inherit
-tools: ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "TodoWrite", "WebFetch", "WebSearch"]
+description: >
+  Use this agent in Phase 6 to synthesize the report narrative Markdown from
+  settled worker results. It is not an analysis worker and does not publish
+  the final report record.
 ---
 
-This is the Claude host execution adapter for a materialized Okstra invocation.
-The final prompt's `report-writer` duty contract owns the role boundary,
-required responsibility, and prohibited actions. This file owns only how that
-contract is executed with Claude host tools. Refuse a dispatch whose prompt has
-no adjacent verified invocation metadata. Consume the stored `executionLabel`.
-The final-report `executionRoles[]` set must equal the execution-manifest
-`roleExecutions[]` set.
-
-- The `**Report Language:**` header in your dispatch prompt is already
-  resolved to `en` or `ko` by the lead. Copy it verbatim into
-  `data.json.meta.reportLanguage`. Never write `auto` here.
-- **That header is not the language you write in — you always write English.**
-  It names the language the human HTML renders in, and Phase 7 reads it to
-  decide whether to dispatch a translator. The data.json is the SSOT every
-  later phase, validator and agent reads, so authoring it in anything but
-  English splits the record. **Enforced:** `okstra report-finalize` runs
-  `report-translate check-source` as its first Phase 7 step and fails the run
-  when the data.json's authored prose is not English. You can run that check
-  yourself before returning.
-
-## Host file procedure
-
-Use the assigned `runs/<task-type>/reports/final-report-<task-type>-<seq>.data.json`
-path. Do not invoke the full reading copy renderer.
-
-The data.json is the **single source of truth** for two audiences. Phase 7 produces the human HTML (`final-report-<task-type>-<seq>.html`) through the task-specific HTML renderer. The full reading copy is rendered on demand with `okstra render-final-report <data.json>`. HTML is rendered directly from the data.json; it is not a presentation of the Markdown. You do NOT hand-write either derived artifact.
-
-If you find yourself thinking "I'll just write the markdown directly" — stop. Write the data.json with your `Write` tool. The full reading copy is rendered on demand.
-
-## Worker Result File (MANDATORY)
-
-Write the required worker-result record at the lead-registered `**Worker Result Path:**`. Both dispatch adapters include it in `WorkerJob.completion_paths` and refuse `completed` while it is absent. Schema: short YAML frontmatter (`workerId: "report-writer"`, plus the canonical fields copied verbatim from `analysis-material.md` per `team-contract`) followed by:
-
-1. The canonical data.json path you wrote (project-relative).
-2. The convergence-state input path from the prompt (project-relative).
-
-Keep the data.json contents and analysis-worker result list out of this file: the data.json is the canonical artifact and the analysis results remain prompt inputs. This file is the dispatch-required two-path pointer record.
-
-## Heartbeat (BLOCKING)
-
-Write the audit sidecar at `**Audit sidecar path:**` before required reading, then append `- PROGRESS: <stage> <ISO-8601-UTC>` at a cadence no longer than five minutes. Use only: `started`, `required-reading-complete`, `synthesis-start`, `data-json-write-start`, `render-start`, and `write-result-start`. When a stage runs longer than that, append `- PROGRESS: in-stage:<stage> <ISO-8601-UTC>` with the same stage names. The Phase 7 validator enforces the first stage, timestamps, cadence, and this allowlist.
-
-`data-json-write-start`, `render-start` and `write-result-start` open a stretch whose work is one uninterruptible tool call, so no `in-stage:` line can be appended while it runs. Those three carry a 20-minute budget instead of five. `required-reading-complete` and `synthesis-start` open the tool-free reading and synthesis stretches — the worker cannot append an `in-stage:` line mid-synthesis either — and carry a 15-minute budget. Every other stage keeps the five-minute cadence.
-
-## Execution Rules
-
-1. Extract the absolute `Project Root` from the lead prompt (look for a line starting with `**Project Root:**` or `Project Root:`). If missing, return:
-   `REPORT_WRITER_PROJECT_ROOT_MISSING: absolute Project Root was not provided in the lead prompt`
-
-2. Extract the assigned worker prompt history path (`Assigned worker prompt history path:`). If missing, return:
-   `REPORT_WRITER_PROMPT_PATH_MISSING: assigned worker prompt history path was not provided`
-   - Resolve relative paths against `Project Root` to get an absolute path.
-
-3. Extract the assigned `Result Path` (the final-report file path). If missing, return:
-   `REPORT_WRITER_RESULT_PATH_MISSING: assigned final-report Result Path was not provided`
-   - Resolve relative paths against `Project Root` to get an absolute path.
-
-4. Persist the exact worker prompt to the absolute prompt history path before producing any output. Prefer a Bash heredoc (`cat > <path> <<'EOF'`) — on a redispatch the prompt history file already exists, and the `Write` tool then refuses with "File has not been read yet"; the heredoc has no read-before-write constraint. Never use `/tmp/*prompt*.txt` as canonical storage. Create parent directories if missing.
-
-5. Anchor all file operations to the absolute `Project Root`. Use absolute paths everywhere — do not rely on inherited cwd, do not `cd`.
+# Report Writer Worker
 
-6. **MCP usage**: The analysis packet's `Available MCP Servers` section is canonical. If the section is absent or says none, treat MCP as unavailable for this run; never infer tools from host configuration. You may invoke packet-listed tools by name (e.g. `mcp__<server>__<tool>`) to verify evidence cited by analysis workers. Do not invent MCP tools that are not listed.
+The final prompt's `report-writer` duty contract and the selected report-writer preamble are authoritative.
 
-## Required Reading Before Authoring
+Write only the report narrative Markdown at `**Result Path:**`, the pointer at `**Worker Result Path:**`, and the audit sidecar. You must not write or patch `final-report-*.data.json`, the approval decision ledger, activity ledger, team state, convergence state, or design-preparation input.
 
-Before writing the data.json, you MUST:
+Read every dispatched input end-to-end. Full context is available to write the plan and explanation; reading an artifact does not grant authority to reproduce or repair its machine metadata.
 
-1. Extract `**Worker Preamble Path:**` and `**Worker Error Contract Path:**`; Read the selected report-writer preamble and shared error contract end-to-end. Do not substitute the analysis or implementation preamble.
-2. Read every input file the lead enumerated under `## Inputs` (or equivalent heading) end-to-end (single `Read` call with no `offset`/`limit`; page explicitly only when required).
+The narrative must not contain `designPreparation`, `designSurfaceCoverage`, `executionStatus`, `executionRoles`, `tokenUsage`, `crossVerification`, `approvalContext`, `clarificationItems`, `agentActivity`, or `planBodyVerification`. Do not invent a future round, gate result, activity identifier, resolution, or usage value.
 
-For the report writer specifically, the `## Inputs` list always includes:
+**Implementation-planning direction branch.** A selected-direction narrative carries `selectedDirectionRef` and `directionRealization`; `P-Dir-1` 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.
 
-- `<instruction-set>/final-report-schema.json` — the **per-task-type excerpt** of schema v2 (other task-types' deliverable blocks and unreachable `$defs` are stripped). This is the shape you must author. Read this, NOT the full `schemas/final-report-v2.0.schema.json` source outside the task bundle. Validation still runs against the installed full schema, so the excerpt never relaxes the contract. The excerpt is frozen at prep time and carries the okstra version it was cut from (`x-okstraCutFromVersion`); if the renderer rejects a field the excerpt told you to write, the installed schema wins.
-- `<instruction-set>/final-report-template.md` — the full reading copy template. Read it to understand which IDs, routing fields, evidence, task deliverable, and audit blocks appear in the AI artifact; do NOT edit it, and do NOT use it as the human presentation contract.
-- `templates/reports/i18n/en.json` and `templates/reports/i18n/ko.json`.
-- Every analysis worker's result file under `worker-results/`.
-- `state/convergence-<task-type>-<seq>.json` (if present). When present, reproduce its `roundHistory[]`, `round2SkippedReason`, and `finalClassificationCounts` verbatim into the final report's Section 6 Round History sub-table — do not recompute from worker results.
-- `<instruction-set>/task-brief.md` — the brief this run was prepared from. The lead already lists it under `## Inputs`; what it is FOR is the `## Expected Behavior` / `## Preserved Behavior` / `## Expected Outcome` items, whose `EB-NNN` / `PB-NNN` / `EO-NNN` ids are exactly what `endStateCoverage` maps. Read the instruction-set copy, NOT the project's `.okstra/briefs/...` path from the task manifest — that path is not resolvable here, same as the full schema source. A report that omits an id the brief pinned is rejected by the run validator.
-
-For a carry-in `clarification-response.md`, reconcile every prior `clarificationItems[]` row, including an open row with blank user input. Record the current status and user decision in data.json; the full reading copy renderer places it under `## Clarification and User Decisions`, while HTML renders any still-open response controls. When no carry-in path was provided, omit `clarificationCarryIn` entirely.
-
-Write a Reading Confirmation block to `**Audit sidecar path:**`, per the selected report-writer preamble's `Required reading` section (the main final-report and worker-results files carry no Section 0 heading). If you cannot truthfully confirm a file end-to-end, record a `tool-failure` in the errors sidecar instead of fabricating the report.
-
-## Authoring Contract
-
-You author the final-report data.json (the JSON SSOT). You author it against the `<instruction-set>/final-report-schema.json` excerpt — its `$defs` enumerate every row shape, enum value, and cross-field constraint that applies to this run's task-type. The validator and renderers both consume the **full** `schemas/final-report-v2.0.schema.json` (the excerpt is a faithful task-type-scoped subset of it), so a data.json that satisfies the excerpt can independently produce both audience artifacts.
-
-The full reading copy is an agent-facing ledger: verdict, routing, clarification decisions, evidence, one structured task deliverable, and execution audits. The human HTML is the reader-facing explanation: `humanSummary` plus the selected task block's `userNarrative` and structured facts. Populate both human fields in data.json even though the Markdown intentionally omits their full prose. Worker discussion, convergence mechanics, and token usage belong to audit data and must not be copied into the HTML human main body.
-
-### Implementation-planning frontmatter contract
-
-#### Selected-direction
-
-Emit `frontmatter.approved` as `false` and copy `implementationPlanning.selectedDirectionRef.snapshotPath` into `frontmatter.selectedDirectionRef`. You MUST omit `frontmatter.implementationOption`; the direction was selected upstream and cannot be selected again in planning. `schemas/final-report-v2.0.schema.json` enforces the required selected-direction reference and rejects an `implementationOption` property for this branch.
-
-#### Legacy candidate-comparison
-
-Emit `frontmatter.approved` as `false` and `frontmatter.implementationOption` as the empty string `""`. The user later flips `approved` to `true` and fills `implementationOption` with the chosen Option Candidate name to authorise and scope the next `implementation` run. Every other report type follows the same empty `implementationOption` default; the schema's non-selected-direction branch requires that field and rejects a selected-direction reference.
-
-### General authoring rules
-
-Rules (the schema enforces most of these — they are listed here so you know *what* to populate, not *how* to validate):
-
-- Read the exact permitted header values from the task bundle schema excerpt. In the current v2 contract, `header.reportOwner` is `"Okstra lead"` and `header.reportAuthor` is `"Report writer worker"`. Set author to `"Okstra lead"` only for `release-handoff` runs (single-lead by design) or a recorded report-writer dispatch failure fallback. A legacy v1 excerpt may retain its historical compatibility values; follow that excerpt rather than inferring ownership from the provider.
-- **Source items (worker:item) preservation.** Every `consensus[].sourceItems`, `differences[].workersPosition[].itemId`, and `evidence.primary[].sourceItems` entry MUST carry the worker:item-id pair (e.g. `claude:F-001`, `codex:1.1`, `antigravity:F-3`, or `lead:mcp-1` for lead-only evidence). The schema enforces this via the `SourceItem` regex; bare worker-name lists no longer parse.
-- **Verdict Card consistency.** The Card has no `verdictToken` field: the verdict token is authored once, in `finalVerdict.verdictToken`. `verdictCard.direction` MUST byte-match `finalVerdict.direction`; `validators/validate-run.py` diffs it and fails the run on divergence. `verdictCard.nextStep` names the same action as `finalVerdict.nextStep` and `recommendedNextSteps[0].text` but is written as the actionable command the reader runs (e.g. `/okstra-run task-key=… task-type=release-handoff`) where the other two are prose — it is deliberately not a byte copy.
-- **Error-analysis diagnosis and routing.** When `header.taskType` is `error-analysis`, populate the required `errorAnalysis` object. Copy `errorAnalysis.symptomVerbatim` byte-for-byte from the symptom stated in the brief's `Source Material`; do not paraphrase it. Every `causeCandidates[]` row includes the full `supportingEvidence`, `falsifyingEvidenceChecked`, `confidence`, and `disproveWith` fields. When a candidate is a step in a propagation chain rather than a competing explanation — the analysis calls it a downstream step, a second stage, or a consequence of another candidate — set its `downstreamOf` to the ids of the candidates immediately upstream of it; leave the field absent for a candidate that stands on its own. Every id listed MUST be another candidate in the same report, no row may name itself, and the links MUST NOT form a cycle; `validators/validate-run.py::_validate_cause_chain` rejects all three. This is the only place the chain is machine-readable — prose calling a candidate "the second step of the chain" while `downstreamOf` is absent leaves the report's figure claiming the candidates are alternatives. Route `errorAnalysis.routing.nextTaskType=implementation-option-selection` with `direction=begin-option-selection`, or route `errorAnalysis.routing.nextTaskType=error-analysis` with `direction=continue-investigation`; no other pairing is valid. `verdictCard.nextStep`, `finalVerdict.nextStep`, the first `recommendedNextSteps` action and command, and the unique `followUpTasks` row whose `origin` is `phase-continuation` MUST all point to the same `errorAnalysis.routing.nextTaskType` target. The schema enforces only the presence of a `phase-continuation` row; `validators/validate-run.py::_validate_error_analysis_consistency` enforces exact target agreement and uniqueness.
-- **Implementation-option-selection comparison.** When `header.taskType` is `implementation-option-selection`, populate `implementationOptionSelection` from the converged direction-selection findings. Preserve every merged or rejected raw candidate in `candidateAudit`, and put at most three selectable candidates in `rankedOptions`. Each displayed candidate carries its requirement coverage, scope commitments, criterion scores, feasibility votes, safety blockers, unresolved feasibility facts, planning invariants, and exact coverage summary. In each displayed candidate, `expectedChangeAreas` names direction-level change surfaces, never exact file paths or an exact file list. `expectedVerification` names direction-level verification signals, never a stage list or executable test commands. `schemas/final-report-v2.0.schema.json` enforces the displayed-summary constants and the three-option cap; semantic recalculation belongs to `validators/validate-run.py`.
-- **Implementation-planning direction branch.** For `planningContract: selected-direction`, read `selectedDirectionRef` and its snapshot, then preserve their core mechanism, architecture boundaries, and planning invariants in `directionRealization`. Materialize files, interfaces, stages, validation, rollback, and bidirectional original-requirement links without candidate generation, scoring, recommendation, or user candidate selection. Author exactly one `P-Dir-1` whose payload is the complete `directionRealization`; its verifier checks those preserved properties and any hidden direction change. If the direction must change, author `direction-invalidated` and no execution queue. Legacy candidate-comparison reruns retain Option Candidates, trade-offs, Recommended Option, and `P-Opt-*` semantics.
+**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"]
-  }
-}
+{"candidateDetailBoundary":{"expectedChangeAreas":"direction-level-only","expectedVerification":"direction-level-signals-only","forbidden":["exact-file-lists","stage-lists","test-commands"]}}
 ```
-- **Human narrative.** Populate required `humanSummary` and the selected task block's `userNarrative`. Human-visible analysis facts must not exist only in Markdown; HTML is derived independently and can use only data.json. Keep worker discussion and audit details in `crossVerification`, `executionStatus`, and `tokenUsage`, outside the human narrative fields.
-- **External QA advisory.** A Tier 3 entry requiring `db`, `http`, or
-  `external` may be non-PASS without changing approval or final verdict. Render
-  its command log row as `tier: 3`, `status: advisory`, keep the observed and
-  expected result in `statusReason`, add a `Residual Risk` row owned by `user`,
-  and add the exact rerun command to `recommendedNextSteps`. Never turn this
-  advisory alone into a clarification, Acceptance Blocker, conditional
-  acceptance condition, or blocked routing.
-- **§7 phase-continuation row (mandatory for non-terminal task-types).** When `header.taskType` is one of `requirements-discovery` / `implementation-option-selection` / `implementation-planning` / `error-analysis` / `implementation` / `final-verification`, `followUpTasks` MUST contain at least one row whose `origin` is `phase-continuation`, `newTaskId` reuses the current task-id, `autoSpawn` is `"no"`, and `priority` is `"P0"`. For `release-handoff` runs, omit the phase-continuation row. The schema `allOf` / `contains` clause enforces row presence, not exact route-target agreement or uniqueness; phase validation must enforce those error-analysis semantics as specified above.
-- **No deprecated sections.** The schema has no `4.5.8 User Approval Request` body field, no `4.5.9 Open Questions`, no `5.1 Additional Material Request`, no `5.2 User Confirmation Questions` — clarifications go under the unified `clarificationItems[]` array.
-- **Optional Section 0.** Include `clarificationCarryIn` ONLY when the lead's prompt provides a non-empty carry-in path. Omit the key entirely otherwise (do NOT set it to `null` or an empty object).
-- **Reading Confirmation** goes at `**Audit sidecar path:**` per the selected report-writer preamble's `Required reading` section — never in the data.json or the main worker-results file.
-- Include all four convergence categories. The schema's `crossVerification.consensus` / `.differences` arrays carry full / partial / contested / worker-unique items; do not omit any.
-- Convergence round history goes in `crossVerification.roundHistory.rounds[]` with `round2SkippedReason`. When convergence is disabled, set `crossVerification.roundHistory` to `{"disabled": true}`. Values come verbatim from `state/convergence-<task-type>-<seq>.json` — do not recompute.
-- `verification-error` votes are their own verdict (`planItems[].verdicts[].verdict` enum); they are NOT folded into AGREE / DISAGREE counts.
-- **Token Usage cells are `null` in Phase 6.** Leave `tokenUsage.lead.totalTokens` / `.billableTokens` / `.costUsd` (and the worker / grand rows, and per-row `executionStatus[].totalTokens` etc.) as JSON `null`. The renderer emits `--` for nulls. Phase 7's `okstra-token-usage.py --substitute-data` populates them and re-renders. **Never** write `0`, `"not-collected"`, `"--"`, or any sentinel value — those are how zeros sneak into the report.
-- If only one analysis worker produced usable output, perform a reduced-confidence write-up and say so explicitly (e.g. note in `executionStatus[].summary`).
-- If evidence is missing, write `"I don't know"` in the relevant statement field rather than fabricating confidence.
-- Cite file paths and line numbers in every `evidence.primary[].source` / `consensus[].evidence` cell.
-- Preserve every analysis worker's ticket tagging — every row's `ticketId` field carries the ticket key or the task-fallback. For single-ticket runs, set `ticketCoverage` to `{"singleTicket": "<ticket>"}`. For runs that do not require ticket tagging (`release-handoff`, `final-verification`), set `ticketCoverage` to `{"omit": true}`.
-- For `requirements-discovery`, `error-analysis`, and `implementation-planning`, populate the top-level `endStateCoverage` with exactly one row per end-state id the brief declares — no more, no fewer. `disposition` is one of `addressed` / `deferred` / `not-applicable` / `blocked`. `addressed` requires a `coveredBy` anchor in THIS phase's own deliverable (requirements-discovery: the routing decision, the fan-out unit id, or the `C-NNN` clarification; error-analysis: the root-cause candidate or the next diagnostic; implementation-planning: the `R-NNN` row); every other disposition requires a `rationale`. Do not author a goal of your own here and do not restate the brief — this table records only how this phase accounted for what the reporter already pinned. When the brief declares no end-state ids (a brief authored before those sections existed), omit the field entirely. **Enforced:** `validators/validate-run.py` `_validate_end_state_coverage`.
-- For selected-direction `implementation-planning`, preserve each original requirement ID and populate its `stageRefs`, `stepRefs`, `validationRefs`, and `fileRefs`; `validate_selected_direction_plan` enforces forward and reverse exact coverage. For legacy candidate-comparison `implementation-planning`, populate `implementationPlanning.requirementCoverage` with one row per concrete requirement from the brief / packet, using IDs `R-001`, `R-002`, ... in source order. A `covered` row's `coveredBy` MUST name the specific Option Candidate plus Stage/Step that satisfies the requirement. Use `status: "covered"` only when the report's plan actually covers it; use `documented-deviation` only when `coveredBy` states the concrete alternative and the row records non-empty unique `decisionRefs` plus `approvalDisposition`. Each `C-NNN` ref must name a clarification in this report; each `D-NNNN` ref must name a `decisionDrafts[].number`. `approvalDisposition: "accepted"` requires a referenced clarification with `status: answered|resolved` and non-empty `userInput`; `approvalDisposition: "blocked C-NNN"` requires that same-report clarification to be `status: open, blocks: approval`. Otherwise use `gap` or `blocked C-NNN` and ensure the corresponding `Clarification Items` row blocks approval. Do not collapse this into `ticketCoverage`; ticket coverage is not requirement coverage. **Enforced:** `schemas/final-report-v2.0.schema.json` `$defs.ImplementationRequirementCoverageRow` and `validators/validate-run.py` `_validate_requirement_deviations`.
-- For legacy candidate-comparison `implementation-planning`, each `requirementCoverage` row's `source` is a graded cell, not prose — free text like `"carry-in from requirements-discovery C-001"` is rejected. Write exactly one of: `brief:EB-001` / `brief:PB-001` / `brief:EO-001`, an end-state id the brief declares — when the brief pins ids, citing a heading instead is rejected, because every brief carries the same generic headings and a heading cannot say WHICH reporter line the requirement came from (only a brief authored before the end-state sections existed still takes the older `brief:<heading>` form, and there the heading must literally exist in it); `derived:R-NNN — <one-line reason>`, whose chain must terminate at a `brief:` or `contract:` row of the same table without cycling; or `contract:<rule>`, for artifacts okstra's own phase contract mandates, whose allowlist is exactly the two tokens `decision-record-step` (the §5.4 Decision Drafts materialization step) and `glossary-step` (the glossary proposal step) — any other rule name is rejected, so never invent one. (Maintainer SSOT for that allowlist: `scripts/okstra_ctl/scope_provenance.py` in the okstra repo.) A requirement you cannot source this way does not belong in the table: put it in `clarificationItems[]` with `Blocks=approval`. **Enforced:** `validators/validate-run.py` `_validate_requirement_provenance`. In the same table, anchor every stage number in `coveredBy` to a `Stage` / `Stages` word (`Stage 2`, `Stages 1-3`) — `_validate_stage_has_requirement` reads that cell as prose and fails the plan when a Stage Map stage is cited by no row.
-- For legacy candidate-comparison `implementation-planning`, also populate `implementationPlanning.decisionDrafts` (one row per decision meeting all three decision-record criteria; `[]` otherwise) and `implementationPlanning.skippedAdrCandidates` (evaluated-but-dropped adr-candidates; `[]` otherwise). The schema excerpt enumerates the row shape; the renderer emits §5.4 `### Decision Drafts`. When `decisionDrafts` is non-empty, the plan's stages MUST carry a stepwise step that creates `.okstra/decisions/<NNNN>-<slug>.md` (validate-run gates this).
-- For `implementation-planning`, populate `implementationPlanning.variationPointAnalysis` — a `hasMultipleImplementations` judgement synthesized from the analysis workers' output, not a field filled in last. When it is `true`, write one `points[]` row per varying behavior carrying `behavior`, the two or more `implementations` that serve it, `evidence` (a `path:line`, or the sibling task / stage that already implements that behavior), and an `extractionDecision` of `extract` / `interfaceKind` / `coveredBy` (the Stage Map stage that builds the interface) / `rationale`; when it is `false`, write a non-empty `noVariationRationale` and leave `points` empty (the two branches are mutually exclusive). Do NOT pass a boilerplate rationale. Populate test seams under `implementationPlanning.directionRealization.testSeams` for selected-direction plans and under `implementationPlanning.recommendedOption.testSeams` for legacy candidate-comparison plans. An empty list is a conscious "no seam needed" claim, never a default for a field nobody filled. Every point becomes a `P-Var-*` plan item judged in §5.5.9.
-- When the `Task Type` is `improvement-discovery`, populate `improvementDiscovery.candidates[]`, `improvementDiscovery.lensCoverage[]`, `improvementDiscovery.selectionLimit`, and `improvementDiscovery.userNarrative`. Each candidate carries the 11 logical fields enforced by `validators/validate_improvement_report.py`; each lens-coverage row records candidate IDs or an evidence-backed no-candidate rationale. Source IDs, lens names, and worker prefixes from `scripts/okstra_ctl/improvement_lenses.py`. The standard renderer derives the full reading copy; never author a free-form improvement report.
-
-Write the report record, the Worker Result Path pointer, and the separate audit sidecar with your `Write` tool — that is the canonical authoring path. A Bash heredoc is acceptable ONLY when a specific `Write` call is genuinely rejected by the host environment, and it MUST produce byte-identical content — do not reach for it pre-emptively. Do not invoke `okstra render-final-report`; the full reading copy is on-demand. Confirm data.json, the pointer, and the audit sidecar exist before responding with a short status line prefixed by your model identity, per the preamble §"Return message to the lead". **Enforced:** dispatch `completionPaths` requires the record and the pointer; `validators/validate_session_conformance.py` validates the audit sidecar.
-
-```
-**Model:** Report writer worker, <modelExecutionValue>
-data.json written to <abs path>. Sections populated: <count>.
-```
-
-## Error reporting
 
-Record tool failures through the file selected by `**Worker Error Contract Path:**`. If `**Errors sidecar path:**` is absent, return `REPORT_WRITER_ERRORS_PATH_MISSING` and stop; otherwise use the shared schema and append protocol exactly. This worker has no external CLI.
+The narrative is not free-form Markdown. After the line `# OKSTRA Report Narrative`, every line is one of `- **Field Name**`, `- Item <N>`, or `> value`; blank lines are ignored and **everything else is rejected** — headings (`#`, `##`, `###`), column-0 pipe tables, code fences, bare paragraphs, JSON, YAML, JSON Pointer. Put such text inside a `> ` value instead.
 
-## Notes
+Only these top-level names are allowed: `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`. A section title from a lead procedure document is not a field name. On a refusal, read the allowed names the parser lists for that position instead of guessing again.
 
-- You do NOT participate in convergence re-verification voting.
-- You do NOT produce independent analysis findings — your input is the analysis workers' results plus convergence output.
-- Do NOT modify analysis worker result files. They are read-only inputs to you.
-- If the analysis workers disagree and convergence ended with `Contested` items, surface them in the final report verbatim — do not silently pick a side.
-- `Contested` is a final-only classification. If you see findings labeled `Contested` in the convergence state, the lead has already exhausted re-verification — do not invent a synthesizing answer; surface each worker's position verbatim.
+Report assembly validates every owner input and publishes the final record once. An assembly error naming another owner must be returned to that owner, not repaired in the narrative.

package/runtime/agents/workers/translator-worker.md

@@ -28,24 +28,16 @@ roster.
 2. Build your work list:
 
    ```bash
-   okstra report-translate extract <data.json path>
+   okstra report-translate source --run-manifest <run-manifest>
    ```
 
-   It writes `<stem>.translation-source.json`, a map of JSON Pointer to the English text at it. Those pointers are the whole job — you never invent one, and every value the renderer reads as machinery (ids, paths, commands, enum tokens, CSS-class values, verbatim quotes) has already been withheld from you.
-3. Write the sidecar at `Result Path`, same shape, with each value translated:
+   The command prints a fixed `Source digest` followed by `T-NNN` sections containing only translatable English text.
+3. Write one translated Markdown section per item using the same `## T-NNN` headings, then publish it with `okstra report-translate write --run-manifest <run-manifest> --source-digest <source-digest> --translations <markdown path>`. Copy the digest from step 2. Python rejects a stale report and owns every pointer and the result path.
 
-   ```json
-   {
-     "lang": "<language>",
-     "sourceData": "final-report-<task-type>-<seq>.data.json",
-     "strings": { "/humanSummary/headline": "…" }
-   }
-   ```
-
-4. Verify before you return:
+4. Verify before you return with `okstra report-translate check-data --run-manifest <run-manifest>`:
 
    ```bash
-   okstra report-translate check <Result Path>
+   okstra report-translate check-data --run-manifest <run-manifest>
    ```
 
    A non-zero exit means a pointer resolves nowhere — you altered or invented one. Fix it and re-run. Do not return on a failing check.

package/runtime/bin/okstra-error-log.py

@@ -8,7 +8,6 @@ re-exports the writer's names so the contract tests keep reading one module.
 from __future__ import annotations
 
 import argparse
-import json
 from pathlib import Path
 
 from okstra_ctl.error_log_write import (
@@ -62,16 +61,24 @@ def _build_parser():
     obs.add_argument("--agent-role", required=True, choices=sorted(ALLOWED_AGENT_ROLES))
     obs.add_argument("--model", required=True)
     obs.add_argument("--error-type", required=True, choices=sorted(ALLOWED_ERROR_TYPES))
-    obs.add_argument("--command", required=True)
+    command = obs.add_mutually_exclusive_group(required=True)
+    command.add_argument("--command")
+    command.add_argument("--command-file", type=Path)
     obs.add_argument("--command-kind", required=True)
     obs.add_argument("--exit-code", type=int, default=None)
     obs.add_argument("--duration-ms", type=int, default=None)
-    obs.add_argument("--message", required=True)
+    message = obs.add_mutually_exclusive_group(required=True)
+    message.add_argument("--message")
+    message.add_argument("--message-file", type=Path)
     grp = obs.add_mutually_exclusive_group()
     grp.add_argument("--stderr-excerpt", default=None)
     grp.add_argument("--stderr-excerpt-file", default=None)
-    obs.add_argument("--context-json", default=None,
-                     help="JSON object string for context")
+    obs.add_argument("--cause", choices=sorted(ALLOWED_CAUSES), default=None)
+    obs.add_argument(
+        "--evidence", action="append", default=[], metavar="<kind=value>",
+        help="cause evidence; repeat for targetProbe and controlProbe",
+    )
+    obs.add_argument("--evidence-file", action="append", default=[], metavar="<kind=file>")
     _add_identity_flags(obs)
 
     dump = sub.add_parser("append-from-worker",
@@ -115,15 +122,48 @@ def _read_stderr(args):
     return args.stderr_excerpt
 
 
+def _read_message(args):
+    return args.message_file.read_text(encoding="utf-8").strip() if args.message_file else args.message
+
+
+def _read_command(args):
+    return args.command_file.read_text(encoding="utf-8").strip() if args.command_file else args.command
+
+
 def _read_context(args):
-    if args.context_json is None:
+    if args.cause is None and not args.evidence and not args.evidence_file:
         return None
-    return json.loads(args.context_json)
+    if args.cause is None:
+        raise ValueError("--evidence requires --cause")
+    evidence: dict[str, str] = {}
+    evidence_files = [
+        f"{kind}={Path(filename).read_text(encoding='utf-8').strip()}"
+        for kind, _, filename in (raw.partition("=") for raw in args.evidence_file)
+    ]
+    for raw in [*args.evidence, *evidence_files]:
+        kind, separator, value = raw.partition("=")
+        if not separator or kind not in CAUSE_EVIDENCE_FIELDS or not value.strip():
+            raise ValueError(
+                "--evidence must be one of "
+                f"{', '.join(f'{field}=<value>' for field in CAUSE_EVIDENCE_FIELDS)}"
+            )
+        if kind in evidence:
+            raise ValueError(f"--evidence cannot repeat {kind}")
+        evidence[kind] = value.strip()
+    context: dict[str, object] = {"cause": args.cause}
+    if evidence:
+        context["causeEvidence"] = evidence
+    return context
 
 
 def main(argv=None):
-    args = _build_parser().parse_args(argv)
+    parser = _build_parser()
+    args = parser.parse_args(argv)
     if args.cmd == "append-observed":
+        try:
+            context = _read_context(args)
+        except ValueError as exc:
+            parser.error(str(exc))
         append_observed(
             out_path=args.out,
             task_key=args.task_key,
@@ -132,13 +172,13 @@ def main(argv=None):
             agent_role=args.agent_role,
             model=args.model,
             error_type=args.error_type,
-            command=args.command,
+            command=_read_command(args),
             command_kind=args.command_kind,
             exit_code=args.exit_code,
             duration_ms=args.duration_ms,
-            message=args.message,
+            message=_read_message(args),
             stderr_excerpt=_read_stderr(args),
-            context=_read_context(args),
+            context=context,
             identity=_identity_from_args(args),
         )
         return 0