okstra 0.6.0 → 0.7.0

package/README.kr.md

@@ -107,7 +107,7 @@ CLI 에서:
 
 ```bash
 cd <대상 프로젝트>
-npx -y okstra@latest setup --project-id <id>     # 예: INV-1234, fontsninja, okstra
+npx -y okstra@latest setup --project-id <id>     # 예: INV-1234, my-app, okstra
 ```
 
 또는 Claude Code 세션 안에서 동일한 슬래시 커맨드:

package/README.md

@@ -106,7 +106,7 @@ From the CLI:
 
 ```bash
 cd <your project>
-npx -y okstra@latest setup --project-id <id>     # e.g. INV-1234, fontsninja, okstra
+npx -y okstra@latest setup --project-id <id>     # e.g. INV-1234, my-app, okstra
 ```
 
 Or, inside a Claude Code session, invoke the equivalent slash command:

package/docs/kr/architecture.md

@@ -283,8 +283,8 @@ Claude launch prompt 본문은 항상 `prompts/launch.template.md` 템플릿에
 
 ```json
 {
-  "projectId": "fontradar-v2-api",
-  "projectRoot": "/Volumes/Workspaces/workspace/projects/fontradar",
+  "projectId": "sample-project-v2-api",
+  "projectRoot": "/Volumes/Workspaces/workspace/projects/sample-project",
   "createdAt": "2026-05-10T00:00:00Z",
   "updatedAt": "2026-05-10T00:00:00Z"
 }
@@ -844,6 +844,7 @@ Claude가 작성하는 최종 보고서는 brief에 더 구체적인 형식이
 - worker 생성과 결과 취합은 Claude가 수행합니다.
 - standard workflow는 `Claude lead` + required worker `Claude worker`, `Codex worker`, `Gemini worker`, `Report writer worker`를 사용합니다.
 - worker 모델은 `--lead-model`, `--claude-model`, `--codex-model`, `--gemini-model`, `--report-writer-model`로 override할 수 있고, 기본값은 `OKSTRA_DEFAULT_*` 환경 변수에서 중앙 관리합니다. fallback 기본값은 `Claude lead`/`Report writer worker`=`opus`, `Claude worker`=`sonnet`, `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 이 기록됩니다.
 - project-level current-task convenience pointer는 `.project-docs/okstra/discovery/latest-task.json`입니다.
 - project-level canonical task inventory는 `.project-docs/okstra/discovery/task-catalog.json`입니다.
 - project-local okstra Claude asset은 `.claude/skills/`와 `.claude/agents/` 아래에 seed되며, 기본 rerun에서는 보존되고 `--refresh-assets`로 다시 생성할 수 있습니다.
@@ -876,7 +877,7 @@ Claude가 작성하는 최종 보고서는 brief에 더 구체적인 형식이
 - 종료 처리는 `okstra-ctl` 의 모든 진입점에서 호출되는 lazy reconcile 이 수행한다(타깃 프로젝트의 `final-report-*.md` 존재로 추론).
 - 다중 rerun 은 대상 1건당 tmux 세션 1개를 detached 로 spawn 하고 즉시 반환한다(fire-and-forget). 사용자는 반환된 attach 명령으로 임의 세션에 접속한다.
 - spawn 임계 기본값은 10. `--max-spawn N` 또는 `OKSTRA_CTL_MAX_SPAWN` 으로 변경 가능.
-- runId 형식: `<project-id>/<task-group>/<task-id>/<task-type>/r<run-seq>` (예: `fontradar/payment/fail/error-analysis/r07`). 입력 시 prefix substring 매칭을 지원한다.
+- runId 형식: `<project-id>/<task-group>/<task-id>/<task-type>/r<run-seq>` (예: `sample-project/payment/fail/error-analysis/r07`). 입력 시 prefix substring 매칭을 지원한다.
 
 ### 동시성 제어 (두 단계 mutex)
 

package/docs/kr/cli.md

@@ -9,7 +9,7 @@
 기본 명령(첫 진입 / full args):
 
 ```bash
-scripts/okstra.sh [--render-only] [--yes] [--refresh-assets] --task-type <task-type> [--workers worker1,worker2] [--lead-model <model>] [--claude-model <model>] [--codex-model <model>] [--gemini-model <model>] [--report-writer-model <model>] [--related-tasks taskA,taskB] [--clarification-response <previous-final-report>] --project-id <project-id> --task-group <task-group> --task-id <task-id> --task-brief <brief-path> [--directive <directive>]
+scripts/okstra.sh [--render-only] [--yes] [--refresh-assets] --task-type <task-type> [--workers worker1,worker2] [--lead-model <model>] [--claude-model <model>] [--codex-model <model>] [--gemini-model <model>] [--report-writer-model <model>] [--executor claude|codex|gemini] [--related-tasks taskA,taskB] [--clarification-response <previous-final-report>] --project-id <project-id> --task-group <task-group> --task-id <task-id> --task-brief <brief-path> [--directive <directive>]
 ```
 
 후속 phase 단축 형식(기존 task-manifest.json이 존재할 때):
@@ -41,7 +41,7 @@ interactive terminal에서 실행하면 다음 규칙이 추가로 적용됩니
 
 예:
 
-- `fontradar-v2-api`
+- `sample-project-v2-api`
 - `jobs`
 
 ### `--task-group`
@@ -268,6 +268,7 @@ scripts/okstra.sh --task-type implementation-planning --workers claude,codex --p
 - `OKSTRA_DEFAULT_CODEX_MODEL`
 - `OKSTRA_DEFAULT_GEMINI_MODEL`
 - `OKSTRA_DEFAULT_REPORT_WRITER_MODEL`
+- `OKSTRA_DEFAULT_EXECUTOR` (`claude` | `codex` | `gemini`, fallback `claude`)
 
 fallback 기본값은 아래와 같습니다.
 
@@ -276,6 +277,28 @@ fallback 기본값은 아래와 같습니다.
 - `Claude worker`: `sonnet`
 - `Codex worker`: `gpt-5.5`
 - `Gemini worker`: `auto`
+- Implementation executor: `claude` (즉 기본은 `Claude executor`)
+
+### `--executor`
+
+`--task-type implementation` 에서 Executor 역할을 맡을 provider 를 선택합니다. 값은 `claude` | `codex` | `gemini` 중 하나이며, 다른 task-type 에서는 무시됩니다.
+
+- 기본값: `OKSTRA_DEFAULT_EXECUTOR` → fallback `claude`
+- Executor 는 이 run 에서 **유일하게 프로젝트 파일을 mutate 할 수 있는 worker** 입니다. 나머지 두 provider 는 같은 run 에서 strict read-only verifier 로 dispatch 됩니다.
+- Executor 의 모델은 provider 별 worker 모델 플래그를 그대로 재사용합니다. 즉 `--executor codex` 이면 Executor 의 모델은 `--codex-model` (기본 `gpt-5.5`), `--executor gemini` 이면 `--gemini-model` (기본 `auto`) 가 됩니다.
+- Claude/Codex/Gemini 세 verifier 는 executor provider 와 관계없이 항상 dispatch 됩니다. Executor 와 같은 provider 라도 별도 CLI 세션으로 verifier 가 호출되어 context 가 분리되므로 self-review 안전장치는 유지됩니다.
+- 실제 파일 변경은 Codex/Gemini 의 경우 각 CLI 의 auto-edit 모드 (예: `codex exec --full-auto`) 를 통해 일어나며, Claude-side Edit/Write tool 을 거치지 않습니다.
+
+예:
+
+```bash
+scripts/okstra.sh --task-type implementation \
+  --executor codex \
+  --codex-model gpt-5.5 \
+  --approved-plan .project-docs/.../runs/implementation-planning/.../reports/final-report-implementation-planning-001.md \
+  --project-id jobs --task-group tasks --task-id 8852 \
+  --task-brief .project-docs/tasks/8852/BUG_REPORT.md
+```
 
 ### `--related-tasks`
 
@@ -387,7 +410,7 @@ chmod +x ~/.local/bin/okstra-ctl
 |---|---|
 | 작업한 프로젝트 목록 | `okstra-ctl projects` |
 | 최근 run 검색 | `okstra-ctl list --since 7d` |
-| 특정 프로젝트만 | `okstra-ctl list --project fontradar` |
+| 특정 프로젝트만 | `okstra-ctl list --project sample-project` |
 | 진행 중 run 보기 | `okstra-ctl tail active` |
 | 단일 run 결과 메타 | `okstra-ctl show <runId-or-prefix>` |
 | 결과 보고서 경로 | `okstra-ctl open <runId-or-prefix>` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.6.0",
+  "version": "0.7.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.6.0",
-  "builtAt": "2026-05-12T04:57:34.255Z",
+  "package": "0.7.0",
+  "builtAt": "2026-05-12T08:22:42.014Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/SKILL.md

@@ -96,6 +96,17 @@ Unless the task bundle overrides:
 
 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.
 
+### Implementation phase: Executor binding
+
+For `--task-type implementation` runs, the task bundle additionally pins one of `claude` / `codex` / `gemini` as the Executor — the only worker permitted to mutate project files in that run. The binding is exposed in two canonical places:
+
+- `instruction-set/analysis-profile.md` — top "Executor binding" block (provider, displayName, workerAgent, model)
+- `runs/implementation/manifests/run-manifest-*.json` — `teamContract.executor` object (same fields plus `appliesTo: "implementation"`)
+
+Lead MUST dispatch Edit/Write-bearing work only through the `workerAgent` declared there. The other two providers still run as read-only verifiers in the same run; the executor's own provider is *also* dispatched separately as a verifier (a fresh CLI session) so the diff is reviewed by a context-isolated session. Session isolation is the primary self-review safeguard — same-model executor and same-provider verifier is acceptable when running in distinct sessions. Selecting a different model variant (e.g. executor=opus / Claude verifier=sonnet) is recommended but no longer mandatory.
+
+Executor is chosen at run-prep time via `--executor <claude|codex|gemini>` (or `OKSTRA_DEFAULT_EXECUTOR`, fallback `claude`); the model used by the executor is taken from the corresponding worker model flag (`--claude-model` / `--codex-model` / `--gemini-model`). For Codex/Gemini executors, the underlying file mutation happens inside the executor CLI's own auto-edit mode (e.g. `codex exec --full-auto`), not through Claude-side Edit/Write tools.
+
 ## Phase 1: Task-bundle intake and required reading order
 
 **REQUIRED SUB-SKILL:** Invoke [okstra-context-loader](./skills/okstra-context-loader/SKILL.md) first to discover task bundle paths.
