okstra 0.37.0 → 0.38.1

package/docs/kr/architecture.md

@@ -257,7 +257,7 @@ Claude launch prompt 본문은 항상 `prompts/launch.template.md` 템플릿에
 - 메인 Claude는 항상 `Claude lead`이며 synthesis-only로 동작합니다.
 - 기본 required worker role은 `Claude worker`, `Codex worker`, `Report writer worker`입니다. `Gemini worker`는 옵션 워커로, `--workers` 또는 프로필의 `- Workers:` 섹션에 명시될 때만 required 로 포함됩니다.
 - `Report writer worker`는 보고서 구조화와 근거 정리에 집중하지만 최종 synthesis owner는 여전히 `Claude lead`입니다.
-- 기본 모델 계약은 중앙 기본값에서 계산합니다. 기본 fallback은 `Claude lead`=`opus-4-6`, `Claude worker`=`sonnet`, `Codex worker`=`gpt-5.5`, `Gemini worker`=`auto`(opt-in 시 적용)이며, `Report writer worker`는 별도 override가 없으면 `Claude lead` 모델을 따릅니다(즉, 기본값에서는 `opus-4-6`).
+- 기본 모델 계약은 중앙 기본값에서 계산합니다. 기본 fallback은 `Claude lead`=`opus`, `Claude worker`=`opus`, `Codex worker`=`gpt-5.5`, `Gemini worker`=`auto`(opt-in 시 적용)이며, `Report writer worker`는 별도 override가 없으면 `Claude lead` 모델을 따릅니다(즉, 기본값에서는 `opus`).
 - `Gemini worker`는 옵션이므로 명시 포함된 run에 한해서만 시도 대상이 됩니다.
 - 최종 판단 전에는 현재 run의 worker roster 에 포함된 각 required role별로 결과 또는 명시적인 terminal status(`completed`, `timeout`, `error`, `not-run`)가 필요합니다.
 - 시도된 worker(`completed`, `timeout`, `error`)는 현재 run의 `prompts/` 아래 assigned worker prompt history file을 반드시 가져야 합니다.
@@ -943,7 +943,7 @@ phase 산출물의 출고 가능 여부를 강제하는 진입점:
 - run directory 내부는 `manifests/`, `state/`, `prompts/`, `reports/`, `status/`, `sessions/`, `worker-results/`처럼 유형별 하위 폴더로 구성되고, prompt snapshot은 `prompts/` 아래에 먼저 준비됩니다.
 - worker 생성과 결과 취합은 Claude가 수행합니다.
 - standard workflow는 `Claude lead` + 기본 worker `Claude worker`, `Codex worker`, `Report writer worker`를 사용하고, `Gemini worker`는 명시할 때만 포함되는 옵션입니다.
-- worker 모델은 `--lead-model`, `--claude-model`, `--codex-model`, `--gemini-model`, `--report-writer-model`로 override할 수 있고, 기본값은 `OKSTRA_DEFAULT_*` 환경 변수에서 중앙 관리합니다. fallback 기본값은 `Claude lead`/`Report writer worker`=`opus-4-6`, `Claude worker`=`sonnet`, `Codex worker`=`gpt-5.5`, `Gemini worker`=`auto`입니다.
+- worker 모델은 `--lead-model`, `--claude-model`, `--codex-model`, `--gemini-model`, `--report-writer-model`로 override할 수 있고, 기본값은 `OKSTRA_DEFAULT_*` 환경 변수에서 중앙 관리합니다. fallback 기본값은 `Claude lead`/`Report writer worker`=`opus`, `Claude worker`=`opus`, `Codex worker`=`gpt-5.5`, `Gemini worker`=`auto`입니다.
 - `--task-type implementation` 에서는 Executor 역할을 맡을 provider 를 `--executor <claude|codex|gemini>` (또는 `OKSTRA_DEFAULT_EXECUTOR`, fallback `claude`) 로 선택합니다. Executor 만 프로젝트 파일을 mutate 할 수 있고, 나머지 두 provider 와 자기 자신의 provider 가 모두 별도 CLI 세션으로 verifier 로 dispatch 됩니다 (세션 분리만으로도 self-review 안전장치 유지). Executor 의 모델은 선택된 provider 의 worker 모델 플래그(`--claude-model` / `--codex-model` / `--gemini-model`) 를 그대로 재사용하며, run-manifest 의 `teamContract.executor` 블록에 provider / displayName / workerAgent / model 이 기록됩니다.
 - Executor 별 worktree cwd 주입: codex / gemini executor 는 wrapper(`okstra-codex-exec.sh -C` / `okstra-gemini-exec.sh --include-directories`) 가 CLI layer 에서 cwd 를 worktree 로 고정합니다. Claude executor 는 Bash tool 에 per-call cwd 인자가 없어 cwd 민감 toolchain (`cargo`/`npm`/`pnpm`/`bun`/`pytest`/`make`/`go`) 호출을 같은 Bash invocation 안에서 `cd {{EXECUTOR_WORKTREE_PATH}} && <cmd>` 로 prefix 합니다 — `bash -lc`/`bash -c` 래핑은 금지되며 (`cd` leading token 이 가려져 permission auto-allow 우회 실패), 작업 디렉터리 플래그 (`git -C`, `cargo --manifest-path` 등) 가 있으면 그것을 우선합니다. 자세한 규약은 `prompts/profiles/implementation.md` 의 *Executor Worktree* 블록과 `agents/workers/claude-worker.md` 의 Executor exception 항목 참고.
 - project-level current-task convenience pointer는 `.okstra/discovery/latest-task.json`입니다.

package/docs/kr/cli.md

@@ -302,12 +302,12 @@ scripts/okstra.sh --task-type implementation-planning --workers claude,codex --p
 ### `--claude-model`
 
 `Claude worker`에 사용할 모델을 지정합니다.
-지정하지 않으면 중앙 기본값 `OKSTRA_DEFAULT_CLAUDE_MODEL` 또는 fallback `sonnet`을 사용합니다.
+지정하지 않으면 중앙 기본값 `OKSTRA_DEFAULT_CLAUDE_MODEL` 또는 fallback `opus`을 사용합니다.
 
 ### `--lead-model`
 
 `Claude lead`에 사용할 모델을 지정합니다.
-지정하지 않으면 중앙 기본값 `OKSTRA_DEFAULT_LEAD_MODEL` 또는 fallback `opus-4-6`를 사용합니다.
+지정하지 않으면 중앙 기본값 `OKSTRA_DEFAULT_LEAD_MODEL` 또는 fallback `opus`을 사용합니다.
 
 ### `--codex-model`
 
@@ -337,7 +337,7 @@ fallback 기본값은 아래와 같습니다.
 
 - `Claude lead`: `opus`
 - `Report writer worker`: `opus`
