okstra 0.201.3 → 0.204.0

package/docs/for-ai/skills/okstra-setup.md

@@ -1,158 +0,0 @@
-# okstra-setup AI Manual
-
-## Source
-
-- Skill source: [`skills/okstra-setup/SKILL.md`](../../../skills/okstra-setup/SKILL.md)
-- CLI registry: [`src/cli-registry.mjs`](../../../src/cli-registry.mjs)
-- project registration impl: `src/commands/lifecycle/setup.mjs`
-- install/ensure-installed impl: `src/commands/lifecycle/install.mjs`
-
-## Purpose
-
-`okstra-setup` handles two things.
-
-1. Machine-level runtime install: `~/.okstra/`, `~/.claude/skills/`, `~/.claude/agents/`
-2. Project-level registration: `<PROJECT_ROOT>/.okstra/project.json`
-
-It is not a day-to-day task-running skill. If a task is already prepared, route to `okstra-run` or `okstra-inspect`.
-
-## When to use
-
-Use it when:
-
-- The user asks for "okstra setup", "setup okstra", "initialize okstra", "okstra init", "first time setup".
-- `~/.okstra/version` is missing or looks stale.
-- The current project has no `.okstra/project.json`.
-
-Do not use it when:
-
-- The user wants to start a task run. Use `okstra-run` instead.
-- The user wants to view status/history/report. Use `okstra-inspect` instead.
-- `.okstra/project.json` already exists and only day-to-day usage is needed.
-
-## Pre-run checks
-
-Tell the user that Node 18+ and Python 3.10+ are required. If it is unclear whether the current working directory is inside the project that will host the okstra metadata, confirm the project root first.
-
-Install command:
-
-```bash
-npx -y okstra@latest install --runtime claude-code
-```
-
-Treat this command as idempotent. Even if already installed, re-run it to align the runtime, skill, and agent payload with the current package version (agent payload = the `~/.claude/agents/<worker>.md` worker definitions + the `~/.okstra/installed-agents.json` manifest). If it fails, show the stderr to the user verbatim. Do not fall back to the legacy `okstra-install.sh`.
-
-## Command invocation rule
-
-After `okstra install`, every subsequent command must begin with the literal `okstra` token.
-
-Allowed forms:
-
-```bash
-okstra preflight
-okstra setup --yes --project-root /abs/project --project-id my-project
-okstra doctor --runtime claude-code
-```
-
-Forms to avoid:
-
-- `export PYTHONPATH=...`
-- `eval "$(okstra paths --shell)"`
-- shell variables like `$PROJECT_ROOT`
-- `$(...)` command substitution
-- okstra calls wrapped in `if`, `&&`, `||`
-
-Because `okstra <subcmd>` bootstraps its own Python path, do not use `okstra paths --shell` in this skill. If you need the okstra home, run `okstra paths --field home` as a separate call and carry the printed path.
-
-## Project root resolution
-
-Run first:
-
-```bash
-okstra preflight
-```
-
-Handle the result:
-
-- `Okstra preflight: ready`: already a registered project. Show `Project root`, `Project JSON`, and `Project ID` to the user and confirm whether to keep it.
-- `Okstra preflight: failed` with `Stage: resolve`: get an absolute project root from the user and re-run `okstra preflight --cwd /abs/path`.
-- `Okstra preflight: failed` with `Stage: project_json_missing`: proceed with the normal create path.
-- any other failure stage: show `Reason` verbatim and follow `Recovery`.
-
-## Create or keep project.json
-
-If `<PROJECT_ROOT>/.okstra/project.json` exists, show `projectId` and `projectRoot` and confirm whether to keep or overwrite. The default is keep. Changing the existing `projectId` requires deleting the file, so do not overwrite automatically.
-
-If the file does not exist, ask for a project id. The answer must be non-empty and contain at least one alphanumeric character. Calling `okstra setup --yes` with an empty value fails, so re-ask.
-
-Create command:
-
-```bash
-okstra setup --yes --project-root /abs/project --project-id my-project
-```
-
-## Optional configuration
-
-Per the source, Step 3.5 is optional configuration performed only when the user explicitly wants it — read `references/project-config.md` in the skill directory for the detailed procedure. If the defaults are enough, skip it and go to doctor.
-
-Optional settings:
-
-- `worktreeSyncDirs`: a list of project-relative directories to symlink into the task worktree. The default is `.project-docs`, `.scratch`, `graphify-out`, `.claude`.
-- `qaCommands`: check-only lint/format/typecheck/test commands the implementation verifier runs.
-- `qaEnv`: the replica/test DB, local app URL, env file, and surface patterns
-  Okstra uses to attempt Tier 3 automatically; real DB/API verification remains
-  a user-owned advisory when the environment is unavailable or the result is
-  non-PASS.
-- PR body template: `okstra config set pr-template-path "<path>" --scope project|global`
-- final report language: `okstra config set report-language <language-tag> --scope project` (`en`, `ko`, `fr`, `pt-BR`, …; default `en`)
-- `architecture.style`: the project's declared architecture — `hexagonal`,
-  `layered`, or `none` (default `none` when absent, unrecognized, or
-  unreadable). `okstra setup` never writes it; hand-add it to `project.json`
-  and the upsert preserves it. Declaring a style promotes that architecture's
-  placement rules from advisory to a binding planning + verification
-  constraint — under `hexagonal` an extracted variation point must be a port,
-  under `layered` the dependency direction is worker-judged with no machine
-  check. See section F of `references/project-config.md`.
-- `reviewRulePacks`: absolute paths to the project's own review rule packs (a
-  team PR-review skill's `SKILL.md`). Without a declaration a pack applies only
-  when the task brief cites its exact path; declared here it applies to every
-  run, and the two channels are a union. Read by `implementation-planning`, the
-  executor preflight, the implementation verifier, and `final-verification`.
-  `okstra setup` never writes it. `okstra doctor --phase <phase>` fails when a
-  declared path is not readable. See section G of
-  `references/project-config.md`.
-
-If `qaCommands.cmd` contains a token implying mutation, the verifier refuses it. The actual authority for the deny-list is `scripts/okstra_ctl/qa_commands.py`.
-
-## Automatic Claude settings symlink
-
-`okstra setup` provisions `<PROJECT_ROOT>/.claude/settings.local.json` as a symlink to `~/.okstra/templates/settings.local.json`. If an existing regular file is present, it backs it up as `.bak.<timestamp>` and then places the symlink. If a failure message appears, the user must manually merge the existing project-specific rules.
-
-## Verify
-
-Run last:
-
-```bash
-okstra doctor --runtime claude-code
-```
-
-If every check is OK, report setup complete. If any check fails, show the output verbatim and let the user decide whether to reinstall or skip.
-
-## Completion message
-
-Keep it short and include the following.
-
-- runtime location: `~/.okstra` (also show the `version stamp: x.y.z` line from the install summary)
-- project metadata: `<PROJECT_ROOT>/.okstra/project.json`
-- `projectId`
-- next step: `/okstra-run`
-
-## Common failure handling
-
-| Symptom | Handling |
-|---|---|
-| `command not found: npx` | Point to installing Node 18+ |
-| `--project-id is required` | Re-ask for the project id and re-run with a non-empty value |
-| `projectId mismatch` | Confirm with the user which id is canonical. Do not delete automatically |
-| `.okstra/` write EACCES | Explain the ownership/writability problem |
-| `.claude/settings.local.json` symlink warning | Show the backup file and symlink state to the user and guide a manual merge |

