okstra 0.180.0 → 0.183.2

package/docs/project-structure-overview.md

@@ -58,7 +58,6 @@ okstra/
 ├── skills/                          Claude Code skills (13); `_fragments/` holds shared marker blocks
 ├── .agents/skills/                  Codex repo-local maintainer skills
 ├── .claude/skills/                  Claude Code project-only mirror-sync surface
-├── .claude/settings.json            Claude Code project-only mirror-sync surface
 ├── .codex/hooks.json                Codex project lifecycle hooks
 ├── agents/                          native Claude execution-adapter definitions
 ├── prompts/                         launch/profile contracts, duty catalog, wizard prompt JSON
@@ -67,7 +66,7 @@ okstra/
 ├── validators/                      run / brief / schedule / view validators
 ├── tools/build.mjs                  source → runtime sync
 ├── tools/sync-skill-fragments.mjs   expand shared fragment blocks into skills/*/SKILL.md
-├── tools/korean-sources/            maintainer-only Korean mirror sync engine
+├── tools/korean-sources/            maintainer-only Korean mirror drift report
 ├── config/korean-sources.json       configured English Markdown source roots
 ├── runtime/                         generated install payload; do not edit directly
 ├── tests/                           pytest unit suite
@@ -199,15 +198,15 @@ Runtime/install asset changes follow this checklist:
 | `token-usage` | `src/commands/execute/token-usage.mts` | Wrap installed Python token usage CLI |
 | `spawn-followups`, `error-log` | `src/commands/execute/*.mts` | Follow-up task bundle creation and run error-log append helpers |
 | `memory` | `src/commands/memory/memory.mts` | Store/find global conversation memory under `~/.okstra/memory-book` |
-| `pr` | `src/commands/pr/pr.mts` | `okstra pr <template\|branches\|gen>` — PR body template store under `~/.okstra/template/pr/` (bundled fallback `src/commands/pr/default.md`), base-branch recommendation, and the `gen` JSON bundle (template + `<base>..HEAD` commits + `<base>...HEAD` diffstat) backing the okstra-pr-gen skill. Git-only; no project registration required |
+| `pr` | `src/commands/pr/pr.mts` | `okstra pr <template\|branches\|gen>` — PR body template store under `~/.okstra/template/pr/` (bundled fallback `src/commands/pr/default.md`), base-branch recommendation, and a fixed-text generation bundle for the okstra-pr-gen skill. `--json` preserves the template + `<base>..HEAD` commits + `<base>...HEAD` diffstat machine contract. Git-only; no project registration required |
 | `recap` | `src/commands/inspect/recap.mts` | `okstra recap <assemble\|record\|note>` Node wrapper backing the okstra-inspect `recap` facet — `assemble` is a read-only phase-transition summary, `record` appends one line to `recap/recap-log.jsonl`, and `note` writes an agent-authored note under `notes/` and prints the `--clarification-response` argument for a follow-up run |
 | `stage-map` | `src/commands/inspect/stage-map.mts` | `okstra stage-map <task-key>` — exposes a task's implementation-planning Stage Map as JSON (`stages[].{stage_number,title,depends_on,step_count}` + consumer-state-based `doneStages[]`). If there is no Stage Map, `stages: []`. The read-side basis from which `okstra-schedule-gen` derives stage units and dependency closure |
 | `design-prep` | `src/commands/inspect/design-prep.mts` | `okstra design-prep <list\|show\|write>` thin shim into `scripts/okstra_ctl/design_prep.py` — queries (`list`/`show`) the design items that implementation-planning pre-authored with AI, and records the user-confirmed responses as an append-only sidecar under `design-prep-inputs/` (`write`, `--confirmed` required). It never modifies the report snapshot |
-| `rollup` | `src/commands/inspect/rollup.mts` | `okstra rollup` thin shim into `scripts/okstra_ctl/rollup.py` — read-only cross-task roll-up backing the okstra-rollup skill |
-| `usage-report` | `src/commands/inspect/usage-report.mts` | `okstra usage-report` thin shim into `scripts/okstra_ctl/usage_report.py` — read-only project usage snapshot backing the okstra-usage skill |
-| `container` | `src/commands/inspect/container.mts` | `bin okstra container` thin shim into `scripts/okstra_ctl/container.py` for the okstra-container-build skill |
+| `rollup` | `src/commands/inspect/rollup.mts` | Read-only roll-up; `--text` is the fixed model projection and machine mode remains JSON |
+| `usage-report` | `src/commands/inspect/usage-report.mts` | Read-only usage snapshot; `--text` is the fixed model projection and machine mode remains JSON |
+| `container` | `src/commands/inspect/container.mts` | Container lifecycle shim; `--text` is the command-specific model projection and machine mode remains JSON |
 | `code-review` | `src/commands/inspect/code-review.mts` | `okstra code-review target` thin shim into `scripts/okstra_ctl/code_review_target.py` — resolves what one implementation stage's or one branch's review reads (worktree, branch, base/head commits) and where its result file goes, for the okstra-code-review skill. Read-only; creates no directory or file |
-| `manager` | `src/commands/manager.mts` | Thin shim into `scripts/okstra_ctl/manager_cli.py` for cross-project manager state and child launch packets |
+| `manager` | `src/commands/manager.mts` | Cross-project manager; fixed text is the default and `--json` selects machine output |
 
 `src/lib/python-helper.mts` centralizes Node → Python execution so command modules do not duplicate subprocess wiring.
 
@@ -305,7 +304,7 @@ Important modules:
 | `container.py` | the `okstra container` convergence entrypoint of the okstra-container-build public skill — `provision_container_group` + `up`/`status`/`logs`/`stop-watcher`/`down` dispatch, env-override synthesis, compose argv assembly, and per-container watcher startup |
 | `container_registry.py` | flock-guarded auxiliary index — tracks per-container-group tmux session/pane and watcher findings |
 | `plan_run_root.py` | shared helper deriving `approved_plan_path` → `plan_run_root` and back-tracing the task-key |
-| `manager_cli.py` | `okstra manager` Python entrypoint — manager init/discover/new/task subcommands and JSON output |
+| `manager_cli.py` | `okstra manager` Python entrypoint — purpose-specific fixed text by default, machine JSON with `--json` |
 | `manager_paths.py` | Manager state path SSOT under `~/.okstra/managers/<manager-id>/`; slug fallback uses `u-<sha1-prefix>` when a safe segment would be empty |
 | `manager_store.py` | Manager-owned state mutation — project membership, task planning, assignment, directives, event append |
 | `manager_sync.py` | One-way child project `.okstra` snapshot reader; corrupt child state becomes row-level `error` so other children continue |
@@ -339,6 +338,7 @@ Important modules:
 | `convergence_store.py`, `convergence_migration.py` | atomic JSON persistence plus legacy/new-engine seed decisions; valid terminal finals are reused, while invalid state requires byte-preserving archival before restart |
 | `convergence.py` | `okstra convergence` internal CLI orchestration for `seed`, `plan-round`, `apply-round`, `apply-critic-gaps`, `finalize`, `validate`, and `example`; it composes the reducer, store, and migration policy without duplicating their decisions |
 | `plan_items.py`, `plan_items_cli.py` | deterministic extraction of the report-writer narrative `P-*` plan-item queue plus the `okstra plan-items extract` / `validate` / `seed` / `collect-verdicts` / `apply-verdicts` / `derivations` adapter; v2 data.json remains a read input |
+| `claim_reproduction.py` | reproduces a plan-body single-vote `fact` claim before it can block on one vote — runs the declared probe (`path-exists` / `path-absent` / `literal-present` / `literal-absent` / `citations-differ`) inside the resolved project root and returns `reproduced` / `not-reproduced` / `not-runnable`, which `plan-items apply-verdicts --run-manifest` writes into `reproductionResult` (always overwriting the worker-sent value so a verifier cannot score its own claim). A `judgement` claim, or a `fact` that does not reproduce, takes the quorum route |
 | `plan_derivations.py` | the supersession sweep `_common-contract.md` requires an author to do by hand — extracts the symbols, paths, and ids an answered clarification names and reports every plan string that mentions one. Advisory: it locates candidates and never judges which are now false |
 | `scope_provenance.py` | single source of truth for the scope-provenance grammar every phase-emitted requirement must declare, shared by `validators/validate-run.py` and `validators/validate_fanout.py` so the planning report and fan-out packets cannot drift |
 | `worker_artifact_paths.py` | canonical worker artifact path derivation (e.g. `audit_sidecar_rel` inserts `-audit-` after the first `-worker-` token), so dispatch and validation agree on non-canonical-path rejection |
@@ -352,6 +352,10 @@ Important modules:
 | `domain/worker_stream.py` | the normalised event vocabulary (`Text` / `ToolCall` / `ToolResult` / `Denial` / `Result`) plus its three pure projections: `format_live` (one readable row per event, for the pane), `format_log` (the same plus bodies, for the archive), `final_text` (the closing message alone). Also `content_block_events`, the normaliser for the wire shape keyed on `type` with `message.content` blocks, which three providers share. No files, no clock |
 | `domain/worker_role.py` | per-role execution budgets — the 1500s/600s idle pair lives here once instead of being re-declared in each wrapper |
 | `task_target.py` | shared helper resolving `task-key → (task_root, project_root)` (`resolve_task_root`) |
+| `contract_graph.py`, `contract_graph_cli.py` | runtime-contract graph loader + cross-reference/dependency-closure validator and its `okstra contract-check --root <dir> (--profile\|--operation)` CLI boundary. Loads the agent contract schemas (`common`/`role`/`duty`/`profile`/`operation`), validates known role capabilities, and reports the dependency closure with per-file `path`/`schemaVersion`/`sha256`; an invalid contract raises `ContractGraphError` |
+| `json_boundary.py` | strict JSON persistence boundaries for okstra-owned artifacts — a sealed `ExternalJsonSource` (validated producer + path) is the only way owned JSON is read, and `JsonBoundaryError` names artifact / reason / path when a write cannot satisfy its contract; the SSOT that keeps the model out of internal JSON key/path authorship |
+| `fixed_text.py` | shared scalar-line format for the model-facing fixed-text projections — `scalar` neutralises complex values and control characters, `line` renders one static-labelled Markdown list row, and `value_lines` losslessly flattens a JSON-shaped value into fixed name/order/value rows |
+| `model_io_cli.py` | renders purpose-scoped fixed Markdown input from okstra-owned JSON for the model boundary — resolves the current run/project through the run manifest (`validated_run_authority`, `canonical_run_state_artifact`) and emits only each command's allow-listed fields in fixed order instead of expanding arbitrary nested objects |
 
 > `i18n.py` (the final-report i18n dictionary loader + Jinja2 lookup) is an intentionally undocumented internal helper — it is a render helper that users and contributors do not need to know about in the canonical docs, so it is excluded from the module map.
 
@@ -367,7 +371,7 @@ Project resolver and read-only state helpers:
 
 Token/cost accounting:
 
-- provider adapters: `claude.py`, `codex.py`, `antigravity.py`
+- provider adapters: `claude.py`, `codex.py`, `antigravity.py`, `grok.py` (`grok.py` reads the Grok Build session docs under `~/.grok/sessions/<percent-encoded-cwd>/`, taking cumulative tokens from the last `params.update.usage.modelUsage` snapshot in `updates.jsonl`)
 - aggregation: `collect.py`, `blocks.py`, `jsonl_io.py`, `paths.py`
 - incremental scan cache: `cursor.py` (`$OKSTRA_HOME/cache/token-usage/` byte cursor + usage event extracts; bypass with `--no-cache`)
 - pricing: `pricing.py`
@@ -475,24 +479,23 @@ These files are native Claude execution adapters, not provider-neutral LLM trans
 
 ### 4.13 `tools/korean-sources/`
 
-The maintainer-only Korean review-mirror lifecycle has one stateful public
-boundary: `lifecycle.mjs`. `cli.mjs` and `hooks.mjs` are adapters that call it;
-they do not reconstruct observations or transitions. `config.mjs` and
-`markdown.mjs` remain pure configuration and protected-Markdown validators.
+The maintainer-only Korean review mirrors. The tool reports which mirrors have
+drifted and checks a translation's structure; a maintainer session does the
+translating and the writing. Nothing here observes edits or runs on its own.
 
 | File | Role |
 |---|---|
-| `lifecycle.mjs` | Public lifecycle seam: bootstrap, inspect, evidence transitions, and reviewed-packet application |
-| `lifecycle-store.mjs` | Versioned lifecycle store, canonical JSON IDs, v1 migration, and repository lock |
-| `lifecycle-observation.mjs` | Current source/mirror snapshots, rename detection, and derived change observations |
-| `lifecycle-evidence.mjs` | Decision, direction, review-packet, semantic-confirmation, and approval validation |
-| `lifecycle-application.mjs` | Allowed packet operations, journaled idempotent apply, and completion verification |
-| `lifecycle-index.mjs` | Korean mirror `.project-docs/INDEX.md` row validation and updates |
-
-Maintainers follow `tools/korean-sources/workflow.md` through observation,
-conditional direction, review packet, semantic confirmation, conditional
-approval, and apply. The paired local skills only delegate to that workflow;
-they are not published user skills.
+| `cli.mjs` | The three commands: `status`, `validate --source`, `mark --source` |
+| `baseline.mjs` | Drift report and the source/mirror hash pair recorded at the last sync |
+| `config.mjs` | `config/korean-sources.json` validation and source↔mirror path mapping |
+| `markdown.mjs` | Protected-Markdown structure comparison behind `validate` |
+| `path-safety.mjs` | Symlink-refusing repository reads and atomic writes |
+
+Source and mirror hold the same document in two languages, so they never hash
+alike and drift cannot be read from the two files alone. `mark` records the pair
+of hashes in `.project-docs/ko-sources/.sync-baseline.json`, which is the only
+state the tool keeps. Maintainers follow `tools/korean-sources/workflow.md`; the
+paired local skills only delegate to it and are not published user skills.
 
 ---
 
@@ -661,7 +664,7 @@ When changing code, keep these docs in sync:
 - New report field/section: update schema, template, report-writer worker, validator tests, this file's report model if user-visible.
 - New phase/profile behavior: update `prompts/profiles/*`, `docs/architecture.md`, `docs/cli.md`, and `README.md` if user-facing.
 
-Edit English canonical Markdown sources directly. After changing a path registered in `config/korean-sources.json`, process the local Korean mirror queue with `$sync-korean-sources` or `/sync-korean-sources`. `.project-docs/ko-sources/**` is maintainer-local only: it is neither published nor committed.
+Edit English canonical Markdown sources directly; nothing asks you to touch the Korean mirror in the same change. A maintainer session reconciles the mirrors on its own schedule with `$sync-korean-sources` or `/sync-korean-sources`, which begins by reading `node tools/korean-sources/cli.mjs status`. `.project-docs/ko-sources/**` is maintainer-local only: it is neither published nor committed.
 
 ---
 
@@ -692,4 +695,4 @@ Clarifications now live in the unified `## 1. Clarification Items` table. Deprec
 
 ---
 
-*Updated: 2026-08-21 · Source of truth checked against `package.json`, `bin/okstra`, `src/cli-registry.mts`, `src/lib/skill-catalog.mts`, `tools/build.mjs`, `scripts/`, `skills/`, `agents/`, `templates/`, `schemas/`, `validators/`, and tests.*
+*Updated: 2026-08-23 · Source of truth checked against `package.json`, `bin/okstra`, `src/cli-registry.mts`, `src/lib/skill-catalog.mts`, `tools/build.mjs`, `scripts/`, `skills/`, `agents/`, `templates/`, `schemas/`, `validators/`, and tests.*

package/docs/task-process/implementation.md

@@ -53,10 +53,13 @@ here because they were previously readable only by tracing the runtime sources.
   Clarification Items` rows — the `user-response-*.md` sidecars under
   `runs/implementation-planning/user-responses/`, a sibling of the directory holding the
   plan itself — are collected into `instruction-set/clarification-response.md`. Those
-  sidecars are written by the user, not by the report renderer: the report HTML's `Export
-  user response` button downloads a file the user then saves there, and `okstra
-  user-response write` writes one directly. The renderer at most pre-creates that
-  directory empty so the user does not have to; it never puts a sidecar in it.
+  sidecars are written by the user, not by the report renderer. The report HTML's `Export
+  user response` button downloads a file the user then saves there. The in-session flow
+  reads `user-response list-view` and `user-response show-view --report <path>
+  --project-root <root>`, then uses `user-response begin`, typed `user-response answer`
+  and decision commands, and `user-response finalize` to publish the sidecar. The
+  renderer at most pre-creates that directory empty so the user does not
+  have to; it never puts a sidecar in it.
   The plan document is *not* copied: it reaches the run as the `--approved-plan` path and
   the executor re-reads it there. An explicit `--clarification-response` wins when given;
   the automatic attachment is the fallback for an implementation run that supplies none

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.180.0",
+  "version": "0.183.2",
   "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.180.0",
-  "builtAt": "2026-08-21T05:25:42.034Z",
+  "package": "0.183.2",
+  "builtAt": "2026-08-23T08:48:03.022Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

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

@@ -48,7 +48,7 @@ from the provider name. `lead` is a compatibility alias for `leader`.
 4. Anchor all file operations to the absolute `Project Root` from the lead prompt. Use absolute paths — do NOT rely on inherited cwd. Never use `cd` to change directory.
    - **Executor exception (implementation phase only):** when this worker is dispatched as the `Executor` and the lead prompt provides an `EXECUTOR_WORKTREE_PATH` that differs from the session's inherited cwd, cwd-sensitive Bash commands (`cargo *`, `npm *`, `pnpm *`, `bun *`, `pytest`, `make *`, `go *`, language-toolchain test/build commands) MUST be prefixed with `cd <EXECUTOR_WORKTREE_PATH> && ` in the same Bash invocation — e.g. `cd /Users/.../worktrees/foo && cargo test -p bar`. Do NOT wrap the whole thing in `bash -lc "..."` or `bash -c "..."`; pass the chained command directly to the Bash tool so the leading `cd` token remains visible to the permission layer. The `cd` is scoped to the single Bash subshell and does not mutate the session's shell state, so this does not conflict with the "never use cd" rule above (which prevents the worker from drifting the session cwd across calls).
    - **Executor coding-conventions preflight (BLOCKING, before your first `Edit` / `Write`):** when dispatched as the `Executor`, you MUST run the coding-conventions preflight defined in the executor sidecar (`prompts/profiles/_implementation-executor.md` → "Pre-implementation context exploration") before writing any code. Use this worker prompt's `**Coding preflight pack:**` anchor header; read that pack's `overview.md` and `clean-code.md`, then follow the routed pack's language → framework → architecture stages, iterating every rule and loading every matching resource (for example `frameworks/node-server.md` and `architectures/hexagonal.md` when their conditions match). The preflight pack is a runtime resource, not an auto-invoked skill; read the files via the Read tool by absolute path.
-   - **Executor post-write gates (BLOCKING, before your final commit / before claiming done):** the same dispatch prompt carries two gate blocks the lead appends after the preflight — `Pre-commit diff review sweep` (`prompts/profiles/_implementation-diff-review.md`) and `Implementation self-check` (`prompts/profiles/_implementation-self-check.md`). Execute both and record their coverage lines in your worker result exactly as the blocks specify. The codex/antigravity wrappers refuse to launch when an executor prompt lacks these blocks (`*_POSTWRITE_GATE_MISSING`); this worker runs in-process with no wrapper gate, so the contract lands on you directly — if either block is missing from your dispatch prompt, record a `tool-failure` in the errors sidecar and tell the lead to re-dispatch with the blocks included instead of skipping the gates.
+   - **Executor post-write gates (BLOCKING, before your final commit / before claiming done):** the same dispatch prompt carries two gate blocks the lead appends after the preflight — `Pre-commit diff review sweep` (`prompts/profiles/_implementation-diff-review.md`) and `Implementation self-check` (`prompts/profiles/_implementation-self-check.md`). Execute both and record their coverage lines in your worker result exactly as the blocks specify. The codex/antigravity wrappers refuse to launch when an executor prompt lacks these blocks (`*_POSTWRITE_GATE_MISSING`); this worker runs in-process with no wrapper gate, so the contract lands on you directly — if either block is missing, record a typed `tool-failure` through `okstra error-log append-observed` and tell the lead to re-dispatch with the blocks included.
    - **Verifier QA-gate exception:** verifier roles MAY use the same `cd <WORKTREE> && <cmd>` shape when executing project-declared `qaCommands` (lint / format / typecheck / test) from `project.json`, since those commands are cwd-sensitive by nature. Outside the QA gate, verifiers still read with absolute paths only — do NOT use `cd` for file inspection.
    - **Shell commands must not be able to prompt:** this worker runs inside the host session, so its Bash calls see the user's own shell, where `cp`, `mv`, and `rm` are commonly aliased to their `-i` form. The confirmation that alias raises has nobody to answer it and the dispatch hangs until it is killed. Invoke these as `command cp` / `command mv` / `command rm` — alias expansion is skipped and the tool behaves exactly as written. Do not reach for `-f` instead; it also changes what the tool does on failure (`rm -f` reports success on a path that never existed).
    - **No extra chaining beyond `cd && cmd`:** the permission matcher only allows the exact two-segment shape `cd <PATH> && <single-command>`. Do NOT append additional pipes, semicolons, redirects, or `&&` chains — e.g. `cd ... && cargo test ... 2>&1 | tail -20; echo "exit:$?"` will trigger a permission prompt every dispatch because the trailing `| tail`, `; echo`, and `2>&1` tokens disqualify the prefix match against `Bash(cargo:*)`. Let Claude Code capture the full stdout/stderr and exit code natively — do not post-process with `tail`, `head`, or `echo "exit:$?"`. If output truncation is genuinely needed, run the command first and read the result in a separate tool call.
@@ -61,7 +61,7 @@ from the provider name. `lead` is a compatibility alias for `leader`.
 
 Before producing any output, you MUST:
 
-1. Extract `**Worker Preamble Path:**` and `**Worker Error Contract Path:**` from the lead prompt and Read both selected files end-to-end with one full-file `Read` each. The preamble owns audience procedure; the error contract owns sidecar schema and write rules. Never replace the selected path with a hard-coded analysis preamble.
+1. Extract `**Worker Preamble Path:**` and `**Worker Error Contract Path:**` from the lead prompt and Read both selected files end-to-end with one full-file `Read` each. The preamble owns audience procedure; the error contract owns typed error-log write rules. Never replace the selected path with a hard-coded analysis preamble.
 2. Read every primary input file the lead enumerated under `## Inputs` (or equivalent heading) end-to-end, following the selected preamble. Analysis workers normally receive `analysis-packet.md`; implementation workers receive their role sidecar and approved deliverable inputs.
 3. When the prompt carries `**Evidence ledger:** required-v1`, follow the selected preamble's `Evidence read ledger` procedure for every claim-evidence file you open. Do not invent a separate audit-row format here.
 
@@ -91,13 +91,13 @@ After your `Write` to the assigned worker-results file (path provided by Lead as
    The `**Model:**` line precedes whatever you return — analysis status above, or a convergence reverify verdict summary.
 2. Do NOT perform additional `Read`, `Grep`, `Glob`, MCP, or self-review tool calls after the file is written.
 3. Do NOT rewrite the worker-results file with `Write` more than once. If a correction is genuinely required, perform a single `Edit` and then return immediately.
-4. The only exception is recording a `tool-failure` in the errors sidecar when a post-Write failure is itself the failure being reported — return immediately after that single sidecar append.
+4. The only exception is recording a `tool-failure` with the typed error-log command when a post-Write failure is itself the failure being reported — return immediately after that command.
 
 If you find yourself thinking "let me double-check section 3" or "I should read one more file to be safer" after the Write succeeded — stop. Convergence (Phase 5.5) and the Report writer worker (Phase 6) will reconcile gaps across all three workers; over-investing in single-worker depth at the expense of returning quickly is a net loss for the run.
 
 ## Error reporting
 
-Record your own tool failures per the file selected by `**Worker Error Contract Path:**`: extract `**Errors sidecar path:**` from the dispatch prompt (return `CLAUDE_WORKER_ERRORS_PATH_MISSING` without proceeding if absent), then append `tool-failure` entries exactly as that shared contract requires. This worker has no external CLI, so MCP and Bash failures use the same sidecar protocol.
+Record your own tool failures per the file selected by `**Worker Error Contract Path:**`: extract `**Errors log path:**` from the dispatch prompt (return `CLAUDE_WORKER_ERRORS_PATH_MISSING` without proceeding if absent), then invoke its typed `okstra error-log append-observed` command. This worker has no external CLI, so MCP and Bash failures use the same typed protocol.
 
 ## Notes
 

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

@@ -14,8 +14,6 @@ Write only the report narrative Markdown at `**Result Path:**`, the pointer at `
 
 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.
 
-The analysis packet is the only MCP authority. If its MCP section is absent or says none, do not infer an MCP server from the task brief or another input.
-
 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.
 
 **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.
@@ -26,6 +24,8 @@ The narrative must not contain `designPreparation`, `designSurfaceCoverage`, `ex
 {"candidateDetailBoundary":{"expectedChangeAreas":"direction-level-only","expectedVerification":"direction-level-signals-only","forbidden":["exact-file-lists","stage-lists","test-commands"]}}
 ```
 
-Use `# OKSTRA Report Narrative`, nested `- **Field**` rows, `- Item N` array entries, and `> value` scalar lines. Do not write JSON, YAML, JSON Pointer, or fenced JSON.
+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.
+
+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.
 
 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