@@ -130,13 +141,14 @@ These phases are governed by [okstra-team-contract](./skills/okstra-team-contrac
 
 `Report writer worker` is NOT an analysis worker. Do not dispatch it in Phase 4/5 alongside analysis workers. It is invoked only in Phase 6 — see [okstra-report-writer](./skills/okstra-report-writer/SKILL.md).
 
-### Phase 3 — Team creation
+### Phase 3 — Team creation (BLOCKING)
 
-Always attempt team creation first. Do not check environment variables or guess availability.
+`TeamCreate` MUST be the first Agent-related tool call after Phase 2 prompt preparation. Do not call `Agent(... team_name: ...)` for any worker until this phase has executed — the Agent tool rejects `team_name` for non-existent teams with `"team을 먼저 생성하거나 team_name 없이 호출해야 합니다"` / `"team must be created first or call without team_name"`, and silently stripping `team_name` to retry is NOT a valid recovery (it loses the Teams split-pane behavior and is indistinguishable from never having attempted Teams mode).
 
 1. Call `TeamCreate(team_name: "okstra-<task-key>", description: "Lead-plus-worker okstra run for <task-key>")`.
-2. If `TeamCreate` succeeds, proceed to Phase 4.
-3. If `TeamCreate` fails (tool error, permission denied, or unavailable), proceed to Phase 5 fallback.
+2. Record the `TeamCreate` outcome in team-state under `teamCreate: { attempted: true, status: "ok"|"error", error?: <message> }` before any dispatch. This is the audit trail that justifies a later no-`team_name` fallback.
+3. If `TeamCreate` succeeds, proceed to Phase 4 (dispatch with `team_name`).
+4. If `TeamCreate` fails (tool unavailable, permission denied, environment lacks Agent Teams support), proceed to Phase 5 fallback (dispatch with `run_in_background: true` and no `team_name`).
 
 Use agent and subagent names that map cleanly to the selected worker roles. Do not create ambiguous role names that differ from `Claude worker`, `Codex worker`, `Gemini worker`, or `Report writer worker`.
 
@@ -144,6 +156,8 @@ Use agent and subagent names that map cleanly to the selected worker roles. Do n
 
 Spawn **analysis workers only** in the same turn (Phase 4 in Teams mode; Phase 5 with `run_in_background: true` and no `team_name` when Teams unavailable). Preserve exact roster, role labels, assigned models from the task bundle.
 
+The no-`team_name` fallback (Phase 5) is only legal when team-state's `teamCreate.status` is `"error"` for this run. If `teamCreate` is missing or `attempted: false`, the correct action when an Agent dispatch is rejected for a missing team is to GO BACK to Phase 3 and call `TeamCreate` — never to strip `team_name` and continue.
+
 After each worker terminates (any terminal status), if a worker errors sidecar exists at `runs/.../worker-results/<role-slug>-errors.json`, dump it to the run error log:
 
 ```bash
@@ -224,6 +238,8 @@ After persistence, reply briefly in Korean with: completion status, final report
 
 | Mistake | Fix |
 |---------|-----|
+| Dispatching workers with `team_name` before calling `TeamCreate` (Phase 3 skipped) | Phase 3 is BLOCKING — call `TeamCreate` first. The Agent tool's `"team must be created first"` rejection is not an environment-availability signal |
+| Stripping `team_name` and retrying when the Agent tool rejects the call for a non-existent team | This is silent loss of Teams split-pane mode. Correct action: go back to Phase 3 and call `TeamCreate`. The no-`team_name` fallback (Phase 5) is only legal after `TeamCreate` was attempted and recorded as `error` in team-state |
 | Substituting Claude lead reasoning for a worker result | Claude lead synthesizes only — spawn the worker |
 | Skipping a worker silently | Always record terminal status with reason |
 | Writing verdict before all workers report | Wait for all results or explicit terminal statuses |

package/runtime/agents/TODO.md

@@ -46,9 +46,22 @@ runs/<task-type>/
 
 ---
 
-## 항목 F4 — `implementation.md` 프로필의 워커 이름 매핑 누락 [블로킹: 설계 결정 필요]
+## 항목 F4 — `implementation.md` 프로필의 워커 이름 매핑 누락 [부분 진행 — Executor 선택 CLI 만 처리됨, 2026-05-12]
 
-### 문제
+### 부분 진행 메모 (2026-05-12)
+
+`--executor <claude|codex|gemini>` 플래그가 추가되어 Executor provider 를 run-prep 시점에 선택할 수 있게 됐고, profile 텍스트도 "Claude executor" → 일반화된 "Executor" 로 재작성됨. 즉 **CLI / 매니페스트 / 프로필 표현 레이어는 정리됨**.
+
+그러나 아래는 여전히 미해결:
+
+- `claude-executor.md` / `claude-verifier.md` / `codex-verifier.md` / `gemini-verifier.md` 4종 subagent 정식 등록은 안 됨. 현재 lead 는 dispatch 할 때 기존 `claude-worker` / `codex-worker` / `gemini-worker` 를 그대로 재사용하며, executor vs verifier 의 도구 화이트리스트 차이는 프롬프트 레벨에서만 강제됨.
+- run-manifest 의 `teamContract.executor.workerAgent` 가 가리키는 subagent 도 위 기존 `*-worker` 이름이라 도구-레벨 차단은 동작하지 않음.
+
+본 항목의 원래 의도(도구-레벨 read-only 강제)는 4종 subagent 등록이 머지되어야 완성됨.
+
+### 문제 (원본)
+
+> 2026-05-12 주: 아래 본문은 F4 가 처음 기록된 시점의 분석. "다음 워커 이름을 사용한다" 의 명단(특히 `Claude executor`)은 그 후 프로필 일반화로 `Executor` 단일 role 로 통합됐고 provider 는 `--executor` 로 선택하게 됐다. 핵심 미해결인 *도구-레벨 read-only 강제* 부분은 그대로 유효.
 
 [prompts/profiles/implementation.md](../../../prompts/profiles/implementation.md) 프로필은 다른 4개 프로필과 달리 다음 워커 이름을 사용한다:
 

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

@@ -18,7 +18,7 @@ description: |
   </example>
 model: inherit
 color: blue
-tools: ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "TodoWrite", "WebFetch", "WebSearch", "mcp__mysql-fontsninja-common__mysql_describe_table", "mcp__mysql-fontsninja-common__mysql_list_tables", "mcp__mysql-fontsninja-common__mysql_select_data", "mcp__mysql-fontsninja-fonthelper__mysql_describe_table", "mcp__mysql-fontsninja-fonthelper__mysql_list_tables", "mcp__mysql-fontsninja-fonthelper__mysql_select_data", "mcp__mysql-fontsninja-fontradar__mysql_describe_table", "mcp__mysql-fontsninja-fontradar__mysql_list_tables", "mcp__mysql-fontsninja-fontradar__mysql_select_data", "mcp__mysql-fontsninja-fontsninja__mysql_describe_table", "mcp__mysql-fontsninja-fontsninja__mysql_list_tables", "mcp__mysql-fontsninja-fontsninja__mysql_select_data"]
+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**.
@@ -43,7 +43,7 @@ Unlike the Codex / Gemini workers, you are an in-process Claude subagent — you
 
 4. Anchor all file operations to the absolute `Project Root` from the lead prompt. Use absolute paths — do NOT rely on inherited cwd. Never use `cd` to change directory.
 
-5. **MCP usage**: When the task requires database inspection, call MCP tools directly by name (e.g. `mcp__mysql-fontsninja-common__mysql_describe_table`). Do NOT shell out via `claude --mcp-cli call ...` — that fallback exists only when MCP tools are unavailable, and this agent has them registered explicitly above. Available MCP servers: `mcp__mysql-fontsninja-{common,fonthelper,fontradar,fontsninja}__{mysql_describe_table,mysql_list_tables,mysql_select_data}`.
+5. **MCP usage**: The canonical list of MCP servers and tools available for this run lives in the lead prompt's `## Available MCP Servers` section (sourced from `.project-docs/okstra/project.json`'s `mcpServers` array). When the task requires inspection of an external system covered by one of those servers, call the listed tool directly by name (e.g. `mcp__<server>__<tool>`). Do NOT shell out via `claude --mcp-cli call ...` or run the tool name as a Bash command — those are not valid invocation paths. If a server you need is not listed, record `MCP not available for this run` in your worker output rather than guessing a tool name.
 
 6. If the task brief includes an `## Available MCP Servers` section in the lead prompt, treat that as the canonical list of MCP tools you may invoke for this run. If a needed server is not listed, record `MCP not available for this run` rather than calling it.
 

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

@@ -11,7 +11,7 @@ description: |
   </example>
 color: purple
 model: inherit
-tools: ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "TodoWrite", "WebFetch", "WebSearch", "mcp__mysql-fontsninja-common__mysql_describe_table", "mcp__mysql-fontsninja-common__mysql_list_tables", "mcp__mysql-fontsninja-common__mysql_select_data", "mcp__mysql-fontsninja-fonthelper__mysql_describe_table", "mcp__mysql-fontsninja-fonthelper__mysql_list_tables", "mcp__mysql-fontsninja-fonthelper__mysql_select_data", "mcp__mysql-fontsninja-fontradar__mysql_describe_table", "mcp__mysql-fontsninja-fontradar__mysql_list_tables", "mcp__mysql-fontsninja-fontradar__mysql_select_data", "mcp__mysql-fontsninja-fontsninja__mysql_describe_table", "mcp__mysql-fontsninja-fontsninja__mysql_list_tables", "mcp__mysql-fontsninja-fontsninja__mysql_select_data"]
+tools: ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "TodoWrite", "WebFetch", "WebSearch"]
 ---
 
 You are the `Report writer worker` for okstra cross-verification. Your sole responsibility is to **author the final-report file** at the assigned `Result Path`. You are NOT an analysis worker — you do not produce independent findings, you do not vote in convergence, and you do not re-do the workers' analysis.
