okstra 0.174.0 → 0.176.0

package/docs/cli.md

@@ -4,6 +4,8 @@
 >
 > This manual covers the phase-execution flags of `okstra.sh`. For the subcommand reference of the separate `okstra container` entry point, see [container.md](container.md).
 
+The Node CLI requires Node.js 22 or newer. Its TypeScript sources are compiled from `src/**/*.mts` to `dist/**/*.mjs`; `bin/okstra` executes the compiled files. The central state helper remains `scripts/okstra-central.sh`.
+
 ---
 
 ## Index
@@ -28,6 +30,8 @@
   - [`--directive`](#--directive)
   - [`--fix-cycle`](#--fix-cycle)
   - [`--workers`](#--workers)
+  - [`--role-count`](#--role-count)
+  - [`--role-model`](#--role-model)
   - [`--lead-runtime`](#--lead-runtime)
   - [`--claude-model`](#--claude-model)
   - [`--lead-model`](#--lead-model)
@@ -60,7 +64,7 @@
 Base command for initial entry with full arguments:
 
 ```bash
-scripts/okstra.sh [--render-only] [--yes] [--no-plan-verification] --task-type <task-type> [--workers worker1,worker2] [--lead-runtime <host-id-or-alias>] [--lead-provider <provider>] [--lead-model <model>] [--worker-model provider=model,...] [--report-writer-provider <provider>] [--report-writer-model <model>] [--executor claude|codex|antigravity] [--critic off|claude|codex|antigravity|grok|kimi] [--related-tasks taskA,taskB] [--work-category bugfix|feature|refactor|ops|improvement|unknown] [--base-ref <branch|tag|sha>] [--clarification-response <previous-final-report>] [--selected-direction <selection-final-report.md>] [--approved-plan <plan-path>] [--approve] --project-id <project-id> --task-group <task-group> --task-id <task-id> --task-brief <brief-path> [--directive <directive>] [--fix-cycle <yes|no>]
+scripts/okstra.sh [--render-only] [--yes] [--no-plan-verification] --task-type <task-type> [--workers worker1,worker2] [--role-count <role>=<N>] [--role-model <role>=<modelRef>] [--lead-runtime <host-id-or-alias>] [--lead-provider <provider>] [--lead-model <model>] [--worker-model provider=model,...] [--report-writer-provider <provider>] [--report-writer-model <model>] [--executor claude|codex|antigravity|grok|kimi] [--critic off|claude|codex|antigravity|grok|kimi] [--related-tasks taskA,taskB] [--work-category bugfix|feature|refactor|ops|improvement|unknown] [--base-ref <branch|tag|sha>] [--clarification-response <previous-final-report>] [--selected-direction <selection-final-report.md>] [--approved-plan <plan-path>] [--approve] --project-id <project-id> --task-group <task-group> --task-id <task-id> --task-brief <brief-path> [--directive <directive>] [--fix-cycle <yes|no>]
 ```
 
 Analysis input ownership is narrower than the base shell command. The `/okstra-run` wizard collects `--analysis-target` and `--evidence-inputs` values and passes them internally to `node bin/okstra render-bundle`. `scripts/okstra.sh` does not accept either flag. Because `feature-analysis` requires a target, start that task type with the in-host skill; the two option sections below document the internal Node render inputs, not standalone shell options.
@@ -149,7 +153,7 @@ The lifecycle task types run in this order:
 - Primary-pass assignment: selected analyser instances are enumerated in `requiredWorkerRoles` order, then the lead rotates the primary pass across the resolved priority lenses. Provider/model names do not affect the order, and every analyser still covers every resolved lens after its primary pass.
 - Two bidirectional grilling points: an enhanced Step 4 in `okstra-brief-gen` with a budget of 8, and the lead's Phase 1.5 reflect-back with a budget of 12.
 - Validator: `validators/validate_improvement_report.py` enforces the 11-part contract for an `improvement-discovery` final report.
-- Because an `improvement-discovery` run is not in `PHASE_SEQUENCE`, the `--task-key` short form does not automatically populate `nextRecommendedPhase` for it.
+- Because an `improvement-discovery` run is not in `PHASE_SEQUENCE`, its report has no routing field to project from, so the run leaves `workflow.nextRecommendedPhase` `pending` with no phase. The `--task-key` short form therefore cannot fill `--task-type` after one.
 
 #### Analysis sidetrack task types
 
@@ -161,7 +165,7 @@ The three read-only analysis types are independent sidetracks outside `PHASE_SEQ
 | `feature-analysis` | Trace one existing feature through flows, domain rules, state changes, external interactions, and test coverage. |
 | `change-impact-analysis` | Map the blast radius of a proposed change across preserved behavior, dependencies, tests, and operations. |
 
-Each one starts from a brief and produces a report only. The target project is strictly read-only: no edits, tests, builds, migrations, or deployments. A run ends at `pending-routing-decision`; it does not advance the normal phase sequence.
+Each one starts from a brief and produces a report only. The target project is strictly read-only: no edits, tests, builds, migrations, or deployments. A run ends with `workflow.nextRecommendedPhase` `pending` and carrying no phase; it does not advance the normal phase sequence.
 
 ### `--analysis-target`
 
@@ -230,10 +234,10 @@ A short form that supplies `--project-id`, `--task-group`, and `--task-id` toget
 - Behavior:
   - Splits the value into the three IDs and populates `PROJECT_ID`, `TASK_GROUP`, and `TASK_ID`.
   - If the same values are also provided explicitly, they are accepted only when they match; a conflict exits immediately with an error.
-  - If the task has a `task-manifest.json`, a missing `--task-brief` is filled from the manifest's `taskBriefPath`, and a missing `--task-type` is filled from `workflow.nextRecommendedPhase`.
+  - If the task has a `task-manifest.json`, a missing `--task-brief` is filled from the manifest's `taskBriefPath`, and a missing `--task-type` is filled from `workflow.nextRecommendedPhase.phase` — but only while that pointer's `status` is `ready`.
   - Without a manifest, as on initial entry, the normal missing-argument validation remains in effect and full arguments are required.
 - Explicit arguments always take precedence over manifest values.
-- When `nextRecommendedPhase` is `pending-routing-decision` or `done-or-follow-up`, it is not filled automatically. Supply `--task-type` explicitly or supplement the brief, then rerun the command.
+- Under any other `status` — `pending`, `blocked`, or `terminal` — the pointer names no runnable phase and `--task-type` is not filled automatically. Supply `--task-type` explicitly or supplement the brief, then rerun the command.
 
 Examples:
 
@@ -407,9 +411,11 @@ scripts/okstra.sh --task-type implementation-planning ... \
 
 ### `--workers`
 
-Directly specifies the workers used in this run.
-The default is `claude,codex,report-writer`. Antigravity is optional; add it explicitly when needed, as in `--workers claude,codex,antigravity,report-writer`.
-When supplied, only the deduplicated worker subset is recorded.
+Compatibility input only. Prefer `--role-count` and `--role-model` for launch selection.
+
+When supplied, the CSV of provider names converts into role slots and model refs for the profile's initial cross-verification role (for example analysers or planners). It is not a provider roster picker and is not the selection unit on the wizard start screen.
+
+If the same role is also named by `--role-model` (or other canonical role flags), the converted providers must match the model-ref provider prefixes in order and slot count. Matching values keep the canonical role models and drop the legacy constraint. Different values fail before any worktree or state file is created.
 
 Example:
 
@@ -445,7 +451,7 @@ worker roster contains Claude, Codex, or Antigravity.
 
 ### Runtime auto-detection (`auto`)
 
-`okstra run` defaults to `auto`. `src/lib/host-registry-client.mjs` asks the Python host registry to resolve explicit IDs and aliases, the `OKSTRA_RUNTIME_HOST` environment declaration, Claude Code skill handoff, or the external tmux claim. It fails fast when no adapter claims the session. Installed CLI presence alone never selects a host.
+`okstra run` defaults to `auto`. `src/lib/host-registry-client.mts` asks the Python host registry to resolve explicit IDs and aliases, the `OKSTRA_RUNTIME_HOST` environment declaration, Claude Code skill handoff, or the external tmux claim. It fails fast when no adapter claims the session. Installed CLI presence alone never selects a host.
 
 - Inside a registered host, the installed `okstra-run` skill uses `current-session`, declares the live semantic function list, and reuses the session you are already in.
 - From a terminal, `okstra run <host-id-or-alias>` uses `spawn-process` and starts the selected host CLI. The leading word is an alias for `--lead-runtime`.
@@ -467,9 +473,25 @@ The Codex worker (`--workers codex`, `--codex-model`) and Codex lead runtime are
 > - Claude (`--lead-model` / `--claude-model` / `--report-writer-model`): `fable`, `fable-5`, `claude-fable-5`, `opus`, `opus-5`, `claude-opus-5`, `opus-4-8`, `claude-opus-4-8`, `opus-4-7`, `claude-opus-4-7`, `opus-4-6`, `claude-opus-4-6`, `sonnet`, `sonnet-5`, `claude-sonnet-5`, `sonnet-4-6`, `claude-sonnet-4-6`, `haiku`, `haiku-4-5`, `claude-haiku-4-5`, `claude-haiku-4-5-20251001`
 > - Codex (`--codex-model`): `gpt-5.6-sol`, `gpt-5.6`, `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.3-codex`, `gpt-5.2`, `codex-auto-review`
 > - Antigravity (`--antigravity-model`): `gemini-3.1-pro` (default), `gemini-3.6-flash`, `gemini-3.5-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-build-0.1`, `grok-4.5`
+> - Grok (`--worker-model grok=<model>`): `grok-4.6`, `grok-4.5`, `grok-build-0.1`
 > - Kimi (`--worker-model kimi=<model>`): `kimi-k2.7-code`, `kimi-for-coding`, `kimi-k3`, `k3`, `k3-256k` and their registered display aliases
 
+### `--role-count`
+
+Sets how many slots open for one static role: `--role-count <role>=<N>`. Repeat the flag for each role. `N` must fall in that role's profile range `min..max`. Omit the flag to use the profile **recommended** count (not a separate roster default). Roles with `min == max` are fixed quantity and reject this flag. Dynamic roles and roles absent from the profile also reject it. `lead` is a compatibility alias for `leader`. New records write `leader`.
+
+Each confirmed count becomes `RoleInstance` ordinals. `ModelPool` then assigns one model ref per ordinal. A pinned model is kept only when the host can bind it exactly. Roles with `min = 0` do not open slots by default; optional add steps or an explicit count above zero open them.
+
+### `--role-model`
+
+Pins one model reference onto a role slot, in ordinal order: `--role-model <role>=<modelRef>`. Repeat the flag to fill later ordinals. `modelRef` is `<provider>/<model>`, for example `claude/opus-5` or `codex/gpt-5.6-sol`.
+
+A known selectable model may be assigned to any canonical role. The same role must not receive the same model ref twice; duplicate refs in one role panel fail before any worktree or state file is created. Same provider with different models is allowed. Fewer models than the confirmed count are filled from the model-default chain. Extra models do not raise the count; set `--role-count <role>=<N>` first. Unknown roles and unknown model refs fail before side effects.
+
+Legacy `--lead-model`, `--claude-model`, `--codex-model`, `--antigravity-model`, `--worker-model`, `--report-writer-model`, `--executor`, and `--workers` remain compatibility inputs. They convert to role-model selections. A new flag and a legacy flag that name different models (or, for `--workers`, different provider prefixes) for the same role fail.
+
+`okstra model list [--role <role>] [--host <host>] [--json]` prints the catalog without an inference call. `okstra model default set|unset <role> ... --scope project|global` writes `modelDefaults` to `.okstra/project.json` or `~/.okstra/config.json`.
+
 ### `--lead-provider`
 
 Compatibility assertion for previously recorded invocations. The value must match the host-native provider: `claude` on Claude Code, `codex` on Codex, and `antigravity` on Antigravity. It is not an independent lead selector. Other providers belong in the worker roster and run through CLI wrappers; preparation rejects a cross-provider lead rather than recording one model and silently running another.
@@ -528,11 +550,11 @@ Fallback defaults are:
 
 ### `--executor`
 
-Selects the provider that performs the Executor role for `--task-type implementation`. The value is `claude`, `codex`, or `antigravity`; it is ignored for other task types.
+Selects the provider that performs the Executor role for `--task-type implementation`. The value is `claude`, `codex`, `antigravity`, `grok`, or `kimi`; it is ignored for other task types.
 
 - Default: `OKSTRA_DEFAULT_EXECUTOR` → fallback `claude`.
-- The Executor is the **only worker allowed to mutate project files** in this run. The other two 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`.
+- 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`.
 - 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 workspace-write`, 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). Without it, the Codex `workspace-write` sandbox rejects worktree writes with EPERM.
 - **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.
@@ -762,7 +784,7 @@ chmod +x ~/.local/bin/okstra-ctl
 
 ### `okstra` Node CLI — introspection subcommands
 
-The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and introspection commands used by skills and agents. It goes through the Node wrapper instead of invoking the Python runtime directly, so `src/lib/python-helper.mjs` wires `PYTHONPATH`.
+The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and introspection commands used by skills and agents. It goes through the Node wrapper instead of invoking the Python runtime directly, so `src/lib/python-helper.mts` wires `PYTHONPATH`.
 
 | Command | Purpose |
 |---|---|
@@ -770,7 +792,9 @@ The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and
 | `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 doctor [--runtime claude-code\|codex\|antigravity\|external\|all] [--phase <phase>] [--json]` | Diagnose the runtime, Python imports, and skill/agent installation. The `codex`, `antigravity`, and `external` runtimes omit Claude skill checks. `--phase` adds readiness checks for `implementation`, `final-verification`, `release-handoff`, or `improvement-discovery` |
+| `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 |
 | `okstra setup --project-id <id>` | Create or update `.okstra/project.json` in the current project |
 | `okstra check-project [--json]` | Verify that the current project is registered |
 | `okstra preflight [--runtime <name>] [--cwd <dir>] [--json]` | Single skill-preflight call combining `ensure-installed`, with silent reinstall when stale, `check-project`, and host-specific `runtimeReadiness` into one JSON response. A `claude-code` host checks project workspace trust. A `codex` current-session host verifies write access to `~/.okstra/worktrees/registry.lock`; a sandbox denial blocks before the wizard with the `switch-codex-to-full-access-and-rerun` action. `antigravity` and `external` hosts return ready without reading Claude Code state. Step 0 of every project-scoped skill converges on this command |
@@ -834,7 +858,7 @@ The convergence state lifecycle is `groups v1.0 → work v1.0 → final v1.3`; r
 
 `okstra convergence` and `okstra plan-items` are internal admin CLI families used by the lead protocol. Each is an internal admin CLI, not a user-facing skill, and their presence does not add a public skill. The former `okstra-convergence` skill remains obsolete; the installed `prompts/lead/convergence.md` and `prompts/lead/plan-body-verification.md` contracts tell the lead when to invoke these operations.
 
-> Every subcommand is wired to `PYTHONPATH` and `~/.okstra/lib/python` by the Python helper (`src/lib/python-helper.mjs`) spawned by `bin/okstra`. When invoking `python3 -m okstra_ctl.*` directly, you must configure `PYTHONPATH` yourself.
+> Every subcommand is wired to `PYTHONPATH` and `~/.okstra/lib/python` by the Python helper (`src/lib/python-helper.mts`) spawned by `bin/okstra`. When invoking `python3 -m okstra_ctl.*` directly, you must configure `PYTHONPATH` yourself.
 
 #### `okstra design-prep`
 

package/docs/contributor-change-matrix.md

@@ -5,8 +5,8 @@ Use this matrix before changing high-risk repo contracts. Update the source file
 | Change | Must update | Tests |
 |---|---|---|
 | 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.mjs`, `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.mjs`, `.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` |
+| 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`, `src/commands/manager.mjs`, `skills/okstra-manager/SKILL.md`, `docs/for-ai/skills/okstra-manager.md`, `docs/cli.md`, `docs/architecture/storage-model.md` | `tests-js/manager.test.mjs`, `tests/test_okstra_manager_*.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 |

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

@@ -87,7 +87,7 @@ Keep the table narrow.
 - workStatus
 - Next
 
-If `awaitingApproval` or `routingStatus == "pending"`, add a marker to the Next cell and explain it.
+`nextRecommendedPhase` is an object `{phase, status, rationale}`. The Next cell is its `phase`, or `--` when that is empty. If `awaitingApproval`, or `nextRecommendedPhase.status` is anything but `ready`, add a marker to the Next cell and explain it.
 
 ### Specific task
 
@@ -98,9 +98,8 @@ Information to show:
 - work category
 - current phase/state
 - last completed phase
-- next recommended phase
+- next-phase pointer: `phase` (or `--`), its `status`, its `rationale`
 - awaiting approval
-- routing status
 - task status, latest run status
 - latest report, resume command
 - workStatus, note

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

@@ -62,6 +62,7 @@ Top level:
 
 - `taskGroup` — the scope (`null` = whole project), `taskCount` — number of tasks.
 - `tasks[]` — per task: `taskKey, taskGroup, taskId, taskType, workCategory, workStatus, currentPhase, currentPhaseState, nextRecommendedPhase, latestRunStatus, updatedAt, reportPath, runCount, cpuSumMs, wallClockMs, errorCount`.
+  - `nextRecommendedPhase` is an object `{phase, status, rationale}`, not a string. Print `phase`, or `--` when it is empty. Never interpolate the object itself.
 - `totals` — `runs, cpuSumMs, wallClockMs, errors`, plus `byWorkStatus` / `byWorkCategory` / `byCurrentPhase` / `byTaskType` (each a `{value: count}` map).
 
 Numeric meanings (must observe):

package/docs/project-structure-overview.md

@@ -25,7 +25,7 @@
 Current baseline:
 
 - package version: see `package.json`
-- Node CLI entrypoint: `bin/okstra`
+- Node CLI entrypoint: `bin/okstra` (Node.js 22+)
 - Python orchestration authority: `scripts/okstra_ctl/run.py::prepare_task_bundle`
 - lifecycle: `requirements-discovery → error-analysis → implementation-option-selection → implementation-planning → implementation → final-verification → release-handoff`
 - installed skills: 13
@@ -46,7 +46,8 @@ Design principles:
 ```text
 okstra/
 ├── bin/okstra                       Node CLI router
-├── src/                             Node command modules
+├── src/                             TypeScript Node command sources (`*.mts`)
+├── dist/                            compiled `.mjs` CLI artifacts; generated
 ├── scripts/                         Python + Bash runtime sources
 │   ├── okstra_ctl/                  orchestration core
 │   ├── okstra_project/              project root / project.json resolver
@@ -145,7 +146,7 @@ Runtime/install asset changes follow this checklist:
 
 `--link <repo>` mode is for development and symlinks installed files back to repo sources.
 
-`src/lib/host-registry-client.mjs` is the single Node boundary for host catalog, ID/alias resolution, and readiness probes. It delegates host policy to `okstra_ctl.entrypoints.hosts`; the Claude Code adapter checks project workspace trust, while other adapters own their own checks. `okstra install` defaults to `--runtime auto`, records the request and any successful resolution in `installed-runtimes.json` schemaVersion 2, and still copies the shared runtime payload from the installed package `runtime/` tree even when host detection is unavailable. Skill targets always include the default Agent-compatible `~/.agents/skills` target, with `~/.claude/skills` also populated when `~/.claude` exists. Dynamic capabilities are probed by the selected adapter rather than frozen into the install manifest.
+`src/lib/host-registry-client.mts` is the single Node boundary for host catalog, ID/alias resolution, and readiness probes. It delegates host policy to `okstra_ctl.entrypoints.hosts`; the Claude Code adapter checks project workspace trust, while other adapters own their own checks. `okstra install` defaults to `--runtime auto`, records the request and any successful resolution in `installed-runtimes.json` schemaVersion 2, and still copies the shared runtime payload from the installed package `runtime/` tree even when host detection is unavailable. Skill targets always include the default Agent-compatible `~/.agents/skills` target, with `~/.claude/skills` also populated when `~/.claude` exists. Dynamic capabilities are probed by the selected adapter rather than frozen into the install manifest.
 
 ---
 
@@ -155,62 +156,62 @@ Runtime/install asset changes follow this checklist:
 
 `bin/okstra` is a thin dynamic-import router. Every command module exports `run(args) -> Promise<number>` or a named install/uninstall runner.
 
-`src/` is layered: the dispatch table (`src/cli-registry.mjs`) stays at the root, shared infrastructure with no command export lives under `src/lib/`, and command modules are grouped by domain under `src/commands/{lifecycle,execute,inspect,report,memory,pr}/`.
+`src/` is layered: the dispatch table (`src/cli-registry.mts`) stays at the root, shared infrastructure with no command export lives under `src/lib/`, and command modules are grouped by domain under `src/commands/{lifecycle,execute,inspect,report,memory,pr}/`. `npm run build:ts` compiles these sources to `dist/**/*.mjs`; `bin/okstra` executes the compiled output. `scripts/okstra-central.sh` remains the Bash central-state helper.
 
 | Command | Module | Role |
 |---|---|---|
-| `paths` | `src/commands/lifecycle/paths.mjs` | Resolve package/runtime/home paths (library at `src/lib/paths.mjs`) |
-| `install`, `ensure-installed` | `src/commands/lifecycle/install.mjs` | Install or refresh runtime, skills, agents, templates |
-| `uninstall` | `src/commands/lifecycle/uninstall.mjs` | Remove managed runtime/skills/agents, optionally purge data |
-| `doctor` | `src/commands/lifecycle/doctor.mjs` | Diagnose runtime and Python imports |
-| `setup` | `src/commands/lifecycle/setup.mjs` | Create/update `<PROJECT_ROOT>/.okstra/project.json` |
-| `check-project` | `src/commands/lifecycle/check-project.mjs` | Verify project registration |
-| `preflight` | `src/commands/lifecycle/preflight.mjs` | One-call skill preflight: ensure-installed + check-project + host-specific runtime readiness (single JSON) |
-| `config` | `src/commands/lifecycle/config.mjs` | Read/write project/global settings such as PR template path |
-| `migrate` | `src/commands/lifecycle/migrate.mjs` | One-shot legacy `.project-docs/okstra` → `.okstra` migration helper |
-| `git-reconcile` | `src/commands/execute/git-reconcile.mjs` | Reconcile stale stage SHAs after external git history changes |
-| `handoff` | `src/commands/execute/handoff.mjs` | Stage-group release-handoff eligibility / assemble / record helpers |
-| `integrate-stages` | `src/commands/execute/integrate-stages.mjs` | Merge verified stages into the task worktree and clean stage worktrees |
-| `task-list`, `task-show` | `src/commands/inspect/task-list.mjs`, `src/commands/inspect/task-show.mjs` | Task/run introspection for skills; `task-show` consumes the Python task read-side snapshot |
-| `resolve-task-key` | `src/commands/inspect/resolve-task-key.mjs` | Resolve a bare task-id to candidate task-keys from the project catalog |
-| `set-work-status` | `src/commands/inspect/set-work-status.mjs` | Set a task's user-managed `workStatus` in task-manifest.json (Python: `okstra_ctl.set_work_status`) |
-| `time-report`, `log-report`, `error-report`, `error-zip` | `src/commands/inspect/*.mjs` | Read-side task runtime, wrapper log, and error aggregation helpers |
-| `run-audit` | `src/commands/inspect/run-audit.mjs` | Anomaly detection — checks run artifacts against progress invariants and reports invariant violations, read-only (Python: `okstra_ctl.run_audit`) |
-| `worker-liveness` | `src/commands/inspect/worker-liveness.mjs` | Report whether pending workers are still alive, so the lead's poll ends a stalled wait early instead of paying the deadline (Python: `okstra_ctl.worker_liveness`) |
-| `worker-audit-check` | `src/commands/execute/worker-audit-check.mjs` | Apply the Phase 7 worker audit-sidecar rules while the worker session is still alive, so it can fix its own citations (Python: `okstra_ctl.worker_audit_check`, rules in `okstra_ctl.worker_audit_ledger`) |
-| `context-cost` | `src/commands/inspect/context-cost.mjs` | Estimate task bundle file/read context cost |
-| `worktree-lookup` | `src/commands/execute/worktree-lookup.mjs` | Look up a task-key's registered worktree |
-| `worktree-status` | `src/commands/execute/worktree-status.mjs` | Clean-worktree check over source paths only, excluding okstra's provisioned entries and nested stage worktrees (Python: `okstra_ctl.worktree.dirty_entries_excluding_okstra`) |
-| `plan-validate` | `src/commands/execute/plan-validate.mjs` | Check approved-plan approval marker |
-| `render-bundle` | `src/commands/execute/render-bundle.mjs` | Preview `prepare_task_bundle(render_only=True)` |
-| `profile` | `src/commands/inspect/profile-show.mjs` | Print a phase profile with `{{INCLUDE:}}` expanded and its lazy-read sidecars appended transitively, so one grep answers whether a task-type covers a rule — a top-level grep alone returns false negatives (Python: `okstra_ctl.profile_show`). Read-only, unlike `render-bundle` |
-| `run` | `src/commands/execute/run.mjs` | Host-aware execution front door (`auto` → Claude/Codex/Antigravity/external path selection) |
-| `codex-run`, `codex-dispatch` | `src/commands/execute/codex-*.mjs` | Codex lead dry-run bundle preparation; `codex-dispatch` is the compatibility alias for provider-neutral worker dispatch |
-| `agent-prompt`, `worker-dispatch` | `src/commands/execute/{agent-prompt,worker-dispatch}.mjs` | Materialize/verify invocation prompts, record host-native specification/result links, and launch verified CLI assignments through the provider-neutral dispatcher |
-| `team` | `src/commands/execute/team.mjs` | External lead tmux-pane worker dispatch / await / teardown |
-| `convergence` | `src/commands/execute/convergence.mjs` | Internal admin CLI for the deterministic Phase 5.5 convergence engine (`seed`/`plan-round`/`apply-round`/`apply-critic-gaps`/`finalize`/`validate`/`example`; Python: `okstra_ctl.convergence`) |
-| `plan-items` | `src/commands/execute/plan-items.mjs` | Internal admin CLI for deterministic plan-body item extraction and exact-match validation (`extract`/`validate`; Python: `okstra_ctl.plan_items_cli`) |
-| `agent-activity` | `src/commands/report/agent-activity.mjs` | Thin Node shim for `okstra_ctl.agent_activity`; `append` records one run-bound activity and `project` writes the validated event projection into final-report data |
-| `report-finalize` | `src/commands/report/finalize.mjs` | Run the whole Phase 7 post-report sequence in contractual order (Python: `okstra_ctl.report_finalize`) — the single reference point shared with the Codex lead adapter |
-| `render-views` | `src/commands/report/render-views.mjs` | Render schema v2 data with its task-specific human template, or use the quick-report compatibility view |
-| `render-final-report`, `inject-report-index` | `src/commands/report/*.mjs` | Render version-selected AI handoff Markdown from data.json; v1 index injection remains compatibility-only |
-| `wizard` | `src/commands/execute/wizard.mjs` | Drive the `okstra-run` interactive state machine, including the final outcome envelope |
-| `token-usage` | `src/commands/execute/token-usage.mjs` | Wrap installed Python token usage CLI |
-| `spawn-followups`, `error-log` | `src/commands/execute/*.mjs` | Follow-up task bundle creation and run error-log append helpers |
-| `memory` | `src/commands/memory/memory.mjs` | Store/find global conversation memory under `~/.okstra/memory-book` |
-| `pr` | `src/commands/pr/pr.mjs` | `okstra pr <template\|branches\|gen>` — PR body template store under `~/.okstra/template/pr/` (bundled fallback `src/commands/pr/default.md`), base-branch recommendation, and the `gen` JSON bundle (template + `<base>..HEAD` commits + `<base>...HEAD` diffstat) backing the okstra-pr-gen skill. Git-only; no project registration required |
-| `recap` | `src/commands/inspect/recap.mjs` | `okstra recap <assemble\|record\|note>` Node wrapper backing the okstra-inspect `recap` facet — `assemble` is a read-only phase-transition summary, `record` appends one line to `recap/recap-log.jsonl`, and `note` writes an agent-authored note under `notes/` and prints the `--clarification-response` argument for a follow-up run |
-| `stage-map` | `src/commands/inspect/stage-map.mjs` | `okstra stage-map <task-key>` — exposes a task's implementation-planning Stage Map as JSON (`stages[].{stage_number,title,depends_on,step_count}` + consumer-state-based `doneStages[]`). If there is no Stage Map, `stages: []`. The read-side basis from which `okstra-schedule-gen` derives stage units and dependency closure |
-| `design-prep` | `src/commands/inspect/design-prep.mjs` | `okstra design-prep <list\|show\|write>` thin shim into `scripts/okstra_ctl/design_prep.py` — queries (`list`/`show`) the design items that implementation-planning pre-authored with AI, and records the user-confirmed responses as an append-only sidecar under `design-prep-inputs/` (`write`, `--confirmed` required). It never modifies the report snapshot |
-| `rollup` | `src/commands/inspect/rollup.mjs` | `okstra rollup` thin shim into `scripts/okstra_ctl/rollup.py` — read-only cross-task roll-up backing the okstra-rollup skill |
-| `usage-report` | `src/commands/inspect/usage-report.mjs` | `okstra usage-report` thin shim into `scripts/okstra_ctl/usage_report.py` — read-only project usage snapshot backing the okstra-usage skill |
-| `container` | `src/commands/inspect/container.mjs` | `bin okstra container` thin shim into `scripts/okstra_ctl/container.py` for the okstra-container-build skill |
-| `code-review` | `src/commands/inspect/code-review.mjs` | `okstra code-review target` thin shim into `scripts/okstra_ctl/code_review_target.py` — resolves what one implementation stage's or one branch's review reads (worktree, branch, base/head commits) and where its result file goes, for the okstra-code-review skill. Read-only; creates no directory or file |
-| `manager` | `src/commands/manager.mjs` | Thin shim into `scripts/okstra_ctl/manager_cli.py` for cross-project manager state and child launch packets |
-
-`src/lib/python-helper.mjs` centralizes Node → Python execution so command modules do not duplicate subprocess wiring.
-
-`src/lib/helper-scripts.mjs` is the SSOT list of the Python helper scripts that `okstra <cmd>` subcommands front through `runInstalledScript()`. `okstra preflight` asserts every one of them resolves under `~/.okstra/bin` using the same resolver the dispatch path uses, so a stale install fails at the cheap environment gate instead of at the blocking lead step that calls it mid-run. A contract test keeps the list in step with the `scriptName:` literals in `src/commands/**`.
+| `paths` | `src/commands/lifecycle/paths.mts` | Resolve package/runtime/home paths (library at `src/lib/paths.mts`) |
+| `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` |
+| `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 |
+| `migrate` | `src/commands/lifecycle/migrate.mts` | One-shot legacy `.project-docs/okstra` → `.okstra` migration helper |
+| `git-reconcile` | `src/commands/execute/git-reconcile.mts` | Reconcile stale stage SHAs after external git history changes |
+| `handoff` | `src/commands/execute/handoff.mts` | Stage-group release-handoff eligibility / assemble / record helpers |
+| `integrate-stages` | `src/commands/execute/integrate-stages.mts` | Merge verified stages into the task worktree and clean stage worktrees |
+| `task-list`, `task-show` | `src/commands/inspect/task-list.mts`, `src/commands/inspect/task-show.mts` | Task/run introspection for skills; `task-show` consumes the Python task read-side snapshot |
+| `resolve-task-key` | `src/commands/inspect/resolve-task-key.mts` | Resolve a bare task-id to candidate task-keys from the project catalog |
+| `set-work-status` | `src/commands/inspect/set-work-status.mts` | Set a task's user-managed `workStatus` in task-manifest.json (Python: `okstra_ctl.set_work_status`) |
+| `time-report`, `log-report`, `error-report`, `error-zip` | `src/commands/inspect/*.mts` | Read-side task runtime, wrapper log, and error aggregation helpers |
+| `run-audit` | `src/commands/inspect/run-audit.mts` | Anomaly detection — checks run artifacts against progress invariants and reports invariant violations, read-only (Python: `okstra_ctl.run_audit`) |
+| `worker-liveness` | `src/commands/inspect/worker-liveness.mts` | Report whether pending workers are still alive, so the lead's poll ends a stalled wait early instead of paying the deadline (Python: `okstra_ctl.worker_liveness`) |
+| `worker-audit-check` | `src/commands/execute/worker-audit-check.mts` | Apply the Phase 7 worker audit-sidecar rules while the worker session is still alive, so it can fix its own citations (Python: `okstra_ctl.worker_audit_check`, rules in `okstra_ctl.worker_audit_ledger`) |
+| `context-cost` | `src/commands/inspect/context-cost.mts` | Estimate task bundle file/read context cost |
+| `worktree-lookup` | `src/commands/execute/worktree-lookup.mts` | Look up a task-key's registered worktree |
+| `worktree-status` | `src/commands/execute/worktree-status.mts` | Clean-worktree check over source paths only, excluding okstra's provisioned entries and nested stage worktrees (Python: `okstra_ctl.worktree.dirty_entries_excluding_okstra`) |
+| `plan-validate` | `src/commands/execute/plan-validate.mts` | Check approved-plan approval marker |
+| `render-bundle` | `src/commands/execute/render-bundle.mts` | Preview `prepare_task_bundle(render_only=True)` |
+| `profile` | `src/commands/inspect/profile-show.mts` | Print a phase profile with `{{INCLUDE:}}` expanded and its lazy-read sidecars appended transitively, so one grep answers whether a task-type covers a rule — a top-level grep alone returns false negatives (Python: `okstra_ctl.profile_show`). Read-only, unlike `render-bundle` |
+| `run` | `src/commands/execute/run.mts` | Host-aware execution front door (`auto` → Claude/Codex/Antigravity/external path selection) |
+| `codex-run`, `codex-dispatch` | `src/commands/execute/codex-*.mts` | Codex lead dry-run bundle preparation; `codex-dispatch` is the compatibility alias for provider-neutral worker dispatch |
+| `agent-prompt`, `worker-dispatch` | `src/commands/execute/{agent-prompt,worker-dispatch}.mts` | Materialize/verify invocation prompts, record host-native specification/result links, and launch verified CLI assignments through the provider-neutral dispatcher |
+| `team` | `src/commands/execute/team.mts` | External lead tmux-pane worker dispatch / await / teardown |
+| `convergence` | `src/commands/execute/convergence.mts` | Internal admin CLI for the deterministic Phase 5.5 convergence engine (`seed`/`plan-round`/`apply-round`/`apply-critic-gaps`/`finalize`/`validate`/`example`; Python: `okstra_ctl.convergence`) |
+| `plan-items` | `src/commands/execute/plan-items.mts` | Internal admin CLI for deterministic plan-body item extraction and exact-match validation (`extract`/`validate`; Python: `okstra_ctl.plan_items_cli`) |
+| `agent-activity` | `src/commands/report/agent-activity.mts` | Thin Node shim for `okstra_ctl.agent_activity`; `append` records one run-bound activity and `project` writes the validated event projection into final-report data |
+| `report-finalize` | `src/commands/report/finalize.mts` | Run the whole Phase 7 post-report sequence in contractual order (Python: `okstra_ctl.report_finalize`) — the single reference point shared with the Codex lead adapter |
+| `render-views` | `src/commands/report/render-views.mts` | Render schema v2 data with its task-specific human template, or use the quick-report compatibility view |
+| `render-final-report`, `inject-report-index` | `src/commands/report/*.mts` | Render version-selected AI handoff Markdown from data.json; v1 index injection remains compatibility-only |
+| `wizard` | `src/commands/execute/wizard.mts` | Drive the `okstra-run` interactive state machine, including the final outcome envelope |
+| `token-usage` | `src/commands/execute/token-usage.mts` | Wrap installed Python token usage CLI |
+| `spawn-followups`, `error-log` | `src/commands/execute/*.mts` | Follow-up task bundle creation and run error-log append helpers |
+| `memory` | `src/commands/memory/memory.mts` | Store/find global conversation memory under `~/.okstra/memory-book` |
+| `pr` | `src/commands/pr/pr.mts` | `okstra pr <template\|branches\|gen>` — PR body template store under `~/.okstra/template/pr/` (bundled fallback `src/commands/pr/default.md`), base-branch recommendation, and the `gen` JSON bundle (template + `<base>..HEAD` commits + `<base>...HEAD` diffstat) backing the okstra-pr-gen skill. Git-only; no project registration required |
+| `recap` | `src/commands/inspect/recap.mts` | `okstra recap <assemble\|record\|note>` Node wrapper backing the okstra-inspect `recap` facet — `assemble` is a read-only phase-transition summary, `record` appends one line to `recap/recap-log.jsonl`, and `note` writes an agent-authored note under `notes/` and prints the `--clarification-response` argument for a follow-up run |
+| `stage-map` | `src/commands/inspect/stage-map.mts` | `okstra stage-map <task-key>` — exposes a task's implementation-planning Stage Map as JSON (`stages[].{stage_number,title,depends_on,step_count}` + consumer-state-based `doneStages[]`). If there is no Stage Map, `stages: []`. The read-side basis from which `okstra-schedule-gen` derives stage units and dependency closure |
+| `design-prep` | `src/commands/inspect/design-prep.mts` | `okstra design-prep <list\|show\|write>` thin shim into `scripts/okstra_ctl/design_prep.py` — queries (`list`/`show`) the design items that implementation-planning pre-authored with AI, and records the user-confirmed responses as an append-only sidecar under `design-prep-inputs/` (`write`, `--confirmed` required). It never modifies the report snapshot |
+| `rollup` | `src/commands/inspect/rollup.mts` | `okstra rollup` thin shim into `scripts/okstra_ctl/rollup.py` — read-only cross-task roll-up backing the okstra-rollup skill |
+| `usage-report` | `src/commands/inspect/usage-report.mts` | `okstra usage-report` thin shim into `scripts/okstra_ctl/usage_report.py` — read-only project usage snapshot backing the okstra-usage skill |
+| `container` | `src/commands/inspect/container.mts` | `bin okstra container` thin shim into `scripts/okstra_ctl/container.py` for the okstra-container-build skill |
+| `code-review` | `src/commands/inspect/code-review.mts` | `okstra code-review target` thin shim into `scripts/okstra_ctl/code_review_target.py` — resolves what one implementation stage's or one branch's review reads (worktree, branch, base/head commits) and where its result file goes, for the okstra-code-review skill. Read-only; creates no directory or file |
+| `manager` | `src/commands/manager.mts` | Thin shim into `scripts/okstra_ctl/manager_cli.py` for cross-project manager state and child launch packets |
+
+`src/lib/python-helper.mts` centralizes Node → Python execution so command modules do not duplicate subprocess wiring.
+
+`src/lib/helper-scripts.mts` is the SSOT list of the Python helper scripts that `okstra <cmd>` subcommands front through `runInstalledScript()`. `okstra preflight` asserts every one of them resolves under `~/.okstra/bin` using the same resolver the dispatch path uses, so a stale install fails at the cheap environment gate instead of at the blocking lead step that calls it mid-run. A contract test keeps the list in step with the `scriptName:` literals in `src/commands/**`.
 
 ### 4.2 `scripts/` — Runtime source
 
@@ -257,11 +258,12 @@ Important modules:
 | `run_context.py` | Per-task mutex, run context and run-input persistence; `consumers_mutex` helper for atomic `consumers.jsonl` writes |
 | `path_hints.py` | Compact path-hint persistence + legacy context hydration — stores `run-context` / `active-run-context` in the schemaVersion `2.0` `identity` + `pathHints` compact schema, and hydrates the legacy flat path keys (`RUN_MANIFEST_RELATIVE_PATH`, `TEAM_STATE_PATH`, etc.) in memory the moment the host-side reader reads them |
 | `consumers.py` | Append-only `consumers.jsonl` writer + reader — records which `implementation` runs consumed which `implementation-planning` stage |
-| `implementation_outcome.py` | Artifact-derived reconstruction of the implementation phase outcome — reads `runs/implementation/carry/stage-<N>.json` + `consumers.jsonl` + the approved Stage Map to derive `phaseOutcome.implementation`, and when every stage has pass-grade carry evidence it corrects `workflow.nextRecommendedPhase` to `final-verification` (keeping the `contract-violated` audit information) |
+| `implementation_outcome.py` | Artifact-derived reconstruction of the implementation phase outcome — reads `runs/implementation/carry/stage-<N>.json` + `consumers.jsonl` + the approved Stage Map to derive `phaseOutcome.implementation`, and when every stage has pass-grade carry evidence it raises `workflow.nextRecommendedPhase.status` to `ready` (keeping the `contract-violated` audit information). It never picks the phase — `phase` is left as the last stage's report routing settled it, and the status is raised only while `phase` is non-empty |
 | `paths.py` | Path/sequence computation for task/run artifacts (including recap directory/log paths) |
 | `recap.py` | deterministic backend for the okstra-inspect `recap` facet — `assemble` builds the cross-run phase transitions from the timeline, `record` append-only writes a summary/Q&A to `<task-root>/recap/recap-log.jsonl` (other task artifacts unchanged) |
 | `render.py` | task manifest, run manifest, timeline, task index, discovery, team-state, prompt/template render |
-| `workflow.py` | Phase sequence, allowed outputs, forbidden actions, next phase |
+| `workflow.py` | Phase sequence (`PHASE_SEQUENCE`), per-phase allowed outputs, forbidden actions. It does not decide the next phase — that is `next_phase.py` |
+| `next_phase.py` | `workflow.nextRecommendedPhase` SSOT — the pointer's shape (`make` / `is_pointer` over `{phase, status, rationale}`, `status` ∈ `ready`/`pending`/`blocked`/`terminal`), the promotion of a legacy string pointer (`promote`), the projection of one report's routing field into a pointer (`project`), and the `ready`-only read the shell and wizard autofill share (`autofill_task_type`). There is no static phase table and no sequence walk: the next phase comes from what the report authored, and nothing else may compute one |
 | `workers.py`, `models.py` | Worker roster; `models.py` is the model catalog SSOT (`ModelSpec` per alias + `ROLE_DEFAULTS`) — add-a-model single reference point from which picker options, codex pricing, and role defaults all derive |
 | `worktree.py`, `worktree_registry.py` | One worktree per task-key, branch registry, sync dirs/files/snapshots |
 | `project_meta.py`, `resolver.py`, `path_resolve.py` | Project/task/run resolution |
@@ -421,7 +423,7 @@ Optional (v1.0 backward-compatible) top-level keys:
 
 ### 4.10 `skills/`
 
-13 user-facing skills (the only skills `okstra install` copies). The list SSOT is `USER_SKILL_NAMES` in `src/lib/skill-catalog.mjs`; the Claude plugin manifest and the installer both derive from it.
+13 user-facing skills (the only skills `okstra install` copies). The list SSOT is `USER_SKILL_NAMES` in `src/lib/skill-catalog.mts`; the Claude plugin manifest and the installer both derive from it.
 
 Boilerplate shared by several skills (bash invocation rule, outdated-CLI preflight, python bootstrap note) is kept canonical in `skills/_fragments/*.md` and expanded in place inside each `SKILL.md` between `<!-- BEGIN FRAGMENT: <name> -->` / `<!-- END FRAGMENT: <name> -->` markers by `tools/sync-skill-fragments.mjs` (`--check` fails on drift). Sources stay fully expanded, so `runtime/` and installed copies remain self-contained; the guards are `tests-js/skill-fragments.test.mjs` and `tests/contract/test_prompt_fragment_ownership.py`.
 
@@ -492,7 +494,7 @@ they are not published user skills.
 `prepare_task_bundle()` coordinates:
 
 1. Resolve project root and verify/upsert `project.json`.
-2. Resolve profile, required workers, model assignments, executor provider.
+2. Resolve profile, required workers, role counts, `ModelPool` assignments, and the implementer provider. `lead`/`executor` remain input aliases only.
 3. Resolve task identity segments, work category, and the run sequence input needed for path allocation.
 4. Provision or reuse the task-key worktree, or the selected implementation stage worktree for stage-isolated runs.
 5. For an analysis sidetrack, resolve the immutable source commit from the provisioned worktree's `HEAD`, then resolve evidence reports, freshness, and the feature target through `analysis_inputs.py`.
@@ -543,6 +545,14 @@ For the three analysis sidetracks, the HTML view also exports an immutable-sourc
 
 Both Markdown and HTML are derived, not authoring sources. The schema is the contract.
 
+### 5.4 Role execution and model defaults
+
+- `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`.
+
 ---
 
 ## 6. Post-install layout
@@ -625,7 +635,7 @@ Project-local `<PROJECT_ROOT>/.claude/settings.local.json` is provisioned as a s
 | `final-verification` | Read-only acceptance verification | `release-handoff` if accepted |
 | `release-handoff` | User-selected commit/PR handoff | done or follow-up |
 
-The independent analysis sidetracks do not appear in this phase sequence. `project-analysis` maps the current project, `feature-analysis` traces one existing feature, and `change-impact-analysis` maps a proposed change's impact. Each returns to `pending-routing-decision` and remains read-only, including no test or build execution.
+The independent analysis sidetracks do not appear in this phase sequence. `project-analysis` maps the current project, `feature-analysis` traces one existing feature, and `change-impact-analysis` maps a proposed change's impact. Each leaves the next-phase pointer `pending` with no phase, and remains read-only, including no test or build execution.
 
 ### 7.5 Report and follow-up
 
@@ -674,4 +684,4 @@ Clarifications now live in the unified `## 1. Clarification Items` table. Deprec
 
 ---
 
-*Updated: 2026-07-22 · Source of truth checked against `package.json`, `bin/okstra`, `src/cli-registry.mjs`, `src/lib/skill-catalog.mjs`, `tools/build.mjs`, `scripts/`, `skills/`, `agents/`, `templates/`, `schemas/`, `validators/`, and tests.*
+*Updated: 2026-08-18 · Source of truth checked against `package.json`, `bin/okstra`, `src/cli-registry.mts`, `src/lib/skill-catalog.mts`, `tools/build.mjs`, `scripts/`, `skills/`, `agents/`, `templates/`, `schemas/`, `validators/`, and tests.*

package/docs/task-process/README.md

@@ -34,6 +34,8 @@ flowchart TD
 
 `okstra-run` does not call `scripts/okstra.sh`. Instead it goes through `okstra wizard` and `okstra render-bundle` and converges on the same single Python entrypoint, `prepare_task_bundle()`.
 
+Launch selection is role slots and model refs, not a provider roster. The wizard shows the leader session read-only, then role counts (`min..max`, default **recommended**), then `--role-model <role>=<provider>/<model>` per slot. Roles with `min = 0` stay closed unless the user adds them. There is no provider multi-pick and no `Use defaults / Customize` fork for worker selection. `--workers` is compatibility-only. `lead` is a compatibility alias for `leader`. `executor` is a compatibility alias for `implementer`. New records write `leader` and `implementer`.
+
 ## 3. task-type documents
 
 | task-type | Document | One-line purpose |
@@ -67,12 +69,14 @@ flowchart TD
 
 ## 5. Quick comparison table
 
-| task-type | wizard special question | runtime prepare gate | lead/worker mode | next phase default |
+The last column is the `workflow.nextRecommendedPhase` pointer Phase 7 leaves behind — an object `{phase, status, rationale}`, projected from the report's own routing field. There is no static default: a run that settles no route ends `pending` with no phase. The authoring rule is stated once, in the Phase 6 checklist of [`prompts/lead/report-writer.md`](../../prompts/lead/report-writer.md).
+
+| task-type | wizard special question | runtime prepare gate | lead/worker mode | next-phase pointer |
 |---|---|---|---|---|
-| `requirements-discovery` | common questions only | profile/brief/base-ref exist | multi-worker analysis, convergence 1 round default | `pending-routing-decision` |
-| `error-analysis` | common questions only | profile/brief/base-ref exist | multi-worker analysis, convergence 2 rounds default | `implementation-option-selection` |
-| `implementation-option-selection` | comparison or preselected-validation context | stable brief IDs and at least three analysers | read-only candidate validation, exact coverage, separate direction confirmation | `implementation-planning` or `blocked` |
-| `implementation-planning` | selected-direction report for a new plan | selection report/sidecar/digest or same-task planning rerun | one-direction realization + Phase 6 plan-body verification | `implementation` after plan approval |
-| `implementation` | approved plan, stage multi-pick, executor | approved marker, Stage Lifecycle Snapshot, stage-key reservation, QA command deny-list | one run = one stage; executor writes in isolated stage worktree, verifiers read-only | `final-verification` |
-| `final-verification` | approved plan, stage pick (whole-task or single-stage) | `VERIFICATION_TARGET` resolved; whole-task auto integration/teardown or single-stage worktree reuse | whole-task may integrate stages first; analyser verification itself is read-only | `pending-release-handoff` |
-| `release-handoff` | handoff scope (stage-group or whole-task), PR template override/scope | Stage Lifecycle Snapshot eligibility, generated `release-handoff-input.md`, empty worker roster | single-lead; whole-task PR or stage-group collector branch/PR | `done-or-follow-up` |
+| `requirements-discovery` | common questions only | profile/brief/base-ref exist | multi-worker analysis, convergence 1 round default | `ready` at `error-analysis` or `implementation-option-selection`; `pending` when neither is settled |
+| `error-analysis` | common questions only | profile/brief/base-ref exist | multi-worker analysis, convergence 2 rounds default | `ready` at `implementation-option-selection`, or at `error-analysis` while the investigation continues |
+| `implementation-option-selection` | comparison or preselected-validation context | stable brief IDs and at least three analysers | read-only candidate validation, exact coverage, separate direction confirmation | `ready` at `implementation-planning`, `pending` on `pending-direction-selection`, or `blocked` |
+| `implementation-planning` | selected-direction report for a new plan | selection report/sidecar/digest or same-task planning rerun | one-direction realization + Phase 6 plan-body verification | `ready` at `implementation` on `plan-ready` (the plan still needs its separate approval), or at `implementation-option-selection` on `direction-invalidated` |
+| `implementation` | approved plan, stage multi-pick, executor | approved marker, Stage Lifecycle Snapshot, stage-key reservation, QA command deny-list | one run = one stage; executor writes in isolated stage worktree, verifiers read-only | `ready` at the stage report's `routingRecommendation.target` — `final-verification` on a clean stage |
+| `final-verification` | approved plan, stage pick (whole-task or single-stage) | `VERIFICATION_TARGET` resolved; whole-task auto integration/teardown or single-stage worktree reuse | whole-task may integrate stages first; analyser verification itself is read-only | `ready` at `release-handoff` on an `accepted` verdict, otherwise at the phase owning the defect; `terminal` on `done` |
+| `release-handoff` | handoff scope (stage-group or whole-task), PR template override/scope | Stage Lifecycle Snapshot eligibility, generated `release-handoff-input.md`, empty worker roster | single-lead; whole-task PR or stage-group collector branch/PR | always `terminal` |

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

@@ -56,18 +56,17 @@ stateDiagram-v2
     TaskType --> BaseRef: no active worktree
     TaskType --> ImplementationExtras: implementation only
     BaseRef --> ImplementationExtras: implementation only
-    BaseRef --> DefaultsOrCustom: non-implementation
-    ImplementationExtras --> DefaultsOrCustom
-    DefaultsOrCustom --> WorkersOverride: non-implementation analyser roster
-    WorkersOverride --> Confirm: defaults
-    DefaultsOrCustom --> ModelAndOptionalInputs: customize
-    ModelAndOptionalInputs --> Confirm
+    BaseRef --> LeaderSession: non-implementation
+    ImplementationExtras --> LeaderSession
+    LeaderSession --> RoleSlots: role-count then role-model
+    RoleSlots --> OptionalInputs: directive / related / clarification
+    OptionalInputs --> Confirm
     Confirm --> EditTarget: Edit
     EditTarget --> TaskType: rewind selected step
     Confirm --> Done: Proceed
 ```
 
-A new task receives its brief first. If the brief frontmatter has `task-group:` and `brief-id:`, the wizard shows the task group/id as recommended picks. An existing task shows the manifest's `workflow.nextRecommendedPhase` as the recommended task-type, and if an existing brief path exists it asks whether to keep or change it.
+A new task receives its brief first. If the brief frontmatter has `task-group:` and `brief-id:`, the wizard shows the task group/id as recommended picks. An existing task shows the manifest's `workflow.nextRecommendedPhase.phase` as the recommended task-type, but only while that pointer's `status` is `ready`. Under any other status the recommended slot stays empty and the list falls back to rerunning `workflow.currentPhase` plus the full task-type choices. If an existing brief path exists it asks whether to keep or change it.
 
 ## 4. render-bundle and prepare_task_bundle
 
@@ -152,20 +151,18 @@ flowchart TD
     T[task-type selected] --> W{active worktree in registry?}
     W -->|yes| Reuse[reuse existing worktree<br/>base-ref prompt skipped]
     W -->|no| Base[ask base-ref<br/>validate with git rev-parse]
-    Base --> D{Use defaults?}
-    Reuse --> D
-    D -->|defaults| R{non-implementation<br/>has analyser roster?}
-    D -->|customize| M[lead/model/directive/related/clarification prompts]
-    R -->|yes| WO[worker multi-pick still shown]
-    R -->|no| Confirm
-    WO --> Confirm
-    M --> Special{release-handoff?}
+    Base --> L[leader session read-only]
+    Reuse --> L
+    L --> C[role-count min..max<br/>omit uses recommended]
+    C --> M[role-model provider/model per slot]
+    M --> O[directive / related / clarification]
+    O --> Special{release-handoff?}
     Special -->|yes| PR[PR template override/scope]
     Special -->|no| Confirm
     PR --> Confirm
 ```
 
-The important point is that `Use defaults` means the model defaults. For non-implementation task-types, the worker roster question still appears even if you choose defaults. Conversely, `implementation` has no worker override question; it uses the profile default roster and executor binding.
+Launch selection is role slots and model refs. The wizard does not show a provider roster multi-pick and does not fork on `Use defaults / Customize` for workers. Omitting `--role-count` keeps each static role at its profile **recommended** count within `min..max`. Duplicate model refs in the same role are rejected. `--workers` remains a CLI compatibility input only.
 
 Worktree rules differ per phase. From `requirements-discovery` through `implementation-planning`, the task-key worktree is reused. `implementation` uses the task-key worktree as an anchor but does the actual execution isolated one stage at a time in a stage-key (`stage-<N>`) worktree and the `runs/implementation/stage-<N>/` deliverables. `final-verification --stage N` reuses that implementation stage worktree as a read target, and whole-task mode auto-integrates the stage commits into the task-key worktree and then builds the verification target. The Stage Lifecycle Snapshot is a read-side view that does not change this storage structure.
 

package/docs/task-process/error-analysis.md

@@ -20,19 +20,18 @@ flowchart TD
     Start[/okstra-run/] --> Common[common task identity flow]
     Common --> Type[task-type = error-analysis]
     Type --> Worktree{active worktree exists?}
-    Worktree -->|yes| Defaults[Use defaults / Customize]
+    Worktree -->|yes| Leader[leader session read-only]
     Worktree -->|no| BaseRef[base-ref pick/text<br/>main recommended]
-    BaseRef --> Defaults
-    Defaults --> Workers[analysis worker multi-pick]
-    Workers --> D{Use defaults?}
-    D -->|yes| Confirm
-    D -->|customize| M[lead/worker model prompts]
-    M --> X[directive, related tasks, clarification]
-    X --> Confirm
+    BaseRef --> Leader
+    Leader --> RoleCount[role-count min..max<br/>omit uses recommended; skip if min==max]
+    RoleCount --> RoleModel[role-model provider/model per slot]
+    RoleModel --> RoleAdd[min=0 roles via role-add only<br/>default skip]
+    RoleAdd --> Extras[directive, related tasks, clarification]
+    Extras --> Confirm
     Confirm --> Render[render-bundle --render-only]
 ```
 
-The default required roster is `claude`, `codex`, `report-writer`. `antigravity` is an optional worker, and if selected it joins the analyser set.
+Launch selection uses role slots and model refs only: leader is the current session (read-only), then each static role's count in `min..max` (default **recommended**; the count step is skipped when `min == max`), then one `provider/model` per slot. Roles with `min = 0` stay closed unless the user opens them with role-add (default skip). Duplicate model refs in the same role are rejected. There is no provider roster multi-pick and no `Use defaults / Customize` fork. Dynamic verifiers are not chosen at launch. `--workers` is a CLI compatibility input only, not a launch picker.
 
 ## 3. prepare_task_bundle handling
 
@@ -57,7 +56,7 @@ sequenceDiagram
 
 For canonical briefs, preflight runs before worker resolution, worktree provisioning, or report creation. A brief whose `reporter-confirmations` status is `pending` stops at this point; legacy briefs keep the compatibility path.
 
-The final report records its next phase in `errorAnalysis.routing.nextTaskType`. After report validation passes, workflow metadata persists that route as `nextRecommendedPhase`. A credible cause uses `implementation-option-selection`; continued investigation uses `error-analysis`. The static fallback also routes a missing or legacy error-analysis report to option selection.
+The final report records its next phase in `errorAnalysis.routing.nextTaskType`. A credible cause uses `implementation-option-selection`; continued investigation uses `error-analysis`. When report validation passes, Phase 7 projects `workflow.nextRecommendedPhase` from that one field (`scripts/okstra_ctl/next_phase.py::project`) — a `ready` pointer naming it. A report that leaves the field empty leaves the pointer `pending`; there is no static fallback that supplies a phase the report did not author.
 
 ## 4. lead execution flow