okstra 0.18.1 → 0.18.3

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.3",
   "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.3",
+  "builtAt": "2026-05-13T13:59:58.844Z",
   "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/python/okstra_token_usage/collect.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 import json
+from datetime import datetime
 from pathlib import Path
 from .blocks import na_block, usage_block
 from .claude import claude_session_totals, find_claude_team_sessions
@@ -11,6 +12,76 @@ from .paths import claude_project_dir, utc_now
 from .pricing import codex_cost_usd, gemini_cost_usd
 
 
+def match_prefixes(worker_id: str) -> list[str]:
+    """Return the agentName prefixes that should be attributed to ``worker_id``.
+
+    The Agent harness records the `name` arg on every dispatch as `agentName`
+    in the subagent jsonl. Lead frequently appends suffixes (`-002`,
+    `-reverify-r1`, `-impl`, `-2`) when it dispatches the same role multiple
+    times or in different sub-flows. We treat every `agentName` matching one of
+    these prefixes — either exactly or as `<prefix>-<suffix>` — as belonging
+    to this worker so its tokens get aggregated. For implementation runs the
+    executor variant `<provider>-executor` is also attributed back to the
+    matching provider worker.
+    """
+    if not worker_id:
+        return []
+    if worker_id == "report-writer":
+        return ["report-writer"]
+    prefixes = [worker_id]
+    if not worker_id.endswith("-worker"):
+        prefixes.append(f"{worker_id}-worker")
+        prefixes.append(f"{worker_id}-executor")
+    return prefixes
+
+
+def agent_matches(agent_name: str, prefixes: list[str]) -> bool:
+    if not agent_name:
+        return False
+    for prefix in prefixes:
+        if agent_name == prefix or agent_name.startswith(f"{prefix}-"):
+            return True
+    return False
+
+
+def _aggregate_totals(items: list[dict]) -> dict:
+    """Sum token + tool counters across multiple session totals dicts.
+
+    `startedAt` / `endedAt` collapse to the union window; `durationMs` is
+    recomputed from that window so re-tries and convergence rounds count
+    against a single contiguous span. `model` and `agentName` keep the first
+    non-empty value (the canonical role identity).
+    """
+    aggregate: dict = {
+        "totalTokens": 0, "inputTokens": 0, "outputTokens": 0,
+        "cacheCreationTokens": 0, "cacheReadTokens": 0,
+        "toolUses": 0, "durationMs": 0,
+        "agentName": None, "model": None,
+        "startedAt": None, "endedAt": None,
+    }
+    for t in items:
+        for k in ("totalTokens", "inputTokens", "outputTokens",
+                  "cacheCreationTokens", "cacheReadTokens", "toolUses"):
+            aggregate[k] += t.get(k, 0) or 0
+        if aggregate["agentName"] is None and t.get("agentName"):
+            aggregate["agentName"] = t["agentName"]
+        if aggregate["model"] is None and t.get("model"):
+            aggregate["model"] = t["model"]
+        s, e = t.get("startedAt"), t.get("endedAt")
+        if s and (aggregate["startedAt"] is None or s < aggregate["startedAt"]):
+            aggregate["startedAt"] = s
+        if e and (aggregate["endedAt"] is None or e > aggregate["endedAt"]):
+            aggregate["endedAt"] = e
+    if aggregate["startedAt"] and aggregate["endedAt"]:
+        try:
+            a = datetime.fromisoformat(aggregate["startedAt"].replace("Z", "+00:00"))
+            b = datetime.fromisoformat(aggregate["endedAt"].replace("Z", "+00:00"))
+            aggregate["durationMs"] = max(0, int((b - a).total_seconds() * 1000))
+        except ValueError:
+            pass
+    return aggregate
+
+
 def collect(team_state_path: Path, project_root: Path | None = None) -> dict:
     state = json.loads(team_state_path.read_text())
     cwd = project_root or _infer_project_root(team_state_path, state)
@@ -26,19 +97,20 @@ def collect(team_state_path: Path, project_root: Path | None = None) -> dict:
         team_name = f"okstra-{task_id}" if task_id else ""
     lead_sid = (state.get("lead") or {}).get("sessionId")
 