@@ -39,7 +39,7 @@ If you find yourself thinking "I'll just return the report inline and let lead s
 
 5. Anchor all file operations to the absolute `Project Root`. Use absolute paths everywhere — do not rely on inherited cwd, do not `cd`.
 
-6. **MCP usage**: If the lead prompt's `## Available MCP Servers` block lists tools, you may invoke them by name to verify evidence cited by analysis workers (e.g., to spot-check a `mcp__mysql-fontsninja-*` query result). Do not invent MCP tools that are not listed.
+6. **MCP usage**: If the lead prompt's `## Available MCP Servers` block lists tools, you may invoke them by name (e.g. `mcp__<server>__<tool>`) to verify evidence cited by analysis workers. Do not invent MCP tools that are not listed.
 
 ## Required Reading Before Authoring
 

package/runtime/bin/okstra.sh

@@ -77,6 +77,7 @@ okstra execution summary:
   directive: ${DIRECTIVE:-None}
   clarification response: ${CLARIFICATION_RESPONSE_PATH:-None}
   workers override: ${WORKERS_OVERRIDE:-None}
+  executor (implementation only): ${EXECUTOR_OVERRIDE:-default(claude)}
   approved plan: ${APPROVED_PLAN_PATH:-None}
   related tasks: ${RELATED_TASKS_RAW:-None}
 CONFIRM_EOF
