okstra 0.146.1 → 0.148.0

package/docs/architecture.md

@@ -8,7 +8,7 @@
 
 ## At a glance
 
-`okstra` is a **task bundle preparation tool** for Claude Code's cross-verification workflow. It is not a single-file review tool. Instead, it organizes task briefs, profiles, prompts, run history, and project-level discovery metadata around a stable task key so Claude can reliably orchestrate lead and worker agents.
+`okstra` is a **host-aware task bundle preparation tool** for multi-provider cross-verification. It is not a single-file review tool. Instead, it organizes task briefs, profiles, prompts, run history, and project-level discovery metadata around a stable task key so the current host-native lead can orchestrate provider workers consistently.
 
 Its core capabilities at a glance are:
 
@@ -16,13 +16,13 @@ Its core capabilities at a glance are:
 - **Profiles by task type**: Loads standard task-type profiles such as `requirements-discovery`, `error-analysis`, `implementation-planning`, `implementation`, `final-verification`, and `release-handoff` to render the instruction set.
 - **Run lifecycle**: Non-stage runs use `runs/<task-type>/` as the run directory, while `implementation` and single-stage `final-verification` use `runs/<task-type>/stage-<N>/`. Manifests, prompts, state, reports, sessions, worker results, and logs accumulate beneath the resolved run directory, and the filename suffix `-<task-type>-<seq>` separates reruns of the same phase.
 - **Single python authority**: All prepare wiring—resolving profiles/workers/models, computing paths, rendering, and central record_start—is concentrated in a single function, [`okstra_ctl.run.prepare_task_bundle()`](../scripts/okstra_ctl/run.py). `okstra.sh` and the `okstra-run` skill are thin callers of that same function and do not pass state through environment variables. Task identity, paths, and workflow state are recalculated from authoritative on-disk files every time.
-- **Claude handoff (two modes)**: (a) the traditional mode, where `okstra.sh` launches a new `claude` process; and (b) in-session mode, where the `okstra-run` skill prepares the task in the current Claude session and hands the lead role to that session. Both use the outputs of `prepare_task_bundle`, including the instruction set, unchanged.
-- **Required team contract**: The `Required workers:` block in each phase profile is authoritative for the roster. General analysis phases use Claude/Codex analyzers plus a report writer by default, while Antigravity is included only when allowed by both the profile and `--workers`. Lead-oriented phases such as `release-handoff` have separate rosters.
-- **User-home install + project-local task bundles**: One `npx okstra@latest install` command installs the runtime (`~/.okstra/{lib/python, bin, templates, prompts}`) and installs public skills to `~/.agents/skills/` by default. If `~/.claude` exists, it also installs Claude skills and four worker agent definitions (`~/.claude/agents/*-worker.md`). Only user entry-point skills are exposed in the skill list; lead/support operating contracts are installed as runtime resources under `~/.okstra/prompts/` and are not discoverable as skills. Global conversation memory is stored separately from projects under `~/.okstra/memory-book/`. Task bundles and discovery metadata are stored under `.okstra/` in the target project. **In addition, `<PROJECT_ROOT>/.claude/settings.local.json` is provisioned as a symlink to `~/.okstra/templates/settings.local.json`** (`okstra setup` or `okstra-ctl` prepare manages it idempotently; if a regular file already existed, it is preserved as `.bak.<timestamp>` before replacement).
+- **Host-aware handoff**: Claude Code, Codex, and Antigravity keep their current native session as the lead. The standalone compatibility launcher still starts a new `claude` process by default, while the external adapter uses registered CLI wrappers. Every path consumes the same `prepare_task_bundle` outputs.
+- **Required team contract**: The `Required workers:` block in each phase profile is authoritative for the roster. General analysis phases use Claude/Codex analysers plus a report writer by default, while Antigravity, Grok, and Kimi are included only when allowed by both the profile and `--workers`. Lead-oriented phases such as `release-handoff` have separate rosters.
+- **User-home install + project-local task bundles**: One `npx okstra@latest install` command installs the runtime (`~/.okstra/{lib/python, bin, templates, prompts}`) and installs public skills to `~/.agents/skills/` by default. If `~/.claude` exists, it also installs Claude skills and six worker agent definitions (`~/.claude/agents/*-worker.md`). Only user entry-point skills are exposed in the skill list; lead/support operating contracts are installed as runtime resources under `~/.okstra/prompts/` and are not discoverable as skills. Global conversation memory is stored separately from projects under `~/.okstra/memory-book/`. Task bundles and discovery metadata are stored under `.okstra/` in the target project. **In addition, `<PROJECT_ROOT>/.claude/settings.local.json` is provisioned as a symlink to `~/.okstra/templates/settings.local.json`** (`okstra setup` or `okstra-ctl` prepare manages it idempotently; if a regular file already existed, it is preserved as `.bak.<timestamp>` before replacement).
 - **Resume and clarification**: Supports resuming the same task and responding to follow-up questions from the lead through `--task-key`, `--resume-clarification`, and `--clarification-response`.
-- **Derived views and telemetry**: Provides final-report data.json → Markdown → Report View Model → self-contained HTML view, worker error sidecars, wrapper log sidecars, and token-usage/cost accounting.
+- **Dual-audience derived views and telemetry**: For schema v2, derives AI handoff Markdown and task-specific human-facing HTML independently from the same v2 data.json. Schema v1 and quick Markdown reports keep their compatibility renderer. Worker error sidecars, wrapper log sidecars, and token-usage/cost accounting remain separate audit inputs.
 
-Claude lead owns judgment policy and worker orchestration. `okstra` focuses on preparing the structured input bundle and output skeleton Claude needs to work reliably.
+The host-native Okstra lead owns judgment policy and worker orchestration. `okstra` prepares one runtime-neutral task bundle and resolves every provider assignment to either the current native session or a registered CLI wrapper.
 
 ## Table of contents
 