-- `Claude worker`: `sonnet`
+- `Claude worker`: `opus`
 - `Codex worker`: `gpt-5.5`
 - `Gemini worker`: `auto`
 - Implementation executor: `claude` (즉 기본은 `Claude executor`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.37.0",
+  "version": "0.38.1",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.37.0",
-  "builtAt": "2026-05-27T07:29:11.725Z",
+  "package": "0.38.1",
+  "builtAt": "2026-05-29T06:34:56.309Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/SKILL.md

@@ -100,19 +100,21 @@ These lines are the only structured signal the user has during a long run. Do NO
 
 `okstra-run` (in-session) surfaces these lines to the user directly; the bash-spawned path leaves them in the session jsonl for post-hoc retrieval. Neither path requires any additional formatting from Lead — emit the literal `PROGRESS:` prefix and the rest of the line as plain text.
 
-## Default model assignments
+## Model assignments
 
-Unless the task bundle overrides:
+**The lead never invents a model.** Every role's model is read from `task-manifest.json` → `resultContract.requiredWorkerRoles[*].modelExecutionValue` (and the lead model metadata). A missing assignment is a manifest defect, not a license to fall back — see [okstra-team-contract](./skills/okstra-team-contract/SKILL.md) "Model Assignment Rules". The manifest is always populated at run-prep time by the CLI, which seeds these values from `OKSTRA_DEFAULT_*_MODEL` (`scripts/okstra_ctl/run.py`).
 
-| Role | Model | subagent_type | Notes |
-|------|-------|---------------|-------|
-| Claude lead | opus-4-6 | -- | orchestration + synthesis |
-| Report writer worker | opus-4-6 | report-writer-worker | authors the final report file (`agents/report-writer-worker.md`) |
-| Claude worker | sonnet | claude-worker | defined in `agents/claude-worker.md` |
-| Codex worker | gpt-5.5 | codex-worker | defined in `agents/codex-worker.md` |
-| Gemini worker | auto | gemini-worker | defined in `agents/gemini-worker.md` |
+The table below documents those prep-time seed values **for reference only** — it is NOT a lead-applied fallback:
 
-If the prepared task bundle contains explicit model assignments, those assignments are canonical for the run. All three analysis workers use dedicated agent definitions; Codex/Gemini wrappers handle external CLI invocation internally; Claude worker runs as an in-process subagent with explicitly registered MCP tools so it does not fall back to `claude --mcp-cli` Bash invocations.
+| Role | Seed model | subagent_type | Source definition |
+|------|-----------|---------------|-------------------|
+| Claude lead | opus | -- | orchestration + convergence supervision + final-report review/approval |
+| Report writer worker | opus | report-writer-worker | `agents/workers/report-writer-worker.md` |
+| Claude worker | opus | claude-worker | `agents/workers/claude-worker.md` |
+| Codex worker | gpt-5.5 | codex-worker | generated from `agents/workers/_cli-wrapper-template.md` + `codex-worker.params.json` |
+| Gemini worker | auto | gemini-worker | generated from `agents/workers/_cli-wrapper-template.md` + `gemini-worker.params.json` |
+
+All three analysis workers use dedicated agent definitions; Codex/Gemini wrappers handle external CLI invocation internally; Claude worker runs as an in-process subagent with explicitly registered MCP tools so it does not fall back to `claude --mcp-cli` Bash invocations.
 
 ### Implementation phase: Executor binding
 
@@ -263,7 +265,7 @@ If convergence is disabled, proceed directly to Phase 6 with the raw worker resu
 
 ### Authoring ownership (BLOCKING)
 
-If `Report writer worker` is in the selected roster (`recommendedWorkers` / `resultContract.requiredWorkerRoles`), **Lead MUST dispatch it to write `runs/<task-type>/reports/final-report-<task-type>-<seq>.md`**. Lead does NOT write that file. Lead's role in this phase is: prepare the report-writer prompt (carrying convergence output, all worker results, and reference expectations), dispatch, then review the produced file.
+If `Report writer worker` is in the selected roster (`recommendedWorkers` / `resultContract.requiredWorkerRoles`), **Lead MUST dispatch it to author the final report**. The worker writes the JSON SSOT at `runs/<task-type>/reports/final-report-<task-type>-<seq>.data.json` and invokes `scripts/okstra-render-final-report.py` to produce the sibling `final-report-<task-type>-<seq>.md` — Lead writes neither file. Lead's role in this phase is: prepare the report-writer prompt (carrying convergence output, all worker results, and reference expectations), dispatch, then review the produced files. See [okstra-report-writer](./skills/okstra-report-writer/SKILL.md) "File-author ownership".
 
 Before constructing the dispatch prompt, the lead MUST:
 
@@ -290,7 +292,7 @@ If only one worker result is usable: reduced-confidence synthesis. If evidence i
 
 After the Report writer worker draft is reviewed (or after the lead-authored fallback completes), **if** `task_type == "implementation-planning"` **and** `task-manifest.json` `convergence.planBodyVerification.enabled == true` (default), the lead MUST run one additional verification round on the consolidated plan body before declaring Phase 6 complete and entering Phase 7.
 
-This is a Phase 6 sub-step — it does NOT introduce a new top-level lifecycle phase. The 6-phase model (1 Intake → 2 Render → 3 Team → 4 Workers → 5 Synthesis prep → 5.5 Convergence → 6 Synthesis → 7 Persist) is preserved.
+This is a Phase 6 sub-step — it does NOT introduce a new top-level lifecycle phase. The lead operating-phase model (Phase 1 Intake → Phase 7 Persist, with the labels in the "Quick Reference" table above as the single source of truth) is preserved.
 
 **REQUIRED SUB-SKILL:** Invoke [okstra-convergence](./skills/okstra-convergence/SKILL.md) "Plan-body verification mode (implementation-planning only)" for the round protocol, plan-item ID scheme (`P-Opt-*` / `P-Step-*` / `P-Dep-*` / `P-Val-*` / `P-Rb-*`), verdict semantics (`AGREE` / `DISAGREE(a-e)` / `SUPPLEMENT`), classification rules, gate-result resolution, and the state-file schema at `runs/<task-type>/state/plan-body-verification.json`.
 

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

@@ -35,7 +35,7 @@ You also write an audit sidecar at the path the lead registers as `**Worker Resu
 1. The canonical data.json path you wrote (project-relative).
 2. The rendered markdown path produced by the renderer (project-relative).
 3. Inputs reconciled (analysis-worker result files + convergence-state file).
-4. Any structural deviations from `schemas/final-report-v1.0.schema.json` and the reason.
+4. Any structural deviations from the `<instruction-set>/final-report-schema.json` excerpt and the reason.
 
 Do NOT duplicate the data.json contents here — the data.json is the canonical artifact; this sidecar is the validator-required pointer / audit record.
 
@@ -67,8 +67,8 @@ Before writing the data.json, you MUST:
 
 For the report writer specifically, the `## Inputs` list always includes:
 
-- `schemas/final-report-v1.0.schema.json` — the JSON Schema you must conform to. The renderer + validator both consume it.
-- `templates/reports/final-report.template.md` — the Jinja2 template the renderer uses. Read it to understand which data.json fields appear where in the rendered markdown; do NOT edit it.
+- `<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.
+- `<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.
 - `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 1 Round History sub-table — do not recompute from worker results.
@@ -79,7 +79,7 @@ Write a Reading Confirmation block to your **audit sidecar** at `runs/<task-type
 
 ## Authoring Contract
 
-You author the final-report data.json (the JSON SSOT). The schema is `schemas/final-report-v1.0.schema.json` — its `$defs` enumerate every row shape, enum value, and cross-field constraint. The validator rejects data that violates the schema; the renderer refuses to render against invalid data. Both consume the same schema, so a data.json that validates is a data.json that 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 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.
 
 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 Phase 7 step 1.5 (`scripts/okstra-render-report-views.py`). The data.json is the only file you write; the rest are derived.
 

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

@@ -128,7 +128,10 @@ def main(argv: list[str] | None = None) -> int:
     css, js = _load_assets()
     meta = RunMeta(task_key=task_key, task_type=task_type, seq=seq, source_report=source_report)
     html_path = render_html_view(report_path, run_meta=meta, css=css, js=js)
-    print(f"html: {html_path}")
+    if html_path is None:
+        print("html: skipped (no §5 clarification rows — html view carries no interactive forms for this report)")
+    else:
+        print(f"html: {html_path}")
     return 0
 
 

package/runtime/prompts/launch.template.md

@@ -81,7 +81,7 @@ Emit one `PROGRESS: <phase-id> <verb-phrase>` line as plain user-facing text at
 ## Available MCP Servers
 
 {{AVAILABLE_MCP_SERVERS}}
-- The full usage policy and per-phase rules live in the task brief's `## Available MCP Servers` section. Read them there before dispatching workers and **forward that section verbatim into every worker prompt** during Phase 2 so workers know they are allowed to call these tools.
+- The full usage policy and per-phase rules live in the task brief's `## Available MCP Servers` section. Read them there before dispatching workers and inject only the one-line pointer below into each worker prompt (the brief is already in every worker's [Required reading], so verbatim copy is redundant): `**MCP servers:** follow the task brief's "## Available MCP Servers" section (already in your Required reading).`
 - **Invocation rule (forward to every worker prompt)**: MCP tools are addressed by their tool name through the host's tool interface — **never via `Bash`**. Claude-side workers call the tool directly (e.g. `mcp__<server>__<tool>`). Codex/Gemini workers call through their CLI's own MCP transport (e.g. `codex mcp call ...`). Running the tool name as a shell command is a contract violation and will always fail regardless of permission grants.
 - Codex worker and Gemini worker run external CLIs; they can only use these MCP servers if their own CLI configs mirror them. If not, instruct the worker to record `MCP not available in this CLI` in its `Missing Information or Assumptions` block rather than guessing or shell-falling-back.
 - MCP queries are evidence-grade. Cite server, table, and the SELECT used in worker output. MCP must NOT be used as a write path in any phase, including `implementation`.