@@ -111,6 +112,7 @@ PY_ARGS=(
 [[ -n "${CODEX_MODEL_OVERRIDE-}" ]] && PY_ARGS+=(--codex-model "$CODEX_MODEL_OVERRIDE")
 [[ -n "${GEMINI_MODEL_OVERRIDE-}" ]] && PY_ARGS+=(--gemini-model "$GEMINI_MODEL_OVERRIDE")
 [[ -n "${REPORT_WRITER_MODEL_OVERRIDE-}" ]] && PY_ARGS+=(--report-writer-model "$REPORT_WRITER_MODEL_OVERRIDE")
+[[ -n "${EXECUTOR_OVERRIDE-}" ]] && PY_ARGS+=(--executor "$EXECUTOR_OVERRIDE")
 [[ -n "${RELATED_TASKS_RAW-}" ]] && PY_ARGS+=(--related-tasks "$RELATED_TASKS_RAW")
 [[ -n "${APPROVED_PLAN_PATH-}" ]] && PY_ARGS+=(--approved-plan "$APPROVED_PLAN_PATH")
 [[ -n "${CLARIFICATION_RESPONSE_PATH-}" ]] && PY_ARGS+=(--clarification-response "$CLARIFICATION_RESPONSE_PATH")

package/runtime/prompts/launch.template.md

@@ -39,9 +39,9 @@ Invoke the `okstra` skill now. Read the manifests below for all task metadata, p
 
 ## Available MCP Servers
 
-- The user-scope MCP registration exposes read-only MySQL servers for the local Docker container: `mcp__mysql-fontsninja-common`, `mcp__mysql-fontsninja-fontradar`, `mcp__mysql-fontsninja-fontsninja`, `mcp__mysql-fontsninja-fonthelper`. Tools per server: `mysql_list_tables`, `mysql_describe_table`, `mysql_select_data` (max 1000 rows; write tools are server-disabled).
+{{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.
-- **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__mysql-fontsninja-fontsninja__mysql_list_tables`). 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.
+- **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/error-analysis.md

@@ -15,7 +15,7 @@
   - the final verdict waits until each required worker has either a result or an explicit terminal status
   - unnamed generic parallel workers must not replace the required role roster
 - Tooling — read-only MCP availability:
-  - `mcp__mysql-fontsninja-{common,fontradar,fontsninja,fonthelper}` (tools: `mysql_list_tables`, `mysql_describe_table`, `mysql_select_data`) may be queried to confirm symptoms against live schema or to inspect rows that reproduce the failure; the canonical usage policy is in the task brief's `## Available MCP Servers` section, and any MCP-derived hypothesis MUST cite server, table, and the SELECT used
+  - the read-only MCP servers declared in the task brief's `## Available MCP Servers` section may be queried to confirm symptoms against live schema or to inspect rows that reproduce the failure; that section is the canonical source of which servers and tools exist for this run, and any MCP-derived hypothesis MUST cite server, table, and the SELECT used
 - Primary focus areas:
   - symptom and trigger clarification
   - root-cause candidates
@@ -31,7 +31,7 @@
   - if any blocking uncertainty remains at the time of writing the final report, populate `## 5. Clarification Requests for the Next Run` in `final-report-template.md`
   - section 5 must be split into two distinct sub-sections per the template — `5.1 추가 자료 요청 (Additional Materials Requested)` for files/logs/screenshots the user must attach, and `5.2 사용자 확인 질문 (Questions for the User)` for decisions or facts only the user can confirm. Never mix material requests and decision questions in the same row or list.
   - write every entry in full, descriptive sentences that a non-developer can act on without further context. Avoid abbreviations and internal jargon (e.g. write "초당 평균 요청 수" instead of "QPS", "재현 절차" instead of "repro"). For each material request, state *why* it is needed, *where* the user can find it, and *where* to place it. For each question, state *why* the answer changes the next step, *what* is being asked in a complete sentence, and *what shape of answer* is expected (예/아니오, 보기 중 하나, 숫자/날짜, 짧은 서술 등); supply concrete option choices when applicable.
-  - the same `final-report.md` file is the canonical artifact carried into the next run; the user appends answers inline before rerunning. The preferred turn-around is `okstra --resume-clarification --task-key <project-id>:<task-group>:<task-id>` (opens the latest report in `$EDITOR`, then auto-reruns the same phase with `--clarification-response` carry-in). The lower-level form `--clarification-response <path>` remains available for scripted runs.
+  - the same `final-report.md` file is the canonical artifact carried into the next run; the user appends answers inline before rerunning. The preferred turn-around is `scripts/okstra.sh --resume-clarification --task-key <project-id>:<task-group>:<task-id>` (opens the latest report in `$EDITOR`, then auto-reruns the same phase with `--clarification-response` carry-in). The lower-level form `--clarification-response <path>` remains available for scripted runs.
   - if a clarification response was carried in for this run, reconcile each prior `A*` (material) and `Q*` (question) row in section 0 and update its `Status` (`resolved`, `obsolete`) before deciding the verdict
 - Authority & permissions assumption (HARD RULE — applies to every okstra task-type):
   - **Assume the user (and their team) holds full authority and every permission required for the anticipated work.** Treat external approvals, third-party access grants, role/IAM permissions, organisational sign-off, legal/compliance review, vendor coordination, and "verify access exists" steps as already satisfied unless the user explicitly states otherwise in the task brief.

package/runtime/prompts/profiles/final-verification.md

@@ -15,7 +15,7 @@
   - the final verdict waits until each required worker has either a result or an explicit terminal status
   - unnamed generic parallel workers must not replace the required role roster
 - Tooling — read-only MCP availability:
-  - `mcp__mysql-fontsninja-{common,fontradar,fontsninja,fonthelper}` (tools: `mysql_list_tables`, `mysql_describe_table`, `mysql_select_data`) may be queried to verify that the delivered change matches the live schema, that expected rows exist after a migration, or that invariants in `reference-expectations.md` hold against the database; the canonical usage policy is in the task brief's `## Available MCP Servers` section, and any MCP-derived blocker MUST cite server, table, and the SELECT used. MCP MUST NOT be used to perform fixes — defects become inputs to a new run.
+  - the read-only MCP servers declared in the task brief's `## Available MCP Servers` section may be queried to verify that the delivered change matches the live schema, that expected rows exist after a migration, or that invariants in `reference-expectations.md` hold against the database; that section is the canonical source of which servers and tools exist for this run, and any MCP-derived blocker MUST cite server, table, and the SELECT used. MCP MUST NOT be used to perform fixes — defects become inputs to a new run.
 - Primary focus areas:
   - requirement coverage
   - whether delivered config files and deployment manifests satisfy the recorded expected values
@@ -27,6 +27,25 @@
   - acceptance blockers
   - residual risk
   - final release recommendations
+- Required deliverable shape (final report, in addition to the standard sections):
+  - **Verdict vocabulary**: Section 2 (`Final Verdict`) MUST state exactly one of `accepted`, `conditional-accept`, or `blocked`. `conditional-accept` requires an explicit, exhaustive list of conditions; ambiguous verdicts ("looks good", "mostly ready") are not allowed.
+  - **Acceptance Blockers block** (under section 4): one row per blocker with `id`, `severity` (`critical` / `major` / `minor`), evidence (file path, log excerpt, or test output), and the recommended follow-up phase (`error-analysis` or `implementation-planning`). Empty block is acceptable and preferred — render the single line `- No acceptance blockers found.`
+  - **Residual Risk block** (under section 4): risks that are not blockers but should be tracked, each with mitigation owner and a trigger that would escalate them to a blocker.
+  - **Validation Evidence**: for every requirement in the originating plan or task brief, cite the artifact (commit SHA, test output, log line, MCP SELECT result) that demonstrates coverage. Paraphrased "verified" claims without an artifact are rejected.
+  - **Read-only command log**: any pre-existing test/validation command executed during this run MUST be listed with its exact command line and exit code. No mutating commands may appear here.
+  - **Routing recommendation**: brief note on the next safe phase (`done`, `error-analysis`, `implementation-planning`) tied to the verdict and blocker list.
+- Clarification request policy:
+  - if a blocker hinges on information only the user can supply (deployment intent, intended target environment, business-rule interpretation), populate `## 5. Clarification Requests for the Next Run` in `final-report-template.md`
+  - section 5 must be split into `5.1 추가 자료 요청 (Additional Materials Requested)` and `5.2 사용자 확인 질문 (Questions for the User)` per the template. Never mix material requests and decision questions in the same row or list.
+  - write every entry in full, descriptive sentences that a non-developer can act on without further context. Avoid abbreviations and internal jargon. For each material request, state *why* it is needed, *where* the user can find it, and *where* to place it. For each question, state *why* the answer changes the verdict, *what* is being asked in a complete sentence, and *what shape of answer* is expected (예/아니오, 보기 중 하나, 숫자/날짜, 짧은 서술 등); supply concrete option choices when applicable.
+  - the preferred turn-around is `scripts/okstra.sh --resume-clarification --task-key <project-id>:<task-group>:<task-id>`; the lower-level form `--clarification-response <path>` remains available for scripted runs.
+  - if a clarification response was carried in for this run, reconcile each prior `A*` and `Q*` row in section 0 and update its `Status` (`resolved`, `obsolete`) before issuing the final verdict
+- Self-review pass before finalising the report (`Claude lead` runs this; do not delegate to a generic subagent):
+  1. **Verdict precision** — section 2 uses one of the three allowed verdict tokens; `conditional-accept` lists every condition as an actionable item.
+  2. **Blocker traceability** — every blocker cites a concrete artifact (file:line, log excerpt, test exit code, MCP SELECT). Blockers without evidence are demoted to residual risk or removed.
+  3. **Coverage check** — every requirement in the originating plan/task brief is either marked covered (with artifact) or listed as a blocker. No silent omissions.
+  4. **Verifier dissent preserved** — if workers reach different verdicts, the disagreement is visible in section 1.2; synthesis hides nothing.
+  5. **No-mutation audit** — scan the run's session transcripts for any Edit / Write / mutating Bash command. Any occurrence means the run has crossed into implementation and MUST be re-routed; do NOT silently strip the evidence.
 - Authority & permissions assumption (HARD RULE — applies to every okstra task-type):
   - **Assume the user (and their team) holds full authority and every permission required for the delivered and follow-up work.** Treat external approvals, third-party access grants, role/IAM permissions, organisational sign-off, legal/compliance review, vendor coordination, and "verify access exists" steps as already satisfied unless the task brief explicitly states otherwise.
   - Do NOT raise such items as acceptance blockers, residual risks, or release recommendations, and do not factor them into any effort/day estimate for follow-up runs. They are not legitimate sources of schedule extension.

package/runtime/prompts/profiles/implementation-planning.md

@@ -15,7 +15,7 @@
   - the final verdict waits until each required worker has either a result or an explicit terminal status
   - unnamed generic parallel workers must not replace the required role roster
 - Tooling — read-only MCP availability:
-  - `mcp__mysql-fontsninja-{common,fontradar,fontsninja,fonthelper}` (tools: `mysql_list_tables`, `mysql_describe_table`, `mysql_select_data`) may be queried to size the blast radius of an option (table cardinality, column types, foreign-key fan-out, indexes), to validate migration assumptions, or to confirm that a proposed query shape returns the expected rows; the canonical usage policy is in the task brief's `## Available MCP Servers` section, and any MCP-derived figure entering the trade-off matrix or risk assessment MUST cite server, table, and the SELECT used. MCP MUST NOT be used as a write path even when planning a migration — schema changes belong in migration files reviewed by humans.
+  - the read-only MCP servers declared in the task brief's `## Available MCP Servers` section may be queried to size the blast radius of an option (table cardinality, column types, foreign-key fan-out, indexes), to validate migration assumptions, or to confirm that a proposed query shape returns the expected rows; that section is the canonical source of which servers and tools exist for this run, and any MCP-derived figure entering the trade-off matrix or risk assessment MUST cite server, table, and the SELECT used. MCP MUST NOT be used as a write path even when planning a migration — schema changes belong in migration files reviewed by humans.
 - Pre-planning context exploration (mandatory before option drafting):
   - read the task brief, related-task briefs, and any cited spec / design doc end-to-end
   - inspect the current state of every file the task names (or the closest matching files if names are stale) — record current responsibilities, public interfaces, and known coupling points

package/runtime/prompts/profiles/implementation.md

@@ -6,18 +6,24 @@
   - codex
   - gemini
   - report-writer
+- **Executor binding (resolved at run-prep time, fixed for this run):**
+  - Executor display name: `{{EXECUTOR_DISPLAY_NAME}}`
+  - Executor provider: `{{EXECUTOR_PROVIDER}}` (one of: `claude` | `codex` | `gemini`; chosen via `--executor` or `OKSTRA_DEFAULT_EXECUTOR`, default `claude`)
+  - Executor subagent for dispatch: `{{EXECUTOR_WORKER_AGENT}}`
+  - Executor model: `{{EXECUTOR_MODEL_DISPLAY}}` (launch value: `{{EXECUTOR_MODEL_EXECUTION_VALUE}}`)
+  - Wherever this profile mentions the `Executor`, it refers to the role bound above. The other two providers in the roster (`claude` / `codex` / `gemini` minus the executor) are dispatched as **verifiers only** for this run and remain strictly read-only.
 - Team contract:
-  - `Claude lead` is synthesis-only and stays distinct from `Claude executor`/`Claude verifier`
-  - **Executor role:** `Claude executor` is the **only worker permitted to use Edit / Write / state-mutating Bash commands** on project files. All other workers run read-only.
-  - **Verifier roles:** `Gemini verifier`, `Codex verifier`, and `Claude verifier` independently review the executor's diff and test output. They 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.
-  - `Claude verifier` and `Claude executor` MUST be assigned different model variants in the run manifest (executor=opus, verifier=sonnet by default) to avoid self-review of the same checkpoint.
+  - `Claude lead` is synthesis-only and stays distinct from the `Executor` and the verifiers
+  - **Executor role:** the `Executor` (bound above) is the **only worker permitted to use Edit / Write / state-mutating Bash commands** on project files. All other workers run read-only. When the executor provider is `codex` or `gemini`, the actual file mutation happens inside the executor CLI's own auto-edit mode (e.g. `codex exec --full-auto`, gemini's equivalent) — not through Claude-side Edit/Write tools — but the safety rules in this profile still apply identically.
+  - **Verifier roles:** the three verifier slots are `Claude verifier`, `Codex verifier`, and `Gemini verifier`. All three are 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. Assigning different model variants (e.g. executor=opus / Claude verifier=sonnet) remains recommended when available because it adds defence-in-depth, but it is no longer a hard requirement.
   - `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`/`Claude executor`/`Report writer worker`=`opus`, `Claude verifier`=`sonnet`, `Codex verifier`=`gpt-5.5`, `Gemini verifier`=`auto`
+  - default model assignments are resolved from centralised defaults; the fallback values are `Claude lead`/`Report writer worker`=`opus`, `Claude verifier`=`sonnet`, `Codex verifier`=`gpt-5.5`, `Gemini verifier`=`auto`. 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`).
   - all three verifier roles (`Gemini verifier`, `Codex verifier`, `Claude verifier`) must be attempted; the final verdict waits until each has either a result or an explicit terminal status
   - **All-verifier-failure policy**: if every required verifier (`Gemini verifier`, `Codex verifier`, `Claude verifier`) ends with a non-result terminal status (`timeout`, `error`, `not-run`) — i.e. zero independent verdicts were produced — the run MUST end with status `blocked` and route to a follow-up `error-analysis` run. `Claude lead` MUST NOT substitute its own verdict in place of the missing verifier outputs; synthesis requires at least one independent verifier's verdict. If one or two verifiers fail but at least one returns a verdict, the run proceeds with the surviving verdict(s) and the final report MUST explicitly notate which verifiers were unavailable, with the captured error / timeout evidence per failed verifier.
   - unnamed generic parallel workers must not replace the required role roster, and no additional sub-agent dispatch is allowed beyond this roster
 - Tooling — read-only MCP availability:
-  - `mcp__mysql-fontsninja-{common,fontradar,fontsninja,fonthelper}` (tools: `mysql_list_tables`, `mysql_describe_table`, `mysql_select_data`) may be queried by both executor and verifiers as a read-only cross-check (sanity-checking row counts after a migration script's dry-run, comparing observed schema against the plan's expectations, etc.); the canonical usage policy is in the task brief's `## Available MCP Servers` section, and any MCP-derived evidence MUST cite server, table, and the SELECT used. MCP MUST NEVER be used as a write path — schema/data mutations go through repository migration files, never through this MCP.
+  - the read-only MCP servers declared in the task brief's `## Available MCP Servers` section may be queried by both executor and verifiers as a read-only cross-check (sanity-checking row counts after a migration script's dry-run, comparing observed schema against the plan's expectations, etc.); that section is the canonical source of which servers and tools exist for this run, and any MCP-derived evidence MUST cite server, table, and the SELECT used. MCP MUST NEVER be used as a write path — schema/data mutations go through repository migration files, never through this MCP.
 - Pre-implementation gate (mandatory — refuse to start if any item fails):
   - the run brief MUST cite `--approved-plan <path>` pointing to a `final-report.md` produced by a prior `implementation-planning` run located under `runs/implementation-planning/.../reports/final-report.md`
   - that file MUST contain a `User Approval Request` block AND a recorded user approval marker matching one of the following line-anchored, case-insensitive forms (the runtime regex in `okstra_ctl.run._validate_approved_plan` enforces this and rejects the run with `PrepareError` before any prompt is generated): `APPROVED` (alone, followed by `:`, or end-of-line), `[x] Approved`, or `User Approval: APPROVED|granted|yes`. Free-form approvals such as "lgtm", "go ahead", or paraphrased confirmations are intentionally NOT accepted; if the user's approval is informal, re-edit the plan file to add one of the exact markers above before invoking the implementation run.

package/runtime/prompts/profiles/requirements-discovery.md

@@ -15,7 +15,7 @@
   - the final verdict waits until each required worker has either a result or an explicit terminal status
   - unnamed generic parallel workers must not replace the required role roster
 - Tooling — read-only MCP availability:
-  - `mcp__mysql-fontsninja-{common,fontradar,fontsninja,fonthelper}` (tools: `mysql_list_tables`, `mysql_describe_table`, `mysql_select_data`) may be queried when local schema or sample data clarifies the work category or routing decision; the canonical usage policy is in the task brief's `## Available MCP Servers` section, and any MCP-derived finding MUST cite server, table, and the SELECT used
+  - the read-only MCP servers declared in the task brief's `## Available MCP Servers` section may be queried when local schema or sample data clarifies the work category or routing decision; that section is the canonical source of which servers and tools exist for this run, and any MCP-derived finding MUST cite server, table, and the SELECT used
 - Primary focus areas:
   - classify the work as bugfix, feature, improvement, refactor, or ops-change
   - determine whether `error-analysis`, `implementation-planning`, or a direct implementation handoff is the next safe step

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

@@ -51,6 +51,7 @@ okstra execution summary:
   recommended workers: ${SELECTED_REVIEWERS}
   lead model: ${LEAD_MODEL_DISPLAY}
   worker models: claude=${CLAUDE_WORKER_MODEL_DISPLAY}, codex=${CODEX_WORKER_MODEL_DISPLAY}, gemini=${GEMINI_WORKER_MODEL_DISPLAY}, report-writer=${REPORT_WRITER_MODEL_DISPLAY}
+  executor (implementation only): ${EXECUTOR_OVERRIDE:-default(claude)}
   task key input: ${TASK_KEY_INPUT:-None}
   task key: ${TASK_KEY}
   task root: ${TASK_ROOT}
@@ -131,6 +132,10 @@ while [[ $# -gt 0 ]]; do
       REPORT_WRITER_MODEL_OVERRIDE="$(require_option_value --report-writer-model "${2-}")"
       shift 2
       ;;
+    --executor)
+      EXECUTOR_OVERRIDE="$(require_option_value --executor "${2-}")"
+      shift 2
+      ;;
     --related-tasks)
       RELATED_TASKS_RAW="$(require_option_value --related-tasks "${2-}")"
       shift 2
@@ -204,7 +209,7 @@ while [[ $# -gt 0 ]]; do
           printf '  hint: did you mean --task-id?\n' >&2
           ;;
       esac
-      printf '  valid options: --render-only --resume-clarification --yes --refresh-assets --workers --lead-model --claude-model --codex-model --gemini-model --report-writer-model --related-tasks --task-type --project-id --project-root --task-group --task-id --task-brief --directive --clarification-response --approved-plan -h|--help\n' >&2
+      printf '  valid options: --render-only --resume-clarification --yes --refresh-assets --workers --lead-model --claude-model --codex-model --gemini-model --report-writer-model --executor --related-tasks --task-type --project-id --project-root --task-group --task-id --task-brief --directive --clarification-response --approved-plan -h|--help\n' >&2
       usage
       exit 1
       ;;

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

@@ -24,6 +24,7 @@ CLAUDE_MODEL_OVERRIDE=""
 CODEX_MODEL_OVERRIDE=""
 GEMINI_MODEL_OVERRIDE=""
 REPORT_WRITER_MODEL_OVERRIDE=""
+EXECUTOR_OVERRIDE=""
 RELATED_TASKS_RAW=""
 ANALYSIS_TYPE=""
 BRIEF_PATH=""

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

@@ -3,7 +3,7 @@
 usage() {
   cat >&2 <<USAGE_EOF
 usage:
-  $DISPLAY_COMMAND_NAME [--render-only] [--yes] [--refresh-assets] --task-type <task-type> [--workers worker1,worker2] [--lead-model <model>] [--claude-model <model>] [--codex-model <model>] [--gemini-model <model>] [--report-writer-model <model>] [--related-tasks taskA,taskB] --project-id <project-id> [--project-root <path>] --task-group <task-group> --task-id <task-id> --task-brief <brief-path> [--directive <directive>]
+  $DISPLAY_COMMAND_NAME [--render-only] [--yes] [--refresh-assets] --task-type <task-type> [--workers worker1,worker2] [--lead-model <model>] [--claude-model <model>] [--codex-model <model>] [--gemini-model <model>] [--report-writer-model <model>] [--executor claude|codex|gemini] [--related-tasks taskA,taskB] --project-id <project-id> [--project-root <path>] --task-group <task-group> --task-id <task-id> --task-brief <brief-path> [--directive <directive>]
 
 summary:
   $DISPLAY_TOOL_NAME prepares a task-keyed instruction bundle for Claude Code and launches an interactive Claude session by default.
@@ -15,7 +15,7 @@ summary:
   permissions are injected via 'claude --settings' at launch time.
 
 required arguments:
-  --project-id         Globally unique project ID. Example: fontradar-v2-api.
+  --project-id         Globally unique project ID. Example: sample-project-v2-api.
                        Each project is registered at <project-root>/.project-docs/okstra/project.json
                        on first run; subsequent runs verify the projectId there matches.
   --task-group         Logical task group. Example: backend-api, bugfix, linear-8858
@@ -66,6 +66,11 @@ options:
   --gemini-model       Model for Gemini worker. Default: OKSTRA_DEFAULT_GEMINI_MODEL or auto
   --report-writer-model
                       Model for report writer worker. Default: OKSTRA_DEFAULT_REPORT_WRITER_MODEL or lead model default
+  --executor           Provider that performs the Executor role during --task-type=implementation.
+                      One of: claude | codex | gemini. Default: OKSTRA_DEFAULT_EXECUTOR or claude.
+                      The Executor is the only worker allowed to mutate project files; the other two
+                      providers are dispatched as read-only verifiers regardless of this selection.
+                      Has no effect on other task types.
   --related-tasks      Optional comma-separated related task identifiers. Example: auth-token-refresh,frontend-login-ui
   --task-type          Set the task purpose for this run and select the matching profile file.
   -h, --help           Show this help.
@@ -76,6 +81,7 @@ model defaults:
   Claude worker: OKSTRA_DEFAULT_CLAUDE_MODEL or sonnet
   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)
 
 output:
   Stable task bundles are stored under:

package/runtime/python/okstra_ctl/render.py

@@ -681,6 +681,14 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
             "disallowLeadSoloAnalysisAsWorkerResult": True,
             "disallowGenericParallelOnlyExecution": True,
             "preferredCompletedWorkerResults": len(reviewers),
+            "executor": {
+                "provider": ctx.get("EXECUTOR_PROVIDER", ""),
+                "displayName": ctx.get("EXECUTOR_DISPLAY_NAME", ""),
+                "workerAgent": ctx.get("EXECUTOR_WORKER_AGENT", ""),
+                "model": ctx.get("EXECUTOR_MODEL_DISPLAY", ""),
+                "modelExecutionValue": ctx.get("EXECUTOR_MODEL_EXECUTION_VALUE", ""),
+                "appliesTo": "implementation",
+            },
         },
         "validation": {
             "required": True,
@@ -857,6 +865,59 @@ def render_task_index(template_path: str, output_path: str, ctx: dict) -> None:
     _write_text(Path(output_path), rendered.rstrip() + "\n")
 
 
+# --------------------------------------------------------------------------- #
+# Available MCP servers block
+# --------------------------------------------------------------------------- #
+
+
+_NO_MCP_SERVERS_LINE = (
+    "- No MCP servers are declared in `.project-docs/okstra/project.json`'s "
+    "`mcpServers` array. Treat MCP tools as unavailable for this run. To enable "
+    "them, add entries shaped `{name, description, tools, notes?}` to that array "
+    "and re-render the bundle."
+)
+
+
+def build_available_mcp_servers_block(project_root: Path) -> str:
+    """Render the `## Available MCP Servers` first bullet from project.json.
+
+    The MCP server list used to be hardcoded for one specific environment.
+    It now comes from the project's `.project-docs/okstra/project.json`
+    (`mcpServers` array), so each user/project declares the MCP surface
+    available to their lead+workers. Missing file or empty array yields a
+    generic "none declared" fallback.
+    """
+    config_path = project_root / ".project-docs" / "okstra" / "project.json"
+    try:
+        raw = json.loads(config_path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError):
+        return _NO_MCP_SERVERS_LINE
+    servers = raw.get("mcpServers") if isinstance(raw, dict) else None
+    if not isinstance(servers, list) or not servers:
+        return _NO_MCP_SERVERS_LINE
+    lines: list[str] = []
+    for entry in servers:
+        if not isinstance(entry, dict):
+            continue
+        name = str(entry.get("name", "")).strip()
+        if not name:
+            continue
+        description = str(entry.get("description", "")).strip()
+        tools = entry.get("tools") or []
+        notes = str(entry.get("notes", "")).strip()
+        parts = [f"`mcp__{name}`"]
+        if description:
+            parts.append(description)
+        if isinstance(tools, list) and tools:
+            tool_names = ", ".join(f"`{str(t).strip()}`" for t in tools if str(t).strip())
+            if tool_names:
+                parts.append(f"Tools: {tool_names}")
+        if notes:
+            parts.append(notes)
+        lines.append("- " + ". ".join(parts) + ".")
+    return "\n".join(lines) if lines else _NO_MCP_SERVERS_LINE
+
+
 # --------------------------------------------------------------------------- #
 # launch.template.md rendering
 # --------------------------------------------------------------------------- #
@@ -1003,6 +1064,10 @@ def render_template_file(template_path: str, output_path: str, ctx: dict) -> Non
         "{{WORKFLOW_NEXT_RECOMMENDED_PHASE}}": ctx.get("WORKFLOW_NEXT_RECOMMENDED_PHASE", ""),
         "{{PHASE_ALLOWED_OUTPUTS}}": ctx.get("PHASE_ALLOWED_OUTPUTS", ""),
         "{{PHASE_FORBIDDEN_ACTIONS}}": ctx.get("PHASE_FORBIDDEN_ACTIONS", ""),
+        "{{AVAILABLE_MCP_SERVERS}}": ctx.get(
+            "AVAILABLE_MCP_SERVERS",
+            build_available_mcp_servers_block(Path(ctx.get("PROJECT_ROOT", "."))),
+        ),
     }
     rendered = template
     for k, v in mapping.items():

package/runtime/python/okstra_ctl/run.py

@@ -81,6 +81,7 @@ class PrepareInputs:
     codex_model: str = ""
     gemini_model: str = ""
     report_writer_model: str = ""
+    executor: str = ""
     related_tasks_raw: str = ""
     approved_plan_path: str = ""
     clarification_response_path: str = ""  # absolute or empty
@@ -265,6 +266,7 @@ def _canonical_argv(inp: PrepareInputs, ctx: dict) -> list[str]:
         ("--codex-model", inp.codex_model or ctx.get("CODEX_WORKER_MODEL_DISPLAY", "")),
         ("--gemini-model", inp.gemini_model or ctx.get("GEMINI_WORKER_MODEL_DISPLAY", "")),
         ("--report-writer-model", inp.report_writer_model or ctx.get("REPORT_WRITER_MODEL_DISPLAY", "")),
+        ("--executor", inp.executor or ctx.get("EXECUTOR_PROVIDER", "")),
         ("--related-tasks", inp.related_tasks_raw),
     ]
     argv: list[str] = []
@@ -285,15 +287,27 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     project_root = Path(inp.project_root)
 
     # ---- validate inputs ----
+    # Hint suffix added to every "okstra runtime asset missing" PrepareError below.
+    # These files ship with the package and live under runtime/ — if any are
+    # missing the install is incomplete or stale, not a user-content issue.
+    _INSTALL_HINT = (
+        " This file ships with the okstra package; its absence usually means a stale "
+        "or partial install. Run 'okstra ensure-installed' (or 'okstra install' again) "
+        "to repair the runtime. If the problem persists, run 'okstra doctor' for a "
+        "fuller diagnostic."
+    )
     profile_dir = workspace_root / "prompts" / "profiles"
     profile_file = profile_dir / f"{inp.task_type}.md"
     if not profile_file.is_file():
         raise PrepareError(
-            f"analysis profile file not found for task-type {inp.task_type}: {profile_file}"
+            f"analysis profile file not found for task-type {inp.task_type}: "
+            f"{profile_file}.{_INSTALL_HINT}"
         )
     prompt_template = workspace_root / "prompts" / "launch.template.md"
     if not prompt_template.is_file():
-        raise PrepareError(f"okstra prompt template not found: {prompt_template}")
+        raise PrepareError(
+            f"okstra prompt template not found: {prompt_template}.{_INSTALL_HINT}"
+        )
     task_index_template = (
         workspace_root / "templates" / "project-docs" / "task-index.template.md"
     )
@@ -304,7 +318,9 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     run_validator = workspace_root / "validators" / "validate-run.py"
     for required in (task_index_template, final_report_template, run_validator, source_skill):
         if not required.is_file():
-            raise PrepareError(f"required okstra template or source skill missing: {required}")
+            raise PrepareError(
+                f"required okstra template or source skill missing: {required}.{_INSTALL_HINT}"
+            )
     if not project_root.is_dir():
         raise PrepareError(f"project root not found: {project_root}")
     if not inp.brief_path.is_file():
@@ -329,7 +345,11 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     try:
         upsert_project_json(project_root, inp.project_id)
     except ResolverError as exc:
-        raise PrepareError(f"project.json upsert failed: {exc}") from exc
+        # Surface the project_root in the prefix so the user can tell which
+        # registration failed when multiple projects are in play. The full
+        # underlying ResolverError text (which carries remediation guidance)
+        # is preserved by the `: {exc}` suffix and the `raise ... from exc`.
+        raise PrepareError(f"project.json upsert failed for {project_root}: {exc}") from exc
 
     # ---- workers resolution ----
     profile_workers_csv = ",".join(resolve_profile_workers(profile_file))
@@ -365,6 +385,22 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         default_display=report_writer_default, default_execution=report_writer_default,
     )
 
+    # ---- executor binding (implementation phase only; recorded universally for manifest consistency) ----
+    executor_default = _default("OKSTRA_DEFAULT_EXECUTOR", "claude")
+    executor_provider = (inp.executor or executor_default).strip().lower()
+    if executor_provider not in ("claude", "codex", "gemini"):
+        raise PrepareError(
+            f"--executor must be one of: claude, codex, gemini (got: {executor_provider!r})"
+        )
+    executor_provider_to_meta = {
+        "claude": ("Claude executor", "claude-worker", cw),
+        "codex": ("Codex executor", "codex-worker", co),
+        "gemini": ("Gemini executor", "gemini-worker", ge),
+    }
+    executor_display_name, executor_worker_agent, executor_model_meta = (
+        executor_provider_to_meta[executor_provider]
+    )
+
     # ---- paths under per-task mutex (writes run-context-*.json) ----
     # OKSTRA_RUN_SEQ_OVERRIDE: okstra-ctl rerun / 테스트 hook 이 미리 reserve
     # 한 seq 를 강제하는 user-knob 환경 변수.
@@ -426,6 +462,11 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         "GEMINI_WORKER_MODEL_EXECUTION_VALUE": ge.execution,
         "REPORT_WRITER_MODEL_DISPLAY": rw.display,
         "REPORT_WRITER_MODEL_EXECUTION_VALUE": rw.execution,
+        "EXECUTOR_PROVIDER": executor_provider,
+        "EXECUTOR_DISPLAY_NAME": executor_display_name,
+        "EXECUTOR_WORKER_AGENT": executor_worker_agent,
+        "EXECUTOR_MODEL_DISPLAY": executor_model_meta.display,
+        "EXECUTOR_MODEL_EXECUTION_VALUE": executor_model_meta.execution,
         "RELATED_TASKS_JSON": related_tasks_json_str,
         "RELATED_TASKS_BULLETS": bullets,
         "RELATED_TASKS_INLINE": inline,
@@ -455,7 +496,16 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     # ---- write instruction-set scaffolding ----
     instruction_set = Path(ctx["INSTRUCTION_SET_DIR"])
     instruction_set.mkdir(parents=True, exist_ok=True)
-    (instruction_set / "analysis-profile.md").write_text(profile_content, encoding="utf-8")
+    profile_rendered = profile_content
+    for key in (
+        "EXECUTOR_PROVIDER",
+        "EXECUTOR_DISPLAY_NAME",
+        "EXECUTOR_WORKER_AGENT",
+        "EXECUTOR_MODEL_DISPLAY",
+        "EXECUTOR_MODEL_EXECUTION_VALUE",
+    ):
+        profile_rendered = profile_rendered.replace("{{" + key + "}}", ctx.get(key, ""))
+    (instruction_set / "analysis-profile.md").write_text(profile_rendered, encoding="utf-8")
     (instruction_set / "analysis-material.md").write_text(review_material, encoding="utf-8")
     shutil.copyfile(inp.brief_path, instruction_set / "task-brief.md")
     if inp.clarification_response_path:
@@ -494,6 +544,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
             "codexModel": co.display,
             "geminiModel": ge.display,
             "reportWriterModel": rw.display,
+            "executor": executor_provider,
             "relatedTasks": inp.related_tasks_raw,
             "approvedPlanPath": inp.approved_plan_path,
             "clarificationResponsePath": inp.clarification_response_path,
@@ -585,6 +636,7 @@ def main(argv: list[str]) -> int:
     p.add_argument("--codex-model", default="")
     p.add_argument("--gemini-model", default="")
     p.add_argument("--report-writer-model", default="")
+    p.add_argument("--executor", default="")
     p.add_argument("--related-tasks", default="", dest="related_tasks_raw")
     p.add_argument("--approved-plan", default="", dest="approved_plan_path")
     p.add_argument("--clarification-response", default="", dest="clarification_response_path")
@@ -623,6 +675,7 @@ def main(argv: list[str]) -> int:
         codex_model=args.codex_model,
         gemini_model=args.gemini_model,
         report_writer_model=args.report_writer_model,
+        executor=args.executor,
         related_tasks_raw=args.related_tasks_raw,
         approved_plan_path=args.approved_plan_path,
         clarification_response_path=clarification_abs,

package/runtime/python/okstra_project/resolver.py

@@ -75,9 +75,12 @@ def resolve_project_root(*, explicit_root: str = "",
     if git_top is not None:
         return git_top.resolve()
     raise ResolverError(
-        "PROJECT_ROOT 를 해석할 수 없습니다. "
-        "--project-root 를 명시하거나, 프로젝트 루트(또는 그 하위)에서 실행하거나, "
-        "git 작업 트리 안에서 실행해 주십시오.")
+        "could not resolve PROJECT_ROOT from cwd. "
+        "Pass --project-root <abs-path>, "
+        "run from inside a project (a directory with .project-docs/okstra/project.json at or above cwd), "
+        "or run from inside a git working tree. "
+        "(PROJECT_ROOT 를 해석할 수 없습니다 — --project-root 를 명시하거나, "
+        "프로젝트 루트 또는 그 하위에서 실행하거나, git 작업 트리 안에서 실행해 주십시오.)")
 
 
 def upsert_project_json(project_root: Path, project_id: str, *,
@@ -100,13 +103,20 @@ def upsert_project_json(project_root: Path, project_id: str, *,
             data = json.loads(target.read_text())
         except (OSError, json.JSONDecodeError) as exc:
             raise ResolverError(
-                f"project.json 을 읽을 수 없습니다: {target} ({exc})") from exc
+                f"failed to read project.json at {target}: {exc} "
+                f"(project.json 을 읽을 수 없습니다.) "
+                f"If the file is corrupted, delete it and re-run 'okstra setup --project-id <id>'."
+            ) from exc
         existing_id = str(data.get("projectId") or "")
         if existing_id and existing_id != project_id:
             raise ResolverError(
-                f"projectId 불일치: project.json={existing_id!r}, "
-                f"인자={project_id!r}. "
-                f"동일 PROJECT_ROOT 에서는 하나의 projectId 만 사용할 수 있습니다.")
+                f"projectId mismatch: existing project.json has {existing_id!r} "
+                f"but the supplied argument is {project_id!r}. "
+                f"okstra allows only one projectId per PROJECT_ROOT. "
+                f"To fix: re-run with --project-id {existing_id!r} to keep the existing registration, "
+                f"or manually delete {target} if you intend to re-register this directory "
+                f"under a different id. "
+                f"(projectId 불일치: 한 PROJECT_ROOT 에는 하나의 projectId 만 허용됩니다.)")
         result = {
             "projectId": project_id,
             "projectRoot": abs_root,

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

@@ -103,6 +103,7 @@ To re-run a specific run:
    - `recommendedWorkers` → `--workers` (comma-separated)
    - `relatedTasks` → `--related-tasks` (if present)
    - model overrides → `--claude-model`, `--codex-model`, `--gemini-model` (if different from default)
+   - for `taskType: implementation`: `teamContract.executor.provider` → `--executor <claude|codex|gemini>` (if different from `claude`)
 4. Display the assembled command:
 
 ```bash

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

@@ -128,8 +128,9 @@ Validate that slugified `task_group` and `task_id` each contain at least one alp
 
 For existing tasks, present `nextRecommendedPhase` as the first option (recommended default).
 
-If `implementation` chosen, ask one more `AskUserQuestion`:
+If `implementation` chosen, ask two more `AskUserQuestion` in order:
 - `"Path to the approved final-report.md (must contain APPROVED marker)"` — the underlying python `prepare_task_bundle` re-validates the marker, but you can pre-check with `grep`.
+- `"Executor provider for this run (claude | codex | gemini)?"` — only this provider mutates project files; the other two run as read-only verifiers. Default `claude` (or `OKSTRA_DEFAULT_EXECUTOR` if set). Pass the answer through `PrepareInputs.executor`.
 
 ## Step 5: Brief path
 
@@ -176,6 +177,7 @@ out = prepare_task_bundle(PrepareInputs(
     lead_model="...", claude_model="...", codex_model="...",
     gemini_model="...", report_writer_model="...",
     related_tasks_raw="...",
+    executor="<claude|codex|gemini or empty>",  # implementation only; empty → default (claude / OKSTRA_DEFAULT_EXECUTOR)
     approved_plan_path="<approved-plan-or-empty>",
     clarification_response_path=str(clarification_abs) if clarification_abs else "",
     render_only=True,

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

@@ -96,7 +96,7 @@ so overwriting requires manually deleting the file first.
 
 If the file does NOT exist, ask via `AskUserQuestion`:
 
-- **Question**: `"Project id for okstra (e.g. INV-1234, fontsninja, okstra)"`
+- **Question**: `"Project id for okstra (e.g. INV-1234, my-app, okstra)"`
 - **Validate**: slugified must contain at least one alphanumeric character.
 
 Then create the file:

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

@@ -42,6 +42,7 @@ Only workers selected from `recommendedWorkers` in `task-manifest.json` and `res
 
 ## Operating Rules
 
+0. **TeamCreate ordering (BLOCKING).** Before issuing any `Agent` dispatch that includes `team_name`, Lead MUST have called `TeamCreate(team_name: "okstra-<task-key>", ...)` in this run and recorded the outcome in team-state as `teamCreate: { attempted: true, status: "ok"|"error", error?: <message> }`. If the Agent tool rejects a dispatch with `"team must be created first or call without team_name"` / `"team을 먼저 생성하거나 team_name 없이 호출해야 합니다"`, the correct response is to go back to Phase 3 and call `TeamCreate` — NOT to strip `team_name` and retry. The no-`team_name` Phase 5 fallback is only legal when `teamCreate.status == "error"` is already recorded; otherwise stripping `team_name` silently degrades the run to in-process background dispatch and loses the Teams split-pane behavior. See [okstra agent SKILL.md Phase 3](../../agents/SKILL.md) for the full team-creation sequence.
 1. `Claude lead` is responsible for orchestration, convergence supervision, and final-report review/approval. It never overrides worker analysis results, and it never authors the final-report file when `Report writer worker` is in the roster.
 2. `Report writer worker` is NOT an analysis worker. It is excluded from Phase 4/5 (initial analysis) and Phase 5.5 (convergence re-verification). It is spawned only in Phase 6 and is the **author** of the final-report file at `runs/<task-type>/reports/final-report-<task-type>-<seq>.md`.
 3. When `Report writer worker` is in the roster, Lead MUST dispatch it in Phase 6. The only legal lead-authored fallback is when a dispatch was attempted and recorded a terminal status of `error` / `timeout` / `not-run` with a concrete logged reason. Speculative reasons such as "session resume constraint" or "team is no longer alive" are NOT valid — Lead can always dispatch a fresh subagent (omit `team_name` if the team is gone).

package/runtime/templates/reports/settings.template.json

@@ -83,19 +83,7 @@
       "Bash(curl:*)",
       "Bash(wget:*)",
       "mcp__test-context7__resolve-library-id",
-      "mcp__test-context7__query-docs",
-      "mcp__mysql-fontsninja-common__mysql_list_tables",
-      "mcp__mysql-fontsninja-common__mysql_describe_table",
-      "mcp__mysql-fontsninja-common__mysql_select_data",
-      "mcp__mysql-fontsninja-fontradar__mysql_list_tables",
-      "mcp__mysql-fontsninja-fontradar__mysql_describe_table",
-      "mcp__mysql-fontsninja-fontradar__mysql_select_data",
-      "mcp__mysql-fontsninja-fontsninja__mysql_list_tables",
-      "mcp__mysql-fontsninja-fontsninja__mysql_describe_table",
-      "mcp__mysql-fontsninja-fontsninja__mysql_select_data",
-      "mcp__mysql-fontsninja-fonthelper__mysql_list_tables",
-      "mcp__mysql-fontsninja-fonthelper__mysql_describe_table",
-      "mcp__mysql-fontsninja-fonthelper__mysql_select_data"
+      "mcp__test-context7__query-docs"
     ]
   }
 }