-    # 1) Claude sessions (lead + claude-side workers).
+    # 1) Claude sessions (lead + claude-side workers). Cache totals at scan
+    # time so we don't re-read the jsonl when a worker matches multiple
+    # sessions.
     claude_sessions = find_claude_team_sessions(cwd, team_name, lead_sid)
-    by_agent: dict[str, tuple[str, Path]] = {}
+    by_agent: dict[str, list[tuple[str, Path, dict]]] = {}
     lead_path: Path | None = None
     for sid, path in claude_sessions.items():
         if sid == lead_sid:
             lead_path = path
             continue
-        # Read agentName lazily.
         totals = claude_session_totals(path)
         agent = totals.get("agentName")
         if agent:
-            by_agent[agent] = (sid, path)
+            by_agent.setdefault(agent, []).append((sid, path, totals))
 
     # Lead.
     if lead_path is not None:
@@ -50,35 +122,39 @@ def collect(team_state_path: Path, project_root: Path | None = None) -> dict:
             f"lead session jsonl not found under {claude_project_dir(cwd)} (sessionId={lead_sid})"
         )
 
-    # Workers.
+    # Workers — match by prefix and aggregate every session that belongs to
+    # the same role (re-dispatches with `-002`, convergence `-reverify-r1`,
+    # implementation `-executor`, report-writer `-impl` / `-2`, etc.).
     for worker in state.get("workers", []):
         worker_id = worker.get("workerId")
         agent = worker.get("agent")
-        # Subagent agentName convention: workerId itself is "claude" but agentName is "claude-worker"; report-writer == "report-writer".
-        agent_name_candidates = []
-        if worker_id:
-            agent_name_candidates.append(worker_id)
-            if not worker_id.endswith("-worker") and worker_id != "report-writer":
-                agent_name_candidates.append(f"{worker_id}-worker")
-
-        # Claude wrapper jsonl (also for codex/gemini-worker, since these are Claude subagents).
-        wrapper = None
-        for cand in agent_name_candidates:
-            if cand in by_agent:
-                wrapper = by_agent[cand]
-                break
-        if wrapper is None:
-            worker["usage"] = na_block(f"no Claude subagent jsonl found with agentName matching {agent_name_candidates}")
+        prefixes = match_prefixes(worker_id) if worker_id else []
+
+        matched: list[tuple[str, Path, dict]] = []
+        for agent_name, entries in by_agent.items():
+            if agent_matches(agent_name, prefixes):
+                matched.extend(entries)
+
+        if not matched:
+            worker["usage"] = na_block(
+                f"no Claude subagent jsonl found with agentName matching prefixes {prefixes}"
+            )
             continue
-        sid, path = wrapper
-        totals = claude_session_totals(path)
-        block = usage_block(totals, source="claude-jsonl")
-        block["sessionId"] = sid
 
-        # For codex/gemini workers, also try to find the underlying CLI session
-        # within the wrapper subagent's time window.
-        wrapper_start = totals.get("startedAt") or ""
-        wrapper_end = totals.get("endedAt") or ""
+        # Stable order by startedAt so the "primary" session is the first one.
+        matched.sort(key=lambda x: x[2].get("startedAt") or "")
+        primary_sid, _primary_path, _primary_totals = matched[0]
+        aggregate = _aggregate_totals([t for _, _, t in matched])
+        block = usage_block(aggregate, source="claude-jsonl")
+        block["sessionId"] = primary_sid
+        if len(matched) > 1:
+            block["additionalSessionIds"] = [sid for sid, _, _ in matched[1:]]
+            block["matchedAgentNames"] = sorted({t.get("agentName") for _, _, t in matched if t.get("agentName")})
+
+        # For codex/gemini workers, find every CLI session that fell inside the
+        # aggregated wrapper window.
+        wrapper_start = aggregate.get("startedAt") or ""
+        wrapper_end = aggregate.get("endedAt") or ""
         if agent in ("codex", "gemini"):
             if agent == "codex":
                 cli = find_codex_session(cwd, wrapper_start, wrapper_end)

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-report-writer/SKILL.md