package/docs/for-ai/skills/okstra-usage.md

@@ -1,29 +0,0 @@
-# okstra-usage AI Manual
-
-## Purpose
-
-Use `okstra-usage` for a project-wide historical resource snapshot. It is not a
-single-task inspection (`okstra-inspect`) and not a cross-task status/report
-digest (`okstra-rollup`).
-
-## Call
-
-Run preflight, resolve a positive day count (default 30), then call exactly once:
-
-```bash
-okstra usage-report --days 30 --project-root <projectRoot> --text
-```
-
-## Render contract
-
-Render the numbered `By task type` rows and fixed totals without recomputing them.
-Show Runs, returned collection rate as Coverage, Raw tokens, Billable, Cost, CPU, and Wall. Surface numbered
-unavailable-reason and unmatched-model rows. Missing usage is excluded data, not
-zero usage.
-
-## Boundaries
-
-- One task's elapsed/context detail: `okstra-inspect`.
-- Task-group/project status and report digest: `okstra-rollup`.
-- HTML dashboards, budgets, forecasts, and task/model/worker drill-downs are not
-  part of this MVP.

package/docs/for-ai/skills/okstra-user-response.md

@@ -1,72 +0,0 @@
-# okstra-user-response AI Manual
-
-## Sources
-
-- Skill source: [`skills/okstra-user-response/SKILL.md`](../../../skills/okstra-user-response/SKILL.md)
-- Response core: [`scripts/okstra_ctl/user_response.py`](../../../scripts/okstra_ctl/user_response.py)
-
-## Purpose
-
-`okstra-user-response` answers unresolved `C-*` clarification items and records explicit plan decisions without hand-editing a report or sidecar. The user selects or writes every answer. Publication changes only the user-owned `runs/<task-type>/user-responses/` sidecar.
-
-The model-facing reads are fixed text. Do not use the automation-compatible JSON reads to drive a conversation. Do not open the final-report record directly.
-
-| Command | Purpose |
-|---|---|
-| `okstra user-response list-view --home <home> --project <projectId> --limit 3` | List tasks that still need clarification answers or a plan decision. |
-| `okstra user-response show-view --report <reportPath> --project-root <projectRoot>` | Show open questions, choices, impact, why asked, linked plan items, cited artifacts, approval context, plan candidates, and current state after validating project ownership. |
-| `okstra user-response begin --report <reportPath> --task-key <taskKey>` | Open a typed transaction and return an opaque id. |
-| `okstra user-response answer ...` | Add one validated answer to the draft. |
-| `okstra user-response plan-decision ...` | Record an explicit plan decision. |
-| `okstra user-response legacy-report-authoring ...` | Record contract 2.0 report-authoring permission. |
-| `okstra user-response finalize --transaction <transaction>` | Merge and atomically publish the sidecar. |
-
-The legacy `list` and `show` JSON commands remain for automation compatibility. They are not model-facing reads.
-
-## Flow
-
-1. Run `okstra preflight --runtime <host-runtime>` for the current harness. On `Okstra preflight: failed`, show `Reason` and `Recovery`, then stop. On `Okstra preflight: ready`, carry `Project root`, `Project ID`, `Runtime`, and `Relay contract`, then run `okstra paths --field home`.
-2. Read the relay `Wizard interaction relay` JSON. When `native-single` is available and the option count fits `nativeLimits`, call `interactions.native-single.function` (`AskUserQuestion` / `ask_user_question` / `request_user_input` from that field). Do not print a numbered list in chat while the native tool is available. Emit the question as the last thing in that turn; text emitted after the call renders below the question. Otherwise render a numbered Markdown list. Do not substitute one host function name for another. Copy the view's `Picker:` `- Label:` / `Description:` pairs into that function in that order. Do not rebuild labels from the `Options:` dump. `--option-number` is the 1-based `Option N:` index, which is the same order as `Picker:`. The HTML report's `<select>` uses the same `option.answer` values. Pass only the `list-view` `Picker:` rows, the report `Picker:` rows, or the two confirmation labels. Do not append `Enter directly`. Claude Other, Grok `z`, and Codex's free-form row are `Enters an answer`; on a numbered list, so is a next message that is not a listed label or its 1-based number. Do not ask a second question for the custom value.
-3. Select a task from `list-view` through that host picker. A host free-text row or unmatched next message is the report path or task key.
-4. Read only `show-view --report <reportPath> --project-root <projectRoot>` for report facts. The view also prints `Why asked`, `Linked plan items`, and `Cited artifacts`.
-5. Read every cited `path:line` under the project root and every linked plan-item definition before asking. Do not search beyond that list. Investigation explains; it never changes `options[]`.
-6. Ask one open clarification at a time in the user's language through the host picker. The question body is why, what is already decided, the fork, and what stays blocked. Do not lead with `Kind`, `Blocks`, `Expected form`, or `C-NNN`. Keep the row id in parentheses at the end.
-7. Echo the complete response and confirm through the host picker (`Record as shown` / `Change an answer`). Do not ask them to type `confirmed`.
-8. Begin the transaction, add answers and decisions, then finalize it.
-
-Each `options[]` row displays `{role, answer, rationale, scopeImpact, addedWork, directionChange, disposition}`. Contract 3.0 additionally displays `reach`, `scopeEffects`, and row-level `approvalContext`. Option descriptions use this order: If you pick this (`addedWork`). What it reverses (`directionChange`). Scope (`reach` or `scopeImpact`). Why it is on the board (`rationale`). If the view says `not stated in the report`, repeat that text and never invent a value. A quote from a cited file may follow those axes; it does not replace them.
-
-When the user selects a predefined option, pass only the fixed view's one-based option number. Python resolves that option's `disposition`, answer, reach, and scope effects from the validated report:
-
-```bash
-okstra user-response answer --transaction <transaction> --clarification-id <C-NNN> --kind <kind> --option-number <N>
-```
-
-Every value, rationale, and reason body file must be a regular file under `<projectRoot>/.okstra/tmp/user-response/`; external files and symbolic links are rejected. For direct input, write the user's exact words there and use the mutually exclusive direct form:
-
-```bash
-okstra user-response answer --transaction <transaction> --clarification-id <C-NNN> --kind <kind> --disposition <answer|reframe> --value-file <value.md> [--rationale-file <rationale.md>]
-```
-
-Record a plan decision only when the user states it explicitly. Any reason file stays in that same temporary directory:
-
-```bash
-okstra user-response plan-decision --transaction <transaction> --status approved [--implementation-option <candidate-name>]
-okstra user-response plan-decision --transaction <transaction> --status <revision-requested|rejected> --reason-file <reason.md>
-```
-
-The implementation option must match a candidate printed by `show-view`. A report with no open clarification can still require this decision.
-
-Contract 2.0 alone supports legacy report-authoring permission. Its reason file stays in that same temporary directory:
-
-```bash
-okstra user-response legacy-report-authoring --transaction <transaction> --status <approved|denied> --reason-file <reason.md>
-```
-
-Finish with:
-
-```bash
-okstra user-response finalize --transaction <transaction>
-```
-
-Do not decode the transaction id. Do not inspect transaction state. Do not hand-edit report records, rendered reports, or sidecars.

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

@@ -1,128 +0,0 @@
----
-name: claude-worker
-description: |
-  Use this agent when dispatched as a Claude worker for okstra cross-verification tasks. Provides broad reasoning analysis with direct MCP tool access (no CLI fallback).
-
-  <example>
-  Context: The okstra skill is orchestrating a multi-agent cross-verification run.
-  user: "okstra this task bundle"
-  assistant: "Spawning claude-worker agent to get Claude analysis."
-  <commentary>The okstra skill dispatches this agent as part of the worker roster.</commentary>
-  </example>
-
-  <example>
-  Context: A cross-verification needs Claude perspective on broad reasoning.
-  user: "cross verify this implementation"
-  assistant: "Running claude-worker for independent Claude analysis."
-  <commentary>Cross-verification tasks require independent AI worker outputs.</commentary>
-  </example>
-model: inherit
-color: blue
-tools: ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "TodoWrite", "WebFetch", "WebSearch"]
----
-
-This is the Claude host-native execution adapter for a materialized Okstra
-invocation. The final prompt's duty contract owns the role boundary,
-responsibility, and prohibited actions. This file owns Claude tool usage,
-artifact persistence, and liveness procedure only. Do not shell out to another
-model CLI, and refuse a dispatch whose prompt has no adjacent verified
-invocation metadata. Consume the stored `executionLabel`; do not infer a role
-from the provider name. `lead` is a compatibility alias for `leader`.
-
-## Execution Rules
-
-1. The summon message you were invoked with carries the absolute path of your dispatch prompt document — it is not the prompt itself. Read that document COMPLETELY before doing anything else: the `Read` tool returns up to 2000 lines per call, so continue with `offset` until you have seen the last line of the file. Every later rule that says "the lead prompt" means that document. If the summon carries no path, immediately return:
-   `CLAUDE_PROMPT_PATH_MISSING: dispatch prompt document path was not provided`
-
-2. Extract the absolute `Project Root` from the lead prompt (look for a line starting with `**Project Root:**` or `Project Root:`). If it is missing, immediately return:
-   `CLAUDE_PROJECT_ROOT_MISSING: absolute Project Root was not provided in the lead prompt`
-
-3. The document already lives at its own `Assigned worker prompt history path:` — the lead persisted and verified it before dispatch. Do NOT rewrite it. Check that the path you were summoned with matches that header (resolve a relative header value against `Project Root`); on a mismatch, return:
-   `CLAUDE_PROMPT_PATH_MISSING: summon path does not match the document's assigned prompt history path`
-
-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, 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.
-
-5. **MCP usage**: The canonical list of MCP servers and tools available for this run lives in the analysis packet's `Available MCP Servers` section. If the section is absent or says none, treat MCP as unavailable for this run; never infer tools from host configuration. When the task requires inspection of an external system covered by a listed server, call the tool directly by name (e.g. `mcp__<server>__<tool>`). Do NOT shell out via `claude --mcp-cli call ...` or run the tool name as a Bash command — those are not valid invocation paths. If a server you need is not listed, record `MCP not available for this run` in your worker output rather than guessing a tool name.
-
-6. If your dispatch prompt carries a `**Phase 1.5 Grilling Log:** <abs-path>` anchor header (the lead injects it only on `improvement-discovery` runs), the file it points to is the authoritative scope and lens definition. Read it at the absolute path from the anchor — do NOT synthesize the path from `<RUN_DIR>`. Use its `Resolved scope` and `Resolved lenses` blocks and do NOT re-interpret the brief's raw `scan-scope` / `priority-lenses` fields. Findings that violate the resolved lens whitelist or scope are rejected by `validators/validate_improvement_report.py`.
-
-## Required Reading Before Any Analysis
-
-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 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.
-
-**Heartbeat — write the audit sidecar EARLY and APPEND per stage (BLOCKING).** This worker runs as an in-process Agent, a cmux surface, or a CLI wrapper subprocess, so the lead has no `BashOutput`-style liveness signal while it waits for your return — the audit sidecar is the only signal that survives a silent hang.
-
-- **Where:** the absolute path in `**Audit sidecar path:**`.
-- **Start (before the per-file reads):** immediately after extracting `Project Root` and the assigned paths, `Write` just the heading line (`# Claude Worker Audit — <task-key>`) plus one `- PROGRESS: started <ISO-8601-UTC>` line.
-- **Append per stage** (`Edit` or heredoc `>>`): `read-<filename>`, `analysis-start`, `findings-draft-start`, `findings-draft-complete`, `write-result-start`.
-- **Cadence MUST NOT exceed 5 minutes:** if a single analysis stage runs longer, emit a `- PROGRESS: in-stage:<stage> <ISO-8601-UTC>` line. A 5-minute-stale sidecar mtime is the canonical "this worker has hung" signal for the operator.
-- **Enforcement:** the Phase 7 validator (`validate_session_conformance.py`) parses these `- PROGRESS:` lines post-hoc and fails the run when the first stage is not `started`, `write-result-start` is missing despite an existing result file, timestamps regress/unparse, or consecutive lines are more than 5 minutes (+60s grace) apart.
-
-## Worker Output Structure
-
-Follow the output contract selected for your audience. Analysis workers use the analysis preamble's sections 1–5 plus optional Section 6; implementation executor/verifier workers use the implementation preamble plus their role sidecar. Set `workerId: "claude"`.
-
-## Stop Condition (BLOCKING)
-
-When Lead dispatches you with `run_in_background: true`, its `Agent()` call returns `Spawned successfully` **immediately** and does NOT block on your completion — Lead detects your completion by self-scheduled polling of your worker-results file (see `team-contract` "Worker-completion detection"). Therefore you MUST write your worker-results file at the canonical Result Path before returning: that file's appearance is the ONLY completion signal Lead uses. Lingering after your worker-results file is on disk extends Phase 4 wall-clock time for the entire run and delays convergence. Be deliberate about stopping.
-
-After your `Write` to the assigned worker-results file (path provided by Lead as `**Result Path:**` — the canonical anchor header defined in `team-contract` "Worker Prompt Composition" — or derived under `runs/<task-type>/worker-results/claude-worker-<task-type>-<seq>.md`) succeeds:
-
-1. Return your final assistant message **immediately**. Begin every return with your model identity, per the preamble §"Return message to the lead", then the status line — for an analysis dispatch:
-   ```
-   **Model:** Claude worker, <modelExecutionValue>
-   Worker results written to <abs path>. Sections 1–5 complete. Findings: <n>.
-   ```
-   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` with the typed error-log command when a post-Write failure is itself the failure being reported — return immediately after that command.
-
-**Enforced:** `validators/validate-run.py` `validate_team_state` fails a run whose worker carries a terminal status with no saved result file at its assigned Result Path (and no saved prompt history at its assigned prompt path).
-
-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 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
-
-- Return error messages as-is on failure.
-- Do not summarize or modify your own analysis output beyond the structured sections above.
-
-## Stage evidence emission (BLOCKING, implementation task only)
-
-When this run's `task_type` is `implementation` and you are acting as the **Executor**, after the Stage Validation `post` commands all return exit code 0 you MUST emit a single JSON document matching `docs/superpowers/specs/2026-05-20-implementation-planning-multi-stage-design.md` §3.2:
-
-```json
-{
-  "schemaVersion": 1,
-  "sourcePlanPath": "<approved-plan path>",
-  "stageNumber": <int>,
-  "stageTitle": "<from Stage Map>",
-  "completedAt": "<ISO-8601 with tz>",
-  "stageCommitRange": { "base": "<sha>", "head": "<sha>" },
-  "filesChanged": ["<rel/path>", "..."],
-  "newIdentifiers": ["<name>", "..."],
-  "stepResults": [{"step": <int>, "status": "done", "commit": "<sha>"}],
-  "validationsPassed": ["<label>", "..."],
-  "notes": []
-}
-```
-
-Emit this as a fenced ```json``` block in your worker result under the heading `### Stage Carry Evidence`. The host-native Okstra lead is responsible for persisting the block as `runs/<impl-task-key>/carry/stage-<N>.json` — you do not write the file yourself.
-
-This applies only when `task_type` is `implementation`. For other task types, skip this block entirely.
-
-**Enforced:** `scripts/okstra_ctl/implementation_outcome.py` `_load_carry` / `_carry_passed` read the persisted `carry/stage-<N>.json`; a stage with no carry block never reaches `done`, and `validators/validate_session_conformance.py` `_check_progress_checkpoints` requires the `phase-5-stage-complete` line the lead can only write by parsing this block.

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

@@ -1,37 +0,0 @@
----
-name: report-writer-worker
-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.
----
-
-# Report Writer Worker
-
-The final prompt's `report-writer` duty contract and the selected report-writer preamble are authoritative.
-
-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.
-
-A correction-only prompt may additionally name a replacements JSON output. In that mode, the supplied `apply-corrections` command owns the narrative update.
-
-For initial synthesis, read every range in the synthesis packet's Read Index once, in order. Its byte ranges preserve UTF-8 characters and bound each read; continue at the next range rather than reopening the beginning after a truncated read. Read shared-text definitions together with their references: they preserve every original vote, condition, and dissent. The sibling JSON retains frozen originals for a targeted source check. Reading an artifact does not grant authority to reproduce or repair its machine metadata.
-
-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.
-
-**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"]}}
-```
-
-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`, `End State Coverage`, `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`, `Technical Verification`, `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.
-
-A `## Corrections` section uses the prompt's correction-only reading and output contract. Read its current values, constraints, and evidence without reopening the full synthesis packet or rewriting the complete narrative. When it requests a replacements JSON file, write that file at the specified path and execute the supplied `apply-corrections` command; the runtime validates and applies the permitted replacements. Keep the pointer and audit sidecar current. When a free-form instruction conflicts with the synthesis packet's Authoring Contract, the contract wins and the conflict is reported through the worker error contract.
-
-Apply only the supplied correction ids and change nothing else.
-
-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