package/runtime/templates/reports/task-brief.template.md

@@ -127,24 +127,13 @@
 
 ## Available MCP Servers
 
-The following MCP servers are registered at the user scope and may be invoked **as needed** during this run by Claude lead, Claude worker, and Report writer worker. The lead is responsible for forwarding this section verbatim into the worker prompts (Phase 2) so workers know they are allowed to call these tools.
+The MCP servers available to this run are declared in `.project-docs/okstra/project.json`'s `mcpServers` array and rendered into the Claude lead's launch prompt under `## Available MCP Servers`. They may be invoked **as needed** by Claude lead, Claude worker, and Report writer worker. The lead is responsible for forwarding the rendered list verbatim into the worker prompts (Phase 2) so workers know which tools they are allowed to call.
 
-| Server | Backing data | Mode | Typical use |
-|--------|--------------|------|-------------|
-| `mcp__mysql-fontsninja-common` | local Docker MySQL `common` schema | read-only | shared lookups, code list, reference data |
-| `mcp__mysql-fontsninja-fontradar` | local Docker MySQL `fontradar` schema | read-only | fontradar service data inspection |
-| `mcp__mysql-fontsninja-fontsninja` | local Docker MySQL `fontsninja` schema | read-only | fontsninja service data inspection |
-| `mcp__mysql-fontsninja-fonthelper` | local Docker MySQL `fonthelper` schema | read-only | fonthelper service data inspection |
-
-Available tools per server (all read-only — write tools are disabled at the server):
-
-- `mysql_list_tables`
-- `mysql_describe_table`
-- `mysql_select_data`
+To declare servers, add entries shaped `{ "name": "<server>", "description": "...", "tools": ["..."], "notes": "..." }` to that array. If the array is empty or absent, treat MCP as unavailable for this run.
 
 How to invoke (worker-by-worker):
 