@@ -90,7 +90,7 @@ Behaviour contract:
 After the spawner completes, the report-writer worker MUST update Section 6 ("Recommended Next Steps") to list every newly created task-key together with its entry command, so the user can pick the follow-up up immediately:
 
 ```
-- Follow-up: `<task-group>/<new-task-id>` — `okstra --task-key <task-group>/<new-task-id> --task-type <suggested>`
+- Follow-up: `<task-group>/<new-task-id>` — Claude Code 세션 안 `/okstra-run task-key=<task-group>/<new-task-id> task-type=<suggested>` / 별도 터미널 `scripts/okstra.sh --task-key <task-group>/<new-task-id> --task-type <suggested>`
 ```
 
 ## Phase 7 token-usage collector (BLOCKING)

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.
 

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

@@ -13,8 +13,12 @@
 > 다음 `implementation` run은 아래 체크박스가 `[x]`로 표시되어 있을 때에만 진입할 수 있습니다 (`okstra_ctl.run._validate_approved_plan` 가 이 마커를 line-anchored 정규식으로 검사하여 통과/거부합니다). 본문(`Sections 1`–`4.5`)을 끝까지 읽고, `4.5.9 Open Questions`가 비어 있거나 모두 해소된 뒤 승인해 주세요.
 
 - 승인 여부 (사용자가 직접 편집): `- [ ] Approved` ← 승인하려면 `[ ]` 를 `[x]` 로 변경하여 저장하세요.
-- 승인 후 다음 단계 명령어 (방법 A — 수동 편집): `okstra --task-key {{TASK_KEY}} --task-type implementation --approved-plan <이 보고서 경로>`
-- 승인 + 실행 한 번에 (방법 B — CLI 자체를 승인 의사로): `okstra --task-key {{TASK_KEY}} --task-type implementation --approved-plan <이 보고서 경로> --approve`
+- 승인 후 다음 단계 명령어 (방법 A — 수동 편집):
+  - Claude Code 세션 안: `/okstra-run task-key={{TASK_KEY}} task-type=implementation approved-plan=<이 보고서 경로>`
+  - 별도 터미널: `scripts/okstra.sh --task-key {{TASK_KEY}} --task-type implementation --approved-plan <이 보고서 경로>`
+- 승인 + 실행 한 번에 (방법 B — 진입 명령 자체를 승인 의사로):
+  - Claude Code 세션 안: `/okstra-run task-key={{TASK_KEY}} task-type=implementation approved-plan=<이 보고서 경로> approve`
+  - 별도 터미널: `scripts/okstra.sh --task-key {{TASK_KEY}} --task-type implementation --approved-plan <이 보고서 경로> --approve`
   - 방법 B 는 `--approve` 입력 행위 자체를 승인 의사로 모델링합니다. 런타임이 본 블록의 체크박스를 자동으로 `[x]` 로 바꾸고, 본 섹션 하단에 `승인 일시 (CLI ack): <ISO8601>` audit 라인을 한 줄 덧붙입니다.
 - 승인을 보류하거나 거부하려면 체크박스는 `[ ]` 로 두고 `--approve` 도 사용하지 마세요. 필요한 변경 사항은 `4.5.9 Open Questions` 또는 `Section 5 Clarification Requests` 에 기록한 뒤 같은 phase 를 재실행해 주세요.
 
@@ -270,7 +274,11 @@ H1 이 `skip` 이거나 H3 가 `cancel` 인 경우, 본 섹션 다음의 4.6.4 ~
   - `resolved`: 다음 run에서 lead가 답변을 받아 검증을 마쳤습니다.
   - `obsolete`: 이후 분석 결과로 더 이상 필요 없어진 항목입니다.
 
-이 보고서에 답을 채우신 뒤에는 `okstra --resume-clarification --task-key {{TASK_KEY}}` 한 줄로 같은 phase를 다시 실행하실 수 있습니다(자동으로 `$EDITOR`가 이 파일을 열고, 저장하면 같은 phase가 `--clarification-response`로 carry-in 되어 재실행됩니다). 스크립트로 자동화하실 때는 기존 형식 `okstra --task-key {{TASK_KEY}} --task-type {{TASK_TYPE}} --clarification-response <이 파일 경로>`도 그대로 사용하실 수 있습니다.
+이 보고서에 답을 채우신 뒤에는 한 줄로 같은 phase를 다시 실행하실 수 있습니다(자동으로 `$EDITOR`가 이 파일을 열고, 저장하면 같은 phase가 `--clarification-response`로 carry-in 되어 재실행됩니다).
+- Claude Code 세션 안: `/okstra-run resume-clarification task-key={{TASK_KEY}}`
+- 별도 터미널: `scripts/okstra.sh --resume-clarification --task-key {{TASK_KEY}}`
+
+스크립트로 자동화하실 때는 셸 형식 `scripts/okstra.sh --task-key {{TASK_KEY}} --task-type {{TASK_TYPE}} --clarification-response <이 파일 경로>`도 그대로 사용하실 수 있습니다. Node `okstra` admin CLI 는 `--task-key`/`--task-type`/`--resume-clarification` 을 받지 않으므로 위 두 진입점 중 하나를 사용하세요.
 
 ### 5.1 추가 자료 요청 (Additional Materials Requested)
 
