okstra 0.6.1 → 0.8.0

package/README.kr.md

@@ -48,6 +48,7 @@ okstra/                          npm 패키지 = repo 루트
 ├── lib/python/                  okstra_project/, okstra_ctl/, okstra_token_usage/, lib/
 ├── bin/                         okstra.sh, codex-exec, gemini-exec, ...
 ├── installed-skills.json        설치된 스킬 매니페스트 (uninstall 이 사용)
+├── installed-agents.json        설치된 워커 에이전트 매니페스트 (uninstall 이 사용)
 ├── recent.jsonl, active.jsonl   run 인덱스
 ├── projects/                    프로젝트별 메타데이터 미러
 └── archive/                     완료된 run
@@ -55,6 +56,10 @@ okstra/                          npm 패키지 = repo 루트
 ~/.claude/skills/                Claude Code 가 자동 인식
 └── okstra-*/SKILL.md            스킬 11종 (§3.3 참조)
 
+~/.claude/agents/                Claude Code 가 자동 인식 (subagent 디스커버리 경로)
+└── {claude,codex,gemini,report-writer}-worker.md   worker subagent 정의
+                                 (multi-agent dispatch 필수)
+
 <프로젝트 루트>/.project-docs/okstra/
 ├── project.json                 {projectId, projectRoot, ...} (`/okstra-setup` 이 작성)
 ├── discovery/{task-catalog,latest-task}.json
@@ -68,6 +73,7 @@ okstra/                          npm 패키지 = repo 루트
 | 런타임 코드 (python + bash) | `~/.okstra/{lib/python, bin}` | `okstra install` |
 | agents/prompts/templates/validators | npm 패키지의 `runtime/` | `okstra` 패키지 자체 (`okstra paths` 로 해석) |
 | 스킬 마크다운 | `~/.claude/skills/<name>/SKILL.md` | `okstra install` (`installed-skills.json` 에 트래킹) |
+| 워커 에이전트 마크다운 | `~/.claude/agents/<worker>.md` | `okstra install` (`installed-agents.json` 에 트래킹) |
 | 프로젝트 메타데이터 | `<project>/.project-docs/okstra/` | `/okstra-setup` + 프로젝트 자체 |
 | Run 인덱스 | `~/.okstra/{recent,active}.jsonl` | `prepare_task_bundle` |
 
@@ -107,7 +113,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

@@ -47,6 +47,7 @@ okstra/                          npm package = repo root
 ├── lib/python/                  okstra_project/, okstra_ctl/, okstra_token_usage/, lib/
 ├── bin/                         okstra.sh, codex-exec, gemini-exec, ...
 ├── installed-skills.json        manifest of installed skills (used by uninstall)
+├── installed-agents.json        manifest of installed worker agents (used by uninstall)
 ├── recent.jsonl, active.jsonl   run index
 ├── projects/                    per-project metadata mirror
 └── archive/                     completed runs
@@ -54,6 +55,10 @@ okstra/                          npm package = repo root
 ~/.claude/skills/                discovered automatically by Claude Code
 └── okstra-*/SKILL.md            11 skills total (see §3.3)
 
+~/.claude/agents/                discovered automatically by Claude Code
+└── {claude,codex,gemini,report-writer}-worker.md   subagent definitions
+                                 (required for multi-agent dispatch)
+
 <project-root>/.project-docs/okstra/
 ├── project.json                 {projectId, projectRoot, ...} (written by /okstra-setup)
 ├── discovery/{task-catalog,latest-task}.json
@@ -67,6 +72,7 @@ okstra/                          npm package = repo root
 | Runtime code (python + bash) | `~/.okstra/{lib/python, bin}` | `okstra install` |
 | agents/prompts/templates/validators | npm package's `runtime/` | the `okstra` package (resolved via `okstra paths`) |
 | Skill markdown | `~/.claude/skills/<name>/SKILL.md` | `okstra install` (tracked in `installed-skills.json`) |
