okstra 0.146.1 → 0.148.0

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

@@ -22,9 +22,9 @@ tools: ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "TodoWrite", "WebFetch"
 
 ## Authority
 
-You are the canonical author of `runs/<task-type>/reports/final-report-<task-type>-<seq>.data.json` for this run. Claude lead has explicitly delegated file-authorship to you. The lead reviews your output but does not write the file.
+You are the canonical author of `runs/<task-type>/reports/final-report-<task-type>-<seq>.data.json` for this run. The host-native Okstra lead has explicitly delegated file-authorship to you. The lead reviews your output but does not write the file.
 
-The data.json is the **single source of truth**. The renderer (`scripts/okstra-render-final-report.py`) produces the user-facing markdown (`final-report-<task-type>-<seq>.md`) deterministically from it. You do NOT hand-write the markdown. The markdown is regenerated whenever the data.json changes (Phase 7 token substitution, future re-renders).
+The data.json is the **single source of truth** for two audiences. The renderer (`scripts/okstra-render-final-report.py`) produces the AI handoff Markdown (`final-report-<task-type>-<seq>.md`) deterministically from it. Phase 7 produces the human HTML (`final-report-<task-type>-<seq>.html`) through the task-specific HTML renderer. HTML is rendered directly from the data.json; it is not a presentation of the Markdown. You do NOT hand-write either derived artifact. Both are regenerated whenever the data.json changes.
 
 If you find yourself thinking "I'll just write the markdown directly" — stop. Write the data.json with your `Write` tool and let the renderer produce the markdown.
 
@@ -72,30 +72,30 @@ Before writing the data.json, you MUST:
 
 For the report writer specifically, the `## Inputs` list always includes:
 