@@ -298,16 +306,22 @@ H1 이 `skip` 이거나 H3 가 `cancel` 인 경우, 본 섹션 다음의 4.6.4 ~
 
 This section is **always present** in every final report — never omit the heading. If there are no concrete actions to take, write the single line `- No further action required. Final verdict in section 2 stands.` under the heading and stop.
 
-When concrete actions exist, list them as a numbered list using the rules below. Each item must include the exact command(s) the user can copy-paste. Prefer the `--task-key` shorthand for follow-up runs and `--resume-clarification` for clarification answer turn-arounds; show the equivalent full-args form only when useful.
+When concrete actions exist, list them as a numbered list using the rules below. Each item must include the exact command(s) the user can copy-paste. Show **both** the Claude Code in-session form (`/okstra-run …`) and the external-terminal shell form (`scripts/okstra.sh …`) — the Node `okstra` admin CLI does NOT accept `--task-key` / `--task-type` / `--resume-clarification`. Prefer the `task-key` shorthand for follow-up runs and `resume-clarification` for clarification answer turn-arounds; show the equivalent full-args form only when useful.
 
 1. **Highest-priority next action.** State what to do and why in one sentence, then the command. Example shortcut forms:
-   - Same phase rerun: `okstra --task-key {{TASK_KEY}} --task-type {{TASK_TYPE}}`
-   - Next phase: `okstra --task-key {{TASK_KEY}} --task-type <next-phase>` (omit `--task-type` to use the manifest's `workflow.nextRecommendedPhase` automatically when it is a concrete phase, not `pending-routing-decision` / `done-or-follow-up`).
+   - Same phase rerun:
+     - Claude Code 세션 안: `/okstra-run task-key={{TASK_KEY}} task-type={{TASK_TYPE}}`
+     - 별도 터미널: `scripts/okstra.sh --task-key {{TASK_KEY}} --task-type {{TASK_TYPE}}`
+   - Next phase (omit `task-type` to use the manifest's `workflow.nextRecommendedPhase` automatically when it is a concrete phase, not `pending-routing-decision` / `done-or-follow-up`):
+     - Claude Code 세션 안: `/okstra-run task-key={{TASK_KEY}} task-type=<next-phase>`
+     - 별도 터미널: `scripts/okstra.sh --task-key {{TASK_KEY}} --task-type <next-phase>`
 2. **Additional verification needed before implementation or release.** List read-only checks (test commands, log queries, dashboard URLs) that the user should run before moving to the next phase. No state-mutating commands here.
 3. **Follow-up tasks or related tasks if needed.** Reference them by `task-key` when they already exist; otherwise describe the new brief to draft.
 4. **If section 5 has any `open` rows**, the highest-priority next step MUST be the clarification turn-around. Show both forms:
-   - Preferred (interactive): `okstra --resume-clarification --task-key {{TASK_KEY}}` — opens this file in `$EDITOR`, then auto-reruns the same phase with `--clarification-response` carry-in.
-   - Scripted: `okstra --task-key {{TASK_KEY}} --task-type {{TASK_TYPE}} --clarification-response <path-to-this-file-after-editing>`.
+   - Preferred (interactive) — opens this file in `$EDITOR`, then auto-reruns the same phase with `--clarification-response` carry-in:
+     - Claude Code 세션 안: `/okstra-run resume-clarification task-key={{TASK_KEY}}`
+     - 별도 터미널: `scripts/okstra.sh --resume-clarification --task-key {{TASK_KEY}}`
+   - Scripted: `scripts/okstra.sh --task-key {{TASK_KEY}} --task-type {{TASK_TYPE}} --clarification-response <path-to-this-file-after-editing>`.
 
 Empty-state placeholder, copy verbatim when nothing else applies: