okstra 0.37.0 → 0.38.0

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.0",
   "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.0",
+  "builtAt": "2026-05-28T09:52:37.801Z",
   "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/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/run.py

@@ -667,8 +667,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)

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.