@@ -30,8 +30,8 @@ Claude lead owns judgment policy and worker orchestration. `okstra` focuses on p
 - [What okstra does](#what-okstra-does)
 - [Runtime assets vs support assets](#runtime-assets-vs-support-assets)
 - [Architecture: python authority + thin callers](#architecture-python-authority--thin-callers)
-- [Claude execution behavior](#claude-execution-behavior)
-- [Claude prompt contract](#claude-prompt-contract)
+- [Host runtime execution behavior](#host-runtime-execution-behavior)
+- [Lead prompt contract](#lead-prompt-contract)
 - [Required team contract](#required-team-contract)
 - [Stable task identity](#stable-task-identity)
 - [Project self-registration](#project-self-registration)
@@ -42,7 +42,7 @@ Claude lead owns judgment policy and worker orchestration. `okstra` focuses on p
 - (See [cli.md](cli.md) for CLI arguments, options, and interactive input)
 - [Storage model & contracts](#storage-model--contracts) → [`architecture/storage-model.md`](architecture/storage-model.md)
   - Stable task root / per-run artifacts / `~/.okstra` indexes
-  - Task manifest · task index · run manifest · timeline · Claude operating contract
+  - Task manifest · task index · run manifest · timeline · runtime-neutral operating contract
 - [Task brief usage](#task-brief-usage)
 - [Recommended workflow](#recommended-workflow)
   - [1. Write a draft](#1-write-a-draft)
@@ -68,10 +68,10 @@ Claude lead owns judgment policy and worker orchestration. `okstra` focuses on p
 ## Purpose
 
 This document is a task-key-oriented operations guide to using `okstra` in `Okstra`.
-Where `README.md` is the quick entry point, this document is the detailed reference for `okstra`'s execution contract, storage model, lifecycle, and Claude handoff rules.
+Where `README.md` is the quick entry point, this document is the detailed reference for `okstra`'s execution contract, storage model, lifecycle, and host handoff rules.
 
 `okstra` is not a single-file review tool.
-`okstra` is a supporting tool that prepares stable task bundles, run history, and project-level discovery metadata so Claude Code can perform cross-verification.
+`okstra` is a supporting tool that prepares stable task bundles, run history, and project-level discovery metadata so a supported host can perform cross-verification.
 
 ## What okstra does
 
@@ -80,11 +80,11 @@ okstra's prepare responsibilities are consolidated in a single Python entry poin
 - Verifies that okstra installation assets exist (`~/.agents/skills/okstra-*`, optional `~/.claude/skills/okstra-*` / `~/.claude/agents/*-worker.md`, `~/.okstra/bin/...`)
 - Self-registers `<PROJECT_ROOT>/.okstra/project.json` (or verifies that the projectId matches)
 - Loads task type → `prompts/profiles/<task-type>.md` and extracts recommended workers
-- Normalizes user worker/model overrides (display ↔ execution-value mapping for Claude/Codex/Antigravity/Report-writer)
+- Normalizes user worker/model overrides through the provider registry (Claude, Codex, Antigravity, Grok, Kimi, and report-writer-capable providers)
 - Resolves task-brief / clarification-response paths (cwd first → PROJECT_ROOT fallback)
 - Computes the stable task root and all paths/sequences inside a per-task mutex (`~/.okstra/.locks/<task-key>.lock`), then persists them to `<run-dir>/manifests/run-context-<seq>.json`
 - Persists user input to `<run-dir>/manifests/run-inputs-<seq>.json`
-- Renders the instruction set (`analysis-profile.md`, `analysis-packet.md`, `analysis-material.md`, `task-brief.md`, `reference-expectations.md`, `final-report-template.md`, `final-report-schema.json`, optional `clarification-response.md`, optional `directive.txt`, final-verification-only `verification-target.md`, `claude-execution-prompt.md`) and writes a run prompt snapshot
+- Renders the instruction set (`analysis-profile.md`, `analysis-packet.md`, `analysis-material.md`, `task-brief.md`, `reference-expectations.md`, `final-report-template.md`, `final-report-schema.json`, optional `clarification-response.md`, optional `directive.txt`, final-verification-only `verification-target.md`, canonical `lead-execution-prompt.md`, and its Claude-named compatibility alias) and writes a run prompt snapshot
 - Updates `task-manifest.json`, `task-index.md`, `run-manifest-*.json`, `history/timeline.json`, and `discovery/{latest-task,task-catalog}.json`
 - Writes a preassigned Claude session ID and `sessions/claude-resume-*.sh` (unless `--render-only` is used)
 - Records record_start in the central indexes (`~/.okstra/{active,recent}.jsonl`, `projects/<id>/{index.jsonl, meta.json}`)
@@ -92,9 +92,9 @@ okstra's prepare responsibilities are consolidated in a single Python entry poin
 The two callers of `prepare_task_bundle` are:
 
 1. **`scripts/okstra.sh`**: Parses and confirms CLI arguments → calls `prepare_task_bundle` → unless `--render-only` is used, launches `claude --model ... --session-id ... "$PROMPT"` via `exec`. It is a thin wrapper of about 160 lines.
-2. **`okstra-run` skill**: Runs the [`okstra_ctl.wizard`](../scripts/okstra_ctl/wizard.py) state machine (`okstra wizard init|step|...` CLI) in the same Claude session to collect user input → calls `okstra render-bundle` (that is, `prepare_task_bundle(render_only=True)`) → the current session reads the rendered lead prompt and assumes the lead role. It does not launch a new Claude process. The wizard decides all branching, validation, and ordering, so the skill body is a roughly 30-line loop that displays either `AskUserQuestion` (`pick`) or a plain-text message (`text`) according to `Prompt.kind`.
+2. **`okstra-run` skill**: Runs the [`okstra_ctl.wizard`](../scripts/okstra_ctl/wizard.py) state machine (`okstra wizard init|step|...` CLI) in the current supported host to collect user input → calls `okstra render-bundle` (that is, `prepare_task_bundle(render_only=True)`) → the current session reads the rendered lead prompt and assumes the lead role. It does not launch a new provider process for the native lead. The wizard decides all branching, validation, and ordering, so the skill body displays either the host's picker (`pick`) or a plain-text message (`text`) according to `Prompt.kind`.
 
-The lead Claude owns judgment policy and worker orchestration. okstra's prepare stage only creates structured assets so that the lead starts with the correct input bundle and output skeleton.
+The host-native Okstra lead owns judgment policy and worker orchestration. okstra's prepare stage only creates structured assets so that the lead starts with the correct input bundle and output skeleton.
 
 ## Runtime assets vs support assets
 
@@ -127,7 +127,7 @@ Runtime entry points are consolidated in Python packages. Bash and skills only c
 
 ### Bash entry points (thin)
 
-- [`scripts/okstra.sh`](../scripts/okstra.sh) — CLI parsing / interactive prompt / confirm-execution-plan / `prepare_task_bundle` invocation / `exec claude`.
+- [`scripts/okstra.sh`](../scripts/okstra.sh) — standalone compatibility launcher: CLI parsing / interactive prompt / `prepare_task_bundle` invocation / default `exec claude`. In-host Claude Code, Codex, and Antigravity runs use `okstra-run` and keep their current native session.
 - [`scripts/lib/okstra/{cli,globals,interactive,project-resolver,usage}.sh`](../scripts/lib/okstra/) — CLI/interactive support only; contains no artifact-generation logic.
 - [`scripts/okstra-ctl.sh`](../scripts/okstra-ctl.sh) + [`scripts/lib/okstra-ctl/`](../scripts/lib/okstra-ctl/) — central control-center CLI (list / show / open / rerun / reconcile / etc.).
 
@@ -135,7 +135,7 @@ Runtime entry points are consolidated in Python packages. Bash and skills only c
 
 - `prompts/launch.template.md` — lead prompt template.
 - `prompts/profiles/*.md` — ten task-type profiles: the six lifecycle profiles (`requirements-discovery`, `error-analysis`, `implementation-planning`, `implementation`, `final-verification`, `release-handoff`) plus `improvement-discovery`, `project-analysis`, `feature-analysis`, and `change-impact-analysis` sidetracks.
-- `templates/project-docs/task-index.template.md` · `templates/reports/final-report.template.md` · `templates/reports/settings.template.json` — runtime render inputs.
+- `templates/project-docs/task-index.template.md` · `templates/reports/final-report.template.md` · `templates/reports/final-report-v2.template.md` · `templates/reports/html/` · `templates/reports/settings.template.json` — runtime render inputs. The unversioned Markdown template is the schema v1 compatibility template; the v2 Markdown and task-specific HTML trees are separate audiences.
 - `<PROJECT_ROOT>/.okstra/project.json` — project self-registration. Created/verified automatically on the first okstra.sh run; when `--project-root` is omitted, PROJECT_ROOT is resolved through ancestors / `git toplevel`.
 
 ### Support assets (not referenced at runtime)
@@ -146,10 +146,11 @@ Runtime entry points are consolidated in Python packages. Bash and skills only c
 ### Skills (`skills/`) and lead resources (`prompts/`)
 
 - [`prompts/lead/okstra-lead-contract.md`](../prompts/lead/okstra-lead-contract.md) is the runtime-neutral lifecycle core: phase boundaries, artifacts, convergence, report ownership, and persistence semantics.
-- `prompts/lead/adapters/claude-code.md`, `prompts/lead/adapters/codex.md`, and `prompts/lead/adapters/external.md` map the same semantic operations to one selected host runtime. The generated launch prompt exposes the core path plus exactly one adapter path.
-- Runtime selection and worker-provider assignment remain independent. Milestone 1 keeps `claude-execution-prompt.md`, existing manifest role labels, model defaults, and worker rosters for compatibility; provider registry and front-door separation are later milestones.
+- `prompts/lead/adapters/claude-code.md`, `prompts/lead/adapters/codex.md`, `prompts/lead/adapters/antigravity.md`, and `prompts/lead/adapters/external.md` map the same semantic operations to one selected host runtime. The generated launch prompt exposes the core path plus exactly one adapter path.
+- Runtime metadata and role assignments are persisted separately, but the lead provider is derived from the host: Claude Code maps to Claude, Codex maps to Codex, and Antigravity CLI maps to Antigravity. New runs persist `hostRuntime`, `leadAssignment`, and `workerAssignments[]`; each assignment records its provider, model, execution value, and resolved `native-session` or `cli-wrapper` runner. `lead-execution-prompt.md` is canonical, while `claude-execution-prompt.md` is a byte-identical compatibility alias for historical consumers.
+- Provider registry and front-door separation are implemented: the active Claude Code, Codex, or Antigravity host owns the native lead session, while non-host providers run through their registered CLI wrappers.
 - [`skills/okstra-setup/SKILL.md`](../skills/okstra-setup/SKILL.md) — **first-run bootstrap**. Runs `okstra install` and creates `project.json`.
-- [`skills/okstra-run/SKILL.md`](../skills/okstra-run/SKILL.md) — in-session entry point that **starts an okstra task in the current Claude session**. Calls `prepare_task_bundle` directly.
+- [`skills/okstra-run/SKILL.md`](../skills/okstra-run/SKILL.md) — host-aware in-session entry point that starts an okstra task in the current Claude Code, Codex, or Antigravity session and calls `prepare_task_bundle` directly.
 - Thirteen skills are user-invocable: `skills/okstra-setup/SKILL.md`, `skills/okstra-brief-gen/SKILL.md`, `skills/okstra-run/SKILL.md`, `skills/okstra-manager/SKILL.md`, `skills/okstra-memory/SKILL.md`, `skills/okstra-inspect/SKILL.md`, `skills/okstra-rollup/SKILL.md`, `skills/okstra-usage/SKILL.md`, `skills/okstra-schedule-gen/SKILL.md`, `skills/okstra-container-build/SKILL.md`, `skills/okstra-pr-gen/SKILL.md`, `skills/okstra-user-response/SKILL.md`, and `skills/okstra-code-review/SKILL.md`. Only these are copied into the agent skill home. They cover brief authoring, phase execution, cross-project manager task coordination, global Memory Book storage/search, read-side status/history/report/time/logs/cost/errors/recap, task-group-level aggregation of run results (rollup), project-wide historical resource usage, schedule support, local container deployment, PR description generation, clarification-response submission, and census-based code review of a stage or branch diff. `okstra-manager` uses `okstra manager` CLI JSON/launch packets as the source of truth, and stores manager-owned plans, assignments, directives, snapshots, and events under `~/.okstra/managers/<manager-id>/`. `okstra-rollup` is a read-side layer that fans the single-task aggregators from `okstra-inspect` (time/errors/recap) out to a task group or the whole project catalog. The `okstra rollup` CLI owns deterministic aggregation, while the skill (LLM) writes only the synthesized report summary. `okstra-usage` is a separate read-only resource snapshot grouped by lifecycle task type; it does not replace single-task `okstra-inspect` detail or the status/report digest from `okstra-rollup`. The canonical definition of `okstra-inspect` read-side facets is the subcommand table in `skills/okstra-inspect/SKILL.md`. `okstra-inspect logs` provides a read-only inventory and cleanup guidance for the live-log sidecars that the Codex/Antigravity wrappers write on every dispatch at the resolved `<run-dir>/prompts/<worker>-prompt-<phase>-<seq>.log`; for stage executions, the stage-qualified `run_dir` includes `stage-<N>/`. `okstra-inspect cost` summarizes `okstra context-cost`; `okstra-inspect errors` collects a task's okstra-run error logs into a timestamped Markdown error report and prints a summary; and `okstra-inspect recap` answers free-form questions about `.okstra` artifacts in addition to summarizing phases before and after each task run.
 - Internal operating contracts—`context-loader` / `team-contract` / `convergence` / `report-writer` and the lead contract—have moved to `prompts/lead/*.md`. Language-specific coding preflight for implementation/verification workers has moved to `prompts/coding-preflight/*` (overview router + clean-code + three-stage language/framework/architecture selection). All are runtime resources installed under `~/.okstra/prompts/` and are not discoverable as skills. The generated launch prompt provides the lead with absolute paths, and reinstalling prunes the legacy exact-name skill directories `okstra-context-loader` / `okstra-team-contract` / `okstra-convergence` / `okstra-report-writer` / `okstra-coding-preflight` / `okstra`.
 - Plugin manifest: [`../../.claude-plugin/plugin.json`](../.claude-plugin/plugin.json) — referenced by the supplementary `npx skills@latest add Devonshin/okstra` channel. Use `npx okstra@latest install` for normal setup. The plugin manifest exposes only the thirteen user entry points (`okstra-setup`, `okstra-brief-gen`, `okstra-run`, `okstra-manager`, `okstra-memory`, `okstra-inspect`, `okstra-rollup`, `okstra-usage`, `okstra-schedule-gen`, `okstra-container-build`, `okstra-pr-gen`, `okstra-user-response`, `okstra-code-review`).
@@ -259,47 +260,48 @@ The following environment variables are read only as user settings, not for stat
 
 Other variables such as `PROJECT_ID`, `TASK_GROUP`, `RUN_*`, `FINAL_*`, and `CLAUDE_*` are not exported and do not leak into child processes.
 
-## Claude execution behavior
+## Host runtime execution behavior
 
-In the current implementation, `okstra` executes Claude as follows.
+The front door declares its host from harness context, never by looking for installed provider binaries. Claude Code selects the Claude native session; Codex selects the Codex native session. Other selected providers resolve to CLI wrappers. A lead provider that disagrees with an in-session host is rejected before dispatch so the manifest cannot claim a model that never ran.
+
+The legacy standalone shell path remains Claude-specific:
 
 **Mode A — `okstra.sh` launches a new Claude process**
 - With `--render-only`, it exits after creating the instruction set without running Claude.
 - Without `--render-only`, the prepare stage preassigns a Claude session ID and creates `claude-resume-<task-type>-<seq>.sh` under the current run's `sessions/` directory.
-- It then runs `claude --model <lead> --session-id "$CLAUDE_SESSION_ID" "$PROMPT"` via `exec` from the target project root using the resolved `Claude lead` model execution value. (The former `--settings <runtime-settings>` argument was removed in 0.14.0; permissions are now provided by the `<PROJECT_ROOT>/.claude/settings.local.json` symlink.)
-- `okstra.sh` performs only the handoff; the Claude lead continues by saving the final report and updating run/task state.
+- It then runs `claude --model <lead> --session-id "$CLAUDE_SESSION_ID" "$PROMPT"` via `exec` from the target project root using the standalone launcher's resolved Claude lead model. (The former `--settings <runtime-settings>` argument was removed in 0.14.0; permissions are now provided by the `<PROJECT_ROOT>/.claude/settings.local.json` symlink.)
+- `okstra.sh` performs only this compatibility handoff; the launched session continues under the same Okstra lead contract. Codex-hosted runs do not pass through this shell path.
 
-**Mode B — the `okstra-run` skill hands off within the current Claude session**
-- Use this when the user is already in a Claude session and wants to start a new okstra task there.
-- The skill collects task candidates, task type, brief, and other input through `AskUserQuestion`, then calls `prepare_task_bundle(render_only=True)` to create the same instruction set on disk.
-- It does not launch a new Claude process. The current session reads the rendered lead prompt and immediately assumes the lead role.
+**Mode B — the `okstra-run` skill hands off within the current host session**
+- Use this when the user is already in Claude Code, Codex, or Antigravity and wants to start a new okstra task there.
+- The skill relays the wizard through the host question/text interface and calls `prepare_task_bundle(render_only=True)` with the explicit host runtime.
+- It does not launch another lead process. The current host-native session reads `lead-execution-prompt.md` and assumes the Okstra lead role.
 
 Both modes create identical artifacts (task-manifest, run-manifest, timeline, instruction set, and central-index registration), so subsequent `okstra-ctl` commands (list / show / rerun / reconcile) operate consistently without distinguishing between them.
-- The handed-off main Claude acts as the `Claude lead`, responsible for orchestration and final synthesis.
-- The default worker roles for the standard workflow are `Claude worker`, `Codex worker`, and `Report writer worker`; `Antigravity worker` is optional and is included only when explicitly requested through `--workers` or the profile.
-- Claude assigns worker responsibilities and makes the final judgment after reading the task bundle.
+- The handed-off native host acts as the Okstra lead, responsible for orchestration and final synthesis.
+- The default worker policy remains Claude + Codex analysis and a Claude report writer. Antigravity, Grok, and Kimi are profile-gated optional assignments; Grok and Kimi are read-only analyser/critic providers.
+- The lead assigns worker responsibilities and makes the final judgment after reading the task bundle.
 - okstra Claude assets installed in the user home (`~/.claude/skills`, `~/.claude/agents`) instruct Claude to dispatch workers through `Agent(name: ...)`; workers automatically join the session's implicit team.
 - **Team lifecycle (Claude Code v2.1.178+)**: v2.1.178 removed the `TeamCreate` / `TeamDelete` tools and the `team_name` parameter from `Agent(...)`. When `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` (seeded into `settings.json` by `okstra install`), one implicit team per session is created automatically at startup. In Phase 3, the lead does not call a team-creation tool. It records only the `teamName` audit label and `teamCreate: { attempted: false, status: "implicit", splitPane: <true-if-TMUX-is-set> }`, then dispatches workers through `Agent(name: "<role>-worker", run_in_background: true)` (without team_name). Split-pane teammates appear when `$TMUX` is set and `teammateMode: auto`; outside tmux they run in-process, and both modes are valid. At run end, after Phase 7 token accounting, the lead checks for remaining tmux panes and asks whether to clean up worker teammates only for split-pane runs. If approved, `okstra-team-reconcile.sh` marks dead-pane stale-active members inactive and sends each completed teammate a `SendMessage` shutdown_request. There is no tool for deleting the implicit team; it disappears when the session ends. If the user keeps the teammates, they remain in the FleetView roster and the lead tells the user to remove them through Teams/FleetView (see *Run-end teammate teardown* in `prompts/profiles/_common-contract.md`). Phase 7 token accounting locates worker sessions by top-level `agentName` or nested `subagents/agent-a<name>-<hash>.jsonl` filenames when `teamCreate.status` is `implicit`/`skipped`/`error`.
 
-## Claude prompt contract
+## Lead prompt contract
 
-The Claude launch prompt body is always rendered only from the `prompts/launch.template.md` template.
+The canonical lead prompt body is rendered from `prompts/launch.template.md` to `lead-execution-prompt.md`. A selected runtime adapter maps its neutral operations to host primitives.
 
 - Prompt substitution is limited to scalar placeholder values such as the task key, session ID, and absolute/relative paths.
 - The selected profile body is rendered to `instruction-set/analysis-profile.md`.
 - The analysis material body is rendered to `instruction-set/analysis-material.md`.
 - The expected state for config/deployment is rendered to `instruction-set/reference-expectations.md`.
-- Claude must read these artifact files directly; long task-specific bodies must not be duplicated inline in the launch prompt.
+- The lead must read these artifact files directly; long task-specific bodies must not be duplicated inline in the launch prompt.
 
 ## Required team contract
 
 The standard `okstra` workflow applies the following team contract consistently across runtime prompts, profiles, manifests, and skill documentation.
 
-- The main Claude is always the `Claude lead` and operates in synthesis-only mode.
-- The default required worker roles are `Claude worker`, `Codex worker`, and `Report writer worker`. `Antigravity worker` is optional and is included as required only when explicitly named by `--workers` or the profile's `- Workers:` section.
-- `Report writer worker` focuses on report structure and evidence organization, but `Claude lead` remains the final synthesis owner.
-- The default model contract is computed from central defaults. Fallbacks are `Claude lead`=`opus`, `Claude worker`=`opus`, `Codex worker`=`gpt-5.6-sol`, `Report writer worker`=`sonnet`, and `Antigravity worker`=`gemini-3.1-pro` (when opted in). `Report writer worker` no longer inherits the `Claude lead` model — it resolves from its own catalog `ROLE_DEFAULTS` entry because it does not vote in convergence; `--report-writer-model opus` or `OKSTRA_DEFAULT_REPORT_WRITER_MODEL` restores the previous behavior.
-- Because `Antigravity worker` is optional, it is attempted only in runs where it is explicitly included.
+- The current host-native provider owns the synthesis-only lead session: Claude on Claude Code, Codex on Codex.
+- Every selected worker comes from the profile roster and provider capability registry. The default analysis policy remains Claude + Codex + a report writer; Antigravity, Grok, and Kimi are attempted only when the profile and resolved roster include them.
+- `Report writer worker` focuses on report structure and evidence organization, while the host-native lead remains the final synthesis owner. Claude is the default report-writer provider; Codex may be selected explicitly.
+- Model defaults are provider and functional-role policy. Fallbacks include Claude lead/analyser=`opus`, Codex lead/analyser=`gpt-5.6-sol`, Claude report writer=`sonnet`, Antigravity=`gemini-3.1-pro`, Grok analyser=`grok-build-0.1`, and Kimi analyser=`kimi-k2.7-code`.
 - Before the final judgment, each required role in the current run's worker roster must have either a result or an explicit terminal status (`completed`, `timeout`, `error`, `not-run`).
 - Every attempted worker (`completed`, `timeout`, `error`) must have an assigned worker prompt history file under the current run's `prompts/` directory.
 - Worker timing begins at the atomic transition to `in-progress`, which records `workers[].startedAt` in `team-state.json`; prompt creation time is not a dispatch proxy. `okstra worker-state transition` and both dispatch adapters share `dispatch_state.transition_worker_status`, while `okstra worker-liveness --team-state ... --worker ...` reads that timestamp as the launch-grace authority.
@@ -595,17 +597,17 @@ There are two entry methods, and they produce identical artifacts.
 scripts/okstra.sh --task-type error-analysis --project-id <project-id> --task-group <task-group> --task-id <task-id> --task-brief <brief-path>
 ```
 
-On this path, `okstra.sh` finishes the prepare stage and then runs a new interactive Claude session via `exec` from the target project root. It performs only the handoff; the Claude lead continues by saving the final report. Because `sessions/claude-resume-<task-type>-<seq>.sh` is written immediately before execution, the same run can be resumed if the session is interrupted.
+On this standalone compatibility path, `okstra.sh` finishes the prepare stage and then runs a new interactive Claude session via `exec` from the target project root. It performs only the handoff; the session continues under the Okstra lead contract. Because `sessions/claude-resume-<task-type>-<seq>.sh` is written immediately before execution, the same run can be resumed if interrupted. In-host Claude Code, Codex, and Antigravity paths retain the current native session instead.
 
-**Option B — hand off within the current Claude session (`okstra-run` skill)**
+**Option B — hand off within the current host session (`okstra-run` skill)**
 
-If you are already using a Claude Code session, the current session can assume the Claude lead role without launching a new process. Example triggers: `"run okstra here"`, `"start error-analysis on this project"`.
+If you are using Claude Code, Codex, or Antigravity, the current native session assumes the Okstra lead role without launching a replacement lead process. Example triggers: `"run okstra here"`, `"start error-analysis on this project"`.
 
 Skill flow:
 
-1. The `okstra-run` skill activates and collects task candidates / task type / brief path with `AskUserQuestion`.
+1. The `okstra-run` skill activates and relays task candidates, task type, and brief path through the current host's question or text interface.
 2. It calls `okstra_ctl.run.prepare_task_bundle(render_only=True)` with the user's input—directly invoking the same Python function without passing through `okstra.sh`.
-3. After the same instruction-set artifacts are written to disk, the current Claude reads the prompt and assumes the lead role.
+3. After the same instruction-set artifacts are written to disk, the current host reads the canonical lead prompt and assumes the lead role.
 
 See [`skills/okstra-run/SKILL.md`](../skills/okstra-run/SKILL.md) for the detailed procedure.
 
@@ -733,8 +735,12 @@ Resume decision rules:
 
 ## Final report structure
 
-The default final report template is `templates/reports/final-report.template.md`.
-Final reports written by Claude should use the following structure unless the brief's augmentation requires a more specific format.
+New task bundles use `schemas/final-report-v2.0.schema.json` as the final-report data contract. The report writer authors one data.json source of truth, including the required `humanSummary` and exactly one task-type deliverable. Two renderers consume it independently:
+
+- `templates/reports/final-report-v2.template.md` produces compact AI handoff Markdown in a fixed order: handoff summary, clarifications, evidence ledger, one task deliverable, cross-verification audit, execution audit, and token/cost audit. Human narrative fields are excluded from this artifact.
+- `templates/reports/html/tasks/<task-type>.template.html` produces the task-specific human-facing HTML. It leads with a plain-language decision summary and presents the selected task's findings, diagrams, tables, evidence, and actions. Worker execution and convergence detail stays in a visually subordinate audit section.
+
+The legacy schema v1 contract remains supported by `schemas/final-report-v1.0.schema.json` and `templates/reports/final-report.template.md`. Its Markdown structure is:
 
 - `## Verdict Card` — **mandatory top section**. Five rows: Final Conclusion / Verdict Token / Direction / Approval Required? / Next Step. The Verdict Token / Direction / Next Step cells must byte-match the authoritative cells in body §2 (execution status) and §6 (next steps).
 - (Optional) `## Reader Summary` — a five-row table rendered immediately below the Verdict Card only when data.json has `readerSummary`: decision (`decision`) / action required from a human (`humanActionRequired`) / blocking items (`blockingItems`) / safe-to-skip items (`safeToSkip`) / recommended command (`recommendedCommand`). When present, all five fields are required (schema `required`), and it contains only a summary rather than repeating raw evidence tables. Older data.json files without it continue to render unchanged.
@@ -756,28 +762,30 @@ Write the actual Markdown report body to the file instead of metadata about save
 
 ## Final report views (HTML)
 
-The Phase 7 `render-views` step deterministically generates a self-contained HTML view from a single final-report MD input. The lead reaches it through `okstra report-finalize`, which runs the whole Phase 7 sequence (`scripts/okstra_ctl/report_finalize.py` — shared with the Codex lead adapter).
+The Phase 7 `render-views` step accepts either a final-report data.json or its Markdown sibling. For schema v2, it locates and validates `final-report-<task-type>-<seq>.data.json`, selects the task type fail-closed, and renders HTML directly from the structured data. It does not parse the AI Markdown back into a human model. The lead reaches this step through `okstra report-finalize`, which owns the shared Phase 7 sequence in `scripts/okstra_ctl/report_finalize.py`.
 
-- `reports/final-report-<task-type>-<seq>.html` — self-contained HTML for human reviewers. CSS / JS are embedded inline (zero external URLs), with system-color dark mode, sticky header, and print support. Reviewers can fill in decision inputs for §1 `C-*` rows—checkboxes, selects, and textareas—in the browser, then generate sidecar Markdown with the `Export user response` button.
-- **Reader Summary dashboard + reader mode**: Renders a top-level dashboard based on `readerSummary` (falling back to `verdictCard` when absent) and offers `Action` / `Audit` / `Full` reader-mode toggles. The default is `Action`, which shows only Reader Summary / Verdict Card / Clarification Items / Recommended Next Steps / Follow-up Tasks. Audit sections such as Evidence, Cross Verification, Execution Status, Token Usage, Plan Body Verification, and Round History are expanded in `Audit` / `Full`.
+- `reports/final-report-<task-type>-<seq>.html` — always generated for schema v2 with one of ten dedicated task templates. It includes an accessible summary, task-specific prose, tables and inline SVG diagrams, evidence references, decisions, and next actions. CSS / JS are embedded inline with no external assets; print and no-JavaScript fallback content preserve the essential information.
+- **Human summary**: `humanSummary` is the sole v2 top-level human summary contract. It is not copied into AI Markdown. Each task view decides how to present it together with the task deliverable instead of sharing a generic dashboard body.
+- **Audit isolation**: worker execution, convergence, and token/cost material remain available for traceability but are subordinate to the user's findings and decisions. They never replace the task analysis narrative.
+- **Schema v1 compatibility**: existing v1 data and quick Markdown reports keep the legacy conditional renderer, including `readerSummary`, reader modes, and the original Markdown-parsing path.
 - **`C-*` select option order**: The `Recommended:` answer from `Expected form` is always the **first option**, followed by the `Alternatives:` items relabelled consecutively as `(a)`, `(b)`, and so on (the original character labels are not retained).
 
 Entry points:
 
-- Single Python reference: `scripts/okstra_ctl/report_views.py` (`build_report_view_model(...)`, `render_report_view_model(..., css, js)`, `render_html(..., css, js)`, `serialize_user_response(...)`). The HTML JavaScript function `buildUserResponseMarkdown` is **byte-identical** to Python `serialize_user_response` (automatically verified by a Node `vm.runInThisContext` unit test).
-- CLI: `scripts/okstra-render-report-views.py <final-report.md>` or delegated Node wrapper `bin/okstra render-views <md>`.
-- Validation: `validators/validate-report-views.py` checks form-control placement in the HTML, absence of external URLs, stale source digests, and Response ID parity (`C-*` ↔ HTML).
+- Python routing references: `scripts/okstra_ctl/report_views.py` owns the version split; `scripts/okstra_ctl/report_html/router.py` maps all v2 task types to dedicated view-model builders and templates. The HTML JavaScript response serializer remains byte-identical to Python `serialize_user_response`.
+- CLI: `scripts/okstra-render-report-views.py <final-report.data.json|final-report.md>` or delegated Node wrapper `bin/okstra render-views <path>`.
+- Validation: `validators/validate-report-views.py` checks schema/source/template digests, required human fields, form controls, external assets, SVG/table ID parity, and Response ID parity. The v2 renderer rejects an unknown task type instead of falling back to a generic page.
 - User-response sidecar schema source of truth: `templates/reports/user-response.template.md`.
 
 Generating a view never modifies the original final-report MD.
 
 ## Worker error collection (optional sidecar)
 
-Errors that occur while workers (Claude/Codex/Antigravity worker, Report writer, Claude lead) run can be collected into a single chronological log for later retrospectives.
+Errors that occur while provider workers, the report writer, or the Okstra lead run can be collected into a single chronological log for later retrospectives.
 
 - Storage location: resolved `<run-dir>/logs/errors-<task-type>-<seq>.jsonl` (`<run-dir>` includes `stage-<N>/` for a stage-isolated run)
 - Append-only JSON Lines, isolated per run, so there is no separate rotation policy.
-- **Single writer**: To avoid concurrent-append collisions, only the `Claude lead` writes this file directly. `<seq>` is an independent three-digit zero-padded counter (`001`, `002`, …) scanned per category directory (`logs/`, `manifests/`, `state/`, and so on), so category values may differ within one run when a prior run recorded only some categories. The cross-category identifier for one run is the manifest's `runDateTimeSegment` ISO timestamp field.
+- **Single writer**: To avoid concurrent-append collisions, only the active Okstra lead writes this file directly. `<seq>` is an independent three-digit zero-padded counter (`001`, `002`, …) scanned per category directory (`logs/`, `manifests/`, `state/`, and so on), so category values may differ within one run when a prior run recorded only some categories. The cross-category identifier for one run is the manifest's `runDateTimeSegment` ISO timestamp field.
   - Internal worker tool failures are reported in the worker-result manifest's `errors[]`, then dumped by the lead immediately after merge
   - Codex/Antigravity CLI failures, timeouts, and rate limits are observed directly by the lead through the wrapper
   - resultContract violations, schema mismatches, and missing required fields are observed directly during lead validation
@@ -826,7 +834,7 @@ Tokens used in each run are collected from lead/worker session transcripts and w
 Entry points that enforce whether phase artifacts may be published:
 
 - `validators/validate-workflow.sh` — integrated phase-contract validation.
-- `validators/validate-run.py` — run-level final-report body contract: requires a Verdict Card; enforces evidence anchors in all four `rationale` fields (`_validate_rationale_evidence`); rejects deprecated §6.1/§6.2/§5.5.8/§5.5.9 Open Questions; cross-checks Plan Body Verification gate × Approval markers; blocks Token Usage sentinel/zero values; requires worker-result audit sidecars; requires the incremental re-verification audit block (`_check_incremental_audit_block`—when data.json has `incrementalDecision.mode == "incremental"`, `### 0.1 Incremental Re-Verification Scope` plus `Re-verified stages` / `Carried-forward stages` rows are mandatory).
+- `validators/validate-run.py` — version-aware run-level final-report contract. For schema v2 it validates the compact AI handoff heading order and rejects human-only fields in Markdown; task deliverables and cross-field rules are validated from data.json. For schema v1 it retains the Verdict Card, Index, numbered-section, Plan Body Verification, approval, and token-table checks. Both versions require rationale evidence, consistent task verdicts, worker-result audit sidecars, and phase-safe execution evidence.
 - `validators/validate-report-views.py` — checks form-control placement in the self-contained HTML view, absence of external URLs, stale source digests, and Response ID parity (`C-*` ↔ HTML).
 - `validators/validate-brief.py` — enforces the brief schema (frontmatter, presence of `Reporter Confirmations`, root parent-id self rule, slug conventions, and so on). `bash validators/validate-brief.sh <brief.md>` is a thin wrapper.
 
@@ -846,16 +854,16 @@ Each validator blocks the phase with a `contract-violated` exit code when a cont
 - The task bundle's `instruction-set/reference-expectations.md` is generated alongside it as the config/deployment expected-state reference.
 - The current run session's resume helper is created at the resolved `<run-dir>/sessions/claude-resume-<task-type>-<seq>.sh`.
 - The run directory is organized into typed subdirectories such as `manifests/`, `state/`, `prompts/`, `reports/`, `status/`, `sessions/`, and `worker-results/`; prompt snapshots are prepared under `prompts/` first.
-- Claude creates workers and collects results.
-- The standard workflow uses a `Claude lead` with default workers `Claude worker`, `Codex worker`, and `Report writer worker`; `Antigravity worker` is optional and included only when explicitly requested.
-- Worker models can be overridden with `--lead-model`, `--claude-model`, `--codex-model`, `--antigravity-model`, and `--report-writer-model`; defaults are centrally managed through `OKSTRA_DEFAULT_*` environment variables. Fallback defaults are `Claude lead`=`opus`, `Claude worker`=`opus`, `Codex worker`=`gpt-5.6-sol`, `Report writer worker`=`sonnet`, and `Antigravity worker`=`gemini-3.1-pro`.
+- The host adapter creates workers and collects results according to persisted runner assignments.
+- The standard policy uses Claude and Codex analysers plus a report writer. Antigravity, Grok, and Kimi are optional and included only when the selected profile allows them.
+- Worker models can be overridden through the legacy provider flags or generic `--worker-model provider=model`; lead and report-writer provider choices are explicit. Defaults are centrally managed through the provider registry and `OKSTRA_DEFAULT_*` environment variables.
 - For `--task-type implementation`, select the provider that takes the Executor role with `--executor <claude|codex|antigravity>` (or `OKSTRA_DEFAULT_EXECUTOR`, fallback `claude`). Only the Executor may mutate project files. The other two providers and the Executor's own provider are each dispatched as verifiers in separate CLI sessions (session isolation preserves the self-review safeguard). The Executor's model reuses the selected provider's worker-model flag (`--claude-model` / `--codex-model` / `--antigravity-model`). Provider / displayName / workerAgent / model are recorded in the run-manifest `teamContract.executor` block.
-- Worktree cwd injection by Executor: Codex / Antigravity executors pin cwd to the worktree at the CLI layer through wrappers (`okstra-codex-exec.sh -C` / `okstra-antigravity-exec.sh --include-directories`). Because the Bash tool has no per-call cwd argument, the Claude executor prefixes cwd-sensitive toolchain invocations (`cargo`/`npm`/`pnpm`/`bun`/`pytest`/`make`/`go`) with `cd {{EXECUTOR_WORKTREE_PATH}} && <cmd>` in the same Bash invocation. Wrapping in `bash -lc`/`bash -c` is prohibited because it hides the leading `cd` token and defeats permission auto-allow. Prefer working-directory flags such as `git -C` or `cargo --manifest-path` when available. See the *Executor Worktree* block in `prompts/profiles/implementation.md` and the Executor exception in `agents/workers/claude-worker.md` for details.
+- Worktree targeting is runner-based. A native-session executor uses its host adapter's edit and command primitives against `EXECUTOR_WORKTREE_PATH`; a CLI-wrapper executor receives the worktree through its provider wrapper. Prefer explicit working-directory flags such as `git -C` or `cargo --manifest-path` when available.
 - The project-level current-task convenience pointer is `.okstra/discovery/latest-task.json`.
 - The project-level canonical task inventory is `.okstra/discovery/task-catalog.json`.
 - At `okstra install` time, okstra skill assets are seeded to `~/.agents/skills/` by default. If `~/.claude` exists, `~/.claude/skills/` + `~/.claude/agents/` are seeded as well (per-project seeding is no longer performed).
 - Seeded okstra Claude assets instruct Claude to dispatch workers into the session's implicit team with `Agent(name: ...)` (v2.1.178 removed `TeamCreate`/`TeamDelete`). Agent targets receive only skill Markdown.
-- Claude, not scripts, makes the final judgment.
+- The host-native Okstra lead, not preparation scripts or a report writer, makes the final judgment.
 - A stable task key must be maintained to enable later bug tracking, corrections, and reverification.
 - Worker errors are collected in the optional sidecar at the resolved `<run-dir>/logs/errors-<task-type>-<seq>.jsonl`, with the lead as the sole writer. For a stage-isolated run, `<run-dir>` includes `stage-<N>/`. The entry-point helper is `scripts/okstra-error-log.py`.
 - Token-usage and cost accounting are handled by `scripts/okstra-token-usage.py` and the Node wrapper `okstra token-usage`.

package/docs/cli.md

@@ -58,10 +58,10 @@
 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 claude-code|codex] [--lead-model <model>] [--claude-model <model>] [--codex-model <model>] [--antigravity-model <model>] [--report-writer-model <model>] [--executor claude|codex|antigravity] [--critic off|claude|codex|antigravity] [--related-tasks taskA,taskB] [--work-category bugfix|feature|refactor|ops|improvement|unknown] [--base-ref <branch|tag|sha>] [--clarification-response <previous-final-report>] [--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] [--lead-runtime claude-code|codex|antigravity|external] [--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>] [--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 `/okstra-run`; the two option sections below document the internal Node render inputs, not standalone shell options.
+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.
 
 Short form for a later phase when an existing task-manifest.json is available:
 
@@ -371,6 +371,7 @@ Lead runtime independence boundary:
 
 - `claude-code`: the current default execution path. Claude Code v2.1.178 removed `TeamCreate`, and the session owns an implicit team. Workers are dispatched with `Agent(name: ..., run_in_background: true)` without `team_name`. `teamName` is audit/display metadata; Claude session JSONL is used for usage accounting.
 - `codex`: the runtime marker for the Codex lead adapter. `okstra codex-run` owns `--render-only --lead-runtime codex` to prepare a task bundle, and the prepared run manifest can be passed to `okstra codex-dispatch` for CLI-backed worker execution.
+- `antigravity`: the runtime marker for the Antigravity CLI lead adapter. The current Antigravity session owns the native lead, keeps Antigravity assignments native, and routes every other provider through its registered CLI wrapper.
 - `external`: without Claude Code Teams, `--render-only --lead-runtime external` prepares the task bundle and external lead prompt. The lead manages the tmux-pane worker lifecycle with `okstra team dispatch`, `okstra team await`, and `okstra team teardown`. This path does not use `TeamCreate` / `Agent(...)` and uses artifact-only accounting.
 
 The current Claude Code independence boundary covers the external lead prompt and `okstra team *` worker dispatch. non-render `okstra_ctl.run --lead-runtime external` remains blocked; a complete external lead driver remains separate future work. `--runtime external` only selects the runtime adapter. `okstra install` creates `~/.agents/skills/` by default and also installs Claude skills and agents when `~/.claude` exists. Selecting the `claude` worker still requires the local Claude CLI wrapper.
@@ -381,32 +382,47 @@ Code session, that session may not have accepted workspace trust yet. The next
 `/okstra-run` preflight reports `runtimeReadiness.checks[id=workspace-trust]`
 and stops before the wizard when trust is required or cannot be verified. The
 user reopens the project, accepts the one Claude Code workspace prompt, and
-reruns the command. This check applies only to a `claude-code` host; `codex` and
-`external` hosts do not inspect Claude Code state, regardless of whether the
+reruns the command. This check applies only to a `claude-code` host; `codex`,
+`antigravity`, and `external` hosts do not inspect Claude Code state, regardless of whether the
 worker roster contains Claude, Codex, or Antigravity.
 
 ### Runtime auto-detection (`auto`)
 
-`okstra run` defaults to `auto`. `auto` resolves to one of `claude-code`, `codex`, or `external` based on the host through `src/lib/runtime-resolver.mjs`. Precedence: explicit runtime > the `OKSTRA_RUNTIME_HOST` environment variable > Claude Code skill handoff > external when tmux is available > fail fast otherwise. The safe fallback never silently selects a runtime different from the user's intent.
+`okstra run` defaults to `auto`. `auto` resolves to one of `claude-code`, `codex`, `antigravity`, or `external` based on the host through `src/lib/runtime-resolver.mjs`. Precedence: explicit runtime > the `OKSTRA_RUNTIME_HOST` environment variable > Claude Code skill handoff > external when tmux is available > fail fast otherwise. The safe fallback never silently selects a runtime different from the user's intent, and the presence of the `agy` binary alone never selects the Antigravity host.
 
-- Inside Claude Code, `/okstra-run` is the front door. bare `okstra run` cannot invoke Claude Code `TeamCreate` / `Agent(...)`.
-- On a Codex host, `okstra run` orchestrates `codex-run` -> `codex-dispatch`.
+- Inside Claude Code, `/okstra-run` is the front door. Bare `okstra run` cannot invoke host-native Claude workers.
+- On a Codex host, the installed `okstra-run` skill is the front door. Bare `okstra run` cannot invoke host-native Codex workers.
+- On an Antigravity host, the installed `okstra-run` skill is the front door. Bare `okstra run` cannot invoke host-native Antigravity workers.
 - In a generic terminal with tmux, `okstra run` orchestrates `render-bundle --lead-runtime external` -> `okstra team dispatch` -> `okstra team await`.
 
-`doctor` and `render-bundle` also default to `auto`, but a plain terminal without a host signal must specify a host. `okstra install` and `ensure-installed` are exceptions. Installation places the shared runtime and skill targets based on agent homes rather than the runtime host, so it records the `auto` request and unresolved state in the manifest and continues even without a host signal. Skill copy targets depend on the presence of agent homes and the default Agent target policy, not runtime resolution. `~/.agents/skills/` is always created, and Claude skills/agents are installed when `~/.claude` exists. Claude Code skills explicitly specify `--runtime claude-code` / `--lead-runtime claude-code`, so execution does not depend on host auto-detection.
+`doctor` and `render-bundle` also default to `auto`, but a plain terminal without a host signal must specify a host. `okstra install` and `ensure-installed` are exceptions. Installation places the shared runtime and skill targets based on agent homes rather than the runtime host, so it records the `auto` request and unresolved state in the manifest and continues even without a host signal. Skill copy targets depend on the presence of agent homes and the default Agent target policy, not runtime resolution. `~/.agents/skills/` is always created, and Claude skills/agents are installed when `~/.claude` exists. The host-aware `okstra-run` skill passes the current harness runtime explicitly; Claude-only maintenance skills continue to pass `--runtime claude-code` where that host is part of their contract.
 
 `installed-runtimes.json` uses schemaVersion 2 and separates `installRequest`, `runtimeResolution`, `installedRuntimes`, and `installedAssets`. `installed-skills.json` uses a schemaVersion 2 target list with `provider`, `root`, and `skills` to record Claude and Agent skill targets; uninstall removes files according to this list. `codexAdapter` / `externalAdapter` retain read compatibility with v1 manifests only.
 
 For a Codex lead dry run, use `okstra codex-run <args...>`. It adds `--render-only --lead-runtime codex` itself and prints the prepared task bundle and lead prompt without dispatching workers.
 The generated team-state, run manifest, and task manifest point `leadEventsPath` to `runs/<task-type>/state/lead-events-<task-type>-<seq>.jsonl`; rendering records a `bundle-prepared` event.
-Then `okstra codex-dispatch --project-root <dir> --run-manifest <run-manifest> --workers codex[,antigravity[,report-writer]]` executes workers through the existing CLI wrappers. Without `--workers`, it automatically selects the Codex-side supported workers from the run roster: `codex`, `antigravity`, and an opted-in `report-writer`. Explicitly requesting an unsupported worker fails. `report-writer` requires explicit opt-in with `--enable-codex-report-writer --report-writer-codex-model <model>`; on success, postprocessing runs token-usage substitution → render-views → spawn-followups → validate-run in order.
+Then `okstra codex-dispatch --project-root <dir> --run-manifest <run-manifest> [--workers <csv>]` reads each persisted assignment. `runner=native-session` rows stay with the current Codex host; `runner=cli-wrapper` rows run through their registered Claude, Antigravity, Grok, Kimi, or report-writer wrapper. The report-writer provider and model come from the manifest without a Codex-only opt-in flag; on success, postprocessing runs token-usage substitution → render-views → spawn-followups → validate-run in order.
 
-The Codex worker (`--workers codex`, `--codex-model`) and Codex lead runtime are separate. The former selects a worker provider dispatched by a Claude Code lead; the latter is the upper runtime boundary for running the lead itself through the Codex adapter.
+The Codex worker (`--workers codex`, `--codex-model`) and Codex lead runtime are separate. The former creates a worker assignment whose runner depends on the host; the latter selects Codex as the native lead boundary. On Claude Code the Codex worker uses a CLI wrapper, while on Codex it uses the host-native worker/session primitive.
 
 > 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`, `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-4-6`, `claude-sonnet-4-6`, `haiku`, `haiku-4-5`, `claude-haiku-4-5`, `claude-haiku-4-5-20251001`
+> - 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.5-flash`, and the space-separated aliases `gemini 3.1 pro` / `gemini 3.5 flash`. The antigravity worker uses the `agy` CLI to run Gemini-family models, so model IDs retain the `gemini-*` form.
+> - 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`
+> - Kimi (`--worker-model kimi=<model>`): `kimi-k2.7-code`, `kimi-for-coding`, `kimi-k3`, `k3`, `k3-256k` and their registered display aliases
+
+### `--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.
+
+### `--worker-model`
+
+Adds generic `provider=model` overrides, separated by commas. It is the model input for registry providers without a legacy dedicated flag, including Grok and Kimi.
+
+### `--report-writer-provider`
+
+Selects a registry provider that declares the `report-writer` capability. Claude remains the default; Codex is also supported. The provider, model, and resolved runner are persisted in `workerAssignments[]`.
 
 ### `--claude-model`
 
@@ -415,8 +431,7 @@ When omitted, it uses the central default `OKSTRA_DEFAULT_CLAUDE_MODEL`, falling
 
 ### `--lead-model`
 
-Selects the model used by the `Claude lead`.
-When omitted, it uses the central default `OKSTRA_DEFAULT_LEAD_MODEL`, falling back to `opus`.
+Selects the model used by the host-native Okstra lead. Claude Code resolves it through the Claude catalog; Codex resolves it through the Codex catalog; Antigravity resolves it through the Antigravity catalog. When omitted, the host-native provider's lead default applies.
 
 ### `--codex-model`
 
@@ -444,7 +459,9 @@ The central-default environment variables are:
 
 Fallback defaults are:
 
-- `Claude lead`: `opus`
+- Claude Code lead: `opus`
+- Codex lead: `gpt-5.6-sol`
+- Antigravity lead: `gemini-3.1-pro`
 - `Report writer worker`: `sonnet`
 - `Claude worker`: `opus`
 - `Codex worker`: `gpt-5.6-sol`
@@ -478,7 +495,7 @@ scripts/okstra.sh --task-type implementation \
 
 ### `--critic`
 
-Selects the provider for the opt-in Phase 5.6 critic pass. The value is `off`, `claude`, `codex`, or `antigravity`; the default is `off`.
+Selects the provider for the opt-in Phase 5.6 critic pass. The value is `off`, `claude`, `codex`, `antigravity`, `grok`, or `kimi`; the default is `off`. The selected critic receives its own role-default model even when that provider is not in the initial analyser roster.
 
 - Critic dispatch runs concurrently with the first convergence reverify round in Phase 5.5, with critic input fixed to the integrated Round 0 result. One gap/blocker verification round runs in Phase 5.6 after convergence finishes. It detects coverage gaps in discovery, error-analysis, and implementation-planning, and acts as an acceptance devil's advocate in final-verification. Follow the "Coverage critic pass" and "Acceptance critic pass" sections of `prompts/lead/convergence.md` for the detailed contract.
 - It shares the same value space as the critic-selection step in the in-session `okstra-run` wizard. `_resolve_model_bindings` in `prepare_task_bundle` validates the value; anything else is rejected immediately with `PrepareError`.
@@ -675,7 +692,7 @@ chmod +x ~/.local/bin/okstra-ctl
 | View in-progress runs | `okstra-ctl tail active` |
 | Show metadata for one run | `okstra-ctl show <runId-or-prefix>` |
 | Print the result-report path | `okstra-ctl open <runId-or-prefix>` |
-| Regenerate a final-report HTML view | `okstra render-views <final-report.md>` |
+| Regenerate a final-report HTML view | `okstra render-views <final-report.data.json\|final-report.md>` |
 | Rerun one run | `okstra-ctl rerun <runId-or-prefix> --yes` |
 | Rerun multiple filtered runs | `okstra-ctl rerun --filter --project X --status failed --yes` |
 | Rerun the latest matching run | `okstra-ctl rerun last --project X --task-group Y --yes` |
@@ -690,13 +707,13 @@ The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and
 | Command | Purpose |
 |---|---|
 | `okstra paths [--field <name>\|--shell]` | Print package, runtime, home, bin, Python path, and version locations |
-| `okstra install [--runtime claude-code\|codex\|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\|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 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\|external\|all] [--phase <phase>] [--json]` | Diagnose the runtime, Python imports, and skill/agent installation. The `codex` 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, 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 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; `codex` and `external` hosts return ready without reading Claude Code state. Step 0 of every project-scoped skill converges on this command |
+| `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; `codex`, `antigravity`, and `external` hosts return ready without reading Claude Code state. Step 0 of every project-scoped skill converges on this command |
 | `okstra convergence seed --groups <path> --work-state <path> --final-state <path> --migration-dir <dir> [--restart-from-round0]` | Create, resume, reuse, or explicitly recover deterministic convergence state |
 | `okstra convergence plan-round --work-state <path> --plan <path>` | Persist the next roster-aware dispatch plan without mutating working state |
 | `okstra convergence apply-round --work-state <path> --plan <path> --results <path>` | Validate one complete structured result set and atomically reduce it into working state |
@@ -729,10 +746,10 @@ The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and
 | `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 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 codex-dispatch --project-root <dir> --run-manifest <path> [--workers codex,antigravity,report-writer]` | Read a run manifest prepared by `codex-run` and execute the Codex-side supported worker subset. Without `--workers`, unsupported roster members such as `claude` are skipped; explicitly requesting one fails. The report writer requires opt-in with `--enable-codex-report-writer --report-writer-codex-model <model>`. On success, it automatically performs token-usage substitution, HTML view rendering, follow-up task-stub generation, and run validation |
+| `okstra codex-dispatch --project-root <dir> --run-manifest <path> [--workers <csv>]` | Read a Codex-host run manifest and dispatch every requested `runner=cli-wrapper` assignment through its registered provider wrapper. Native Codex rows remain in-session. The persisted report-writer assignment needs no Codex-specific opt-in; successful report completion triggers token substitution, HTML rendering, follow-up generation, and validation |
 | `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 tmux-pane workers. If a tmux pane cannot be created, gracefully degrade to the CLI wrapper and record the fallback in `workerDispatches[].degradedFrom` |
 | `okstra report-finalize --project-root <dir> --run-manifest <path> --report <final-report.md>` | Run the whole Phase 7 post-report sequence in its contractual order: `token-usage` → `render-views` → `spawn-followups` → `validate-run`. Stops at the first non-zero exit and names the failing step, then prints a per-step `[ok]` / `[FAIL]` / `[skip]` summary on stderr so the outcome is legible without parsing the JSON payload. Every step is idempotent, so re-running after a fix is safe — but `--only <step>` (repeatable) reruns just the named steps in contractual order, which matters because `validate-run` is the step that usually fails and retrying it otherwise repeats the three steps before it at full token and wall-clock cost. This is the same code path (`scripts/okstra_ctl/report_finalize.py`) the Codex lead adapter runs automatically after its report-writer completes, so a Claude-led and a Codex-led run finalize identically. `--workspace-root` is owned by the Node wrapper. Prefer this over invoking the four steps individually |
-| `okstra render-views <final-report.md>` | The Phase 7 `render-views` step, runnable on its own: deterministically create a human-facing self-contained sibling `*.html` view from one final-report Markdown file after token substitution. The source Markdown is unchanged. The Node delegation wrapper calls `scripts/okstra-render-report-views.py`; `validators/validate-report-views.py` verifies form-control placement, absence of external URLs, stale source digests, and Response ID parity |
+| `okstra render-views <final-report.data.json\|final-report.md>` | The Phase 7 `render-views` step, runnable on its own. Schema v2 data is rendered directly (contract: `schemas/final-report-v2.0.schema.json`) into an always-generated, task-specific human HTML sibling while `templates/reports/final-report-v2.template.md` independently owns the AI handoff Markdown. Passing the Markdown sibling locates the same v2 data.json. Schema v1 and quick reports keep the legacy conditional renderer. The Node wrapper calls `scripts/okstra-render-report-views.py`; `validators/validate-report-views.py` verifies source/schema/template digests, required human fields, form controls, external assets, diagram/table ID parity, and Response ID parity |
 | `okstra design-prep <list\|show\|write>` | Review AI-prepared implementation design requests, inspect their effective confirmed response, or append a confirmed user/wizard response without editing the planning report |
 | `okstra wizard <init\|step\|render-args\|confirmation\|outcome> --state-file <path>` | Interactive input state machine for okstra-run, implemented by `okstra_ctl.wizard`. Seed a state file with `init`, then repeatedly call `step --answer <val>` to receive the next `Prompt` JSON. `--answer` is **required**; use `--no-submit` to peek at the next prompt without submitting a response. A `pick` with more choices than the host picker can display keeps `kind: "pick"` but adds `presentation: "numbered-text"`; render every option as a numbered Markdown list and submit the user's 1-based number, exact value, or exact label. Invalid, out-of-range, and ambiguous answers re-prompt without dropping choices. `render-args` returns the final `render-bundle` argument map, and `confirmation` returns the user echo block. On a completed wizard, `outcome` returns `renderArgs`, `persistActions`, and `confirmationText` together; project/global release-handoff PR-template persistence appears as `persistActions[].command == "config.set"`. For an `implementation` task type, `stage_pick` follows `approved_plan_pick` and selects the stage before `executor_pick`. The brief step appears only for entry task types—requirements-discovery, error-analysis, improvement-discovery, project-analysis, feature-analysis, and change-impact-analysis. Analysis inputs use `feature_evidence_pick` / `feature_evidence`, `project_evidence_pick` / `project_evidence`, and `analysis_target_pick` / `analysis_target`; a revision-requested report prioritizes its same-task, same-type rerun. Downstream lifecycle phases automatically carry the manifest brief, with a three-option `brief_carry` fallback when none is registered; `release-handoff` has no brief and enters multi-select `handoff_stage_pick` for eligible stage groups or the whole task |
 | `okstra token-usage ...` | Wrap the installed `okstra-token-usage.py` to collect and substitute run token usage. Session JSONL is incrementally scanned by default through a byte-cursor cache at `$OKSTRA_HOME/cache/token-usage/`; `--no-cache` bypasses the cache and forces a full rescan as an accuracy fallback |