okstra 0.202.0 → 0.204.0

package/docs/cli.md

@@ -500,9 +500,9 @@ The Codex worker (`--workers codex`, `--codex-model`) and Codex lead runtime are
 
 > Every `--*-model` flag accepts only aliases registered in the provider mappings in `scripts/okstra_ctl/models.py`. An unregistered value is immediately rejected with `UnknownModelError`, preventing a contract violation where the manifest's `modelExecutionValue` differs from the actual execution value. Allowed values:
 > - Claude (`--lead-model` / `--claude-model` / `--report-writer-model`): `fable`, `fable-5-1`, `claude-fable-5-1`, `fable-5`, `claude-fable-5`, `opus`, `opus-5`, `claude-opus-5`, `sonnet`, `sonnet-5`, `claude-sonnet-5`, `haiku`, `haiku-4-5`, `claude-haiku-4-5`
-> - Codex (`--codex-model`): `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-5.4-mini`, `codex-auto-review`. Codex slugs are gated at dispatch against the provider catalog the CLI caches in `~/.codex/models_cache.json`; a slug that catalog does not list is rejected rather than renamed.
-> - Antigravity (`--antigravity-model`): `gemini-3.1-pro` (default), `gemini-3.7-flash`, and their space-separated aliases. The antigravity worker uses the `agy` CLI to run Gemini-family models, so model IDs retain the `gemini-*` form.
-> - Grok (`--worker-model grok=<model>`): `grok-4.6`, `grok-build-0.1`
+> - Codex (`--codex-model`): `gpt-6-astra`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` — the newest generation this account actually serves per tier. `gpt-6-sol` and `gpt-6-luna` stay in the catalog (a ChatGPT-account login is refused with HTTP 400 for them, measured 2026-09-23) together with `gpt-5.4-mini` and `codex-auto-review`, so past runs still price and an account that does serve them can still be pinned explicitly, but they are not offered. Codex slugs are gated at dispatch against the provider catalog the CLI caches in `~/.codex/models_cache.json`; a slug that catalog does not list is rejected rather than renamed.
+> - Antigravity (`--antigravity-model`): `gemini-3.1-pro` (default), `gemini-3.8-flash`, and their space-separated aliases. The antigravity worker uses the `agy` CLI to run Gemini-family models, so model IDs retain the `gemini-*` form.
+> - Grok (`--worker-model grok=<model>`): `grok-4.7`
 > - Kimi (`--worker-model kimi=<model>`): `kimi-k3`, `k3`, `k3-256k` and their registered display aliases
 >
 > Not every registered alias is offered for selection. A model whose `ModelSpec` sets `selectable=False` stays in the catalog — so served-model attestation and historical pricing still resolve it — but it is hidden from the wizard's role-model picker, from `okstra model list`, and from `--role-model`. `okstra model list` still prints them, marked `selectable: no` with the reason. Currently hidden: `claude/fable-5-1`, `claude/fable-5`, `claude/opus-5`, `claude/sonnet-5`, `claude/haiku-4-5`, `claude/haiku-4-5-20251001` (each one the pinned twin of a channel entry that already appears; `claude/fable-5` is the previous served id, kept for attestation and pricing), `kimi/k3` (same model as `kimi/kimi-k3`), `codex/gpt-5.4-mini`, `codex/codex-auto-review`, `grok/grok-build-0.1`, `kimi/k3-256k`.
@@ -571,11 +571,11 @@ The central-default environment variables are:
 Fallback defaults are:
 
 - Claude Code lead: `opus`
-- Codex lead: `gpt-5.6-sol`
+- Codex lead: `gpt-6-sol`
 - Antigravity lead: `gemini-3.1-pro`
 - `Report writer worker`: `sonnet`
 - `Claude worker`: `opus`
-- `Codex worker`: `gpt-5.6-sol`
+- `Codex worker`: `gpt-6-sol`
 - `Antigravity worker`: `gemini-3.1-pro`
 - Implementation executor: `claude`, so the default is `Claude executor`.
 
@@ -585,12 +585,12 @@ Selects the provider that performs the Executor role for `--task-type implementa
 
 - Default: `OKSTRA_DEFAULT_EXECUTOR` → fallback `claude`.
 - The Executor is the **only worker allowed to mutate project files** in this run. The other providers are dispatched as strict read-only verifiers in the same run.
-- The Executor reuses the provider's worker model flag. With `--executor codex`, its model comes from `--codex-model`, default `gpt-5.6-sol`; with `--executor antigravity`, it comes from `--antigravity-model`, default `gemini-3.1-pro`. With `--executor grok`, its model comes from `--worker-model grok=`, default `grok-4.6`.
+- The Executor reuses the provider's worker model flag. With `--executor codex`, its model comes from `--codex-model`, default `gpt-6-sol`; with `--executor antigravity`, it comes from `--antigravity-model`, default `gemini-3.1-pro`. With `--executor grok`, its model comes from `--worker-model grok=`, default `grok-4.7`.
 - All three Claude, Codex, and Antigravity verifiers are always dispatched regardless of the Executor provider. Even the verifier using the same provider runs in a separate CLI session with isolated context, preserving the self-review safeguard.
 - Codex and Antigravity mutate files through each CLI's auto-edit mode, for example `codex exec --sandbox danger-full-access`, without passing through Claude-side Edit/Write tools. Mutations occur in the task worktree described below. Every `okstra-<provider>-exec.sh` entrypoint receives the worktree path as its fourth positional argument and adds it to the worker's write scope, which each provider is told as repeated `--add-dir` (Codex names the project root with `-C` and skips the repeat). No provider CLI enforces a sandbox boundary: the write scope tells a worker where its work belongs, and the run checks afterwards that it stayed there.
 - **Claude Executor cwd handling**: Claude's Bash tool has no per-call cwd argument and inherits the lead session cwd. To run cwd-sensitive toolchains such as `cargo`, `npm`, `pnpm`, `bun`, `pytest`, `make`, or `go` inside the worktree, prefix the invocation with `cd {{EXECUTOR_WORKTREE_PATH}} && <cmd>`. Keep `cd` as the leading token in a single Bash call so Claude Code permission auto-allow works; do not wrap it in `bash -lc "..."` or `bash -c "..."`, which hides `cd` and causes a permission prompt on every call. Prefer a tool's working-directory option—such as `git -C <path>`, `cargo --manifest-path`, or `pytest --rootdir`—over a `cd && ` chain. Edit/Write/Read tools already use absolute paths and need no cwd handling. This rule applies only to the Claude Executor; the Codex and Antigravity wrappers inject cwd.