-- `<instruction-set>/final-report-schema.json` — the **per-task-type excerpt** of the data.json schema (scoped to this run's task-type at prep time: other task-types' deliverable blocks and their unreachable `$defs` are stripped). This is the shape you must author. Read this, NOT the full `schemas/final-report-v1.0.schema.json` (it is not in the task bundle and its `schemas/...` path is not resolvable here). Validation still runs against the full schema post-hoc, so the excerpt never relaxes the contract. The excerpt is frozen at prep time and carries the okstra version it was cut from (`x-okstraCutFromVersion`); if the renderer rejects a field the excerpt told you to write, the runtime upgraded mid-run — the renderer's error names the version skew, and the **installed schema wins**.
-- `<instruction-set>/final-report-template.md` — the **phase-stripped** Jinja2 template the renderer uses (only this run's §4.x deliverable block remains). Read it to understand which data.json fields appear where in the rendered markdown; do NOT edit it, and do NOT pull the full `templates/reports/final-report.template.md` source.
+- `<instruction-set>/final-report-schema.json` — the **per-task-type excerpt** of schema v2 (other task-types' deliverable blocks and unreachable `$defs` are stripped). This is the shape you must author. Read this, NOT the full `schemas/final-report-v2.0.schema.json` source outside the task bundle. Validation still runs against the installed full schema, so the excerpt never relaxes the contract. The excerpt is frozen at prep time and carries the okstra version it was cut from (`x-okstraCutFromVersion`); if the renderer rejects a field the excerpt told you to write, the installed schema wins.
+- `<instruction-set>/final-report-template.md` — the AI handoff Markdown template. Read it to understand which IDs, routing fields, evidence, task deliverable, and audit blocks appear in the AI artifact; do NOT edit it, and do NOT use it as the human presentation contract.
 - `templates/reports/i18n/en.json` and `templates/reports/i18n/ko.json`.
 - Every analysis worker's result file under `worker-results/`.
 - `state/convergence-<task-type>-<seq>.json` (if present). When present, reproduce its `roundHistory[]`, `round2SkippedReason`, and `finalClassificationCounts` verbatim into the final report's Section 6 Round History sub-table — do not recompute from worker results.
 - `<instruction-set>/task-brief.md` — the brief this run was prepared from. The lead already lists it under `## Inputs`; what it is FOR is the `## Expected Behavior` / `## Preserved Behavior` / `## Expected Outcome` items, whose `EB-NNN` / `PB-NNN` / `EO-NNN` ids are exactly what `endStateCoverage` maps. Read the instruction-set copy, NOT the project's `.okstra/briefs/...` path from the task manifest — that path is not resolvable here, same as the full schema source. A report that omits an id the brief pinned is rejected by the run validator.
 
-For the carry-in `clarification-response.md` (if present), walk every row of `## 1. Clarification Items` including rows whose `User input` cell is blank — a blank cell with `Status=open` is a signal you must surface in the conditional `## 0. Clarification Response Carried In From Previous Run` section (the template's `RENDER_IF` guard activates it when the carry-in path is non-empty). When no carry-in path was provided, OMIT the `## 0.` heading entirely — do NOT write an empty-state stub.
+For a carry-in `clarification-response.md`, reconcile every prior `clarificationItems[]` row, including an open row with blank user input. Record the current status and user decision in data.json; the AI handoff renderer places it under `## Clarification and User Decisions`, while HTML renders any still-open response controls. When no carry-in path was provided, omit `clarificationCarryIn` entirely.
 
 Write a Reading Confirmation block to `**Audit sidecar path:**`, per the selected report-writer preamble's `Required reading` section (the main final-report and worker-results files carry no Section 0 heading). If you cannot truthfully confirm a file end-to-end, record a `tool-failure` in the errors sidecar instead of fabricating the report.
 
 ## Authoring Contract
 
-You author the final-report data.json (the JSON SSOT). You author it against the `<instruction-set>/final-report-schema.json` excerpt — its `$defs` enumerate every row shape, enum value, and cross-field constraint that applies to this run's task-type. The validator and renderer both consume the **full** `schemas/final-report-v1.0.schema.json` (the excerpt is a faithful task-type-scoped subset of it), so a data.json that satisfies the excerpt is a data.json that validates and renders correctly.
+You author the final-report data.json (the JSON SSOT). You author it against the `<instruction-set>/final-report-schema.json` excerpt — its `$defs` enumerate every row shape, enum value, and cross-field constraint that applies to this run's task-type. The validator and renderers both consume the **full** `schemas/final-report-v2.0.schema.json` (the excerpt is a faithful task-type-scoped subset of it), so a data.json that satisfies the excerpt can independently produce both audience artifacts.
 
-The rendered markdown (`final-report-<task-type>-<seq>.md`) is produced by `scripts/okstra-render-final-report.py` immediately after you write the data.json. The HTML view (`*.html`) is produced from the markdown by the lead's Phase 7 `okstra report-finalize` run, not by you. The data.json is the only file you write; the rest are derived.
+The AI handoff Markdown is an agent-facing ledger: verdict, routing, clarification decisions, evidence, one structured task deliverable, and execution audits. The human HTML is the reader-facing explanation: `humanSummary` plus the selected task block's `userNarrative` and structured facts. Populate both human fields in data.json even though the Markdown intentionally omits their full prose. Worker discussion, convergence mechanics, and token usage belong to audit data and must not be copied into the HTML human main body.
 
 Rules (the schema enforces most of these — they are listed here so you know *what* to populate, not *how* to validate):
 
-- `header.reportAuthor` is `"Report writer worker"`; `header.reportOwner` is `"Claude lead"`. Set author to `"Claude lead"` only for `release-handoff` runs (single-lead by design) or a recorded report-writer dispatch failure fallback.
+- Read the exact permitted header values from the task bundle schema excerpt. In the current v2 contract, `header.reportOwner` is `"Okstra lead"` and `header.reportAuthor` is `"Report writer worker"`. Set author to `"Okstra lead"` only for `release-handoff` runs (single-lead by design) or a recorded report-writer dispatch failure fallback. A legacy v1 excerpt may retain its historical compatibility values; follow that excerpt rather than inferring ownership from the provider.
 - **Source items (worker:item) preservation.** Every `consensus[].sourceItems`, `differences[].workersPosition[].itemId`, and `evidence.primary[].sourceItems` entry MUST carry the worker:item-id pair (e.g. `claude:F-001`, `codex:1.1`, `antigravity:F-3`, or `lead:mcp-1` for lead-only evidence). The schema enforces this via the `SourceItem` regex; bare worker-name lists no longer parse.
 - **Verdict Card consistency.** `verdictCard.verdictToken` and `verdictCard.direction` MUST byte-match `finalVerdict.verdictToken` / `.direction`; `validators/validate-run.py` diffs both and fails the run on divergence. `verdictCard.nextStep` names the same action as `finalVerdict.nextStep` and `recommendedNextSteps[0].text` but is written as the actionable command the reader runs (e.g. `/okstra-run task-key=… task-type=release-handoff`) where the other two are prose — it is deliberately not a byte copy. Duplicating the compared values across `verdictCard` and `finalVerdict` is intentional so the validator can diff them.
 - **Error-analysis diagnosis and routing.** When `header.taskType` is `error-analysis`, populate the required `errorAnalysis` object. Copy `errorAnalysis.symptomVerbatim` byte-for-byte from the symptom stated in the brief's `Source Material`; do not paraphrase it. Every `causeCandidates[]` row includes the full `supportingEvidence`, `falsifyingEvidenceChecked`, `confidence`, and `disproveWith` fields. Route `errorAnalysis.routing.nextTaskType=implementation-planning` with `direction=begin-planning`, or route `errorAnalysis.routing.nextTaskType=error-analysis` with `direction=continue-investigation`; no other pairing is valid. `verdictCard.nextStep`, `finalVerdict.nextStep`, the first `recommendedNextSteps` action and command, and the unique `followUpTasks` row whose `origin` is `phase-continuation` MUST all point to the same `errorAnalysis.routing.nextTaskType` target. The schema enforces only the presence of a `phase-continuation` row. Phase validation MUST enforce exact target agreement and uniqueness through `validators/validate-run.py::_validate_error_analysis_consistency`; until that check is implemented and executed, those semantics are contract requirements rather than enforced guarantees.
-- **Reader Summary.** Populate `readerSummary` when the schema excerpt exposes it. It is the human-first entrypoint for both Markdown and HTML: one sentence for the decision, one for the human action required, one for blockers, one for audit sections safe to skip on first read, and one runnable recommended command. Do not duplicate raw evidence tables here.
+- **Human narrative.** Populate required `humanSummary` and the selected task block's `userNarrative`. Human-visible analysis facts must not exist only in Markdown; HTML is derived independently and can use only data.json. Keep worker discussion and audit details in `crossVerification`, `executionStatus`, and `tokenUsage`, outside the human narrative fields.
 - **External QA advisory.** A Tier 3 entry requiring `db`, `http`, or
   `external` may be non-PASS without changing approval or final verdict. Render
   its command log row as `tier: 3`, `status: advisory`, keep the observed and
@@ -116,11 +116,11 @@ Rules (the schema enforces most of these — they are listed here so you know *w
 - Cite file paths and line numbers in every `evidence.primary[].source` / `consensus[].evidence` cell.
 - Preserve every analysis worker's ticket tagging — every row's `ticketId` field carries the ticket key or the task-fallback. For single-ticket runs, set `ticketCoverage` to `{"singleTicket": "<ticket>"}`. For runs that do not require ticket tagging (`release-handoff`, `final-verification`), set `ticketCoverage` to `{"omit": true}`.
 - For `requirements-discovery`, `error-analysis`, and `implementation-planning`, populate the top-level `endStateCoverage` with exactly one row per end-state id the brief declares — no more, no fewer. `disposition` is one of `addressed` / `deferred` / `not-applicable` / `blocked`. `addressed` requires a `coveredBy` anchor in THIS phase's own deliverable (requirements-discovery: the routing decision, the fan-out unit id, or the `C-NNN` clarification; error-analysis: the root-cause candidate or the next diagnostic; implementation-planning: the `R-NNN` row); every other disposition requires a `rationale`. Do not author a goal of your own here and do not restate the brief — this table records only how this phase accounted for what the reporter already pinned. When the brief declares no end-state ids (a brief authored before those sections existed), omit the field entirely. **Enforced:** `validators/validate-run.py` `_validate_end_state_coverage`.
-- For `implementation-planning`, populate `implementationPlanning.requirementCoverage` with one row per concrete requirement from the brief / packet, using IDs `R-001`, `R-002`, ... in source order. A `covered` row's `coveredBy` MUST name the specific Option Candidate plus Stage/Step that satisfies the requirement. Use `status: "covered"` only when the report's plan actually covers it; use `documented-deviation` only when `coveredBy` states the concrete alternative and the row records non-empty unique `decisionRefs` plus `approvalDisposition`. Each `C-NNN` ref must name a clarification in this report; each `D-NNNN` ref must name a `decisionDrafts[].number`. `approvalDisposition: "accepted"` requires a referenced clarification with `status: answered|resolved` and non-empty `userInput`; `approvalDisposition: "blocked C-NNN"` requires that same-report clarification to be `status: open, blocks: approval`. Otherwise use `gap` or `blocked C-NNN` and ensure the corresponding `Clarification Items` row blocks approval. Do not collapse this into `ticketCoverage`; ticket coverage is not requirement coverage. **Enforced:** `schemas/final-report-v1.0.schema.json` `$defs.ImplementationRequirementCoverageRow` and `validators/validate-run.py` `_validate_requirement_deviations`.
+- For `implementation-planning`, populate `implementationPlanning.requirementCoverage` with one row per concrete requirement from the brief / packet, using IDs `R-001`, `R-002`, ... in source order. A `covered` row's `coveredBy` MUST name the specific Option Candidate plus Stage/Step that satisfies the requirement. Use `status: "covered"` only when the report's plan actually covers it; use `documented-deviation` only when `coveredBy` states the concrete alternative and the row records non-empty unique `decisionRefs` plus `approvalDisposition`. Each `C-NNN` ref must name a clarification in this report; each `D-NNNN` ref must name a `decisionDrafts[].number`. `approvalDisposition: "accepted"` requires a referenced clarification with `status: answered|resolved` and non-empty `userInput`; `approvalDisposition: "blocked C-NNN"` requires that same-report clarification to be `status: open, blocks: approval`. Otherwise use `gap` or `blocked C-NNN` and ensure the corresponding `Clarification Items` row blocks approval. Do not collapse this into `ticketCoverage`; ticket coverage is not requirement coverage. **Enforced:** `schemas/final-report-v2.0.schema.json` `$defs.ImplementationRequirementCoverageRow` and `validators/validate-run.py` `_validate_requirement_deviations`.
 - For `implementation-planning`, each `requirementCoverage` row's `source` is a graded cell, not prose — free text like `"carry-in from requirements-discovery C-001"` is rejected. Write exactly one of: `brief:EB-001` / `brief:PB-001` / `brief:EO-001`, an end-state id the brief declares — when the brief pins ids, citing a heading instead is rejected, because every brief carries the same generic headings and a heading cannot say WHICH reporter line the requirement came from (only a brief authored before the end-state sections existed still takes the older `brief:<heading>` form, and there the heading must literally exist in it); `derived:R-NNN — <one-line reason>`, whose chain must terminate at a `brief:` or `contract:` row of the same table without cycling; or `contract:<rule>`, for artifacts okstra's own phase contract mandates, whose allowlist is exactly the two tokens `decision-record-step` (the §5.4 Decision Drafts materialization step) and `glossary-step` (the glossary proposal step) — any other rule name is rejected, so never invent one. (Maintainer SSOT for that allowlist: `scripts/okstra_ctl/scope_provenance.py` in the okstra repo.) A requirement you cannot source this way does not belong in the table: put it in `clarificationItems[]` with `Blocks=approval`. **Enforced:** `validators/validate-run.py` `_validate_requirement_provenance`. In the same table, anchor every stage number in `coveredBy` to a `Stage` / `Stages` word (`Stage 2`, `Stages 1-3`) — `_validate_stage_has_requirement` reads that cell as prose and fails the plan when a Stage Map stage is cited by no row.
 - For `implementation-planning`, also populate `implementationPlanning.decisionDrafts` (one row per decision meeting all three decision-record criteria; `[]` otherwise) and `implementationPlanning.skippedAdrCandidates` (evaluated-but-dropped adr-candidates; `[]` otherwise). The schema excerpt enumerates the row shape; the renderer emits §5.4 `### Decision Drafts`. When `decisionDrafts` is non-empty, the plan's stages MUST carry a stepwise step that creates `.okstra/decisions/<NNNN>-<slug>.md` (validate-run gates this).
-- For `implementation-planning`, populate `implementationPlanning.variationPointAnalysis` — a `hasMultipleImplementations` judgement synthesized from the analysis workers' output, not a field filled in last. When it is `true`, write one `points[]` row per varying behavior carrying `behavior`, the two or more `implementations` that serve it, `evidence` (a `path:line`, or the sibling task / stage that already implements that behavior), and an `extractionDecision` of `extract` / `interfaceKind` / `coveredBy` (the Stage Map stage that builds the interface) / `rationale`; when it is `false`, write a non-empty `noVariationRationale` and leave `points` empty (the two branches are mutually exclusive). Do NOT pass a boilerplate rationale — `false` is the cheaper field to fill, and a `false` declaration the brief or the sibling code in the workers' evidence contradicts is a `P-Var` DISAGREE, not a saving. Also populate `implementationPlanning.recommendedOption.testSeams`: one row per boundary a test injects at and replaces, each carrying `boundary` / `injectedAs` / `replacedInTest`. An empty list is a conscious "no seam needed" claim, never a default for a field nobody filled. The schema excerpt enumerates both row shapes — author against it. (Maintainer SSOT for these two rules: the `Required deliverable shape` bullet in `prompts/profiles/implementation-planning.md` in the okstra repo; that path is not resolvable here, so it is provenance, not a file to open.) **Enforced:** `schemas/final-report-v1.0.schema.json` `$defs.VariationPointAnalysis` / `$defs.VariationPoint` (the block is in `implementationPlanning.required`) plus `testSeams` in `$defs.RecommendedOption`'s `required`; `validators/validate-run.py` `_validate_variation_point_analysis` rejects a rationale-less `false`, a `false` carrying points, a `true` with no point, an `extract: true` decision leaving `interfaceKind` or `coveredBy` empty, and a hexagonal project extracting as anything but a port; and every point becomes a `P-Var-*` plan item judged in §5.5.9.
-- When the `Task Type` is `improvement-discovery`, populate `## 5.9 Improvement Candidates` with the 11-column schema enforced by `validators/validate_improvement_report.py`. The `Expected behavior after` cell states in one observable sentence what becomes different once the candidate is applied — it seeds the downstream brief's `EB-NNN` / `EO-NNN`, and an empty cell fails the run. Source the row IDs (`I-NNN`), lens whitelist, and Source workers patterns from `scripts/okstra_ctl/improvement_lenses.py` — do NOT introduce new lens names or worker prefixes. `improvement-discovery` is NOT in the data.json schema enum, so author its markdown directly (not via `okstra-render-final-report.py`). Immediately after writing the markdown, run (`Bash`): `okstra inject-report-index <markdown path> --report-language <en|ko>`. That adds the top-of-report Index plus `I-NNN` / `C-NNN` scroll anchors; the run validator fails the report when the Index anchor is absent.
+- For `implementation-planning`, populate `implementationPlanning.variationPointAnalysis` — a `hasMultipleImplementations` judgement synthesized from the analysis workers' output, not a field filled in last. When it is `true`, write one `points[]` row per varying behavior carrying `behavior`, the two or more `implementations` that serve it, `evidence` (a `path:line`, or the sibling task / stage that already implements that behavior), and an `extractionDecision` of `extract` / `interfaceKind` / `coveredBy` (the Stage Map stage that builds the interface) / `rationale`; when it is `false`, write a non-empty `noVariationRationale` and leave `points` empty (the two branches are mutually exclusive). Do NOT pass a boilerplate rationale — `false` is the cheaper field to fill, and a `false` declaration the brief or the sibling code in the workers' evidence contradicts is a `P-Var` DISAGREE, not a saving. Also populate `implementationPlanning.recommendedOption.testSeams`: one row per boundary a test injects at and replaces, each carrying `boundary` / `injectedAs` / `replacedInTest`. An empty list is a conscious "no seam needed" claim, never a default for a field nobody filled. The schema excerpt enumerates both row shapes — author against it. (Maintainer SSOT for these two rules: the `Required deliverable shape` bullet in `prompts/profiles/implementation-planning.md` in the okstra repo; that path is not resolvable here, so it is provenance, not a file to open.) **Enforced:** `schemas/final-report-v2.0.schema.json` `$defs.VariationPointAnalysis` / `$defs.VariationPoint` (the block is in `implementationPlanning.required`) plus `testSeams` in `$defs.RecommendedOption`'s `required`; `validators/validate-run.py` `_validate_variation_point_analysis` rejects a rationale-less `false`, a `false` carrying points, a `true` with no point, an `extract: true` decision leaving `interfaceKind` or `coveredBy` empty, and a hexagonal project extracting as anything but a port; and every point becomes a `P-Var-*` plan item judged in §5.5.9.
+- When the `Task Type` is `improvement-discovery`, populate `improvementDiscovery.candidates[]`, `improvementDiscovery.lensCoverage[]`, `improvementDiscovery.selectionLimit`, and `improvementDiscovery.userNarrative`. Each candidate carries the 11 logical fields enforced by `validators/validate_improvement_report.py`; each lens-coverage row records candidate IDs or an evidence-backed no-candidate rationale. Source IDs, lens names, and worker prefixes from `scripts/okstra_ctl/improvement_lenses.py`. The standard renderer derives the AI handoff Markdown; never author a free-form improvement report.
 
 Write the three completion artifacts and the separate audit sidecar with your `Write` tool — that is the canonical authoring path, and okstra ships no hook that blocks `.md` writes (its only settings hook is the `SessionEnd` trace-cleanup; the coding-preflight hook emits reminders but never blocks). A Bash heredoc is acceptable ONLY when a specific `Write` call is genuinely rejected by the host environment, and it MUST produce byte-identical content — do not reach for it pre-emptively. After writing data.json, invoke the renderer (`Bash`): `okstra render-final-report <data.json path>`, then write the Worker Result Path pointer. Confirm data.json, rendered Markdown, the pointer, and the audit sidecar exist before responding with a short status line prefixed by your model identity, per the preamble §"Return message to the lead". **Enforced:** dispatch `completionPaths` requires the first three files and `validators/validate_session_conformance.py` validates the audit sidecar.
 

package/runtime/bin/lib/okstra/cli.sh

@@ -66,6 +66,10 @@ while [[ $# -gt 0 ]]; do
       LEAD_MODEL_OVERRIDE="$(require_option_value --lead-model "${2-}")"
       shift 2
       ;;
+    --lead-provider)
+      LEAD_PROVIDER_OVERRIDE="$(require_option_value --lead-provider "${2-}")"
+      shift 2
+      ;;
     --claude-model)
       CLAUDE_MODEL_OVERRIDE="$(require_option_value --claude-model "${2-}")"
       shift 2
@@ -78,6 +82,14 @@ while [[ $# -gt 0 ]]; do
       ANTIGRAVITY_MODEL_OVERRIDE="$(require_option_value --antigravity-model "${2-}")"
       shift 2
       ;;
+    --worker-model)
+      WORKER_MODELS_OVERRIDE="$(require_option_value --worker-model "${2-}")"
+      shift 2
+      ;;
+    --report-writer-provider)
+      REPORT_WRITER_PROVIDER_OVERRIDE="$(require_option_value --report-writer-provider "${2-}")"
+      shift 2
+      ;;
     --report-writer-model)
       REPORT_WRITER_MODEL_OVERRIDE="$(require_option_value --report-writer-model "${2-}")"
       shift 2
@@ -212,7 +224,7 @@ while [[ $# -gt 0 ]]; do
           printf '  hint: did you mean --task-id?\n' >&2
           ;;
       esac
-      printf '  valid options: --render-only --resume-clarification --yes --workers --lead-model --claude-model --codex-model --antigravity-model --report-writer-model --lead-runtime --executor --critic --related-tasks --work-category --task-type --project-id --project-root --task-group --task-id --task-brief --directive --base-ref --fix-cycle --clarification-response --task-key --approved-plan --approve --implementation-option --stage --stages --qa-waiver --no-plan-verification -h|--help\n' >&2
+      printf '  valid options: --render-only --resume-clarification --yes --workers --lead-provider --lead-model --claude-model --codex-model --antigravity-model --worker-model --report-writer-provider --report-writer-model --lead-runtime --executor --critic --related-tasks --work-category --task-type --project-id --project-root --task-group --task-id --task-brief --directive --base-ref --fix-cycle --clarification-response --task-key --approved-plan --approve --implementation-option --stage --stages --qa-waiver --no-plan-verification -h|--help\n' >&2
       usage
       exit 1
       ;;

package/runtime/bin/lib/okstra/globals.sh

@@ -18,9 +18,12 @@ ASSUME_YES="false"
 RESUME_CLARIFICATION_MODE="false"
 WORKERS_OVERRIDE=""
 LEAD_MODEL_OVERRIDE=""
+LEAD_PROVIDER_OVERRIDE=""
 CLAUDE_MODEL_OVERRIDE=""
 CODEX_MODEL_OVERRIDE=""
 ANTIGRAVITY_MODEL_OVERRIDE=""
+WORKER_MODELS_OVERRIDE=""
+REPORT_WRITER_PROVIDER_OVERRIDE=""
 REPORT_WRITER_MODEL_OVERRIDE=""
 LEAD_RUNTIME="claude-code"
 EXECUTOR_OVERRIDE=""

package/runtime/bin/lib/okstra/usage.sh

@@ -3,10 +3,10 @@
 usage() {
   cat >&2 <<USAGE_EOF
 usage:
-  $DISPLAY_COMMAND_NAME [--render-only] [--yes] [--no-plan-verification] --task-type <task-type> [--workers worker1,worker2] [--lead-model <model>] [--claude-model <model>] [--codex-model <model>] [--antigravity-model <model>] [--report-writer-model <model>] [--lead-runtime claude-code|codex] [--executor claude|codex|antigravity] [--critic off|claude|codex|antigravity] [--related-tasks taskA,taskB] --project-id <project-id> [--project-root <path>] --task-group <task-group> --task-id <task-id> --task-brief <brief-path> [--directive <directive>] [--fix-cycle <yes|no>]
+  $DISPLAY_COMMAND_NAME [--render-only] [--yes] [--no-plan-verification] --task-type <task-type> [--workers worker1,worker2] [--lead-provider <provider>] [--lead-model <model>] [--worker-model provider=model,...] [--report-writer-provider <provider>] [--report-writer-model <model>] [--lead-runtime claude-code|codex|antigravity|external] [--executor claude|codex|antigravity] [--critic off|claude|codex|antigravity|grok|kimi] [--related-tasks taskA,taskB] --project-id <project-id> [--project-root <path>] --task-group <task-group> --task-id <task-id> --task-brief <brief-path> [--directive <directive>] [--fix-cycle <yes|no>]
 
 summary:
-  $DISPLAY_TOOL_NAME prepares a task-keyed instruction bundle for Claude Code and launches an interactive Claude session by default.
+  $DISPLAY_TOOL_NAME prepares a task-keyed instruction bundle. The standalone launcher defaults to an interactive Claude session; supported in-host skills keep the current Claude Code, Codex, or Antigravity session as the native lead.
   The stable task identifier is composed of project-id + task-group + task-id.
 
   Skills, worker agents, and the codex wrapper are installed once per user under
@@ -75,7 +75,7 @@ optional arguments:
                        workflow.nextRecommendedPhase). Explicit flags always win.
 
 options:
-  --render-only        Render the Claude handoff prompt only. Do not launch Claude.
+  --render-only        Render the host-neutral lead handoff prompt only. Do not launch a session.
   --resume-clarification
                        Interactive convenience mode that wraps --clarification-response.
                        Locates the latest requirements-discovery or error-analysis
@@ -86,24 +86,27 @@ options:
                        (--project-id/--task-group/--task-id or --task-key). Mutually
                        exclusive with --clarification-response and --approved-plan.
   --yes                Skip interactive prompting and confirmation. Requires all required arguments.
-  --workers            Comma-separated worker list for this run. Default: claude,codex,report-writer
-                      (Antigravity worker is optional; add \`antigravity\` explicitly, e.g. --workers claude,codex,antigravity,report-writer)
-  --lead-model         Model for Claude lead. Default: OKSTRA_DEFAULT_LEAD_MODEL or opus
+  --workers            Comma-separated worker list for this run. Default: claude,codex,report-writer.
+                      Optional read-only providers: antigravity, grok, kimi.
+  --lead-provider      Compatibility assertion for the lead assignment. Must match the native Claude Code, Codex, or Antigravity host.
+  --lead-model         Model for the host-native lead. Default: the selected provider's lead policy.
   --claude-model       Model for Claude worker. Default: OKSTRA_DEFAULT_CLAUDE_MODEL or opus
   --codex-model        Model for Codex worker. Default: OKSTRA_DEFAULT_CODEX_MODEL or gpt-5.6-sol
   --antigravity-model       Model for Antigravity worker. Default: OKSTRA_DEFAULT_ANTIGRAVITY_MODEL or gemini-3.1-pro
+  --worker-model       Provider-qualified worker override CSV, e.g. grok=grok-4.5,kimi=kimi-k3.
+  --report-writer-provider
+                      Provider for report writer. Supported: claude, codex. Default: claude.
   --report-writer-model
                       Model for report writer worker. Default: OKSTRA_DEFAULT_REPORT_WRITER_MODEL or sonnet
-  --lead-runtime      Lead runtime adapter. Default: claude-code.
-                      codex is currently render-only and records Codex adapter
-                      metadata in prepared artifacts without dispatching workers.
+  --lead-runtime      Lead runtime adapter. Default: claude-code. In-host runs use the
+                      matching native lead; non-host providers use CLI wrappers.
   --executor           Provider that performs the Executor role during --task-type=implementation.
                       One of: claude | codex | antigravity. Default: OKSTRA_DEFAULT_EXECUTOR or claude.
                       The Executor is the only worker allowed to mutate project files; the other two
                       providers are dispatched as read-only verifiers regardless of this selection.
                       Has no effect on other task types.
   --critic             Provider for the opt-in Phase 5.6 critic pass (coverage gaps /
-                      acceptance devil's-advocate). One of: off | claude | codex | antigravity.
+                      acceptance devil's-advocate). One of: off | claude | codex | antigravity | grok | kimi.
                       Default: off.
   --related-tasks      Optional comma-separated related task identifiers. Example: auth-token-refresh,frontend-login-ui
   --work-category      Work-category classification for this task. One of:
@@ -121,11 +124,13 @@ options:
   -h, --help           Show this help.
 
 model defaults:
-  Claude lead: OKSTRA_DEFAULT_LEAD_MODEL or opus
-  Report writer worker: OKSTRA_DEFAULT_REPORT_WRITER_MODEL or Claude lead default
+  Host-native lead: provider policy (Claude default: opus; Codex default: gpt-5.6-sol)
+  Report writer worker: selected provider policy (Claude default: sonnet)
   Claude worker: OKSTRA_DEFAULT_CLAUDE_MODEL or opus
   Codex worker: OKSTRA_DEFAULT_CODEX_MODEL or gpt-5.6-sol
   Antigravity worker: OKSTRA_DEFAULT_ANTIGRAVITY_MODEL or gemini-3.1-pro
+  Grok worker: grok-build-0.1 (analyser) or grok-4.5 (critic)
+  Kimi worker: kimi-k2.7-code (analyser) or kimi-k3 (critic)
   Implementation executor: OKSTRA_DEFAULT_EXECUTOR or claude (one of: claude | codex | antigravity)
 
 output:

package/runtime/bin/okstra-grok-exec.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+exec python3 "$script_dir/okstra-provider-exec.py" grok "$@"

package/runtime/bin/okstra-kimi-exec.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+exec python3 "$script_dir/okstra-provider-exec.py" kimi "$@"

package/runtime/bin/okstra-provider-exec.py

@@ -0,0 +1,235 @@
+#!/usr/bin/env python3
+"""Run an external LLM CLI with the shared okstra wrapper contract."""
+from __future__ import annotations
+
+import json
+import os
+import selectors
+import shutil
+import signal
+import subprocess
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable
+
+
+@dataclass(frozen=True)
+class ProviderCommand:
+    binary: str
+    wrapper: str
+    build_args: Callable[[str, str, str], list[str]]
+
+
+def _grok_args(prompt: str, model: str, cwd: str) -> list[str]:
+    return [
+        "grok",
+        "-p",
+        prompt,
+        "-m",
+        model,
+        "--output-format",
+        "streaming-json",
+        "--cwd",
+        cwd,
+    ]
+
+
+def _kimi_args(prompt: str, model: str, _cwd: str) -> list[str]:
+    return ["kimi", "-p", prompt, "-m", model, "--output-format", "stream-json"]
+
+
+PROVIDERS = {
+    "grok": ProviderCommand("grok", "okstra-grok-exec.sh", _grok_args),
+    "kimi": ProviderCommand("kimi", "okstra-kimi-exec.sh", _kimi_args),
+}
+
+
+@dataclass(frozen=True)
+class Invocation:
+    provider: ProviderCommand
+    project_root: Path
+    model: str
+    prompt_path: Path
+    execution_root: Path
+    role: str
+    idle_timeout_seconds: int
+
+
+class PreflightError(Exception):
+    def __init__(self, exit_code: int, message: str) -> None:
+        super().__init__(message)
+        self.exit_code = exit_code
+
+
+def _parse_invocation(argv: list[str]) -> Invocation:
+    if len(argv) < 4 or len(argv) > 7:
+        raise PreflightError(
+            64,
+            "usage: okstra-provider-exec.py <provider> <project-root> <model-execution-value> "
+            "<prompt-path> [worktree-path] [role] [idle-timeout-seconds]",
+        )
+    provider_id, project_root_raw, model, prompt_raw = argv[:4]
+    provider = PROVIDERS.get(provider_id)
+    if provider is None:
+        raise PreflightError(64, f"unsupported provider: {provider_id}")
+    worktree_raw = argv[4] if len(argv) >= 5 else ""
+    role = argv[5] if len(argv) >= 6 and argv[5] else "worker"
+    default_timeout = 1500 if role in {"executor", "verifier"} else 600
+    timeout_raw = argv[6] if len(argv) >= 7 else str(default_timeout)
+    return _validate_invocation(
+        provider, project_root_raw, model, prompt_raw, worktree_raw, role, timeout_raw
+    )
+
+
+def _validate_invocation(
+    provider: ProviderCommand,
+    project_root_raw: str,
+    model: str,
+    prompt_raw: str,
+    worktree_raw: str,
+    role: str,
+    timeout_raw: str,
+) -> Invocation:
+    project_root = Path(project_root_raw)
+    prompt_path = Path(prompt_raw)
+    if not project_root_raw or not project_root.is_dir():
+        raise PreflightError(65, f"project-root is missing or not a directory: {project_root_raw!r}")
+    if not model:
+        raise PreflightError(66, "model-execution-value is empty")
+    if not prompt_raw or not prompt_path.is_file():
+        raise PreflightError(67, f"prompt-path is missing or not a file: {prompt_raw!r}")
+    if not timeout_raw.isdigit():
+        raise PreflightError(69, f"idle-timeout-seconds must be a non-negative integer: {timeout_raw!r}")
+    execution_root = Path(worktree_raw) if worktree_raw else project_root
+    if worktree_raw and not execution_root.is_dir():
+        raise PreflightError(68, f"worktree-path was provided but is not a directory: {worktree_raw!r}")
+    if shutil.which(provider.binary) is None:
+        raise PreflightError(127, f"{provider.binary} CLI is not installed on PATH")
+    return Invocation(
+        provider=provider,
+        project_root=project_root.resolve(),
+        model=model,
+        prompt_path=prompt_path.resolve(),
+        execution_root=execution_root.resolve(),
+        role=role,
+        idle_timeout_seconds=int(timeout_raw),
+    )
+
+
+def _log_path(prompt_path: Path) -> Path:
+    if prompt_path.name.endswith(".md"):
+        return prompt_path.with_name(f"{prompt_path.name[:-3]}.log")
+    return Path(f"{prompt_path}.log")
+
+
+def _write_status(path: Path, status: dict[str, object]) -> None:
+    temporary = Path(f"{path}.tmp")
+    temporary.write_text(json.dumps(status, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    os.replace(temporary, path)
+
+
+def _terminate_process(process: subprocess.Popen[bytes]) -> None:
+    try:
+        os.killpg(process.pid, signal.SIGTERM)
+    except ProcessLookupError:
+        return
+    try:
+        process.wait(timeout=5)
+    except subprocess.TimeoutExpired:
+        try:
+            os.killpg(process.pid, signal.SIGKILL)
+        except ProcessLookupError:
+            pass
+        process.wait()
+
+
+def _stream_process(
+    process: subprocess.Popen[bytes], log_file, idle_timeout_seconds: int
+) -> tuple[int, bool, int]:
+    selector = selectors.DefaultSelector()
+    assert process.stdout is not None
+    selector.register(process.stdout, selectors.EVENT_READ)
+    last_output = time.monotonic()
+    timed_out = False
+    idle_seconds = 0
+    while selector.get_map():
+        for key, _ in selector.select(timeout=0.25):
+            chunk = os.read(key.fd, 8192)
+            if not chunk:
+                selector.unregister(key.fileobj)
+                continue
+            last_output = time.monotonic()
+            sys.stdout.buffer.write(chunk)
+            sys.stdout.buffer.flush()
+            log_file.write(chunk)
+            log_file.flush()
+        idle_seconds = int(time.monotonic() - last_output)
+        if idle_timeout_seconds and idle_seconds >= idle_timeout_seconds and process.poll() is None:
+            timed_out = True
+            _terminate_process(process)
+    exit_code = process.wait()
+    return (124 if timed_out else exit_code), timed_out, idle_seconds
+
+
+def _run(invocation: Invocation) -> int:
+    prompt = invocation.prompt_path.read_text(encoding="utf-8")
+    command = invocation.provider.build_args(prompt, invocation.model, str(invocation.execution_root))
+    status_path = Path(f"{invocation.prompt_path}.status.json")
+    log_path = _log_path(invocation.prompt_path)
+    started_ts = int(time.time())
+    started_monotonic = time.monotonic()
+    status: dict[str, object] = {
+        "schemaVersion": 1,
+        "wrapper": invocation.provider.wrapper,
+        "role": invocation.role,
+        "pid": os.getpid(),
+        "started_ts": started_ts,
+        "log_path": str(log_path),
+        "stage": "started",
+    }
+    _write_status(status_path, status)
+    with log_path.open("wb") as log_file:
+        process = subprocess.Popen(
+            command,
+            cwd=invocation.execution_root,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            start_new_session=True,
+        )
+        exit_code, timed_out, idle_seconds = _stream_process(
+            process, log_file, invocation.idle_timeout_seconds
+        )
+    ended_ts = int(time.time())
+    status.update(
+        stage="exited",
+        exit_code=exit_code,
+        ended_ts=ended_ts,
+        duration_ms=int((time.monotonic() - started_monotonic) * 1000),
+    )
+    if timed_out:
+        status.update(
+            timeout=True,
+            idle_at_ts=ended_ts,
+            idle_seconds=idle_seconds,
+            terminated_by="idle-watchdog",
+        )
+    _write_status(status_path, status)
+    return exit_code
+
+
+def main(argv: list[str]) -> int:
+    try:
+        invocation = _parse_invocation(argv[1:])
+        return _run(invocation)
+    except PreflightError as exc:
+        print(f"okstra-provider-exec: {exc}", file=sys.stderr)
+        return exc.exit_code
+    except OSError as exc:
+        print(f"okstra-provider-exec: execution failed: {exc}", file=sys.stderr)
+        return 127 if isinstance(exc, FileNotFoundError) else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/runtime/bin/okstra-render-final-report.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""CLI entry for the final-report renderer.
+"""CLI entry for the schema-selected AI handoff Markdown renderer.
 
 Usage:
     python3 scripts/okstra-render-final-report.py \\
@@ -57,9 +57,9 @@ def main(argv: list[str]) -> int:
         type=Path,
         default=None,
         help=(
-            "Optional override for the Jinja2 template file. Default: "
-            "$OKSTRA_HOME/templates/reports/final-report.template.md or "
-            "the repo-local copy."
+            "Optional override for the Jinja2 template file. By default, "
+            "data.json.schemaVersion selects the matching installed or "
+            "repo-local report template."
         ),
     )
     parser.add_argument(