-- **Claude lead / Claude worker / Report writer worker**: invoke the MCP tool **directly by its tool name** (e.g. `mcp__mysql-fontsninja-fontsninja__mysql_list_tables`) through the host's tool interface. **Do NOT call it via `Bash`** — these names are MCP tools, not shell commands; running them in a shell will always fail with `command not found` regardless of permission settings.
+- **Claude lead / Claude worker / Report writer worker**: invoke the MCP tool **directly by its tool name** (e.g. `mcp__<server>__<tool>`) through the host's tool interface. **Do NOT call it via `Bash`** — these names are MCP tools, not shell commands; running them in a shell will always fail with `command not found` regardless of permission settings.
 - **Codex worker / Gemini worker**: invoke through the external CLI's own MCP transport (e.g. `codex mcp call <server> <tool> <args>` for Codex CLI; the equivalent Gemini CLI MCP invocation for Gemini). If the worker's CLI has no matching MCP config, treat the server as unavailable for this run and record `MCP not available in this CLI` in `Missing Information or Assumptions` — do **not** attempt a shell fallback such as `mysql -h ...` or piping a tool name into `bash`.
 - All workers: cite the exact server, tool, and SELECT (or `WHERE` filters) used in the result file. Tool-call failures must be logged in the worker's `*-errors.json` (commandKind `mcp_call`) so the lead can decide whether to retry under a different worker.
 