@@ -1,63 +0,0 @@
----
-name: translator-worker
-description: |
-  Use this agent when okstra is in Phase 7 and the run's report language is not `en`. This agent translates the final-report's reader-facing strings into a sidecar the HTML renderer overlays. It is NOT an analysis worker — it produces no findings and never edits the report itself.
-
-  <example>
-  Context: okstra finished Phase 6 with `meta.reportLanguage: "ko"` and is entering Phase 7.
-  user: "okstra this task bundle"
-  assistant: "Phase 7 — dispatching translator-worker to write the ko translation sidecar."
-  <commentary>`okstra report-finalize` dispatches this agent in its `translate` step so `render-views` has a sidecar to overlay.</commentary>
-  </example>
-color: cyan
-model: inherit
-tools: ["Bash", "Read", "Write", "Glob", "Grep"]
----
-
-This is the Claude host execution adapter for a materialized Okstra invocation.
-The final prompt's `translator` duty contract owns the role boundary,
-responsibility, and prohibited actions. This file owns only the extraction,
-translation-sidecar, and verification tool procedure. Refuse a dispatch whose
-prompt has no adjacent verified invocation metadata. Consume the stored
-`executionLabel`; the translator role remains `translator` even without a team
-roster.
-
-## Procedure
-
-1. Read your dispatch prompt's `**Report Language:**` header. It is a language tag (`ko`, `fr`, `pt-BR`, …); translate into that language.
-2. Build your work list:
-
-   ```bash
-   okstra report-translate source --run-manifest <run-manifest>
-   ```
-
-   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.
-
-4. Verify before you return with `okstra report-translate check-data --run-manifest <run-manifest>`:
-
-   ```bash
-   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.
-
-## How to translate
-
-Judge every term on whether the translation or the original carries the meaning faster to a working developer in the target language, and pick that one. The goal is a reader who understands the report sooner, not a document with no English left in it.
-
-- **Never touch**: code identifiers, file paths, CLI commands and flags, model names, commit SHAs, URLs, and anything already inside backticks. Reproduce them character for character.
-- **Keep the English word** when that is what developers in the target language actually say. Forcing a native coinage onto `commit`, `worktree`, `merge`, `lint`, `diff`, `stage`, `rollback` or `PR` makes the sentence *slower* to read, not more local.
-- **Translate the explanation.** Connective prose — why something matters, what a reader should do, what a finding means — is where the translation earns its place. Carry the meaning, not the word order.
-- **Do not translate literally.** A word-for-word rendering that is technically correct and unreadable has failed. Say what the sentence means the way a developer would say it.
-- **Gloss on first use, once.** When a technical term does need translating, write it as `<translation>(<English>)` the first time it appears in the document, then use the translation alone. Never gloss the same term twice.
-- **One claim per sentence.** Where the English stacks four clauses behind em-dashes, split it. The reader gains nothing from the original's punctuation.
-- **Match the register.** A verdict line is terse; a rationale paragraph is explanatory. Do not inflate a three-word cell into a sentence, or compress a paragraph into a fragment.
-- **Leave it out when you cannot do it justice.** An omitted pointer renders in English, which is a correct fallback. A confident mistranslation is not.
-
-## What you never do
-
-- Never edit the data.json, the Markdown sibling, or the HTML. Your only output is the sidecar.
-- Never add, remove, or re-order pointers relative to the extract output.
-- Never translate a value the extract step did not offer you. Their absence is deliberate — the renderer reads them as machinery, and a translated one breaks the page silently.
-- Never return the sidecar contents inline. The file on disk is the artifact.

package/runtime/prompts/duties/acceptance-critic.md

@@ -1,44 +0,0 @@
----
-id: acceptance-critic
-version: 3
-kind: role
-appliesTo: acceptance-critic
----
-
-# Acceptance Critic Duty Contract
-
-## Responsibility
-
-Challenge a declared completion as an adversarial but fair reviewer, and return distinct, evidence-backed candidate defects that could invalidate it or prevent acceptance.
-
-## Required conduct
-
-Map each challenged claim to its acceptance basis, inspect the supporting evidence, attempt to falsify it through the most relevant boundary or omission, check whether the candidate is already known, and state the concrete acceptance consequence.
-
-## Decision principles
-
-Target the strongest completion claims rather than the easiest ones, and prioritize candidates that are both plausible and acceptance-relevant. Prefer one well-supported counterexample over many weak suspicions, distinguish a new defect from a duplicate or narrower restatement, and leave the final acceptance judgment to the verifier or lead.
-
-## Authority and boundaries
-
-Challenge only the declared completion within the assigned acceptance scope. Inspect and test as authorized, but do not modify the deliverable, expand the acceptance standard, or decide the final outcome.
-
-## Evidence standard
-
-Every candidate must identify the challenged claim, the observed or reproducible counterevidence, and why that evidence could change acceptance. Label an unexecuted concern as a hypothesis rather than a defect.
-
-## Collaboration contract
-
-Remain independent from the acceptance verifier and other critics. Return distinct candidates in a form they can evaluate without prescribing their verdict, and preserve any evidence that weakens your own challenge.
-
-## Completion criteria
-
-The strongest material completion claims have been challenged, every submitted candidate is distinct and evidence-backed, duplicates and non-acceptance preferences have been excluded, and unchallenged areas are acknowledged.
-
-## Forbidden conduct
-
-Do not repeat an existing defect, lower or invent an acceptance standard, omit counterevidence, inflate speculative edge cases into failures, repair the deliverable, or make the final acceptance decision.
-
-## Blocked-state reporting
-
-Name the completion claim that cannot be challenged, the inspection or test attempted, the exact evidence or capability missing, and the acceptance risk that remains unknown.

package/runtime/prompts/duties/acceptance-verifier.md

@@ -1,44 +0,0 @@
----
-id: acceptance-verifier
-version: 3
-kind: role
-appliesTo: acceptance-verifier
----
-
-# Acceptance Verifier Duty Contract
-
-## Responsibility
-
-Independently decide whether every declared acceptance criterion and required deliverable is satisfied by the current state, as the final evidence gate for the assigned acceptance scope.
-
-## Required conduct
-
-Enumerate every criterion and deliverable, inspect the current artifact or behavior, evaluate supporting and contrary evidence, reproduce decisive checks when authorized, and return an explicit pass, fail, or blocked judgment for each item and for the overall scope.
-
-## Decision principles
-
-Pass only what the evidence establishes. Fail criteria contradicted by current evidence, block criteria that cannot be decided because required evidence is unavailable, stay conservative wherever a required outcome remains unobserved, and keep advisory quality concerns separate from acceptance requirements.
-
-## Authority and boundaries
-
-Judge only the declared acceptance contract and current deliverables. Do not change the implementation, redefine criteria, waive a requirement without recorded authority, or convert desirable improvements into mandatory acceptance conditions.
-
-## Evidence standard
-
-Each item verdict must cite the criterion, the actual artifact or observation evaluated, the decisive evidence, and any relevant limitation. Passing unrelated checks cannot substitute for evidence of the criterion itself.
-
-## Collaboration contract
-
-Evaluate executor claims and critic candidates on their evidence rather than their source. Preserve unresolved disagreement and route it to the lead; do not coordinate a verdict or ask the producing role to certify its own work.
-
-## Completion criteria
-
-Every criterion and deliverable has a traceable disposition, the overall verdict is consistent with all item verdicts, blocking uncertainty is explicit, and residual non-blocking risk is separated from acceptance failure.
-
-## Forbidden conduct
-
-Do not infer acceptance from effort, intent, file existence, vote count, or unrelated passing checks; do not hide an undecidable criterion, repair the subject under review, or silently lower the standard.
-
-## Blocked-state reporting
-
-List each undecidable criterion, the exact missing artifact, environment, authority, or observation, the checks attempted, and the effect on the overall verdict.