okstra 0.18.1 → 0.18.2

package/docs/kr/cli.md

@@ -236,6 +236,11 @@ scripts/okstra.sh --task-type implementation-planning ... \
 scripts/okstra.sh --task-type implementation-planning --workers claude,codex --project-id jobs --task-group tasks --task-id 8852 --task-brief .project-docs/tasks/8852/BUG_REPORT.md
 ```
 
+> 모든 `--*-model` 플래그는 `scripts/okstra_ctl/models.py` 의 provider 별 mapping 에 등록된 alias 만 허용합니다. 등록되지 않은 값은 `UnknownModelError` 로 즉시 거부됩니다 (manifest 의 `modelExecutionValue` 와 실제 실행값 불일치로 인한 contract-violation 을 사전에 차단). 허용값:
+> - Claude (`--lead-model` / `--claude-model` / `--report-writer-model`): `opus`, `opus-4-7`, `claude-opus-4-7`, `sonnet`, `sonnet-4-6`, `claude-sonnet-4-6`, `haiku`, `haiku-4-5`, `claude-haiku-4-5`, `claude-haiku-4-5-20251001`
+> - Codex (`--codex-model`): `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.3-codex`, `gpt-5.2`, `codex-auto-review`
+> - Gemini (`--gemini-model`): `auto`, `pro`, `gemini-3-flash-preview`, `gemini-3-pro-preview` (그리고 `gemini auto` / `gemini pro` 별칭)
+
 ### `--claude-model`
 
 `Claude worker`에 사용할 모델을 지정합니다.

package/package.json

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

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.18.1",
-  "builtAt": "2026-05-13T13:27:26.867Z",
+  "package": "0.18.2",
+  "builtAt": "2026-05-13T13:51:20.597Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/SKILL.md

@@ -270,7 +270,7 @@ After persistence, reply briefly in Korean with: completion status, final report
 | Skipping a worker silently | Always record terminal status with reason |
 | Writing verdict before all workers report | Wait for all results or explicit terminal statuses |
 | Ignoring task bundle model assignments | Task bundle overrides are canonical |
-| Sending identical prompts to all workers | Add role-specific emphasis per [okstra-team-contract](./skills/okstra-team-contract/SKILL.md) |
+| Inserting per-worker emphasis sentences ("you focus on X") into dispatch prompts | Send byte-identical dispatch prompts per [okstra-team-contract](./skills/okstra-team-contract/SKILL.md) "Dispatch-prompt invariant" — specialization lives in Section 6 of the worker output, not the prompt body |
 | Omitting contested or worker-unique findings | All categories must appear in the report |
 | Running full re-analysis when lightweight suffices | Default lightweight; full only when manifest opts in |
 | Using `/tmp/*prompt*.txt` for worker prompt persistence | Persist the exact worker prompt to the assigned run-level `prompts/` path |

package/runtime/agents/workers/claude-worker.md

@@ -21,7 +21,9 @@ color: blue
 tools: ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "TodoWrite", "WebFetch", "WebSearch"]
 ---
 
-You are a Claude worker agent for okstra cross-verification. Your emphasis: **broad reasoning quality, hidden assumptions, missing context, execution risk**.
+You are a Claude worker agent for okstra cross-verification. You share an **identical core responsibility** with the Codex and Gemini workers: cover every brief question across feasibility, requirement interpretation, hidden assumptions, alternatives, and execution risk in sections 1–5 of the worker output. Cross-verification only triangulates if all three workers answer the same questions against the same brief.
+
+Your specialization lens — **broad reasoning depth, hidden-assumption surfacing, execution-risk decomposition** — is the only content that belongs in optional Section 6 (additive, not subject to convergence). Do NOT let the lens narrow sections 1–5: a Claude-only "Findings" populated solely with assumption-class items is a contract violation.
 
 Unlike the Codex / Gemini workers, you are an in-process Claude subagent — you do NOT shell out to a CLI. Use your native tools (Read / Grep / Glob / MCP) directly.
 
@@ -108,4 +110,4 @@ There is NO `cli-failure` category for this worker — Claude worker has no exte
 
 - Return error messages as-is on failure.
 - Do not summarize or modify your own analysis output beyond the structured sections above.
-- Your emphasis: broad reasoning quality, hidden assumptions, missing context, execution risk — distinct from Codex (implementation realism) and Gemini (requirement interpretation, alternative viewpoints).
+- Sections 1–5 are the common core — same dimensions for every analysis worker. Your specialization (broad reasoning depth, hidden-assumption surfacing, execution-risk decomposition) only enters Section 6 if you have additive content beyond the core. See `skills/okstra-team-contract/SKILL.md` "Worker Output Contract" for the authoritative split.

package/runtime/agents/workers/codex-worker.md

@@ -204,4 +204,4 @@ pre-flight terminal status, not a runtime CLI error.
 - Ignore stderr warnings from MCP integration.
 - Return error messages as-is on failure.
 - Do not summarize or modify Codex results.
-- Your emphasis: implementation realism, code-path implications, edge cases, technical trade-offs.
+- Sections 1–5 of the worker output are the common core shared with the Claude and Gemini workers — the dispatched prompt asks identical questions for all three roles, and the Codex CLI must answer all of them, not only implementation-realism findings. Your specialization (implementation realism, code-path implications, edge cases, technical trade-offs) belongs only in optional Section 6 as additive depth. A Codex result whose Findings section is populated solely with implementation-feasibility items is in breach of contract; see `skills/okstra-team-contract/SKILL.md` "Worker Output Contract".

package/runtime/agents/workers/gemini-worker.md

@@ -204,4 +204,4 @@ pre-flight terminal status, not a runtime CLI error.
 - Always specify the assigned `-m` value for the current run.
 - Return error messages as-is on failure.
 - Do not summarize or modify Gemini results.
-- Your emphasis: requirement interpretation, consistency, safety, documentation quality, alternative viewpoints.
+- Sections 1–5 of the worker output are the common core shared with the Claude and Codex workers — the dispatched prompt asks identical questions for all three roles, and the Gemini CLI must answer all of them, not only requirement-interpretation findings. Your specialization (requirement interpretation, consistency, safety, documentation quality, alternative viewpoints) belongs only in optional Section 6 as additive depth. A Gemini result whose Findings section is populated solely with requirement-interpretation items is in breach of contract; see `skills/okstra-team-contract/SKILL.md` "Worker Output Contract".

package/runtime/python/okstra_ctl/models.py

@@ -45,19 +45,36 @@ class ModelAssignment:
     execution: str
 
 
+class UnknownModelError(ValueError):
+    """raw_value 가 provider mapping 에 등록되어 있지 않을 때 발생."""
+
+
 def resolve_model_metadata(
     *, provider: str, raw_value: str, default_display: str, default_execution: str,
 ) -> ModelAssignment:
-    """alias → (display, execution_value). 알 수 없는 값은 그대로 통과.
+    """alias → (display, execution_value).
 
     provider: "claude" | "codex" | "gemini" (그 외는 mapping 미적용)
+
+    Mapping 이 정의된 provider 에 대해 사용자가 빈 값이 아닌 raw_value 를 줬는데
+    mapping 에 없는 경우 `UnknownModelError` 를 발생시킨다. 이는 manifest 에
+    Codex 가 지원하지 않는 `gpt-5.5-high` 같은 유령 모델이 기록되어 실제
+    실행값과 contract 가 불일치하는 사고를 막기 위함이다.
     """
     raw_value = (raw_value or "").strip()
+    mapping = PROVIDER_MAPPINGS.get(provider)
+    if raw_value and mapping is not None:
+        normalized = raw_value.lower()
+        if normalized not in mapping:
+            allowed = ", ".join(sorted(mapping.keys()))
+            raise UnknownModelError(
+                f"{provider} model {raw_value!r} is not a supported alias. "
+                f"Allowed values: {allowed}"
+            )
     value = raw_value or default_display
     display = value
     execution = raw_value or default_execution
     normalized = value.strip().lower()
-    mapping = PROVIDER_MAPPINGS.get(provider)
     if mapping and normalized in mapping:
         display, execution = mapping[normalized]
     return ModelAssignment(display=display, execution=execution)

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

@@ -37,6 +37,8 @@ Configure this in the `convergence` block of `task-manifest.json`. If the block
 
 Read the worker result files generated in Phase 4/5 and extract individual findings.
 
+**Convergence scope.** Convergence operates on sections 1–5 of the worker output (the common core, see `okstra-team-contract` "Worker Output Contract"). Section 6 ("Specialization Lens") is additive worker-specific depth and MUST NOT be fed into the consensus grouping, the verification queue, or the round-N reverify prompts. Carry Section 6 forward into the final report verbatim through the report-writer worker — do not let it inflate `unique` counts or trigger spurious `verification-error` statuses.
+
 1. In the "Findings" section of each worker's results, identify individual items by number (F-001, F-002, ...) and parse the ticket identifier attached to each item:
    - For table-form findings, read the `Ticket ID` column.
    - For bullet/numbered findings, parse `[TICKETID: <id>]` from the item title.

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

@@ -184,31 +184,41 @@ Single `AskUserQuestion` first: `"기본 워커/모델로 진행할까요, 아
 - `Use defaults` → all overrides remain empty.
 - `Customize` → the prompts you ask depend on the `task_type` chosen in Step 4. Blank answer always means "use default". Never call the prompt label "worker CSV" — use plain Korean labels as shown below.
 
+### Model selection options (used by 6a and 6b)
+
+All model prompts MUST use `AskUserQuestion` with a fixed option list — never free text. This prevents typos like `gpt-5.5-high` (a non-existent model) reaching the manifest. The options below are derived from `scripts/okstra_ctl/models.py` `*_MAPPING` and show "default + 3 latest". Blank/`default` means "use phase default".
+
+- **Claude (lead / claude-worker / report-writer)** options: `default`, `opus`, `sonnet`, `haiku`
+- **Codex (codex-worker)** options: `default`, `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`
+- **Gemini (gemini-worker)** options: `default`, `gemini-3-pro-preview`, `gemini-3-flash-preview`, `auto`
+
+When the user picks `default`, pass an empty string to the corresponding `--*-model` flag. Pick any other option ⇒ pass it verbatim. If the user truly needs a value outside the list (e.g. a pinned long-form id), they can use the question's built-in `Other` to type it — but the four canonical options cover the supported set, so `Other` should be rare.
+
 ### 6a. `implementation` phase (executor-driven)
 
-In this phase the roster is fixed by the profile (executor + two verifiers + report-writer). The Step 4 `executor` answer already determines who mutates code; verifier models use phase-specific defaults (`Claude verifier`=sonnet, `Codex verifier`=gpt-5.5, `Gemini verifier`=auto). So ask **only three model prompts**, plus directive/related/clarification:
+In this phase the roster is fixed by the profile (executor + two verifiers + report-writer). The Step 4 `executor` answer already determines who mutates code; verifier models use phase-specific defaults (`Claude verifier`=sonnet, `Codex verifier`=gpt-5.5, `Gemini verifier`=auto). So ask **only three model prompts** (each via `AskUserQuestion` with options from the table above), plus directive/related/clarification:
 
-1. `"리더(Claude lead) 모델? (빈 칸 = 기본값)"` → `lead_model`
-2. `"실행자({executor-provider}) 모델? (빈 칸 = 기본값)"` → maps to `claude_model` / `codex_model` / `gemini_model` based on the Step 4 executor choice. The other two provider model fields stay empty (verifiers use defaults).
-3. `"리포트 작성자(report-writer) 모델? (빈 칸 = 기본값)"` → `report_writer_model`
-4. `"추가 directive (선택, 빈 칸 가능)"` → `directive`
-5. `"관련 task id 목록, 쉼표 구분 (선택, 빈 칸 가능)"` → `related_tasks_raw`
+1. `AskUserQuestion` `"리더(Claude lead) 모델?"` (Claude options) → `lead_model`
+2. `AskUserQuestion` `"실행자({executor-provider}) 모델?"` with options matching the executor's provider (Claude / Codex / Gemini list above) → maps to `claude_model` / `codex_model` / `gemini_model`. The other two provider model fields stay empty (verifiers use defaults).
+3. `AskUserQuestion` `"리포트 작성자(report-writer) 모델?"` (Claude options) → `report_writer_model`
+4. `AskUserQuestion` `"추가 directive (선택, 빈 칸 가능)"` (free text) → `directive`
+5. `AskUserQuestion` `"관련 task id 목록, 쉼표 구분 (선택, 빈 칸 가능)"` (free text) → `related_tasks_raw`
 
 Do NOT ask for `workers_override` in implementation — the profile's required roster must be preserved (verifier slots are mandatory). Leave `workers_override=""`.
 
 ### 6b. Other phases (`requirements-discovery`, `error-analysis`, `implementation-planning`, `final-verification`, `release-handoff`)
 
-Ask each in turn (free text, blank = default):
+Ask each in turn (model prompts use `AskUserQuestion` with the option lists above; others are free text):
 
-1. `"참여 워커 목록 (쉼표 구분, 빈 칸 = 프로필 기본값 claude,codex,report-writer). 선택지: claude, codex, gemini, report-writer — gemini는 옵션이므로 필요할 때 명시"` → `workers_override`
-2. `"리더(Claude lead) 모델? (빈 칸 = 기본값)"` → `lead_model`
-3. `"claude 워커 모델? (빈 칸 = 기본값)"` → `claude_model`
-4. `"codex 워커 모델? (빈 칸 = 기본값)"` → `codex_model`
-5. `"gemini 워커 모델? (빈 칸 = 기본값)"` → `gemini_model`
-6. `"리포트 작성자 모델? (빈 칸 = 기본값)"` → `report_writer_model`
-7. `"추가 directive (선택, 빈 칸 가능)"` → `directive`
-8. `"관련 task id 목록, 쉼표 구분 (선택, 빈 칸 가능)"` → `related_tasks_raw`
-9. `"clarification-response 파일 경로 (follow-up 시에만, 빈 칸 가능)"` → `clarification_response_path`
+1. `AskUserQuestion` `"참여 워커 목록 (쉼표 구분, 빈 칸 = 프로필 기본값 claude,codex,report-writer). 선택지: claude, codex, gemini, report-writer — gemini는 옵션이므로 필요할 때 명시"` (free text) → `workers_override`
+2. `AskUserQuestion` `"리더(Claude lead) 모델?"` (Claude options) → `lead_model`
+3. `AskUserQuestion` `"claude 워커 모델?"` (Claude options) → `claude_model`
+4. `AskUserQuestion` `"codex 워커 모델?"` (Codex options) → `codex_model`
+5. `AskUserQuestion` `"gemini 워커 모델?"` (Gemini options) → `gemini_model`
+6. `AskUserQuestion` `"리포트 작성자 모델?"` (Claude options) → `report_writer_model`
+7. `AskUserQuestion` `"추가 directive (선택, 빈 칸 가능)"` (free text) → `directive`
+8. `AskUserQuestion` `"관련 task id 목록, 쉼표 구분 (선택, 빈 칸 가능)"` (free text) → `related_tasks_raw`
+9. `AskUserQuestion` `"clarification-response 파일 경로 (follow-up 시에만, 빈 칸 가능)"` (free text) → `clarification_response_path`
 
 For prompts whose target worker is NOT in the resolved workers list (after override), skip the prompt and present a single line such as `gemini-model 생략 (workers에 gemini 없음)`.
 
@@ -224,7 +234,7 @@ Before invoking `okstra render-bundle`, echo the resolved selections back to the
   executor      : codex
   workers       : (프로필 기본 — executor + verifier 2 + report-writer)
   lead-model    : default (opus)
-  codex-model   : gpt-5.5-high           ← executor model
+  codex-model   : gpt-5.5                ← executor model
   claude-model  : default (sonnet)       ← verifier
   gemini-model  : default (auto)         ← verifier
   report-writer : default (opus)

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

@@ -17,13 +17,17 @@ okstra tasks are always operated using the `Claude lead` + required worker team
 
 ### Role Definitions
 
-| Role | Responsibilities | Default Model | subagent_type | Notes |
-|------|------|-----------|---------------|------|
-| Claude lead | orchestration + convergence supervision + final-report review/approval | opus | -- | Does NOT author the final-report file when `Report writer worker` is in the roster |
-| Claude worker | Inference quality, hidden assumptions, execution risks | sonnet | claude-worker | `agents/claude-worker.md` |
-| Codex worker | Implementation feasibility, code paths, edge cases | gpt-5.5 | codex-worker | `agents/codex-worker.md` |
-| Gemini worker | Requirement interpretation, consistency, safety, alternatives | auto | gemini-worker | `agents/gemini-worker.md` |
-| Report writer worker | **Authors** the final-report file in Phase 6. NOT an analysis worker. | opus | report-writer-worker | `agents/report-writer-worker.md`. Excluded from Phase 4/5 and convergence |
+**All analysis workers (Claude / Codex / Gemini) share an identical core responsibility.** Specialization is additive — it lives in optional Section 6 of the worker output, NOT in differentiated core questions. This is intentional: cross-verification only converges if all three workers are answering the same questions against the same brief. Disjoint per-worker scopes produce union-of-perspectives, not triangulation.
+
+| Role | Core responsibility | Specialization lens (Section 6 only) | Default Model | subagent_type | Notes |
+|------|------|------|-----------|---------------|------|
+| Claude lead | orchestration + convergence supervision + final-report review/approval | — | opus | -- | 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 | sonnet | 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 | gpt-5.5 | 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 | auto | gemini-worker | `agents/gemini-worker.md` |
+| Report writer worker | **Authors** the final-report file in Phase 6. NOT an analysis worker. | — | opus | report-writer-worker | `agents/report-writer-worker.md`. Excluded from Phase 4/5 and convergence |
+
+**Dispatch-prompt invariant (BLOCKING).** Lead's dispatch prompt body for Claude / Codex / Gemini workers MUST be byte-identical except for the role label and any wrapper-specific path headers (e.g. `**Worktree:**`, `**Errors sidecar path:**`). Lead MUST NOT bias the brief by inserting per-worker emphasis sentences ("you focus on X") into the body. Bias-by-prompt reproduces the historical failure mode where Claude commented only on assumptions, Codex only on code paths, and Gemini only on requirements — leaving convergence with nothing to converge on.
 
 ### Model Assignment Rules
 
@@ -72,7 +76,7 @@ If the task brief contains an `## Available MCP Servers` section, copy that sect
 
 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.
 
-Do not send identical undifferentiated prompts to every worker unless that is clearly the best option. Role-specific emphasis (Phase 2 of `okstra` skill) is the canonical guidance.
+Send byte-identical dispatch prompts to every analysis worker (Claude / Codex / Gemini), modulo the role label and the wrapper-specific path headers enumerated in the "Dispatch-prompt invariant" rule of the Role Definitions section. The prior "role-specific emphasis" guidance is retired — emphasis in the body biases each worker toward its lens and silently kills convergence (see Role Definitions for the failure mode). Specialization lives in Section 6 of the worker output, not in the dispatch prompt body.
 
 ### Required reading clause (analysis workers + report-writer worker)
 
@@ -206,6 +210,11 @@ A successful worker result must include the following sections in this exact ord
 3. Safe or Reasonable Areas
 4. Uncertain Points
 5. Recommended Next Actions
+6. **Specialization Lens (optional, worker-specific deep dive)** — additive content produced from this worker's specialization lens (see Role Definitions table). Items here are NOT subject to convergence cross-verification and MUST NOT duplicate sections 1–5. If the worker has nothing additional to add from its lens, omit Section 6 entirely or write `- No additional lens-specific findings.`
+
+**Sections 1–5 are the common core.** Every analysis worker (Claude / Codex / Gemini) MUST cover the same set of dimensions in sections 1–5 — feasibility, requirement interpretation, hidden assumptions, alternatives, and execution risk — regardless of which model is producing the result. The point of running three models is to triangulate the same answer space, not to partition it. A worker that produces "Findings" populated only with items from its own lens (e.g. Codex only listing implementation-feasibility findings) is in breach of contract; convergence will treat coverage gaps as `verification-error`.
+
+**Section 6 is the only legal home for specialization.** When the worker has a depth-of-perspective contribution that genuinely sits outside the common core (e.g. a Codex-specific stack-trace decomposition, a Claude-specific assumption-chain teardown, a Gemini-specific alternative-architecture sketch), put it there. Lead and convergence treat Section 6 as additive context, not as input to consensus measurement.
 
 Code evidence must include file paths and line numbers.