package/runtime/validators/validate-run.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import os
 import sys
 from datetime import datetime, timezone
 from pathlib import Path
@@ -478,6 +479,137 @@ def validate_phase_boundary(
             )
 
 
+def _import_token_usage():
+    """Resolve and import the okstra_token_usage package across layouts.
+
+    Source tree:    <repo>/scripts/okstra_token_usage
+    Built runtime:  <runtime>/python/okstra_token_usage   (next to validators/)
+    Installed:      $OKSTRA_PYTHONPATH/okstra_token_usage (~/.okstra/lib/python)
+    """
+    here = Path(__file__).resolve().parent
+    candidates = [
+        here.parent / "scripts",
+        here.parent / "python",
+    ]
+    env_pp = os.environ.get("OKSTRA_PYTHONPATH", "").strip()
+    if env_pp:
+        candidates.append(Path(env_pp))
+    for candidate in candidates:
+        if candidate.is_dir() and (candidate / "okstra_token_usage").is_dir():
+            if str(candidate) not in sys.path:
+                sys.path.insert(0, str(candidate))
+            break
+    from okstra_token_usage.collect import collect  # noqa: E402
+    from okstra_token_usage.report import substitute_final_report  # noqa: E402
+    return collect, substitute_final_report
+
+
+def _needs_token_autofix(team_state: dict, report_path: Path) -> bool:
+    summary = team_state.get("usageSummary") or {}
+    if not summary or not summary.get("collectedAt"):
+        return True
+    if report_path.is_file():
+        content = report_path.read_text()
+        if any(p in content for p in TOKEN_PLACEHOLDERS):
+            return True
+    return False
+
+
+def _accuracy_failures(updated: dict) -> list[str]:
+    """Return human-readable reasons the collected usage is incomplete.
+
+    Goal: never let zero-valued usage be silently written or substituted into
+    the final report. If a session jsonl is missing, the operator must know
+    which one and why so they can re-collect — recording accurate token usage
+    is the contract this autofix preserves.
+    """
+    reasons: list[str] = []
+    lead_usage = updated.get("leadUsage") or {}
+    if lead_usage.get("source") == "unavailable":
+        reasons.append(
+            "lead Claude session jsonl was not found — "
+            f"{lead_usage.get('note', 'reason unknown')}. "
+            "Token usage cannot be recorded accurately until the lead session is locatable."
+        )
+    for worker in updated.get("workers") or []:
+        role = worker.get("role") or worker.get("workerId") or "<unknown worker>"
+        status = worker.get("status")
+        usage = worker.get("usage") or {}
+        if status == "completed" and usage.get("source") == "unavailable":
+            reasons.append(
+                f"worker `{role}` (status=completed) has no usage data — "
+                f"{usage.get('note', 'reason unknown')}."
+            )
+        if worker.get("agent") in ("codex", "gemini") and usage.get("source") != "unavailable":
+            if "cliTotalTokens" not in usage:
+                reasons.append(
+                    f"worker `{role}` ({worker.get('agent')}) wrapper jsonl was located "
+                    f"but its underlying CLI session usage was not — "
+                    f"{usage.get('cliNote', 'reason unknown')}."
+                )
+    return reasons
+
+
+def attempt_token_usage_autofix(
+    team_state: dict,
+    team_state_path: Path,
+    report_path: Path,
+    project_root: Path,
+) -> tuple[str, list[str]]:
+    """Run the Phase 7 token-usage collector in-process when artifacts indicate
+    Phase 7 was skipped.
+
+    Returns ``(state, messages)`` where ``state`` is one of:
+
+    - ``"skipped"`` — opt-out or autofix not needed; messages is empty.
+    - ``"recovered"`` — collector ran AND every session that should have a
+      jsonl was found; team-state is rewritten and the final report's token
+      placeholders are substituted with real values. messages carries a
+      single info line.
+    - ``"accuracy-failed"`` — collector ran but at least one expected
+      session is missing. Nothing is written to disk; messages contains the
+      contract violations the validator must surface so the operator can
+      re-collect accurately rather than ship a report containing zeros.
+    - ``"import-failed"`` / ``"collector-error"`` — autofix could not run;
+      caller falls back to the original contract failures.
+    """
+    if os.environ.get("OKSTRA_VALIDATE_NO_AUTOFIX") == "1":
+        return "skipped", []
+    if not _needs_token_autofix(team_state, report_path):
+        return "skipped", []
+    try:
+        collect, substitute_final_report = _import_token_usage()
+    except Exception as exc:  # noqa: BLE001
+        return "import-failed", [f"okstra_token_usage import failed: {exc}"]
+    try:
+        updated = collect(team_state_path, project_root)
+    except Exception as exc:  # noqa: BLE001
+        return "collector-error", [f"token-usage collector raised: {exc}"]
+
+    accuracy_problems = _accuracy_failures(updated)
+    if accuracy_problems:
+        # Refuse to persist zeroed usage. Surface specific reasons so the
+        # operator can locate the missing session(s) instead of silently
+        # shipping a report with `0` token counts.
+        return "accuracy-failed", [
+            f"Phase 7 token-usage auto-recovery refused to write incomplete data: {reason}"
+            for reason in accuracy_problems
+        ]
+
+    team_state_path.write_text(
+        json.dumps(updated, indent=2, ensure_ascii=False) + "\n"
+    )
+    replaced = substitute_final_report(report_path, updated)
+    detail = (
+        f"replaced {replaced} placeholder(s)"
+        if replaced > 0
+        else "no placeholders to replace"
+        if replaced == 0
+        else "report file missing"
+    )
+    return "recovered", [f"usageSummary repopulated; {detail}"]
+
+
 def main() -> int:
     parser = argparse.ArgumentParser(
         description="Validate okstra run contract artifacts."
@@ -527,7 +659,20 @@ def main() -> int:
     report_path = resolve_input(args.report)
     team_state = load_json(team_state_path)
 
+    autofix_state, autofix_messages = attempt_token_usage_autofix(
+        team_state, team_state_path, report_path, project_root
+    )
+    if autofix_state == "recovered":
+        team_state = load_json(team_state_path)
+        for msg in autofix_messages:
+            print(f"validate-run: Phase 7 auto-recovery — {msg}", file=sys.stderr)
+    elif autofix_state in ("import-failed", "collector-error"):
+        for msg in autofix_messages:
+            print(f"validate-run: Phase 7 auto-recovery skipped — {msg}", file=sys.stderr)
+
     failures: list[str] = []
+    if autofix_state == "accuracy-failed":
+        failures.extend(autofix_messages)
     contract = extract_contract(run_manifest, task_manifest, failures)
     validate_team_state(team_state, project_root, contract, failures)
     validate_report(report_path, contract["required_agent_status_entries"], failures)

package/src/check-project.mjs

@@ -103,10 +103,15 @@ export async function run(args) {
   );
 
   if (probe.code !== 0) {
+    const raw = probe.stderr.trim() || probe.stdout.trim();
     emit(opts, {
       ok: false,
       stage: "python",
-      reason: `python invocation failed: ${probe.stderr.trim() || probe.stdout.trim()}`,
+      reason:
+        `python invocation failed: ${raw}. ` +
+        "This usually means the okstra runtime is stale or missing — " +
+        "run 'okstra doctor' to diagnose, then 'okstra ensure-installed' " +
+        "to repair.",
     });
     return 1;
   }

package/src/setup.mjs

@@ -1,6 +1,8 @@
 import { promises as fs } from "node:fs";
 import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
+import { homedir } from "node:os";
+import { resolve as resolvePath } from "node:path";
 import { resolvePaths } from "./paths.mjs";
 
 const USAGE = `okstra setup — register the current project with okstra
@@ -192,8 +194,51 @@ export async function run(args) {
   try {
     resolved = await resolveProjectRoot(paths, opts.projectRoot);
   } catch (err) {
+    if (err.code === "RESOLVER") {
+      const cwd = resolvePath(process.cwd());
+      const home = resolvePath(homedir());
+      const inHome = cwd === home;
+      process.stderr.write(
+        "error: 'okstra setup' registers the CURRENT directory as an okstra project,\n" +
+          "       but no project root could be resolved from here.\n" +
+          `       cwd: ${cwd}\n` +
+          (inHome
+            ? "       (this looks like your home directory — setup is project-level, not machine-level;\n" +
+              "        machine-level install is 'okstra install', which you've likely already done.)\n"
+            : "") +
+          "\nFix one of:\n" +
+          "  1. cd into the project you want to register, then re-run:\n" +
+          "       cd <your project> && okstra setup --project-id <id>\n" +
+          "  2. pass an explicit path:\n" +
+          "       okstra setup --project-root <abs-path> --project-id <id>\n" +
+          "  3. run from inside any git working tree (the toplevel becomes PROJECT_ROOT).\n" +
+          `\n(underlying error: ${err.message})\n`,
+      );
+      return 2;
+    }
+    // Non-RESOLVER path: typically python invocation failure (PYTHONPATH wrong,
+    // ~/.okstra missing, python3 not on PATH, okstra_project module missing).
+    // The user can't fix this by adjusting setup arguments — it's a runtime
+    // health issue, not a PROJECT_ROOT issue. Reword accordingly.
+    const looksLikePythonFailure = /python invocation failed|ModuleNotFoundError|No module named/.test(
+      err.message,
+    );
+    if (looksLikePythonFailure) {
+      process.stderr.write(
+        "error: 'okstra setup' could not start because the okstra runtime is not\n" +
+          "       reachable from this process. This is almost always a stale or\n" +
+          "       incomplete install, not a problem with your setup arguments.\n" +
+          "\nFix:\n" +
+          "  1. run 'okstra doctor' to see exactly what is missing\n" +
+          "  2. run 'okstra ensure-installed' (or 'npx -y okstra@latest install')\n" +
+          "     to repair the runtime\n" +
+          "  3. retry: okstra setup --project-id <id>\n" +
+          `\n(underlying error: ${err.message})\n`,
+      );
+      return 1;
+    }
     process.stderr.write(`error: could not resolve PROJECT_ROOT: ${err.message}\n`);
-    return err.code === "RESOLVER" ? 2 : 1;
+    return 1;
   }
   const { projectRoot, projectJsonPath } = resolved;
 
@@ -220,7 +265,7 @@ export async function run(args) {
       return 1;
     }
     process.stderr.write(`PROJECT_ROOT: ${projectRoot}\n`);
-    const answer = await prompt("project-id (e.g. INV-1234, fontsninja): ");
+    const answer = await prompt("project-id (e.g. INV-1234, my-app): ");
     projectId = answer;
   }