-- **Task worktree (automatic isolation for every task type)**: During the first phase's preparation for any task type, prepare creates a `git worktree` at `~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>/` and branches `<work-category-namespace>/<task-id-segment>` from the resolved commit of the user-selected `--base-ref`, for example `feature/dev-9436` or `fix/dev-7311`. Later phases for the same task key reuse the path and branch and record status `reused`; no new `git worktree add` occurs during run preparation. Special characters such as `/` and `:` in every segment are normalized to `-`, and `~/.okstra/worktrees/registry.json` globally manages task-key-to-path/branch mappings under flock. Executor edits, writes, builds, tests, and commits—and verifier reads—run in this worktree. If the caller is already in another worktree or project_root is not a Git repository, provisioning is skipped and records `skipped-in-worktree` or `skipped-not-git`. Path or branch collisions fail immediately with `PrepareError`. Worktrees are not deleted after a run; remove one manually with `git worktree remove`, then `git branch -D`, then delete the registry entry. **The implementation stage isolation below is the exception.**
-- **`implementation` stage isolation (concurrent parallelism)**: The task-key worktree above applies only from `requirements-discovery` through `implementation-planning`. Each `implementation` run executes in a **stage-specific isolated worktree** at `~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>--stage-<N>/` (a sibling of the task worktree — a nested layout made the task tree's prettier/tsc read the stage tree as source; whole-task `final-verification` prepare moves any remaining nested stage worktree out with `git worktree move` and updates the registry), on branch `<work-category-namespace>/<task-id-segment>-s<N>`. The registry atomically reserves a stage key, `<task-key>#stage-<N>`, under flock. `_resolve_effective_stages` excludes `started` rows in `consumers.jsonl` and reserved stages. Stage selection, worktree creation, and registry reservation all happen in one critical section protected by the task-key provisioning mutex at `~/.okstra/.locks/worktree-provision/`, so concurrent `implementation` runs safely select different ready stages: **one run = one stage**. A stage worktree's base depends on its dependency shape: independent (`depends-on (none)`) uses the common anchor fixed once at first stage entry; a single dependency (`depends-on X`) uses the predecessor stage's completed `head_commit`; multiple dependencies (`depends-on X,Y…`) use task-worktree HEAD after all predecessors have been merged, verified with `git merge-base --is-ancestor`, and otherwise fail with `PrepareError` and merge guidance. Select the stage with `--stage <auto|N>` for `okstra.sh`/`render-bundle`, or with the okstra-run wizard's `stage_pick` step. If `project_root` is not a Git repository or is a nested worktree, stage isolation also degrades to flat operation.
+- **Task worktree (automatic isolation for every task type)**: During the first phase's preparation for any task type, prepare creates a `git worktree` at `~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>/` and branches `<work-category-namespace>/<task-id-segment>` from the resolved commit of the user-selected `--base-ref`, for example `feature/dev-9436` or `fix/dev-7311`. Later phases for the same task key reuse the path and branch and record status `reused`; no new `git worktree add` occurs during run preparation. Special characters such as `/` and `:` in every segment are normalized to `-`, and `~/.okstra/worktrees/registry.json` manages task-key-to-path/branch mappings under flock — paths machine-wide, branch names within one project id. Executor edits, writes, builds, tests, and commits—and verifier reads—run in this worktree. If the caller is already in another worktree or project_root is not a Git repository, provisioning is skipped and records `skipped-in-worktree` or `skipped-not-git`. Path or branch collisions fail immediately with `PrepareError`. Worktrees are not deleted after a run; remove one manually with `git worktree remove`, then `git branch -D`, then delete the registry entry. **The implementation stage isolation below is the exception.**
+- **`implementation` stage isolation (concurrent parallelism)**: The task-key worktree above applies only from `requirements-discovery` through `implementation-planning`. Each `implementation` run executes in a **stage-specific isolated worktree** at `~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>--stage-<N>/` (a sibling of the task worktree — a nested layout made the task tree's prettier/tsc read the stage tree as source; whole-task `final-verification` prepare moves any remaining nested stage worktree out with `git worktree move` and updates the registry), on branch `<work-category-namespace>/<task-id-segment>-s<N>`. The registry atomically reserves a stage key, `<task-key>#stage-<N>`, under flock. `_resolve_effective_stages` excludes `started` rows in `consumers.jsonl` and reserved stages. Stage selection, worktree creation, and registry reservation all happen in one critical section protected by the task-key provisioning mutex at `~/.okstra/.locks/worktree-provision/`, so concurrent `implementation` runs safely select different ready stages: **one run = one stage**. A stage worktree's base depends on its dependency shape: independent (`depends-on (none)`) uses the common anchor fixed once at first stage entry; a single dependency (`depends-on X`) uses the predecessor stage's completed `head_commit`; multiple dependencies (`depends-on X,Y…`) use a base holding exactly those predecessors — the predecessor commit that already contains the others, or else a branch merging them (`<work-category-namespace>/<task-id-segment>-g<n1>-<n2>`, built by `stage_integrate.ensure_stage_merge_branch` and reused as that stage's PR base in release-handoff). The branch is advanced when a predecessor's done commit moves, and only a predecessor commit missing from the repository fails the run. Select the stage with `--stage <auto|N>` for `okstra.sh`/`render-bundle`, or with the okstra-run wizard's `stage_pick` step. If `project_root` is not a Git repository or is a nested worktree, stage isolation also degrades to flat operation.
 - **Single-stage `final-verification` artifact isolation**: `--task-type final-verification --stage <N>` reuses the implementation stage worktree read-only from the registry. Run artifacts are isolated per stage under `runs/final-verification/stage-<N>/`, and the team name receives a `-fv-s<N>` suffix. Concurrent final-verification runs for different stages do not collide in state, worker results, or team names. For concurrent verification of the same stage, `teamName` is only an audit label and each session has its own implicit team, so the sessions can coexist without a TeamCreate/name collision. This statement is limited to per-session team identity and does not claim safety for shared mutable state. Whole-task verification with an empty stage keeps the flat `runs/final-verification/` layout.
 
 Example:
@@ -819,7 +819,7 @@ The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and
 | `okstra paths [--field <name>\|--shell]` | Print package, runtime, home, bin, Python path, and version locations |
 | `okstra install [--runtime claude-code\|codex\|antigravity\|external\|all] [--refresh\|--dry-run\|--link <repo>]` | Install or update the runtime, templates, skills, and agents. The default runtime is `auto`; skill targets are not runtimes. `~/.agents/skills/` is always created, and Claude skills and agents are also installed when `~/.claude` exists |
 | `okstra ensure-installed [--runtime claude-code\|codex\|antigravity\|external\|all] [-q]` | Check installation state and reinstall stale assets for the same runtime. Default `auto` continues without a host signal and checks drift in the Agent skill target and any existing Claude target |
-| `okstra uninstall [--purge -y]` | Remove installed assets. By default, removes files listed by the `installed-skills.json` targets and `installed-agents.json` while preserving user data |
+| `okstra uninstall [--purge -y]` | Remove installed assets. By default, removes the installed trees under `~/.okstra` (including `agents/`), the skill targets recorded in `installed-skills.json`, and any host agent files `installed-agents.json` proves a past install owned, while preserving user data |
 | `okstra doctor [--runtime claude-code\|codex\|antigravity\|external\|all] [--phase <phase>] [--json]` | Diagnose the runtime, Python imports, skill/agent installation, and model-pool state. The JSON `modelPool` object reports pool errors, default errors, binding precision, observed model, max write boundary, and invocation downgrade reason. It never sends an inference call. The `codex`, `antigravity`, and `external` runtimes omit Claude skill checks. `--phase` adds readiness checks for `implementation`, `final-verification`, `release-handoff`, or `improvement-discovery` |
 | `okstra model list [--role <role>] [--host <host>] [--json]` | List catalog models for a host and optional role. Unselectable exact bindings report `exact binding unavailable`. No inference call |
 | `okstra model default set\|unset <role> ... --scope project\|global [--cwd <dir>]` | Atomically write or remove `modelDefaults` for one canonical role |
@@ -856,7 +856,7 @@ The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and
 | `okstra model-io active-context-input --project-root <dir> --run-manifest <path>` | Resolve the prior implementation-planning active context only through the current project and run authority, then emit fixed fields such as the executor base ref. Caller-supplied active-context paths are not accepted. |
 | `okstra report-translate <source\|write\|check-data> --run-manifest <path> …` | Resolve the report data and translation sidecar from the run manifest. `source` emits a source digest with the fixed translation queue; `write` requires that digest and rejects a stale report; `check-data` verifies the derived sidecar. Models never choose the data or sidecar path. |
 | `okstra convergence prepare-groups --run-manifest <path> --input <grouping.md>` | Parse fixed grouping Markdown, validate distinct per-worker evidence and group semantics against the run authority, then publish the schema-valid groups artifact at the run-owned path. |
-| `okstra manager <init\|discover-projects\|new\|task\|list\|view> [--json]` | Public CLI for grouping cross-project okstra tasks into manager-owned context. The default is purpose-specific fixed text for model use; `--json` preserves the machine contract and exit codes. `new project --project-root` accepts only existing directories and performs setup-equivalent registration only if `.okstra/project.json` is absent. `list managers`, `list projects --manager-id <id>` and `list tasks --manager-id <id>` enumerate manager state; `view --manager-id <id>` writes `~/.okstra/managers/<id>/view/index.html` and prints its path and `file://` URL. `task split --plan <json>` writes one validated brief with a `## Project Scope` section into each project an issue is assigned to and registers those children; `task run` then passes `--task-brief`. |
+| `okstra manager <init\|discover-projects\|new\|task\|list\|remove\|view> [--json]` | Public CLI for grouping cross-project okstra tasks into manager-owned context. The default is purpose-specific fixed text for model use; `--json` preserves the machine contract and exit codes. `new project --project-root` accepts only existing directories and performs setup-equivalent registration only if `.okstra/project.json` is absent. `list managers`, `list projects --manager-id <id>` and `list tasks --manager-id <id>` enumerate manager state; `view --manager-id <id>` writes `~/.okstra/managers/<id>/view/index.html` and prints its path and `file://` URL. `task split --plan <json>` writes one validated brief with a `## Project Scope` section into each project an issue is assigned to and registers those children; `task run` then passes `--task-brief`. `list task-groups` lists groups including empty ones; `task update` edits a task's objective, common brief or progress mode; `remove project`, `remove task`, `remove task-group` and `task remove-child` print their targets and delete manager files only with `--confirm`, and `remove project` keeps the project's children marked unlinked. |
 | `okstra rollup [--task-group <group>] [--project-root <dir>] [--cwd <dir>] [--text\|--json]` | Read-only backend for the okstra-rollup skill. `--text` emits ordered fixed labels for model use. The default and `--json` preserve the full machine JSON contract and exit codes. Omitting `--task-group` targets the whole project catalog. |
 | `okstra usage-report [--days <positive-int>] [--project-root <dir>] [--cwd <dir>] [--text\|--json]` | Read-only backend for the okstra-usage skill. `--text` emits ordered fixed labels for model use. The default and `--json` preserve the full machine JSON contract and exit codes. Defaults to the current project's last 30 days. |
 | `okstra worker-state transition --team-state <path> --worker <id> --status <in-progress\|completed\|timeout\|error\|not-run> [--reason <text>] [--model <execution-value>]` | Atomically update one persisted worker row. `in-progress` records the authoritative `startedAt` and clears `endedAt`; terminal states record `endedAt`; `timeout`, `error`, and `not-run` require a reason. Dispatch adapters use this same transition path, so CLI-backed and in-process orchestration share the status timestamp contract |
@@ -866,6 +866,7 @@ The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and
 | `okstra log-report [--project-root <dir>] [--cwd <dir>] [--top <N>] [--json]` | Read-only inventory of wrapper transcript `.log` files and their sibling prompt `.md` files. Each ranked entry preserves `path` / `sizeBytes` for compatibility and also reports `transcriptPath`, `transcriptBytes`, `promptPath`, `promptBytes`, and `transcriptToPromptRatio`; totals distinguish prompt bytes from transcript bytes and count paired files. Ranking remains transcript-size descending |
 | `okstra recap <assemble\|record\|note> (<task-root\|task-key> \| --task-group <group>) …` | Backend for the okstra-inspect `recap` facet. `assemble` is read-only: for a task it prints a JSON summary of phase transitions across its runs; with `--task-group` it prints the group's start order (briefs in ordinal order, each `done` / `in progress` / `not started` from the catalog's task-manifests, memory entries only for tasks the catalog does not know) and every recorded task's latest conclusion from `group-context.md`'s Task Memory. `okstra model-io recap-input --task-group <group>` is the fixed-text projection of the same join. `record --kind <summary\|qa> --mode <artifact\|code> --answer <text> [--question <text>] [--citation <path:line> …]` appends one line to `<task-root>/recap/recap-log.jsonl`, or with `--task-group` to `.okstra/tasks/<group>/.recap/recap-log.jsonl`, and never mutates other artifacts. `note` is task-only. `note --kind <verification-evidence\|decision-draft\|analysis-note> --slug <topic> --purpose <text> --scope-note <text> (--body <markdown>\|--body-file <path>)` writes an agent-authored note to `<task-root>/notes/` and prints its path plus the `--clarification-response` argument for feeding it into a later run |
 | `okstra user-response <list-view\|show-view\|begin\|answer\|plan-decision\|legacy-report-authoring\|finalize> …` | Backend for the `/okstra-user-response` skill. `list-view` and `show-view --report <md\|data.json> --project-root <dir>` are fixed-text model views; `show-view` validates that the report belongs to the explicit project root and prints each open row's why-asked line, linked plan items, and cited `path:line` artifacts so the skill can read them before asking. The legacy `list` and `show` JSON reads retain their automation-compatible fields. `begin --report <md\|data.json> --task-key <key>` returns an opaque transaction id. A predefined clarification choice uses `answer --transaction <id> --clarification-id <C-NNN> --kind <kind> --option-number <N>`; Python resolves the answer, disposition, reach, and scope effects from the validated report. Direct input instead uses `--disposition <answer\|reframe> --value-file <md> [--rationale-file <md>]`. Every value, rationale, and reason file must be a regular file under `<PROJECT_ROOT>/.okstra/tmp/user-response/`; external paths and symbolic links are rejected. `plan-decision` accepts `approved`, `revision-requested`, or `rejected`, validates any `--implementation-option` against the report candidates, and requires `--reason-file` for the latter two statuses. `legacy-report-authoring` is restricted to report contract 2.0. `finalize` validates the complete existing sidecar before a lossless merge, uses compare-and-swap under a run-local lock, and atomically publishes only the user-owned sidecar; exit 0 ok / 1 error. |