+| Worker agent markdown | `~/.claude/agents/<worker>.md` | `okstra install` (tracked in `installed-agents.json`) |
 | Project metadata | `<project>/.project-docs/okstra/` | `/okstra-setup` + the project itself |
 | Run index | `~/.okstra/{recent,active}.jsonl` | `prepare_task_bundle` |
 
@@ -106,7 +112,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.1",
+  "version": "0.8.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.1",
-  "builtAt": "2026-05-12T05:33:06.736Z",
+  "package": "0.8.0",
+  "builtAt": "2026-05-12T09:54:25.514Z",
   "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,7 +77,9 @@ 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}
+  approve ack (CLI 승인 의사): ${APPROVE_PLAN_ACK}
   related tasks: ${RELATED_TASKS_RAW:-None}
 CONFIRM_EOF
   printf 'Continue? [y/yes]: ' >&2
@@ -111,9 +113,12 @@ 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")
+[[ "$APPROVE_PLAN_ACK" == "true" ]] && PY_ARGS+=(--approve)
 [[ -n "${CLARIFICATION_RESPONSE_PATH-}" ]] && PY_ARGS+=(--clarification-response "$CLARIFICATION_RESPONSE_PATH")
+[[ -n "${WORK_CATEGORY-}" ]] && PY_ARGS+=(--work-category "$WORK_CATEGORY")
 [[ "$RENDER_ONLY" == "true" ]] && PY_ARGS+=(--render-only)
 [[ "$REFRESH_OKSTRA_ASSETS" == "true" ]] && PY_ARGS+=(--refresh-assets)
 

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
@@ -40,7 +40,7 @@
 - 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.
   - Do NOT add such items to option trade-offs, dependency/migration risk, validation checklists, rollout plans, `Open Questions`, or day/effort estimates. They are not legitimate sources of schedule extension; effort sizing must reflect engineering work only.
-  - The `User Approval Request` block at the end of the plan is the only authorised approval gate — that gate is the user themselves and is expected to be cleared without external coordination.
+  - The `User Approval Request (사용자 승인 게이트)` block at the **top of the final report** (immediately under the metadata header, before `Section 0`) is the only authorised approval gate — that gate is the user themselves, who clears it either by (a) editing the single checkbox `- [ ] Approved` to `- [x] Approved` directly, or (b) invoking the next phase with `--approve` so the CLI invocation itself is treated as the approval signal and the runtime flips the checkbox on the user's behalf. No external coordination is expected.
 - Non-goals:
   - code-level micro-optimization unless it changes the implementation approach
   - **source code edits of any kind** — this run produces a plan document only; Edit/Write on project source files is forbidden until the plan is approved and a separate `implementation` run starts
@@ -66,7 +66,7 @@
   - dependency / migration risk assessment (ordering constraints, data backfills, feature-flag prerequisites, cross-team coordination)
   - validation checklist (pre / mid / post) — each item is an exact command or observable outcome
   - rollback strategy — exact revert path (commits, flags, migrations) and the signal that triggers rollback
-  - explicit `User Approval Request` block — the next `implementation` run must not begin until the user replies with explicit approval
+  - explicit `User Approval Request (사용자 승인 게이트)` block placed at the **top of the report** with a single canonical checkbox marker `- [ ] Approved` (user toggles to `- [x] Approved` to authorise the next `implementation` run). Section `4.5.8` is retained only as a back-pointer to this top block for validator/key-substring compatibility — it must NOT carry an independent marker.
   - `Open Questions` block listing every ambiguity flagged during pre-planning that the user must resolve before approval
 - No-placeholder rule (plan failures — reject any option or step that contains these):
   - "TBD", "TODO", "implement later", "fill in details", "add appropriate error handling", "handle edge cases", "write tests for the above" without actual test code

package/runtime/prompts/profiles/implementation.md

@@ -6,21 +6,31 @@
   - 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.