package/runtime/prompts/profiles/_common-contract.md

@@ -8,7 +8,7 @@ profile document.
 - Team contract (shared):
   - `Claude lead` is synthesis-only and stays distinct from `Claude worker` (or, in `implementation`, the `Executor` and verifiers).
   - `Report writer worker` is the **author** of the final-report file; `Claude lead` reviews and approves the produced draft and does NOT write the file itself (see `okstra-team-contract` and `okstra-report-writer` for the authoritative contract).
-  - default model assignments are resolved from centralised defaults; the fallback values are `Claude lead`/`Report writer worker`=`opus`, `Claude worker`=`sonnet`, `Codex worker`=`gpt-5.5`, `Gemini worker`=`auto`. Phase-specific overrides (e.g. `implementation`'s executor binding) live in the per-profile document.
+  - default model assignments are resolved from centralised defaults; the fallback values are `Claude lead`/`Report writer worker`=`opus`, `Claude worker`=`opus`, `Codex worker`=`gpt-5.5`, `Gemini worker`=`auto`. Phase-specific overrides (e.g. `implementation`'s executor binding) live in the per-profile document.
   - every required worker listed in the per-profile `Required workers:` block must be attempted; the final verdict waits until each has either a result or an explicit terminal status (`timeout`, `error`, `not-run`).
   - unnamed generic parallel workers must not replace the required role roster, and no additional sub-agent dispatch is allowed beyond this roster.
 - Worker interaction model (shared — read before inferring behaviour from the roster):

package/runtime/prompts/profiles/_implementation-verifier.md

@@ -11,7 +11,7 @@ at Phase 5, BEFORE constructing the verifier worker dispatch prompts.
 
 - The verifier slots are `Claude verifier` and `Codex verifier`, plus `Gemini verifier` **only when `gemini` is in the resolved `--workers` roster**. Every verifier in the resolved roster is dispatched regardless of which provider holds the executor role; the executor's own provider is run *separately* as a verifier (a fresh CLI session with no shared context) so that no verdict is produced from the same session that wrote the diff. Verifiers MUST NOT call Edit, Write, or any Bash command that mutates files outside the run's artifact directories. If a verifier wants a fix, it records the recommendation in its worker result; it does not apply the fix itself.
 - Session isolation — not model-variant divergence — is the primary self-review safeguard: each verifier is a separate CLI invocation with its own context window, so reusing the same model variant for executor and same-provider verifier is acceptable. Different model variants (e.g. executor=opus / Claude verifier=sonnet) remain recommended when available.
-- Phase-specific model defaults override the shared defaults: `Claude verifier`=`sonnet`, `Codex verifier`=`gpt-5.5`, `Gemini verifier`=`auto` (only when present in the roster). The `Executor`'s model is taken from the provider-specific worker model corresponding to `--executor`: claude→`--claude-model` (default `sonnet`, override to `opus` recommended when this run's executor is claude), codex→`--codex-model` (default `gpt-5.5`), gemini→`--gemini-model` (default `auto`).
+- Phase-specific model defaults override the shared defaults: `Claude verifier`=`opus`, `Codex verifier`=`gpt-5.5`, `Gemini verifier`=`auto` (only when present in the roster). The `Executor`'s model is taken from the provider-specific worker model corresponding to `--executor`: claude→`--claude-model` (default `opus`), codex→`--codex-model` (default `gpt-5.5`), gemini→`--gemini-model` (default `auto`).
 - Verifiers read from the SAME working tree path the Executor used so they observe the exact diff the Executor produced. Verifiers remain strictly read-only there.
 
 ## Verifier QA duties (independent re-run mandate)

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

@@ -154,8 +154,8 @@ GEMINI_WORKER_MODEL_EXECUTION_VALUE=""
 REPORT_WRITER_MODEL=""
 REPORT_WRITER_MODEL_EXECUTION_VALUE=""
 DEFAULT_WORKERS="claude,codex,report-writer"
-DEFAULT_LEAD_MODEL_NAME="${OKSTRA_DEFAULT_LEAD_MODEL:-opus-4-6}"
-DEFAULT_CLAUDE_WORKER_MODEL_NAME="${OKSTRA_DEFAULT_CLAUDE_MODEL:-sonnet}"
+DEFAULT_LEAD_MODEL_NAME="${OKSTRA_DEFAULT_LEAD_MODEL:-opus}"
+DEFAULT_CLAUDE_WORKER_MODEL_NAME="${OKSTRA_DEFAULT_CLAUDE_MODEL:-opus}"
 DEFAULT_CODEX_WORKER_MODEL_NAME="${OKSTRA_DEFAULT_CODEX_MODEL:-gpt-5.5}"
 DEFAULT_GEMINI_WORKER_MODEL_NAME="${OKSTRA_DEFAULT_GEMINI_MODEL:-auto}"
 DEFAULT_REPORT_WRITER_MODEL_NAME="${OKSTRA_DEFAULT_REPORT_WRITER_MODEL:-$DEFAULT_LEAD_MODEL_NAME}"

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

@@ -71,8 +71,8 @@ options:
   --yes                Skip interactive prompting and confirmation. Requires all required arguments.
   --workers            Comma-separated worker list for this run. Default: claude,codex,report-writer
                       (Gemini worker is optional; add `gemini` explicitly, e.g. --workers claude,codex,gemini,report-writer)
-  --lead-model         Model for Claude lead. Default: OKSTRA_DEFAULT_LEAD_MODEL or opus-4-6
-  --claude-model       Model for Claude worker. Default: OKSTRA_DEFAULT_CLAUDE_MODEL or sonnet
+  --lead-model         Model for Claude lead. Default: OKSTRA_DEFAULT_LEAD_MODEL or opus
+  --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.5
   --gemini-model       Model for Gemini worker. Default: OKSTRA_DEFAULT_GEMINI_MODEL or auto
   --report-writer-model
@@ -98,9 +98,9 @@ options:
   -h, --help           Show this help.
 
 model defaults:
-  Claude lead: OKSTRA_DEFAULT_LEAD_MODEL or opus-4-6
+  Claude lead: OKSTRA_DEFAULT_LEAD_MODEL or opus
   Report writer worker: OKSTRA_DEFAULT_REPORT_WRITER_MODEL or Claude lead default
-  Claude worker: OKSTRA_DEFAULT_CLAUDE_MODEL or sonnet
+  Claude worker: OKSTRA_DEFAULT_CLAUDE_MODEL or opus
   Codex worker: OKSTRA_DEFAULT_CODEX_MODEL or gpt-5.5
   Gemini worker: OKSTRA_DEFAULT_GEMINI_MODEL or auto
   Implementation executor: OKSTRA_DEFAULT_EXECUTOR or claude (one of: claude | codex | gemini)

package/runtime/python/okstra_ctl/paths.py

@@ -144,6 +144,7 @@ def compute_run_paths(
     final_status = run_status / f"final{suffixes['status']}.status"
     team_state = run_state / f"team-state{suffixes['state']}.json"
     final_report_template = instruction_set / "final-report-template.md"
+    final_report_schema = instruction_set / "final-report-schema.json"
     reference_expectations = instruction_set / "reference-expectations.md"
     claude_resume_command = run_sessions / f"claude-resume{suffixes['sessions']}.sh"
     latest_task_file = discovery_dir / "latest-task.json"
@@ -205,6 +206,7 @@ def compute_run_paths(
         "FINAL_STATUS_PATH": str(final_status),
         "TEAM_STATE_PATH": str(team_state),
         "FINAL_REPORT_TEMPLATE_PATH": str(final_report_template),
+        "FINAL_REPORT_SCHEMA_PATH": str(final_report_schema),
         "REFERENCE_EXPECTATIONS_FILE": str(reference_expectations),
         "CLAUDE_RESUME_COMMAND_PATH": str(claude_resume_command),
         "OKSTRA_LATEST_TASK_FILE": str(latest_task_file),
@@ -264,6 +266,7 @@ def compute_run_paths(
         ("WORKER_RESULTS_RELATIVE_PATH", worker_results),
         ("RUN_CARRY_RELATIVE_PATH", run_carry),
         ("FINAL_REPORT_TEMPLATE_RELATIVE_PATH", final_report_template),
+        ("FINAL_REPORT_SCHEMA_RELATIVE_PATH", final_report_schema),
         ("REFERENCE_EXPECTATIONS_RELATIVE_PATH", reference_expectations),
         ("CLAUDE_RESUME_COMMAND_RELATIVE_PATH", claude_resume_command),
         ("RUN_VALIDATOR_RELATIVE_PATH", run_validator_script),

package/runtime/python/okstra_ctl/report_views.py

@@ -664,17 +664,41 @@ def serialize_user_response(
 # Convenience entrypoint for tests + CLI.
 # --------------------------------------------------------------------------- #
 
+def report_has_clarification_items(src_md: str) -> bool:
+    """True when the final-report MD has at least one §5 ``C-*``
+    clarification row. This is the single predicate that gates HTML-view
+    generation: the self-contained html's only value over the markdown is
+    the embedded ``<form>`` widgets for those rows, so a clarification-free
+    report does not get an html sibling. The renderer, the CLI, and
+    ``validators/validate-report-views.py`` all key off this same function
+    so generation and validation never disagree."""
+    return any(
+        re.fullmatch(r"C-\d+", item.row_id)
+        for item in (parse_clarification_items(src_md) or [])
+    )
+
+
 def render_html_view(
     src_md_path: Path,
     *,
     run_meta: RunMeta,
     css: str,
     js: str,
-) -> Path:
-    """Write ``<stem>.html`` next to ``src_md_path`` and return its
-    path. Idempotent — overwrites the existing html sibling."""
+) -> Path | None:
+    """Write ``<stem>.html`` next to ``src_md_path`` and return its path,
+    or return ``None`` when generation is skipped because the report has
+    no §5 clarification rows (see ``report_has_clarification_items``).
+    Idempotent — overwrites an existing html sibling, and removes a stale
+    one when a previously-clarification-bearing report no longer has rows."""
     src_text = src_md_path.read_text(encoding="utf-8")
     html_path = src_md_path.with_name(src_md_path.stem + ".html")
+    if not report_has_clarification_items(src_text):
+        # Conditional generation: no interactive forms to render. Drop any
+        # stale html left over from a prior clarification-bearing run so the
+        # validator's "no rows → no html" branch stays consistent.
+        if html_path.is_file():
+            html_path.unlink()
+        return None
     html_text = render_html(src_text, run_meta=run_meta, css=css, js=js)
     html_path.write_text(html_text, encoding="utf-8")
     return html_path

package/runtime/python/okstra_ctl/run.py

@@ -35,7 +35,9 @@ from .material import (
     related_tasks_inline,
     resolve_related_tasks,
 )
+from .final_report_schema import load_schema
 from .models import resolve_model_metadata
+from .schema_excerpt import build_schema_excerpt
 from .path_resolve import relative_to_project_root, resolve_user_file
 from .render import (
     apply_lead_prompt_defaults,
@@ -667,8 +669,8 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         pr_template_source = resolved_tpl.source
 
     # ---- model assignments ----
-    lead_default = _default("OKSTRA_DEFAULT_LEAD_MODEL", "opus-4-6")
-    claude_default = _default("OKSTRA_DEFAULT_CLAUDE_MODEL", "sonnet")
+    lead_default = _default("OKSTRA_DEFAULT_LEAD_MODEL", "opus")
+    claude_default = _default("OKSTRA_DEFAULT_CLAUDE_MODEL", "opus")
     codex_default = _default("OKSTRA_DEFAULT_CODEX_MODEL", "gpt-5.5")
     gemini_default = _default("OKSTRA_DEFAULT_GEMINI_MODEL", "auto")
     report_writer_default = _default("OKSTRA_DEFAULT_REPORT_WRITER_MODEL", lead_default)
@@ -932,6 +934,26 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     render_template_with_ctx(
         str(final_report_template), ctx["FINAL_REPORT_TEMPLATE_PATH"], ctx,
     )
+    # Per-task-type schema excerpt for the report-writer worker. The full
+    # schema validates the data.json post-hoc (load_schema); the worker only
+    # needs the common structure + this run's task-type block, so we write a
+    # scoped excerpt into the instruction-set rather than make the worker read
+    # the whole 44 KB / all-task-types schema (whose repo `schemas/...` path is
+    # not resolvable from a consumer project's task bundle anyway).
+    #
+    # Guarded: a missing/unreadable schema must NOT break bundle preparation.
+    # If the excerpt cannot be produced (e.g. an older install that predates
+    # the schemas/ copy step), prep proceeds without it — the report-writer
+    # still has the phase-stripped template + skill structure guide, and
+    # validation runs against the full schema regardless.
+    try:
+        _excerpt = build_schema_excerpt(load_schema(), inp.task_type)
+        Path(ctx["FINAL_REPORT_SCHEMA_PATH"]).write_text(
+            json.dumps(_excerpt, indent=2, ensure_ascii=False) + "\n",
+            encoding="utf-8",
+        )
+    except Exception:  # noqa: BLE001 — advisory artifact; never fail prep over it
+        pass
     render_template_with_ctx(
         str(prompt_template), str(instruction_set / "claude-execution-prompt.md"), ctx,
     )

package/runtime/python/okstra_ctl/schema_excerpt.py

@@ -0,0 +1,116 @@
+"""Build a task-type-scoped excerpt of the final-report schema.
+
+The full schema (``schemas/final-report-v1.0.schema.json``) carries the
+deliverable property blocks for ALL task-types (``implementationPlanning``,
+``releaseHandoff``, ``implementation``, ``finalVerification``) plus a
+``$defs`` library (~38% of the file) shared across them. A single run only
+authors ONE task-type's data.json, so the report-writer worker only needs
+the common structure + its own task-type's block + the ``$defs`` those
+reach.
+
+This module produces that scoped excerpt, written into the run's
+instruction-set at prep time so the worker reads a smaller, path-local
+file (`instruction-set/final-report-schema.json`) instead of the full
+repo/installed schema (whose `schemas/...` path is not even resolvable
+from inside a consumer project's task bundle).
+
+The excerpt is ADVISORY — a reading aid for the author. Validation always
+runs against the FULL schema via ``final_report_schema.load_schema()``, so
+the excerpt never gates correctness; it only trims what the worker reads.
+"""
+from __future__ import annotations
+
+import json
+import re
+
+# task-type → the per-type deliverable property key it owns. task-types
+# absent from this map (requirements-discovery, error-analysis,
+# improvement-discovery) have no per-type block; their excerpt keeps only
+# the common properties.
+_TASK_TYPE_PROPERTY = {
+    "implementation-planning": "implementationPlanning",
+    "release-handoff": "releaseHandoff",
+    "implementation": "implementation",
+    "final-verification": "finalVerification",
+}
+_ALL_PER_TYPE_PROPERTIES = frozenset(_TASK_TYPE_PROPERTY.values())
+
+_REF_RE = re.compile(r'"\$ref"\s*:\s*"#/\$defs/([^"]+)"')
+
+
+def _refs_in(obj) -> set[str]:
+    """Every ``#/$defs/<name>`` referenced anywhere inside ``obj``."""
+    return set(_REF_RE.findall(json.dumps(obj)))
+
+
+def _conditional_applies(entry: dict, task_type: str) -> bool:
+    """True when an ``allOf`` if/then entry is relevant to *task_type*.
+
+    Universal entries (no ``header.taskType`` constraint) always apply;
+    ``const`` entries apply on exact match; ``enum`` entries apply when
+    *task_type* is a member.
+    """
+    constraint = (
+        entry.get("if", {})
+        .get("properties", {})
+        .get("header", {})
+        .get("properties", {})
+        .get("taskType", {})
+    )
+    const = constraint.get("const")
+    enum = constraint.get("enum")
+    if const is None and enum is None:
+        return True
+    if const is not None:
+        return const == task_type
+    return task_type in (enum or [])
+
+
+def build_schema_excerpt(schema: dict, task_type: str) -> dict:
+    """Return a task-type-scoped copy of *schema*.
+
+    Drops the per-type property blocks that do not belong to *task_type*,
+    the ``allOf`` conditionals that cannot fire for it, and the ``$defs``
+    that become unreachable as a result (transitive closure preserves any
+    def reachable from a kept property or conditional). Top-level metadata
+    and ``required`` are preserved (``required`` never lists per-type
+    blocks, but it is filtered defensively).
+    """
+    keep_per_type = _TASK_TYPE_PROPERTY.get(task_type)
+    drop_props = _ALL_PER_TYPE_PROPERTIES - ({keep_per_type} if keep_per_type else set())
+
+    props = {
+        k: v for k, v in schema.get("properties", {}).items() if k not in drop_props
+    }
+    all_of = [e for e in schema.get("allOf", []) if _conditional_applies(e, task_type)]
+
+    # Reachable $defs = transitive closure of $ref from kept props + allOf.
+    defs = schema.get("$defs", {})
+    reachable: set[str] = set()
+    work = list(_refs_in(props) | _refs_in(all_of))
+    while work:
+        name = work.pop()
+        if name in reachable or name not in defs:
+            continue
+        reachable.add(name)
+        work.extend(_refs_in(defs[name]))
+
+    excerpt = {
+        k: v
+        for k, v in schema.items()
+        if k not in ("properties", "allOf", "$defs", "required", "description")
+    }
+    excerpt["description"] = (
+        f"Per-task-type excerpt of the okstra final-report schema, scoped to "
+        f"`{task_type}`. Reading aid for the report-writer worker — validation "
+        f"runs against the full schema (schemas/final-report-v1.0.schema.json)."
+    )
+    excerpt["properties"] = props
+    excerpt["required"] = [
+        r for r in schema.get("required", []) if r not in drop_props
+    ]
+    if all_of:
+        excerpt["allOf"] = all_of
+    if reachable:
+        excerpt["$defs"] = {k: v for k, v in defs.items() if k in reachable}
+    return excerpt

package/runtime/skills/okstra-convergence/SKILL.md

@@ -322,8 +322,6 @@ For each finding:
 
 Save it to `runs/<task-type>/state/convergence-<task-type>-<seq>.json`.
 
-Schema version `1.1` extends `1.0` (legacy fields kept as aliases for backward-compat with already-shipped reports):
-
 ```json
 {
   "schemaVersion": "1.1",
@@ -368,12 +366,7 @@ Schema version `1.1` extends `1.0` (legacy fields kept as aliases for backward-c
       ],
       "skippedWorkers": [
         { "worker": "claude-worker", "reason": "no items to verify" }
-      ],
-      "verificationsRequested": 2,
-      "verificationsCompleted": 2,
-      "newConsensus": 3,
-      "remainingInQueue": 0,
-      "earlyExit": true
+      ]
     }
   ],
   "round2SkippedReason": "queue-empty",
@@ -384,12 +377,6 @@ Schema version `1.1` extends `1.0` (legacy fields kept as aliases for backward-c
     "partialConsensus": 1,
     "contested": 0,
     "workerUnique": 1
-  },
-  "summary": {
-    "fullConsensus": 5,
-    "partialConsensus": 1,
-    "contested": 0,
-    "workerUnique": 1
   }
 }
 ```
@@ -408,9 +395,8 @@ Schema rules:
 - `roundHistory[].carriedForwardCount`: queue size at the END of this round — the single definition. In-round insertions into the queue are forbidden, so this always equals `inputQueueSize - resolvedCount`. The pseudocode's per-item `carriedForwardCount += 1` accumulator is a counting convenience that lands on the same value; persist the post-round queue length, not the loop accumulator, if the two ever diverge.
 - `roundHistory[].dispatches[]`: one entry per worker that was actually dispatched in this round. Each entry is `{worker, status, durationMs}`. `status ∈ {completed, timeout, error, not-run}`. `durationMs` is integer milliseconds and is always present, even for terminal-non-result dispatches (use the elapsed time before the wrapper gave up).
 - `roundHistory[].skippedWorkers[]`: per-worker `{worker, reason}` for workers with no items to verify OR with a non-result dispatch.
-- `roundHistory[].verificationsRequested|verificationsCompleted|newConsensus|remainingInQueue|earlyExit`: legacy v1.0 aliases. New runs SHOULD populate them so existing parsers keep working: `verificationsRequested == len(dispatches)`, `verificationsCompleted == len(d for d in dispatches if d.status == "completed")`, `newConsensus == resolvedCount`, `remainingInQueue == carriedForwardCount`, `earlyExit == (round < effectiveMaxRounds AND carriedForwardCount == 0)`.
 - `round2SkippedReason`: literal enum `queue-empty | max-rounds-1 | all-reverify-non-result | not-skipped`. Always present. Use `"not-skipped"` when Round 2 actually ran. Use `"max-rounds-1"` when `effectiveMaxRounds == 1` (Round 2 was never attempted). Use `"queue-empty"` when Round 1 fully drained the queue. Use `"all-reverify-non-result"` when all Round 1 dispatches terminated as non-result.
-- `finalClassificationCounts`: post-loop counts. New required field — must equal `summary` 1:1. `summary` is retained as the v1.0 alias.
+- `finalClassificationCounts`: post-loop counts. Required field with keys `fullConsensus`, `partialConsensus`, `contested`, `workerUnique`.
 - `finalState ∈ {converged, max-rounds-reached, aborted-non-result}`. Assigned by the lead at WHILE-loop exit: `converged` when the queue is empty at the end of any round; `max-rounds-reached` when the loop exits because `roundIndex == effectiveMaxRounds` with the queue still non-empty; `aborted-non-result` when the loop exits via the Worker-failure BREAK (Task 3's "Worker failure handling in reverify" rule 4). `aborted-non-result` is the new v1.1 value.
 - `totalRounds`: count of rounds actually executed (not `effectiveMaxRounds`). May be `0` when Round 0 produced no queue items (all findings reached consensus during grouping).
 

package/runtime/skills/okstra-report-writer/SKILL.md

@@ -46,9 +46,11 @@ The prompt MUST include, in this order at the top:
 4. `**Worker Result Path:** runs/<task-type>/worker-results/report-writer-worker-<task-type>-<seq>.md` — mandatory validator-checked worker-results audit file
 5. `Assigned worker prompt history path: <absolute-path>`
 6. `**Model:** Report writer worker, <modelExecutionValue>` (resolved per Phase 5.5 anchor-header rules)
-7. The full `[Required reading]` clause (see [okstra-team-contract](../okstra-team-contract/SKILL.md)) including `schemas/final-report-v1.0.schema.json` and `templates/reports/final-report.template.md` (template is read-only — the worker writes the data.json that drives it).
-8. The verbatim `## Available MCP Servers` block from the task brief, if present.
-9. The convergence classifications (Full/Partial/Contested/Worker-Unique), the round history table (`roundHistory[]`), the `round2SkippedReason` value, and pointers to all worker result files under `worker-results/`. The report-writer worker must reproduce a Round History sub-table in Section 1 of the final report so the reader can see which rounds executed, queue sizes, and why Round 2 was (or was not) skipped.
+7. The full `[Required reading]` clause (see [okstra-team-contract](../okstra-team-contract/SKILL.md)) — for Phase 6 it adds two **per-task-type, instruction-set-local** read-only files, both scoped to this run's task-type by `okstra-ctl` at prep time:
+   - `<instruction-set>/final-report-schema.json` — a task-type excerpt of the data.json schema (the other task-types' deliverable blocks and their unreachable `$defs` are stripped; ~38% of the full schema is `$defs` alone). This is your authoring contract for the data.json shape. Do **NOT** pull the full `schemas/final-report-v1.0.schema.json` — it carries all task-types and its `schemas/...` path is not part of the task bundle. (Validation still runs against the full schema post-hoc via the renderer, so the excerpt never relaxes the contract.)
+   - `<instruction-set>/final-report-template.md` — the **phase-stripped** template (every other task-type's §4.x deliverable block removed by `render.py`'s `_strip_phase_blocks`, leaving only your run's §4.x). Do **NOT** also pull the full `templates/reports/final-report.template.md` source (it re-adds ~330 lines of other phases' deliverables and is not in the task bundle).
+8. A one-line MCP pointer instead of the verbatim block — `**MCP servers:** follow the task brief's "## Available MCP Servers" section (already in your Required reading).` The brief is already in the report-writer's Required reading (item 7), so the verbatim block is redundant.
+9. The convergence classifications (Full/Partial/Contested/Worker-Unique), the round history data (`roundHistory[]`), the `round2SkippedReason` value, and pointers to all worker result files under `worker-results/`. The report-writer worker populates `crossVerification.roundHistory` in the data.json so Section 1 can show which rounds executed, queue sizes, and why Round 2 was (or was not) skipped. The renderer prints the full per-round table only when more than one round ran; single-round or zero-round histories are auto-collapsed to a one-line summary.
 10. `**Report Language:** <en|ko>` — must be either `en` or `ko`; `auto`
     has been resolved by the lead from project.json / global config
     before the dispatch is constructed. The worker copies this verbatim
@@ -89,7 +91,7 @@ The four steps below MUST execute in this exact order. Reordering them is the re
    ```
 
    The data.json paths populated: `tokenUsage.lead.{totalTokens,billableTokens,costUsd}`, the `worker` / `grand` rows, `tokenUsage.cli.costUsd`, and each `executionStatus[].{totalTokens,billableTokens,costUsd,durationMs,cliTotalTokens,cliCostUsd}` for rows whose role matches a team-state worker. The data.json MUST already exist (Phase 6 output).
-3. **Phase 7 step 1.5 — Render report views** (BLOCKING). Produces the self-contained HTML view from the now-substituted final-report MD:
+3. **Phase 7 step 1.5 — Render report views** (BLOCKING, conditional output). Always invoke the renderer; it decides whether an html sibling is warranted:
 
    ```bash
    python3 scripts/okstra-render-report-views.py \
@@ -97,9 +99,10 @@ The four steps below MUST execute in this exact order. Reordering them is the re
    ```
 
    Output (idempotent — re-running overwrites):
-   - `runs/<task-type>/reports/final-report-<task-type>-<seq>.html` — single-file self-contained human view. Section 5 `C-*` clarification rows with `Status` ∈ {`open`, `answered`} embed form widgets (`<select>` for enum-style decisions, `<input>` for material / data-point kinds, `<textarea>` fallback); an `Export user response` button serialises form values to a markdown sidecar (schema in [`templates/reports/user-response.template.md`](../../templates/reports/user-response.template.md)) that the user pastes to `runs/<task-type>/user-responses/user-response-<task-type>-<seq>.md`. The original final-report MD is **never** mutated by user input — the sidecar is the single write target.
+   - `runs/<task-type>/reports/final-report-<task-type>-<seq>.html` — single-file self-contained human view, **generated only when the report has at least one §5 `C-*` clarification row**. Those rows with `Status` ∈ {`open`, `answered`} embed form widgets (`<select>` for enum-style decisions, `<input>` for material / data-point kinds, `<textarea>` fallback); an `Export user response` button serialises form values to a markdown sidecar (schema in [`templates/reports/user-response.template.md`](../../templates/reports/user-response.template.md)) that the user pastes to `runs/<task-type>/user-responses/user-response-<task-type>-<seq>.md`. The original final-report MD is **never** mutated by user input — the sidecar is the single write target.
+   - When the report has **no** `C-*` clarification rows, the html carries no interactive forms (it would only duplicate the MD), so the renderer prints `html: skipped (...)` and writes nothing. This is the expected state for clarification-free runs — `validators/validate-report-views.py` treats "no C-* rows + no html" as a pass, not a missing artifact.
 
-   Must run AFTER step 1 (so token placeholders are substituted in the rendered html) and BEFORE step 2 (so the html artifact exists for any validator step that checks it).
+   Must run AFTER step 1 (so token placeholders are substituted in any rendered html) and BEFORE step 2 (so the html artifact, when generated, exists for the validator step that checks it).
 4. **Phase 7 step 2 — Follow-up task spawner** (BLOCKING when Section 7 is non-empty). Turns the report's `## 7. Follow-up Tasks (후속 작업)` rows into `tasks/<task-group>/<new-task-id>/` stubs.
 
    ```bash
@@ -255,7 +258,7 @@ Skipping this file because "the real report is in `reports/`" is wrong. Both fil
 
 ### Main Body Section
 
-Section numbering follows `templates/reports/final-report.template.md` exactly — that file is the single source of truth. Below is a one-line summary of each section's writer obligation; consult the template for full body structure.
+Section numbering follows `templates/reports/final-report.template.md` exactly — that file is the documentation SSOT for section names and ordering. For full body structure at authoring time, consult your run's **phase-stripped** `final-report-template.md` (the instruction-set copy of the same template, with other task-types' §4.x deliverable blocks removed); the "copy that block verbatim" references below mean the §-block as it appears in that stripped copy, not a re-read of the full source.
 
 **Verdict Card (top-of-report, mandatory).** Render `## Verdict Card` between the report header and the (conditional) Approval block. Its `Verdict Token` / `Direction` / `Next Step` cells MUST byte-match the corresponding cells in `## 2. Final Verdict` and the first item of `## 6.`. Divergence is `contract-violated`.
 
@@ -313,7 +316,7 @@ Persistence steps that must be performed in Phase 7:
 - [ ] 6. **Generate final status file**: `runs/<task-type>/status/final-<task-type>-<seq>.status` (if necessary)
 - [ ] 7. **Save convergence state**: `runs/<task-type>/state/convergence-<task-type>-<seq>.json` (when convergence is enabled)
 - [ ] 8. **Spawn follow-up task stubs**: run `scripts/okstra-spawn-followups.py` against the final-report per the canonical spawn rule defined in "Phase 7 follow-up task spawner" above. Do not restate the trigger condition here — that section is the single source of truth. The script is idempotent across reruns.
-- [ ] 9. **Human HTML report**: `runs/<task-type>/reports/final-report-<task-type>-<seq>.html` (produced by Phase 7 step 1.5 — self-contained, embeds `Export user response` button)
+- [ ] 9. **Human HTML report** (conditional): `runs/<task-type>/reports/final-report-<task-type>-<seq>.html` — produced by Phase 7 step 1.5 **only when the report has ≥1 §5 `C-*` clarification row** (self-contained, embeds `Export user response` button). Clarification-free reports legitimately have no html sibling; do not treat its absence as a missing artifact.
 
 ### Response after Persistence
 

package/runtime/skills/okstra-team-contract/SKILL.md

@@ -24,10 +24,10 @@ okstra tasks are always operated using the `Claude lead` + required worker team
 | Role | Core responsibility | Specialization lens (Section 6 only) | subagent_type | Notes |
 |------|------|------|---------------|------|
 | Claude lead | orchestration + convergence supervision + final-report review/approval | — | -- | Does NOT author the final-report file when `Report writer worker` is in the roster |
-| Claude worker | Answer every brief question across feasibility, requirement interpretation, hidden assumptions, and alternatives — with file:line evidence | broad reasoning depth, hidden assumptions, execution-risk surfacing | claude-worker | `agents/claude-worker.md` |
-| Codex worker | Same core responsibility as Claude worker — identical questions, identical sections 1–5 | implementation realism, code-path implications, edge cases, technical trade-offs | codex-worker | `agents/codex-worker.md` |
-| Gemini worker | Same core responsibility as Claude worker — identical questions, identical sections 1–5 | requirement interpretation, consistency, safety, alternative viewpoints | gemini-worker | `agents/gemini-worker.md` |
-| Report writer worker | **Authors** the final-report file in Phase 6. NOT an analysis worker. | — | report-writer-worker | `agents/report-writer-worker.md`. Excluded from Phase 4/5 and convergence |
+| Claude worker | Answer every brief question across feasibility, requirement interpretation, hidden assumptions, and alternatives — with file:line evidence | broad reasoning depth, hidden assumptions, execution-risk surfacing | claude-worker | `agents/workers/claude-worker.md` |
+| Codex worker | Same core responsibility as Claude worker — identical questions, identical sections 1–5 | implementation realism, code-path implications, edge cases, technical trade-offs | codex-worker | generated from `agents/workers/_cli-wrapper-template.md` + `codex-worker.params.json` |
+| Gemini worker | Same core responsibility as Claude worker — identical questions, identical sections 1–5 | requirement interpretation, consistency, safety, alternative viewpoints | gemini-worker | generated from `agents/workers/_cli-wrapper-template.md` + `gemini-worker.params.json` |
+| Report writer worker | **Authors** the final-report file in Phase 6. NOT an analysis worker. | — | report-writer-worker | `agents/workers/report-writer-worker.md`. Excluded from Phase 4/5 and convergence |
 
 **Model assignment has no default.** The model for every role comes from `resultContract.requiredWorkerRoles[*].modelExecutionValue` in `task-manifest.json` (and lead model metadata). There is no per-role hard-coded fallback — see "Model Assignment Rules" below.
 
@@ -80,7 +80,7 @@ The body must include: role name, task type, task key, required bundle paths, as
 
 When a worker reads any project-relative path from the prompt, it MUST resolve it against `Project Root` (e.g. `<Project Root>/<Result Path>`) — never use bare relative paths that depend on cwd.
 
-If the task brief contains an `## Available MCP Servers` section, copy that section verbatim into every analysis worker's prompt (and into the report-writer prompt when it is dispatched in Phase 6). Codex/Gemini workers run external CLIs whose MCP availability is governed by their own CLI configs; still forward the section so they can record `MCP not available in this CLI` cleanly when their CLI lacks the matching server.
+If the task brief contains an `## Available MCP Servers` section, inject only the one-line pointer into every analysis worker's prompt (and into the report-writer prompt when it is dispatched in Phase 6) — the brief is already in every worker's [Required reading], so verbatim copy is redundant: `**MCP servers:** follow the task brief's "## Available MCP Servers" section (already in your Required reading).` Codex/Gemini workers run external CLIs whose MCP availability is governed by their own CLI configs; they can record `MCP not available in this CLI` cleanly after reading that section in the brief.
 
 Before dispatching any required worker, lead persists the exact worker prompt to the assigned current-run prompt history path under `runs/<task-type>/prompts/`. Do not use `/tmp/*prompt*.txt` as the canonical artifact path.
 
@@ -100,7 +100,7 @@ Audience-scoped file enumeration (BLOCKING — performance optimization):
 | Recipient | Files the lead lists under `## Inputs` |
 |---|---|
 | Claude / Codex / Gemini analysis workers | task-brief, analysis-profile, analysis-material (if present), reference-expectations, clarification-response (if carry-in) |
-| Report writer worker (Phase 6) | all of the above **plus** `final-report-template.md` |
+| Report writer worker (Phase 6) | all of the above **plus** the instruction-set-local `final-report-template.md` (phase-stripped) and `final-report-schema.json` (per-task-type excerpt) — NOT the full `templates/reports/...` / `schemas/...` sources |
 | Reverify dispatches | none — the lead provides only the items to reverify |
 
 Asymmetry note: `claude-worker` runs in-process and the Agent SDK auto-loads its agent definition; lead's dispatch prompt body for claude-worker can therefore be shorter than for codex/gemini. The Worker Preamble pointer is still emitted for all three so the contract source is identical regardless of dispatch path.
@@ -318,41 +318,33 @@ Every worker result file under `worker-results/` must begin with a standardized
 ```markdown
 # <Role> Analysis — <task-key>
 
-**Task:** <task-type>
 **Target:** <path or scope>   <!-- OPTIONAL: include when the run is scoped to a specific file/module -->
-**Date:** <YYYY-MM-DD>
 **Model:** <Role>, <AI model>
 ```
 
-The `Target:` line is optional. Include it when the run is scoped to a specific path or module; omit it when the run spans the whole project. When included, place it between `Task:` and `Date:` as shown.
+Task-type and date are **not** repeated in this human header — they already live in the YAML frontmatter (`taskType`, `date`), which is the copy Obsidian indexes. Restating them here added a third, un-indexed, machine-unparsed copy with no value; the frontmatter is the single source for both. The `Target:` line is optional — include it when the run is scoped to a specific path or module, omit it for whole-project runs; when present, place it between the title and the `Model:` line.
 
 Examples:
 
 ```markdown
 # Claude Worker Analysis — jobs:tasks:8852
 
-**Task:** error-analysis
 **Target:** server/auth.ts
-**Date:** 2026-04-06
-**Model:** Claude worker, sonnet
+**Model:** Claude worker, opus
 ```
 
 ```markdown
 # Codex Worker Analysis — jobs:tasks:8852
 
-**Task:** error-analysis
 **Target:** server/auth.ts
-**Date:** 2026-04-06
 **Model:** Codex worker, <codex-model-id>
 ```
 
 ```markdown
 # Report Writer Worker Analysis — jobs:tasks:8852
 
-**Task:** error-analysis
 **Target:** server/auth.ts
-**Date:** 2026-04-06
-**Model:** Report writer worker, opus-4-6
+**Model:** Report writer worker, opus
 ```
 
 Use the actual model identifier recorded in team-state (never invent a model ID — read it from `resultContract.requiredWorkerRoles[*].modelExecutionValue` or the tool response metadata).

package/runtime/templates/reports/final-report.template.md

@@ -96,7 +96,9 @@ approved: {{ frontmatter.approved | yaml_scalar }}
 | {{ t("tokenSummary.rowLead") }} | `{{ tokenUsage.lead.totalTokens | format_int }}` | `{{ tokenUsage.lead.billableTokens | format_int }}` | `{{ tokenUsage.lead.costUsd | format_usd }}` |
 | {{ t("tokenSummary.rowWorkerTotal") }} | `{{ tokenUsage.worker.totalTokens | format_int }}` | `{{ tokenUsage.worker.billableTokens | format_int }}` | `{{ tokenUsage.worker.costUsd | format_usd }}` |
 | {{ t("tokenSummary.rowGrandTotal") }} | **`{{ tokenUsage.grand.totalTokens | format_int }}`** | **`{{ tokenUsage.grand.billableTokens | format_int }}`** | **`{{ tokenUsage.grand.costUsd | format_usd }}`** |
+{% if tokenUsage.cli and tokenUsage.cli.costUsd is not none and tokenUsage.cli.costUsd > 0 -%}
 | {{ t("tokenSummary.rowCliExtra") }} |  |  | `{{ tokenUsage.cli.costUsd | format_usd }}` |
+{% endif %}
 
 {# At Phase 6 numeric cells are null and render as `--`.
    Phase 7's okstra-token-usage.py populates tokenUsage in data.json then
@@ -107,6 +109,7 @@ approved: {{ frontmatter.approved | yaml_scalar }}
 {% if crossVerification.roundHistory and not crossVerification.roundHistory.disabled -%}
 ### 1.0 Round History
 
+{% if crossVerification.roundHistory.rounds | length > 1 -%}
 | Round | inputQueueSize | resolvedCount | carriedForwardCount | dispatches (worker:status:durationMs) | skippedWorkers (worker:reason) |
 |-------|----------------|---------------|----------------------|----------------------------------------|---------------------------------|
 {% for row in crossVerification.roundHistory.rounds -%}
@@ -114,6 +117,12 @@ approved: {{ frontmatter.approved | yaml_scalar }}
 {% endfor %}
 
 - `round2SkippedReason`: `{{ crossVerification.roundHistory.round2SkippedReason }}`  ← {{ t("roundHistory.round2SkippedReasonNote") }}
+{% elif crossVerification.roundHistory.rounds | length == 1 -%}
+{% set r = crossVerification.roundHistory.rounds[0] -%}
+- {{ t("roundHistory.singleRoundPrefix") }} resolved={{ r.resolvedCount }}, carriedForward={{ r.carriedForwardCount }}, round2SkippedReason=`{{ crossVerification.roundHistory.round2SkippedReason }}`
+{% else -%}
+- {{ t("roundHistory.noRoundsNote") }} round2SkippedReason=`{{ crossVerification.roundHistory.round2SkippedReason }}`
+{% endif %}
 
 {% endif %}
 ### 1.1 Consensus

package/runtime/templates/reports/i18n/en.json

@@ -75,7 +75,9 @@
     "sourceItemsColumnNote": "`Source items` column rule is the same as §1.1."
   },
   "roundHistory": {
-    "round2SkippedReasonNote": "value is one of `queue-empty | max-rounds-1 | all-reverify-non-result | not-skipped | convergence-disabled | single-analyser-only`"
+    "round2SkippedReasonNote": "value is one of `queue-empty | max-rounds-1 | all-reverify-non-result | not-skipped | convergence-disabled | single-analyser-only`",
+    "singleRoundPrefix": "Single round —",
+    "noRoundsNote": "No reverify rounds executed (all findings reached consensus at grouping)."
   },
   "implementationPlanning": {
     "optionInterfacesLabel": "Affected interfaces / public contracts / downstream consumers",

package/runtime/templates/reports/i18n/ko.json

@@ -75,7 +75,9 @@
     "sourceItemsColumnNote": "`Source items` 컬럼 규칙은 §1.1 과 동일."
   },
   "roundHistory": {
-    "round2SkippedReasonNote": "값은 `queue-empty | max-rounds-1 | all-reverify-non-result | not-skipped | convergence-disabled | single-analyser-only` 중 하나."
+    "round2SkippedReasonNote": "값은 `queue-empty | max-rounds-1 | all-reverify-non-result | not-skipped | convergence-disabled | single-analyser-only` 중 하나.",
+    "singleRoundPrefix": "단일 라운드 —",
+    "noRoundsNote": "재검증 라운드 미실행 (그룹핑 단계에서 전부 합의)."
   },
   "implementationPlanning": {
     "optionInterfacesLabel": "영향 인터페이스 / 공개 계약 / 다운스트림 소비자",

package/runtime/templates/worker-prompt-preamble.md

@@ -17,7 +17,7 @@ Different recipients need different files. Do NOT include `final-report-template
 | Recipient | Files included in `[Required reading]` |
 |---|---|
 | Claude / Codex / Gemini analysis workers | task-brief, analysis-profile, analysis-material (if present), reference-expectations, clarification-response (if carry-in) |
-| Report writer worker (Phase 6) | all of the above **plus** `final-report-template.md` |
+| Report writer worker (Phase 6) | all of the above **plus** the instruction-set-local `final-report-template.md` (phase-stripped) and `final-report-schema.json` (per-task-type excerpt) — NOT the full `templates/reports/...` / `schemas/...` sources |
 | Reverify dispatches (Phase 5.5, lightweight mode) | **do NOT inject `[Required reading]` at all** — see [okstra-convergence](../skills/okstra-convergence/SKILL.md) "Reverify prompt: required-reading suppression". |
 
 ### Reading rules

package/runtime/validators/validate-report-views.py

@@ -80,9 +80,16 @@ def validate(report_path: Path) -> list[str]:
 
     md = report_path.read_text(encoding="utf-8")
     html_path = report_path.with_name(report_path.stem + ".html")
+    md_ids = _md_response_ids(md)
 
-    # (1) sibling artifact exists
+    # (1) sibling artifact exists — conditional on §5 clarification rows.
+    # The html view's sole value over the MD is its embedded form widgets
+    # for §5 C-* rows, so a clarification-free report intentionally has no
+    # html sibling (see report_views.report_has_clarification_items). When
+    # there are no C-* rows and no html, that is the expected skip state.
     if not html_path.is_file():
+        if not md_ids:
+            return []
         return [f"missing html artifact: {html_path}"]
 
     html_text = html_path.read_text(encoding="utf-8")
@@ -119,7 +126,7 @@ def validate(report_path: Path) -> list[str]:
     # (5) Response ID parity: HTML form rows ↔ §5 C-* rows in MD.
     # Bidirectional — catches both "MD has C-* the HTML lost" AND
     # "HTML has stale C-* that the current MD no longer declares".
-    md_ids = _md_response_ids(md)
+    # (md_ids computed once at the top.)
     html_ids = sorted(set(_RESPONSE_ID_ATTR_RE.findall(html_text)))
     if md_ids != html_ids:
         failures.append(

package/runtime/validators/validate-run.py

@@ -1540,9 +1540,11 @@ def _rerender_report_views_after_autofix(report_path: Path) -> str:
         source_report=report_path.name,
     )
     try:
-        render_html_view(report_path, run_meta=meta, css=css, js=js)
+        rendered = render_html_view(report_path, run_meta=meta, css=css, js=js)
     except Exception as exc:  # noqa: BLE001
         return f"report-views re-render failed: {exc}"
+    if rendered is None:
+        return "report-views skipped (no §5 clarification rows)"
     return "report-views re-rendered"
 
 

package/src/install.mjs

@@ -589,11 +589,24 @@ export async function runInstall(args) {
     join(paths.home, "templates"),
     { refresh: opts.refresh, dryRun: opts.dryRun, mode: 0o644 },
   );
+  // schemas/ tree — final-report-v1.0.schema.json is loaded at runtime by
+  // okstra_ctl.final_report_schema.load_schema() (parent-walk from the
+  // installed okstra_ctl package finds ~/.okstra/schemas/). It is needed by
+  // (a) prepare_task_bundle to write the per-task-type schema excerpt into
+  // each run's instruction-set, and (b) validate-run's data.json schema
+  // check. Without this step copy-mode installs leave load_schema() unable
+  // to locate the schema. Link mode resolves it through the repo symlink.
+  const schemasResult = await copyTreeIfChanged(
+    join(runtimeRoot, "schemas"),
+    join(paths.home, "schemas"),
+    { refresh: opts.refresh, dryRun: opts.dryRun, mode: 0o644 },
+  );
 
   if (!opts.quiet) {
     summarise("python", pythonResult, paths.pythonpath);
     summarise("bin", binResult, paths.bin);
     summarise("templates", templatesResult, join(paths.home, "templates"));
+    summarise("schemas", schemasResult, join(paths.home, "schemas"));
   }
 
   if (pythonResult.missingSource && binResult.missingSource) {
@@ -606,6 +619,11 @@ export async function runInstall(args) {
       "warning: runtime/templates is empty. report.css / report.js will be missing — re-run the build step.\n",
     );
   }
+  if (schemasResult.missingSource) {
+    process.stderr.write(
+      "warning: runtime/schemas is empty. final-report schema validation + excerpt generation will be unavailable — re-run the build step.\n",
+    );
+  }
 
   const skillResult = await installSkillsCopy(runtimeRoot, opts);
   await writeSkillsManifest(paths.home, skillResult.installed, { dryRun: opts.dryRun });
@@ -682,6 +700,9 @@ export async function runEnsureInstalled(args) {
   }
   if (!(await dirExists(paths.pythonpath))) reasons.push(`missing ${paths.pythonpath}`);
   if (!(await dirExists(paths.agents))) reasons.push(`missing agents dir ${paths.agents}`);
+  if (!(await fileExists(join(paths.home, "schemas", "final-report-v1.0.schema.json")))) {
+    reasons.push(`missing ${join(paths.home, "schemas", "final-report-v1.0.schema.json")}`);
+  }
   if (!(await fileExists(join(CLAUDE_SKILLS_DIR, "okstra-setup", "SKILL.md")))) {
     reasons.push(`missing ${CLAUDE_SKILLS_DIR}/okstra-setup/SKILL.md`);
   }