+| `okstra option-comparison --report <data.json\|md>` | Read-only backend for the okstra-run comparison material. Prints one implementation-option-selection report's comparison facts as JSON: `criteria` (the eight evaluation criteria and their weights), `workers` (voting analysts in first-seen order), and per ranked direction `scores`, `scoreRationales`, the recorded `weightedScore` (publication already checks it against the recalculated value), `coverage` (verdict, counts, requirement ids), `safetyBlockers` and `unresolvedFeasibilityFacts` counts, and `votes` per worker (verdict, rationale, counterevidence); plus the report's `narrative` texts and `nextStep`, which is the next-phase pointer rationale. Exits 2 when the record has no `implementationOptionSelection` block or ranks no direction. |
 | `okstra pr <template\|branches\|gen> … [--json]` | Backend for the okstra-pr-gen skill. Git-only—no project registration required. `template list\|show <name\|default>\|add --name <name> (--content <text>\|--file <path>)\|path` manages PR body templates under `~/.okstra/template/pr/` (bundled fallback `src/commands/pr/default.md`); `branches` recommends a base branch; `gen --base <ref> [--template <name\|default>]` emits fixed `Base`, `Current branch`, `Template name`, `Commits`, `Diff stat`, and `Template` sections by default. `--json` preserves the machine bundle for automation. |
 | `okstra migrate [--apply] [--cwd <dir>] [--quiet]` | One-time migration of the project artifact root from `.project-docs/okstra/` to `.okstra/`. It is a dry run by default; `--apply` performs the move with `git mv` in a Git worktree, removes an empty `.project-docs/`, and synchronizes the `<PROJECT>/CLAUDE.md` import line, `.gitignore`, the project's rows in `~/.okstra/{recent,active}.jsonl`, and `~/.okstra/worktrees/registry.json`. It exits 1 if `.okstra/` already exists or the legacy directory is absent. Scheduled for removal by the end of v0.x |
 | `okstra task-list [--project-root <path>]` | Combine `list_project_tasks` and `read_latest_task` into JSON containing the task catalog and latest task |
@@ -879,14 +880,16 @@ The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and
 | `okstra worktree-lookup <project-id> <task-group> <task-id>` | Return the `worktree_registry.lookup` result: reserved path, branch, base ref, and current status |
 | `okstra worktree-status [--path <dir>] [--check-clean]` | Answer "is this worktree clean?" over source paths only, excluding what okstra provisioned there — `.okstra`, the configured sync entries (`.project-docs`, `.claude`, …), and any nested stage worktree. A bare `git status --porcelain` in a task worktree is never empty for that reason, so a plan step asserting a clean tree with one fails on okstra's scaffolding instead of on the stage's own work; this is the same gate `handoff` and stage integration use. Output is JSON `{ ok, path, clean, entries, excluded }` where `entries` holds the `git status --short` rows that made it dirty. Exit code is 0 regardless unless `--check-clean` is given, which exits 1 on a dirty tree so it can stand as a shell assertion (`okstra worktree-status --check-clean`). okstra writes `stage-<N>-exit` itself when it settles the stage, so a plan step must not tag. A path outside a git work tree exits 2 rather than reporting a clean tree |
 | `okstra plan-validate <plan-path>` | Run `_validate_approved_plan` and report frontmatter `approved` recognition plus unresolved Blocks=approval rows |
-| `okstra render-bundle <args…> [--stage <auto\|N>] [--stages <csv>]` | Thin shim over `prepare_task_bundle(render_only=True)` with the same signature as `python3 -m okstra_ctl.run --render-only`. `--stage` is for `implementation` and `final-verification`: for implementation, `auto` (default) selects the earliest incomplete stage with satisfied dependencies, while `<N>` forces a stage; for final-verification, `<N>` verifies one stage with artifacts under `runs/final-verification/stage-<N>/` and a `-fv-s<N>` team suffix, while an empty value performs whole-task verification with the flat layout. The separate `--stages <csv>` channel is for `release-handoff`: stage-group mode bundles the listed stage numbers into one PR, while an empty value selects whole-task mode. Preparation enforces eligibility—`done` + accepted `verified` + not yet `pr`—and automatically creates an input document that cites verification reports |
+| `okstra render-bundle <args…> [--stage <auto\|N>] [--stages <csv>]` | Thin shim over `prepare_task_bundle(render_only=True)` with the same signature as `python3 -m okstra_ctl.run --render-only`. `--stage` is for `implementation` and `final-verification`: for implementation, `auto` (default) selects the earliest incomplete stage with satisfied dependencies, while `<N>` forces a stage; for final-verification, `<N>` verifies one stage with artifacts under `runs/final-verification/stage-<N>/` and a `-fv-s<N>` team suffix, while an empty value performs whole-task verification with the flat layout. The separate `--stages <csv>` channel is for `release-handoff`: it names the stages to open a PR for, one PR per stage, and an empty value takes every eligible stage. Preparation enforces eligibility—`done` + accepted `verified` + not yet `pr`—and automatically creates an input document that cites verification reports |
 | `okstra profile show <task-type> [--resolved]` | Print a phase profile. `--resolved` expands its `{{INCLUDE:}}` targets and appends the lazy-read sidecars named in the profile body — transitively, because sidecars name sidecars of their own (`_implementation-executor.md` points at the coding-conventions preflight, the diff-review sweep, and the completion self-check). That matters because a profile is assembled from three places, so grepping only the top-level file returns false negatives: `grep clarification prompts/profiles/implementation.md` finds nothing while the assembled profile has many hits. One grep over this output answers whether a task-type covers a rule. The sidecar list is read from the profile body, never hard-coded, so a newly added sidecar is picked up without a code change. Read-only: it writes no manifest and registers no run, which is what separates it from `render-bundle` — `render-bundle` answers the same question but records a run in `recent.jsonl`, so it cannot be used to look something up. Exits 2 for an unknown task-type |
 | `okstra codex-run <args…>` | Codex lead-adapter dry-run entry point. Accepts the same arguments as `render-bundle` but owns `--render-only --lead-runtime codex`. It prepares the task bundle and prints the prompt for the Codex lead without dispatching workers |
 | `okstra worker-dispatch --project-root <dir> --run-manifest <path> [--workers <csv>] [--dry-run]` | Provider-neutral deterministic dispatcher for `runner=cli-wrapper` assignments. It verifies each adjacent invocation specification against the immutable run manifest immediately before process creation and records `core-pre-dispatch`; native-session rows stay with the host. The default selects CLI analysis assignments only. Phase 6 uses explicit `--workers report-writer`, and a mixed analysis/report batch is rejected. `--dry-run` performs the same verification and resolution without starting a provider process. |
 | `okstra codex-dispatch --project-root <dir> --run-manifest <path> [--workers <csv>] [--dry-run]` | Compatibility alias for `okstra worker-dispatch`; it no longer selects a Codex-only transport-agent path. |