+  - that file MUST contain a `User Approval Request` block (canonically placed at the **top of the report**, immediately under the metadata header) AND a recorded user approval marker. The canonical, recommended form is the single markdown checkbox line `- [x] Approved`. The runtime regex in `okstra_ctl.run._validate_approved_plan` also accepts (case-insensitive, line-anchored, optional leading `-`/`*`/`+` bullet): `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 flip the top checkbox to `- [x] Approved` before invoking the implementation run.
+  - Two equally-valid approval paths exist (both end up satisfying the same regex gate):
+    - **Manual edit** — the user opens the report, flips `- [ ] Approved` to `- [x] Approved`, saves, then runs `okstra ... --task-type implementation --approved-plan <path>`.
+    - **CLI ack** — the user runs `okstra ... --task-type implementation --approved-plan <path> --approve`. The CLI invocation itself is modelled as the user's act of approval; the runtime (`okstra_ctl.run._apply_cli_approval`) flips the checkbox in the report file and appends an audit line `- 승인 일시 (CLI ack): <ISO8601> — recorded by \`okstra --approve\`` before the standard regex validation runs. Use this when running unattended or when you want a single command to both approve and launch the next phase.
+  - The `--approve` flag is **only meaningful with `--task-type implementation` and `--approved-plan <path>`**. Passing it with any other task-type causes `PrepareError` (the runtime refuses to silently ignore approval signals). It is also a no-op if the file already carries a valid approval marker (idempotent — only an audit line is appended, the marker is not re-toggled).
   - the file's `Recommended option` and its bite-sized step list become the authoritative scope for this run; any deviation must be justified in the final report and routed back to a new `implementation-planning` run instead of being silently expanded.
 - Pre-implementation context exploration (executor before first edit):
   - re-read the approved plan end-to-end and extract: file list, step order, validation commands, rollback path

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,10 +132,18 @@ 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
       ;;
+    --work-category)
+      WORK_CATEGORY="$(require_option_value --work-category "${2-}")"
+      shift 2
+      ;;
     --task-type)
       ANALYSIS_TYPE="$(require_option_value --task-type "${2-}")"
       shift 2
@@ -175,6 +184,13 @@ while [[ $# -gt 0 ]]; do
       APPROVED_PLAN_PATH="$(require_option_value --approved-plan "${2-}")"
       shift 2
       ;;
+    --approve)
+      # 사용자가 CLI 명령을 입력한 행위 자체를 plan 승인 의사로 간주한다.
+      # 런타임에서 approved-plan 파일의 승인 체크박스를 [x] 로 갱신하고
+      # 승인 시각/방식을 함께 기록한다 (scripts/okstra_ctl/run.py 참조).
+      APPROVE_PLAN_ACK="true"
+      shift
+      ;;
     -h|--help)
       usage
       exit 0
@@ -204,7 +220,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 --related-tasks --task-type --project-id --project-root --task-group --task-id --task-brief --directive --clarification-response --approved-plan --approve -h|--help\n' >&2
       usage
       exit 1
       ;;

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

@@ -24,6 +24,8 @@ CLAUDE_MODEL_OVERRIDE=""
 CODEX_MODEL_OVERRIDE=""
 GEMINI_MODEL_OVERRIDE=""
 REPORT_WRITER_MODEL_OVERRIDE=""
+EXECUTOR_OVERRIDE=""
+WORK_CATEGORY=""
 RELATED_TASKS_RAW=""
 ANALYSIS_TYPE=""
 BRIEF_PATH=""
@@ -36,6 +38,7 @@ REVIEW_PROFILE=""
 DIRECTIVE=""
 CLARIFICATION_RESPONSE_PATH=""
 APPROVED_PLAN_PATH=""
+APPROVE_PLAN_ACK="false"
 CLARIFICATION_RESPONSE_FILE=""
 CLARIFICATION_RESPONSE_RELATIVE_PATH=""
 PROJECT_ROOT=""