+| `okstra agent-prompt resolve-operation --operation <id> [--json]` | Print what a non-run operation runs: its duty, its canonical role, the worker count, and one slot line per worker carrying that slot's provider and model reference. The operation contract (`agents/operations/<id>.json`) owns the duty and the count; the models come from the same project/global/bundled default chain a run uses, one distinct model per slot. A machine with fewer distinct models than the contract requires fails here rather than dispatching a short roster. The default output is fixed text because a skill body must not instruct a model to parse okstra-owned JSON; `--json` is for programmatic callers. |
 | `okstra agent-prompt jobs --project-root <dir> --run-manifest <path> --dispatch-kind <kind> --metadata <path> [--metadata <path>] --out <path> [--json]` | Generate an immutable v2 jobs file from verified invocation metadata. Reads canonical identity, role, five digests, and actual result anchors; validates the full batch through the dispatch consumer before publishing. Rejects mixed runs or dispatch kinds, duplicate attempts, and translator input (use canonical `worker-dispatch --workers translator`). Reuses identical output; preserves differing output and requests a new `--out` path. Does not launch workers. |
 | `okstra agent-prompt materialize\|check-corrections\|apply-corrections\|verify\|record-dispatch\|link-result\|reject-result\|abandon-attempt\|materialize-result\|complete\|verify-completion` | Internal invocation-contract CLI. `materialize` composes model assignment, functional duty, and task instructions; `verify` rejects identity, path, snapshot, assignment, source, or digest drift. Every run-branch report-writer prompt gets its `## Output` section (narrative, pointer record, reading audit) rendered by okstra, and an instruction body that writes a `## Output` or `## Corrections` heading is refused. A corrective report-writer round — the narrative at `reportNarrativePath` already exists and its structure parses, value defects included — must pass `--corrections <ledger>` (`schemas/report-writer-corrections-v1.0.schema.json`: `replace` / `remove` / `add` / `move` / `rewrite` entries keyed by the validator's field-path grammar, `baseNarrativePath` naming a preserved copy of the attempt, and optional `baseNarrativeSha256` binding that version): the ledger is applied to that base and checked against the writer-owned schema and the task's semantic validator before dispatch, every defect is reported at once, and okstra renders the prompt's `## Corrections` section from it; a report-writer materialization without a ledger over such a narrative is refused before any prompt is written, while a narrative whose structure does not parse (line grammar, unknown top-level field) is re-authored without one. `check-corrections --run-manifest <path> --corrections <ledger> [--json]` runs the same check without materializing (exit 1 lists the defects; `mechanical: true` means every entry is a validated `replace`, `remove`, `add`, or `move`, including derived planning step counts). `apply-corrections` with the same arguments applies such a mechanical ledger without a writer round: it writes the corrected narrative to `reportNarrativePath` and records a `lead-correction-applied` activity row (`evidenceRefs` = ledger path + correction ids) through the run's activity contract; `--rewrite-results <file>` also accepts hash-bound replacement values for exactly the requested rewrite ids. Correction-only materialization sends those target fields, evidence, and constraints instead of the initial instructions and complete synthesis packet; the runtime merges the submitted values and checks the complete narrative before writing. It refuses unresolved `rewrite` entries or any defect, a stale live narrative, a base that is the live narrative, a run without `activityContractVersion` 1, and a ledger already applied. An empty ledger can preflight the initial writer result and derive `stageMap[].stepCount` from matching execution rows without another writer call. Run-backed calls resolve `assignmentRef` from the manifest, enforce `authorizedPaths`, and reject real-path or symbolic-link escape. `record-dispatch` records a verified host-native specification before dispatch and `link-result` binds the accepted result; one result path belongs to one dispatch, so a corrective round retires the first attempt with `reject-result --dispatch-id <first> --superseded-by <corrective> --reason <text>` before the new link is accepted — the rejected row stays in `agentResultLinks` carrying `supersededBy` and `rejectionReason` rather than being deleted. The corrective dispatch is a new invocation: an invocation whose last attempt finished with a mutation takes no further attempt (`execution_manifest._validate_next_attempt` lets only `failed-no-mutation` be followed), so a retry attempt of the rejected invocation itself is refused by the manifest, and `reject-result` does not make it possible. `abandon-attempt --invocation-ref <ref> --reason <text>` closes a started attempt whose worker died without producing a result — the one case neither `link-result` (which needs the result file) nor the dispatch-failure path covers — so a retry can follow it instead of the run having to be re-rendered. It refuses any attempt whose `writePolicy.sourcePolicy.mode` is not `source-readonly`: closing an attempt records `failed-no-mutation`, which is true by policy for a read-only worker and a guess for a mutating one. Standalone calls are identified by `(purpose, invocationId)` under `.okstra/agent-invocations/<purpose>/`; they publish a canonical result envelope and publish the completion marker last. Consumers use only the `returnedBody` from `verify-completion`. Metadata contains exactly `catalogDigest`, `assignmentDigest`, `dutyDigest`, `instructionDigest`, and `promptDigest`; JSON inputs use UTF-8, sorted keys, compact separators, and no non-finite values, while duty files use versioned sorted-name/byte framing. Instruction sources use `{kind: project\|runtime, path: <relative POSIX path>}` and never persist an installed absolute runtime path. A published prompt is immutable, so re-running `materialize` with an edited instruction file fails as `existing_invocation_conflict`; `--replace-undispatched` is the one exit, for a call that failed a pre-dispatch gate and therefore ran nowhere — it covers a differing prompt and a differing metadata alike, since the two are published together and describe one call. It republishes prompt and metadata together, and it is verified rather than trusted — a row in `agentDispatches` or `workerDispatches` naming this `invocationId` refuses the replacement and names the dispatch that used it. |
-| `okstra team dispatch --project-root <dir> --run-manifest <path> [--workers <csv>] [--jobs-file <path>] [--dry-run]` / `okstra team await --project-root <dir> --run-manifest <path> [--json]` / `okstra team teardown --project-root <dir> --run-manifest <path> [--dry-run] [--json]` | Read a `leadRuntime=external` run manifest and dispatch, await, or tear down pane-backed workers. Default dispatch excludes report writer; Phase 6 selects it explicitly, and mixed analysis/report jobs are rejected. If a pane cannot be opened, gracefully degrade to the CLI wrapper and record the fallback in `workerDispatches[].degradedFrom` |
+| `okstra agent-prompt refreeze-contracts --project-root <dir> --run-manifest <path> [--json]` | Re-freeze one run's duty contract snapshot in the installed format and stamp `agentContract.catalogDigest` and `contractFormatVersion` on its run manifest. A run freezes its contracts at prepare time and pins their digest; installing a release that changed the contract format leaves that digest unmatchable, so the run can materialize no further prompt and `materialize` stops with the format message naming this command. It replaces the frozen directory's contents (no file of the old format is kept), touches no prompt, result or ledger, and reports `changed: false` when the run is already on the installed format. User-invoked recovery only — nothing runs it automatically, because a run's contracts are frozen on purpose. |
+| `okstra team dispatch --project-root <dir> --run-manifest <path> [--workers <csv>] [--jobs-file <path>] [--dry-run]` / `okstra team await --project-root <dir> --run-manifest <path> [--json]` / `okstra team teardown --project-root <dir> --run-manifest <path> [--dry-run] [--json]` | Read a `leadRuntime=external` run manifest and dispatch, await, or tear down pane-backed workers. Default dispatch excludes report writer; Phase 6 selects it explicitly, and mixed analysis/report jobs are rejected. If a pane cannot be opened, gracefully degrade to the CLI wrapper, print a `DEGRADED <role>: cmux-pane -> cli-wrapper (<why>)` line, and record the fallback in `workerDispatches[].degradedFrom` with the reason in `degradedReason`. A degraded worker is not waited for inside the dispatch — it settles through `okstra team await` like a pane worker, so the round still runs concurrently |
 | `okstra agent-activity append --project-root <dir> --run-manifest <path> --kind <kind> --agent <assigned-id> (--summary <text>\|--summary-file <markdown>) --outcome <outcome> [--plan-item-id <current-id>]… [--command <text> --command-cwd <dir> --command-exit-code <n> --command-output-file <markdown>] [--request-ref <returned-ref>]` | Append one structured activity after checking the agent against this run's role assignments and every plan item against its current convergence state. Python returns an `activityRequestRef`; supply only that returned value with `--request-ref` to retry idempotently. A new call without it remains a distinct activity even with identical contents. Legacy JSON command records remain automation compatibility only. |
 | `okstra agent-activity project --project-root <dir> --run-manifest <path> --data <data.json>` | Project this run's canonical activity events into `agentActivity[]`. The command preserves event order, rejects duplicate or decreasing activity IDs, and replaces no other report field. A historical manifest without `activityContractVersion: 1` returns an empty projection and leaves data.json unchanged. Normal Phase 7 execution reaches this behavior through `report-finalize`; use the standalone command only for diagnostics. |
 | `okstra lead-progress append --project-root <dir> --run-manifest <path> --phase <phase-id> [--worker <role>] [--field NAME=VALUE]… [--detail <text>]` | Append one `PROGRESS:` checkpoint to the run's `leadEventsPath` and print the line to emit to the user as `progressLine`. The checkpoint is what `validate_session_conformance.py` reads, and on a host whose adapter declares `sessionAccounting: artifact-only` the ledger is the only place it can read one — a conversation line alone is not retained there. `--phase` accepts the phase ids the lead contract's "Progress reporting (BLOCKING)" list defines; the fixed-prose checkpoints render their contract wording without `--detail`. `--worker` is resolved against team-state and rewritten to the roster `workers[].role` the per-worker checks match, so a phase-specific functional label still lands on the right worker; a name that matches no roster row is written through with a note on stderr. |

package/docs/contributor-change-matrix.md

@@ -6,8 +6,9 @@ Use this matrix before changing high-risk repo contracts. Update the source file
 |---|---|---|
 | Add CLI flag | `src/`, `scripts/okstra_ctl/run.py`, `docs/cli.md`, `prompts/wizard/` | JS CLI tests and pytest CLI contracts |
 | Add Node subcommand | `src/cli-registry.mts`, `src/commands/`, `docs/cli.md`, `docs/project-structure-overview.md` | `tests-js/cli-registry.test.mjs` plus command-specific JS/Python tests |
-| Add public skill | `src/lib/skill-catalog.mts`, `.claude-plugin/plugin.json`, `skills/<name>/SKILL.md`, `docs/for-ai/README.md`, `docs/project-structure-overview.md`, `README.md` | `tests-js/skill-catalog.test.mjs`, `tests/contract/test_docs_runtime_contract.py` |
-| Change manager contract | `scripts/okstra_ctl/manager_*.py`, `skills/okstra-manager/SKILL.md`, `docs/for-ai/skills/okstra-manager.md`, `docs/cli.md`, `docs/architecture/storage-model.md` | `tests-js/cli-wrapper-contract.test.mjs`, `tests/test_okstra_manager_*.py` |
+| Add public skill | `src/lib/skill-catalog.mts`, `.claude-plugin/plugin.json`, `skills/<name>/SKILL.md`, `docs/skills/<name>.md`, `docs/skills/README.md`, `docs/project-structure-overview.md`, `README.md` | `tests-js/skill-catalog.test.mjs`, `tests/contract/test_docs_runtime_contract.py` |
+| Change manager contract | `scripts/okstra_ctl/manager_*.py`, `skills/okstra-manager/SKILL.md`, `docs/skills/okstra-manager.md`, `docs/cli.md`, `docs/architecture/storage-model.md` | `tests-js/cli-wrapper-contract.test.mjs`, `tests/test_okstra_manager_*.py` |
+| Change a skill's behaviour | `skills/<name>/SKILL.md`, `docs/skills/<name>.md` (every Guarantees row names its enforcement or says `unenforced`) | `tests/contract/test_skill_specs.py` |
 | Add phase | `scripts/okstra_ctl/workflow.py`, `prompts/profiles/`, `validators/`, `tests/` | workflow and validation contract tests |
 | Change worker roster | `prompts/profiles/*.md`, `scripts/okstra_ctl/workers.py`, `tests/contract/test_repo_contracts.py` | worker roster contract tests |
 | Change report section | `schemas/final-report-v2.0.schema.json`, `templates/reports/final-report-v2.template.md`, `scripts/okstra_ctl/render_final_report.py`, `validators/validate-run.py` | final-report schema, renderer, and validator tests |

package/docs/performance-improvement-plan-v2.md

@@ -227,13 +227,12 @@ Goals:
 
 Cautions:
 
-- Before extracting shared worker text into `agents/workers/_cli-wrapper-template.md`, confirm that install/packaging paths and skill/agent loaders support includes.
+- Superseded (2026-08-13, `cf9fcfe`): the shared CLI-wrapper template and the per-provider worker parameter files this item planned to edit were removed. Worker prompts are now composed by `okstra agent-prompt materialize`, so shared worker text belongs in the materializer's inputs, not in a wrapper template.
 - Merely moving text into a separate file can increase cost if the runtime does not inline it and the worker must read another file.
 
 Change targets:
 
-- `agents/workers/codex-worker.params.json`
-- `agents/workers/antigravity-worker.params.json`
+- `scripts/okstra_ctl/agent/prompt_cli/materialize.py` (replaces the removed per-provider worker parameter files)
 - `prompts/lead/team-contract.md`
 - Install/build packaging
 

package/docs/project-structure-overview.md

@@ -138,8 +138,8 @@ Runtime/install asset changes follow this checklist:
 - `runtime/templates/*` → `~/.okstra/templates/`
 - `runtime/skills/<name>` (the fourteen user-facing skills only) → `~/.agents/skills` always, plus `~/.claude/skills` when `~/.claude` exists
 - `runtime/prompts/*` → `~/.okstra/prompts/` (lead contracts under `prompts/lead/`, coding-preflight pack under `prompts/coding-preflight/`)
-- the native Claude execution adapters in `runtime/agents/workers/` → `~/.claude/agents/` when `~/.claude` exists; retired provider transport-agent files are removed only when the prior install manifest owned them
-- install manifests → `~/.okstra/installed-skills.json` (target-aware), `~/.okstra/installed-agents.json`
+- `runtime/agents/*` → `~/.okstra/agents/` (the common contract, the nine role contracts under `agents/roles/`, and the non-run operation contracts under `agents/operations/`). Nothing is written to a host-global agent discovery path such as `~/.claude/agents/`; agent definitions a previous version installed there are removed only when the prior install manifest proves okstra owned them (ADR-0017)
+- install manifests → `~/.okstra/installed-skills.json` (target-aware), `~/.okstra/installed-agents.json` (now only the record of host files to reclaim)
 - version stamp → `~/.okstra/version`
 
 `--link <repo>` mode is for development and symlinks installed files back to repo sources.
@@ -166,7 +166,7 @@ The Module column below is where the command's behaviour lives — a `src/` modu
 | `install`, `ensure-installed` | `src/commands/lifecycle/install.mts` | Install or refresh runtime, skills, agents, templates |
 | `uninstall` | `src/commands/lifecycle/uninstall.mts` | Remove managed runtime/skills/agents, optionally purge data |
 | `doctor` | `src/commands/lifecycle/doctor.mts` | Diagnose runtime and Python imports |
-| `setup` | `src/commands/lifecycle/setup.mts` | Create/update `<PROJECT_ROOT>/.okstra/project.json` |
+| `setup` | `src/commands/lifecycle/setup.mts` | Create/update `<PROJECT_ROOT>/.okstra/project.json`; also appends/refreshes the okstra citation-guidance block in an existing `CLAUDE.md` / `AGENTS.md` via `src/lib/citation-guidance.mts` (neither file is created) |
 | `check-project` | `src/commands/lifecycle/check-project.mts` | Verify project registration |
 | `preflight` | `src/commands/lifecycle/preflight.mts` | One-call skill preflight: ensure-installed + check-project + host-specific runtime readiness (single JSON) |
 | `config` | `src/commands/lifecycle/config.mts` | Read/write project/global settings such as PR template path |
@@ -327,7 +327,7 @@ Important modules:
 | `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 — 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 — plus the `list managers/projects/tasks` readers |
+| `manager_store.py` | Manager-owned state mutation — project membership, task planning, assignment, directives, event append — plus the `list managers/projects/task-groups/tasks` readers, `task update`, and the `remove project/task/task-group` and `task remove-child` operations |
 | `manager_sync.py` | One-way child project `.okstra` snapshot reader; corrupt child state becomes row-level `error` so other children continue |
 | `manager_launch.py` | Child launch packet and manager child context renderer; records `prepared` launch metadata/events without changing project-local task state |
 | `manager_view.py` | `okstra manager view` — renders one manager's projects, tasks, child summaries, directives and events into `view/index.html` from `templates/manager/view.template.html`; reads manager-owned files only |
@@ -383,6 +383,31 @@ Important modules:
 | `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 (backticks escaped for the code span `line` wraps it in), `block` projects a prose body outside any code span with its backticks intact, `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`, `model_io/` | 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. `model_io_cli.py` is the argparse surface only; inside the package, `references` resolves paths and reads JSON, `lines` turns an already-read mapping into fixed Markdown and opens nothing, and `renderers` composes the two into one function per command |
+| `assignment_environment.py` | loads ambient host-adapter facts once, outside the deterministic assignment logic; read by `run.py`, `dispatch_core.py`, the wizard's role step, and `agent-prompt materialize` |
+| `execution_identity.py` | provider-neutral execution identity value objects — participant assignment, role execution, invocation, attempt, execution manifest — and their versioned readers |
+| `attempt_evidence.py` | atomic attempt-evidence seals and the orchestrator-owned host event streams written around each worker attempt |
+| `execution_mutation_audit.py` | batch-scoped source and Git mutation audit for worker invocations (snapshots taken around a dispatch batch) |
+| `mutation_recovery.py` | recovery decisions after a sealed or unsealed implementer attempt that mutated source |
+| `write_policy.py` | canonical invocation write policy — which paths an invocation may write — and the enforcement the runner truthfully reports; read by the provider wrapper, `worker_request.py`, `dispatch_core.py`, and report assembly |
+| `role_requirements.py` | parses the canonical role requirements that phase profiles declare |
+| `model_defaults.py` | pure replacement of role-model default scopes |
+| `legacy_model_selection.py` | normalises canonical role selections and legacy provider CLI flags into one selection |
+| `validation_contract.py` | the validation contract version pinned at prepare time (`CURRENT_VALIDATION_CONTRACT_VERSION`) |
+| `usage_identity.py` | projects usage rows from stored execution-identity refs; shared by usage-report, time-report, error-report, and the token collector |
+| `user_response_values.py` | value types and parsers of the `user-responses/` sidecar |
+| `stage_map_view.py` | read-side Stage Map view behind `okstra stage-map` |
+| `lead_progress.py` | `okstra lead-progress append` — records the lead's `PROGRESS:` checkpoints in the lead-events ledger |
+| `plan_verify_cli.py` | `okstra plan-verify` entry point |
+| `doctor_cli.py` | diagnostic projection that `okstra doctor` (`src/commands/lifecycle/doctor.mts`) calls |
+| `worktree_cli.py` | handlers behind `okstra worktree-lookup` and `okstra worktree-status` |
+| `interactive_cli.py` | lookup helpers for the `okstra.sh` interactive input path (`scripts/lib/okstra/interactive.sh`) |
+| `brief_frontmatter.py` | shared lightweight parser for a brief's frontmatter; read by `run.py`, direct completion, the task-group context, the wizard's brief suggestions, and the improvement-report validator |
+| `convergence_provenance.py` | Round-0 grouping provenance — checks that every source item a group cites exists in the canonical worker result; shared by the convergence engine, the critic prompts, and `validate-run.py` |
+| `verdict_blocks.py` | parser for the worker verdict block that plan-body verification and convergence re-verification share |
+| `worker_artifacts.py` | the roster worker-id vocabulary and the artifact paths derived from it |
+| `worker_state.py` | `okstra worker-state transition` — the authoritative status transitions of one persisted team-state |
+| `usage_cells.py` | how a token, cost, or duration figure reads in a report cell; shared by the Markdown and HTML report renderers |
+| `report_contract.py` | single registry of the public final-report task contracts, read by prepare, rendering, approval decisions, and the report synthesis packet |
 
 > `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.
 
@@ -433,6 +458,8 @@ Token/cost accounting:
 | `templates/worker-prompt-preamble.md` | Initial analysis audience procedure and output contract |
 | `templates/implementation-worker-preamble.md` | Shared implementation executor/verifier procedure, including coding-preflight and worktree rules |
 | `templates/report-writer-prompt-preamble.md` | Report-writer input and authoring procedure without analysis or implementation instructions |
+| `templates/translator-prompt-preamble.md` | Translator output ownership and translation conduct, delivered to every provider regardless of host |
+| `scripts/okstra_ctl/adapters/hosts/claude-code/worker-session.md` | Rules that hold because a worker runs inside the lead's Claude Code session; delivered to `runner=native-session` prompts only |
 | `templates/worker-error-contract.md` | Audience-neutral error-path, sidecar schema, and write protocol shared by every initial worker |
 
 ### 4.8 `schemas/`
@@ -490,11 +517,11 @@ Boilerplate shared by several skills (bash invocation rule, outdated-CLI preflig
 
 | File | Role |
 |---|---|
-| `agents/workers/claude-worker.md` | Claude analyzer/verifier/executor spec |
-| `agents/workers/report-writer-worker.md` | data.json SSOT author and audit sidecar writer |
-| `agents/workers/translator-worker.md` | Claude-native final-report translation execution adapter |
+| `agents/common.json` | The contract every okstra LLM call carries, ahead of role and duty |
+| `agents/roles/<role>.json` | One of the nine canonical roles: identity, responsibilities, required capabilities, prohibitions |
+| `agents/operations/<operation>.json` | A non-run operation's duty and worker count (`okstra agent-prompt resolve-operation`) |
 
-These files are native Claude execution adapters, not provider-neutral LLM transport wrappers. Non-native providers execute through the deterministic `worker-dispatch` process boundary. The neutral lead lifecycle contract lives at `prompts/lead/okstra-lead-contract.md`. Executable host strategies and their relay contracts live together under `scripts/okstra_ctl/adapters/hosts/<host-id>/`; `prompts/lead/adapters/cmux.md` remains the environment-selected cmux worker-backend contract. Lead resources are installed under `~/.okstra/prompts/lead/`, while executable host adapters are installed under `~/.okstra/lib/python/okstra_ctl/adapters/hosts/`. They are runtime resources, not agent skills.
+These are provider-neutral contracts rendered into every dispatch prompt, not host agent definitions: okstra registers nothing in a host-global discovery path (ADR-0017). Non-native providers execute through the deterministic `worker-dispatch` process boundary. The neutral lead lifecycle contract lives at `prompts/lead/okstra-lead-contract.md`. Executable host strategies and their relay contracts live together under `scripts/okstra_ctl/adapters/hosts/<host-id>/`; `prompts/lead/adapters/cmux.md` remains the environment-selected cmux worker-backend contract. Lead resources are installed under `~/.okstra/prompts/lead/`, while executable host adapters are installed under `~/.okstra/lib/python/okstra_ctl/adapters/hosts/`. They are runtime resources, not agent skills.
 
 ### 4.12 `tests/` and `tests-e2e/`
 
@@ -589,7 +616,6 @@ Both Markdown and HTML are derived, not authoring sources. The schema is the con
 - `scripts/okstra_ctl/domain/role.py` — canonical roles and duty mapping.
 - `scripts/okstra_ctl/model_pool.py` — unified catalog lookup.
 - `scripts/okstra_ctl/model_cli.py` — `okstra model list` and atomic `modelDefaults` writes. No inference call.
-- `scripts/okstra_ctl/pane_title.py` — pane titles from stored `executionLabel`.
 - `scripts/okstra_ctl/doctor.py` — `model_pool_diagnostics()` for `okstra doctor --json`.
 
 ---

package/docs/task-process/README.md

@@ -55,7 +55,7 @@ Launch selection is role slots and model refs, not a provider roster. The wizard
 | okstra-run skill procedure | [`skills/okstra-run/SKILL.md`](../../skills/okstra-run/SKILL.md) |
 | wizard state machine | [`scripts/okstra_ctl/wizard/`](../../scripts/okstra_ctl/wizard/) |
 | wizard prompt text | [`prompts/wizard/prompts.ko.json`](../../prompts/wizard/prompts.ko.json) |
-| render-bundle Node shim | [`src/commands/execute/render-bundle.mjs`](../../src/commands/execute/render-bundle.mjs) |
+| render-bundle Node shim | [`src/commands/execute/render-bundle.mts`](../../src/commands/execute/render-bundle.mts) |
 | single entrypoint for bundle creation | [`scripts/okstra_ctl/run.py`](../../scripts/okstra_ctl/run.py) |
 | implementation stage selection/provisioning | [`scripts/okstra_ctl/implementation_stage.py`](../../scripts/okstra_ctl/implementation_stage.py) |
 | Stage Lifecycle Snapshot + stage target/base/verification policy | [`scripts/okstra_ctl/stage_targets.py`](../../scripts/okstra_ctl/stage_targets.py) |

package/docs/task-process/common-flow.md

@@ -95,7 +95,7 @@ sequenceDiagram
     Skill->>FS: read lead-execution-prompt.md
 ```
 
-The Node shim for `render-bundle` is [`src/commands/execute/render-bundle.mjs`](../../src/commands/execute/render-bundle.mjs). This shim attaches the `--workspace-root`, `--render-only`, and runtime resolution arguments directly. As a result, on the okstra-run path the initial run status starts at `prepared` and the task status starts at `ready-for-lead`.
+The Node shim for `render-bundle` is [`src/commands/execute/render-bundle.mts`](../../src/commands/execute/render-bundle.mts). This shim attaches the `--workspace-root`, `--render-only`, and runtime resolution arguments directly. As a result, on the okstra-run path the initial run status starts at `prepared` and the task status starts at `ready-for-lead`.
 
 ## 5. Okstra lead phase 1-7
 

package/docs/task-process/final-verification.md

@@ -118,10 +118,12 @@ flowchart TD
 
 `## 7. Final Verdict` must contain exactly one `Verdict Token` field, and its value is one of the following three.
 
-- `accepted`: a state that becomes a candidate for plain `release-handoff` when whole-task, or `release-handoff(stage-group)` when single-stage
+- `accepted`: a state that becomes a release-handoff candidate — whole-task for every stage it covers, single-stage for that one stage's PR
 - `conditional-accept`: all conditions must be stated explicitly, and when a condition is a gate it blocks the next phase
 - `blocked`: a state that has acceptance blockers and cannot proceed to release-handoff
 
+A blocked or conditional run routes to the phase that owns the defect. When every remaining blocker is an environment or configuration fault this report already diagnosed - a `qaCommands` entry naming a path that no longer exists, a missing credential, a stale fixture - the target is `final-verification` itself: repair the configuration and re-verify the same head, rather than spending a root-cause phase on a cause that is already known.
+
 Vague phrasings such as "looks good" or "mostly ready" are not allowed.
 
 ## 6. Deliverables

package/docs/task-process/implementation.md

@@ -170,7 +170,7 @@ flowchart LR
 
 Stage selection is `auto` or a number. If `--stage` comes from another task-type, it is a `PrepareError`. The runtime reads `done`/`started` of `consumers.jsonl`, carry sidecar backfill, and the active stage-key of the registry together in the Stage Lifecycle Snapshot, and excludes occupied stages. The Snapshot is not a new stored file but a read-side view of `stage_targets.py`.
 
-The stage worktree base is decided by dependency shape. An independent stage uses the task-key worktree HEAD fixed at first implementation entry as its anchor, and a single-dependency stage branches from the predecessor stage's done `head_commit`. A multi-dependency stage branches from the task-key worktree HEAD after confirming that every predecessor done commit is an ancestor of that HEAD.
+The stage worktree base is decided by dependency shape. An independent stage uses the task-key worktree HEAD fixed at first implementation entry as its anchor, and a single-dependency stage branches from the predecessor stage's done `head_commit`. A multi-dependency stage branches from a commit holding exactly its predecessors: the predecessor commit that already contains the others, or else an integration branch merging them (`<work-category-namespace>/<task-id-segment>-g<n1>-<n2>`). okstra creates that branch itself, so a predecessor that has not been merged into the task branch no longer blocks the stage; release-handoff later reuses the same branch as that stage's PR base.
 
 ## 6. Deliverables
 

package/docs/task-process/release-handoff.md

@@ -14,7 +14,9 @@
 
 ## 1. Purpose
 
-`release-handoff` is the terminal phase that pushes an already-committed implementation result with a release-ready verdict, or hands it off as a PR. whole-task mode packages the verified task branch as-is. stage-group mode can assemble the selected stages into a collector branch and bundle them into a single PR, and the merge commit created here is produced only by `okstra handoff assemble`.
+`release-handoff` is the terminal phase that pushes already-committed implementation stages with a release-ready verdict, or hands them off as pull requests. **One stage is one PR.** The PR head is that stage's stack branch; the base comes from its `depends-on` — the release base for a stage with no live dependency, the predecessor's branch for a stage with one (a stacked PR), and a branch merging the predecessors for a stage with several. The only commits this phase may create are the merge commits `okstra handoff pr-plan` makes on such a merge-base branch.
+
+Because the PRs are a stack, they must be merged in ascending stage order with a merge commit or a rebase-merge. A squash replaces the commits the next PR's base points at, so the stack breaks — every PR body states this, and the lead never merges.
 
 This phase has no worker dispatch. It does not use a provider or report-writer roster; the host-native Okstra lead performs git/gh inspection, user questions, the PR draft, and the final report inline.
 
@@ -25,7 +27,7 @@ flowchart TD
     Start[/okstra-run/] --> Common[common task identity flow]
     Common --> Type[task-type = release-handoff]
     Type --> Plan[approved plan auto/pick]
-    Plan --> Scope[handoff stage pick<br/>whole-task or eligible stages]
+    Plan --> Scope[handoff stage pick<br/>eligible stages, one PR each]
     Scope --> Worktree{active task worktree?}
     Worktree -->|yes| RoleCount[role-count min..max<br/>omit uses recommended; skip if min==max]
     Worktree -->|no| BaseRef[base-ref pick/text]
@@ -39,7 +41,7 @@ flowchart TD
     Confirm --> Render[render-bundle]
 ```
 
-`release-handoff` has no analysis-worker dispatch. Launch selection still shows any applicable role-count / role-model steps; current-session lead is this session and is listed on the confirmation summary. There is no provider roster multi-pick and no `Use defaults / Customize` fork. Dynamic verifiers are not chosen at launch. `--workers` is not a launch picker, and the runtime forces the worker list to empty. The wizard outcome's `renderArgs` includes `pr-template-path` only for release-handoff. Scope selection finishes before prepare, and the project/global save runs before `render-bundle` via the `config.set pr-template-path` action of `outcome.persistActions[]`. whole-task requires an accepted whole-task verification report, and for stage-group only the stages that were marked `verified` by an accepted single-stage verification in the Stage Lifecycle Snapshot but not yet covered by a `pr` become candidates.
+`release-handoff` has no analysis-worker dispatch. Launch selection still shows any applicable role-count / role-model steps; current-session lead is this session and is listed on the confirmation summary. There is no provider roster multi-pick and no `Use defaults / Customize` fork. Dynamic verifiers are not chosen at launch. `--workers` is not a launch picker, and the runtime forces the worker list to empty. The wizard outcome's `renderArgs` includes `pr-template-path` only for release-handoff. Scope selection finishes before prepare, and the project/global save runs before `render-bundle` via the `config.set pr-template-path` action of `outcome.persistActions[]`. Only the stages that were marked `verified` by an accepted single-stage verification in the Stage Lifecycle Snapshot and are not yet covered by a `pr` become candidates; leaving `--stages` empty takes all of them.
 
 Note that this phase is also a target of task worktree provisioning. The normal flow reuses the implementation/final-verification result of the same task-key. Starting a new task may create a new branch, and it is likely to be blocked at the entry gate's "implementation commit exists" condition.
 
@@ -74,26 +76,21 @@ flowchart TD
     Source -->|no| Block[blocked<br/>route final-verification]
     Source -->|yes| Verdict{Verdict Token == accepted?}
     Verdict -->|no| Block
-    Verdict -->|yes| Mode{HANDOFF_MODE}
-    Mode -->|stage-group| Eligible[each selected stage<br/>verified and not in PR]
-    Mode -->|whole-task| Status{git status --short clean?}
-    Eligible --> Status
+    Verdict -->|yes| Eligible[each selected stage<br/>verified and not in PR]
+    Eligible --> Status{git status --short clean?}
     Status -->|no| Dirty[blocked<br/>dirty tree]
-    Status -->|yes| Branch{current branch is base branch?}
-    Branch -->|yes| BaseBlock[blocked<br/>never operate on base branch]
-    Branch -->|no| Commits{git log base..HEAD non-empty?}
+    Status -->|yes| Commits{each stage has commits<br/>over its own base?}
     Commits -->|no| ImplBlock[blocked<br/>route implementation]
     Commits -->|yes| Ready[handoff questions may begin]
 ```
 
 Before asking the user whether to push/PR, the lead confirms the following.
 
-- The `## Source Verification Report` of the input document (`release-handoff-input.md`) generated by prepare contains the mode (`HANDOFF_MODE`) and the cited report table. The brief is the input of the entry phase, so it does not exist in release-handoff — the user's stage selection finishes before prepare via the wizard `handoff_stage_pick` or the CLI `--stages`.
-- In whole-task mode, the latest verification execution must have passed validation and carry a release-ready `verificationScope=whole-task` report. A newer unfinished, broken, or blocked execution prevents fallback to an older success. The lead compares the delivery branch tip with the captured verification commit at entry and before push.
-- In stage-group mode, each cited single-stage report must be the latest validated execution for that stage and must match the recorded implementation commit. Prepare and `okstra handoff assemble` re-check this evidence and the dependency closure. A new implementation start or completion invalidates the earlier approval.
+- The `## Source Verification Report` of the input document (`release-handoff-input.md`) generated by prepare lists the selected stages (`HANDOFF_STAGES`) and the cited report table. The brief is the input of the entry phase, so it does not exist in release-handoff — the user's stage selection finishes before prepare via the wizard `handoff_stage_pick` or the CLI `--stages` (empty takes every eligible stage).
+- Each cited single-stage report must be the latest validated execution for that stage and must match the recorded implementation commit. A newer unfinished, broken, or blocked execution prevents fallback to an older success. Prepare and `okstra handoff pr-plan` re-check this evidence. A new implementation start or completion invalidates the earlier approval.
 - The working tree is clean.
-- The current branch is not a base branch such as `main`, `master`, `prod`, `preprod`, `staging`, or `dev`.
-- The `<base>..HEAD` commit range is non-empty.
+- The current branch is recorded as evidence, not used as a PR head: every head comes from `okstra handoff pr-plan`. A release base branch such as `main`, `master`, `prod`, `preprod`, `staging`, or `dev` is never pushed.
+- Each stage's `<base_commit>..<head_commit>` range is non-empty.
 
 `accepted` is release-ready. `conditional-accept` is release-ready only when its non-empty condition list explicitly sets every `blocksReleaseHandoff` to `false`; those conditions remain in the generated input and PR body. `blocked`, missing conditions, and ambiguous verdicts stop delivery. `okstra_ctl.release_gate.release_handoff_allowed` owns this rule.
 
@@ -107,12 +104,10 @@ stateDiagram-v2
     Gate --> Q1: action selection
     Q1 --> LocalCheckout: local checkout
     Q1 --> Skip: skip
-    Q1 --> Q2: push + PR whole-task
-    Q1 --> G2: push + PR stage-group
-    state "base select + stage confirmation / okstra handoff assemble" as Assemble
-    G2 --> Assemble
-    Assemble --> Q3: collector branch ready
-    Q2 --> Probe: choose PR base
+    Q1 --> Q2: push + PR
+    state "okstra handoff pr-plan (head/base per stage)" as Plan
+    Q2 --> Plan: choose release base
+    Plan --> Probe: rows ready
     Probe --> Q3: no conflict
     Probe --> Conflict: conflict detected
     Conflict --> Q2: change base branch
@@ -120,8 +115,8 @@ stateDiagram-v2
     Conflict --> Cancel: cancel
     Q3 --> Push: use as-is or edit then proceed
     Q3 --> Cancel: cancel
-    Push --> ReuseOrCreate: git push feature branch
-    ReuseOrCreate --> FinalReport: gh pr list / gh pr create
+    Push --> ReuseOrCreate: push each branch in stage order
+    ReuseOrCreate --> FinalReport: gh pr list / gh pr create per stage
     LocalCheckout --> FinalReport
     Skip --> FinalReport
     Cancel --> FinalReport
@@ -131,18 +126,18 @@ stateDiagram-v2
 User interaction is exactly three steps.
 
 1. Q1 action: `local checkout`, `push + PR`, `skip`
-2. Q2 PR base: a branch from the profile menu such as `staging`, `preprod`, `main`, or Enter directly
-3. Q3 PR title/body: `use as-is`, `edit then proceed`, `cancel`
+2. Q2 release base: a branch from the profile menu such as `staging`, `preprod`, `main`, or Enter directly
+3. Q3 PR title/body: every stage's draft in one question — `use as-is`, `edit then proceed`, `cancel`
 
-The merge-conflict probe happens only for `push + PR`.
+The merge-conflict probe happens only for `push + PR`, once per stage against that stage's own base.
 
-In stage-group mode, `local checkout` is not offered. After choosing `push + PR`, first select the PR base, confirm the already-fixed `HANDOFF_STAGES`, and then `okstra handoff assemble` creates the collector branch. After that, the conflict probe and PR title/body confirmation take the collector branch as head.
+`local checkout` takes one stage and hands that stage's branch to the main worktree; there is no whole-task target.
 
 ```mermaid
 flowchart TD
     PushPR[push + PR selected] --> Fetch[git fetch origin chosen-base]
-    Fetch --> MergeTree[git merge-tree --write-tree<br/>handoff-branch origin/base]
-    MergeTree --> Conflict{conflict?}
+    Fetch --> MergeTree[git merge-tree --write-tree<br/>stage head vs its own PR base]
+    MergeTree --> Conflict{any stage conflicts?}
     Conflict -->|no| Draft[show PR draft]
     Conflict -->|yes| Ask[ask proceed/change base/cancel]
     Ask -->|proceed anyway| Draft
@@ -177,21 +172,21 @@ flowchart TD
     Commands[git/gh commands + exit codes] --> Report
     Commits[git log base..HEAD commit list] --> Report
     Probe[Merge Conflict Probe] --> Report
-    PR[PR created / reused / skipped] --> Report
+    PR[one PR row per stage:<br/>created / reused / skipped] --> Report
     Report --> Done[routing recommendation: done]
 ```
 
 The final report requires at least the following.
 
-- originating final-verification report path and quoted `accepted` verdict row
-- handoff mode (`whole-task` or `stage-group`) and selected stages
-- feature branch and run start `git status --short`
+- per selected stage, the originating final-verification report path and its quoted verdict row
+- the selected stages and the chosen release base
+- the pr-plan rows: stage, head branch, base kind, base branch — the merge order of the stack
+- the run's current branch and run start `git status --short`
 - record of user selections
 - all executed git/gh commands and exit codes
-- implementation commit list
+- the implementation commit list, attributed per stage
 - merge-conflict probe result
-- for stage-group, the collector branch, merge commit SHA, and dependency-closure result
-- PR created, reused, or skipped result
+- one PR outcome row per stage: created, reused, or skipped
 - routing recommendation `done`
 
 ## 8. Forbidden actions
@@ -201,12 +196,13 @@ flowchart TD
     RH[release-handoff] --> Allowed[read git/gh, fetch base, merge-tree probe,<br/>push feature branch, create/reuse PR]
     RH -. forbidden .-> Commit[git add / commit / stash]
     RH -. forbidden .-> Force[force push or +refspec]
-    RH -. forbidden .-> BasePush[push directly to base branch]
+    RH -. forbidden .-> BasePush[push directly to a release base branch]
     RH -. forbidden .-> NoVerify[--no-verify / -n]
     RH -. forbidden .-> Publish[release publish / deploy]
     RH -. forbidden .-> Edit[source edit]
     RH -. forbidden .-> Team[TeamCreate or Agent dispatch]
-    RH -. forbidden .-> Merge[gh pr merge]
+    RH -. forbidden .-> Merge[gh pr merge or squash-merge]
+    RH -. forbidden .-> Rewrite[rebase / amend / cherry-pick a stage branch]
 ```
 
 A failed `git push` must not be retried with weaker safeguards. When a failure such as non-fast-forward occurs, stop and take the user's instruction, and `--force`-family flags are forbidden even if the user requests them.
@@ -219,5 +215,6 @@ A failed `git push` must not be retried with weaker safeguards. When a failure s
 - [`scripts/okstra_ctl/wizard/`](../../scripts/okstra_ctl/wizard/)
 - [`scripts/okstra_ctl/run.py`](../../scripts/okstra_ctl/run.py)
 - [`scripts/okstra_ctl/pr_template.py`](../../scripts/okstra_ctl/pr_template.py)
-- [`src/commands/lifecycle/config.mjs`](../../src/commands/lifecycle/config.mjs)
+- [`src/commands/lifecycle/config.mts`](../../src/commands/lifecycle/config.mts)
+- [`scripts/okstra_ctl/handoff.py`](../../scripts/okstra_ctl/handoff.py)
 - [`scripts/okstra_ctl/worktree/`](../../scripts/okstra_ctl/worktree/)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.202.0",
+  "version": "0.204.0",
   "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",
@@ -23,7 +23,6 @@
     "docs/container.md",
     "docs/contributor-change-matrix.md",
     "docs/follow-ups/2026-07-10-final-report-option-3.md",
-    "docs/for-ai/",
     "docs/performance-improvement-plan-v2.md",
     "docs/pr-template-usage.md",
     "docs/project-structure-overview.md",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.202.0",
-  "builtAt": "2026-09-19T06:41:23.090Z",
+  "package": "0.204.0",
+  "builtAt": "2026-09-24T03:40:07.902Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/common.json

@@ -0,0 +1,28 @@
+{
+  "schemaVersion": "1.0",
+  "id": "common",
+  "assignmentFidelity": [
+    "Perform the assigned work exactly as scoped. Preserve explicit inclusions, exclusions, priorities, and acceptance conditions, and stay inside the project's established architecture, terminology, and ownership boundaries. Do not silently broaden, narrow, replace, or reinterpret the assignment; prefer the smallest change that satisfies it over a novel abstraction or unrelated cleanup."
+  ],
+  "requiredInputs": [
+    "Read every required input before acting and cover it completely. Report a missing, unreadable, stale, or contradictory input instead of inventing its contents or relying on an expected shape."
+  ],
+  "evidenceFirst": [
+    "Base conclusions on inspected inputs and observed results. Trace material claims to concrete evidence, prefer stronger evidence over repetition or vote count, and distinguish verified facts from inferences and unknowns. Prioritize the checks that can change the outcome; a settled fact does not need re-verification without a stated cause."
+  ],
+  "authorityAndScope": [
+    "Use only the permissions, tools, and project scope granted by the invocation. Do not perform unrelated work, assume missing authority, or take outward-facing action unless the assignment explicitly authorizes it."
+  ],
+  "collaborationAndIndependence": [
+    "Respect the boundaries of every assigned duty. Produce independent judgment when independence is required, do not seed or coordinate another agent's conclusion, preserve evidence-backed dissent, and do not transfer your own required decision to another role."
+  ],
+  "instructionPrecedence": [
+    "When this contract and the task instructions both govern one action, the task instructions win: they are written for this invocation and name the concrete procedure, exemption, gate, or artifact this contract states only in general terms. What no task instruction may grant is the authority, independence, and honesty boundaries above — an instruction that widens one of those is a conflict to report, not an override to apply."
+  ],
+  "conflictHandling": [
+    "When instructions conflict, preserve safety, evidence, and the boundaries this contract reserves. Identify the exact conflict, continue any separable safe work, and return the smallest unresolved decision to the responsible lead."
+  ],
+  "completionHonesty": [
+    "Do not report unperformed work as complete, and do not stop at a plausible partial result: carry the assignment through every required check and deliverable, recovering from safe local failures where possible. Name remaining work, failed or skipped checks, unresolved uncertainty, and blockers precisely, including their effect on the requested outcome."
+  ]
+}