okstra 0.34.1 → 0.36.1

package/docs/superpowers/plans/2026-05-20-okstra-run-prompt-sot-b1.md

@@ -0,0 +1,1007 @@
+# okstra-run Lead Prompt Token SOT (Phase B1) Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** `claude-execution-prompt.md` 의 `{{TOKEN}}` 들이 `prompts/launch.template.md` 단독 권위가 되도록 만든다. 렌더러의 hand-maintained mapping dict 제거 + ctx 키 = token 명 정합화. 누락 시 fail-fast.
+
+**Architecture:** 
+1. ctx producer 측 키 이름을 token 이름에 맞춰 일괄 rename (`*_FILE`/`*_DIR`/`*_SCRIPT` → `*_PATH`, `*_DISPLAY` 접미사 제거 등 — design 문서 2.2 표). 이 시점에서 옛 `render_template_file` 의 mapping dict 도 새 키를 읽도록 갱신 — 동작 동일성 유지. 
+2. 기존 `render_template_file` 내부의 compute 블록(team_creation_gate 등)을 `inject_lead_prompt_computed_tokens(ctx)` 로 분리해 ctx 에 미리 머지. 
+3. 신규 `render_template_with_ctx(template, out, ctx)` 가 정규식으로 토큰 추출 → `ctx[token]` 직접 lookup → 미존재 시 `RenderError`. 
+4. caller 를 새 함수로 전환, 옛 `render_template_file` 제거.
+
+**Tech Stack:** Python 3 (stdlib `re`, `pathlib`), pytest, bash (e2e scenario).
+
+**Reference:** [docs/superpowers/specs/2026-05-20-okstra-run-prompt-sot-design.md](../specs/2026-05-20-okstra-run-prompt-sot-design.md) (Phase B1 = 본 플랜의 범위. Phase A1 은 별도 플랜)
+
+---
+
+## File Structure
+
+**생성**
+- `scripts/okstra_ctl/render.py` 안에 두 함수 신규 추가 (Task 2/3):
+  - `inject_lead_prompt_computed_tokens(ctx)` — C3 / C4 (computed + default) 를 ctx 에 머지
+  - `render_template_with_ctx(template_path, output_path, ctx)` — pure ctx[token] lookup 렌더러
+- `tests/test_render_inject_computed_tokens.py` — inject 함수 단위 테스트
+- `tests/test_render_template_with_ctx.py` — 신규 렌더러 단위 테스트
+- `tests/test_lead_prompt_token_resolution.py` — 합성 ctx 로 실제 `launch.template.md` 렌더 → 미치환 토큰 0 검증 (CI 게이트)
+
+**수정**
+- `scripts/okstra_ctl/render.py` — Task 1 에서 mapping dict 의 ctx lookup 키 rename; Task 5 에서 mapping dict 와 옛 `render_template_file` 함수 자체 제거 + CLI dispatcher 의 `template` subcommand 가 새 함수 호출
+- `scripts/okstra_ctl/run.py` — Task 1 에서 ctx 빌드 시 새 키 이름 사용; Task 5 에서 `render_template_file(prompt_template, ...)` 호출을 새 두 함수 호출로 교체
+- `scripts/okstra_ctl/paths.py` — Task 1: ctx 키 rename
+- `scripts/okstra_ctl/index.py` — Task 1: ctx 키 rename
+- `scripts/lib/okstra/cli.sh`, `scripts/lib/okstra/globals.sh`, `scripts/lib/okstra/interactive.sh`, `scripts/okstra.sh`, `scripts/okstra-central.sh` — Task 1: 옛 키 이름으로 ctx-render-context 를 읽는 shell 경로 rename
+- `validators/validate-workflow.sh`, `validators/lib/runners.sh` — Task 1: 옛 키 참조 rename
+- 영향받는 기존 테스트 (Task 1 안에서 함께 rename): `tests/test_okstra_run_context.py`, `tests/test_render_phase_blocks.py`, `tests/test_okstra_central_record_start.py`, `tests/test_okstra_ctl_frontmatter.py`, `tests/test_plan_body_verification.py`
+- `tests-e2e/scenario-01-record-start-reconcile.sh` (또는 다른 시나리오 하나) — Task 6: 렌더된 `claude-execution-prompt.md` 에 `{{...}}` 잔여 없음 grep 게이트 추가
+- `CHANGES.md` — Task 7: 사용자 영향 줄 추가
+
+---
+
+## Task 1: ctx 키 rename — 한 commit 으로 원자적
+
+**Files:**
+- Modify: `scripts/okstra_ctl/paths.py`
+- Modify: `scripts/okstra_ctl/run.py`
+- Modify: `scripts/okstra_ctl/render.py` — mapping dict 의 ctx lookup 키 + 다른 render_* 함수의 옛 키
+- Modify: `scripts/okstra_ctl/index.py`
+- Modify: `scripts/lib/okstra/cli.sh`, `scripts/lib/okstra/globals.sh`, `scripts/lib/okstra/interactive.sh`
+- Modify: `scripts/okstra.sh`, `scripts/okstra-central.sh`
+- Modify: `validators/validate-workflow.sh`, `validators/lib/runners.sh`
+- Modify: `tests/test_okstra_run_context.py`, `tests/test_render_phase_blocks.py`, `tests/test_okstra_central_record_start.py`, `tests/test_okstra_ctl_frontmatter.py`, `tests/test_plan_body_verification.py`
+
+이 task 는 **behavior-preserving refactor** — 동작 동일성 검증은 기존 pytest 회귀가 담당. 새 테스트는 추가하지 않음.
+
+**Rename 표** (design 문서 2.2 — 좌측 → 우측):
+
+```
+TASK_MANIFEST_FILE        → TASK_MANIFEST_PATH
+TASK_INDEX_FILE           → TASK_INDEX_PATH
+INSTRUCTION_SET_DIR       → INSTRUCTION_SET_PATH
+RUN_MANIFEST_FILE         → RUN_MANIFEST_PATH
+TIMELINE_FILE             → TIMELINE_PATH
+FINAL_REPORT_FILE         → FINAL_REPORT_PATH
+FINAL_STATUS_FILE         → FINAL_STATUS_PATH
+TEAM_STATE_FILE           → TEAM_STATE_PATH
+WORKER_RESULTS_DIR        → WORKER_RESULTS_PATH
+RUN_VALIDATOR_SCRIPT      → RUN_VALIDATOR_PATH
+RUN_ERRORS_LOG_FILE       → RUN_ERRORS_LOG_PATH
+CLAUDE_WORKER_ERRORS_SIDECAR_FILE        → CLAUDE_WORKER_ERRORS_SIDECAR_PATH
+CODEX_WORKER_ERRORS_SIDECAR_FILE         → CODEX_WORKER_ERRORS_SIDECAR_PATH
+GEMINI_WORKER_ERRORS_SIDECAR_FILE        → GEMINI_WORKER_ERRORS_SIDECAR_PATH
+REPORT_WRITER_WORKER_ERRORS_SIDECAR_FILE → REPORT_WRITER_WORKER_ERRORS_SIDECAR_PATH
+LEAD_MODEL_DISPLAY                       → LEAD_MODEL
+CLAUDE_WORKER_MODEL_DISPLAY              → CLAUDE_WORKER_MODEL
+CODEX_WORKER_MODEL_DISPLAY               → CODEX_WORKER_MODEL
+GEMINI_WORKER_MODEL_DISPLAY              → GEMINI_WORKER_MODEL
+REPORT_WRITER_MODEL_DISPLAY              → REPORT_WRITER_MODEL
+FINAL_REPORT_TEMPLATE_FILE               → FINAL_REPORT_TEMPLATE_PATH
+CLARIFICATION_RESPONSE_FILE              → CLARIFICATION_RESPONSE_PATH
+CLAUDE_RESUME_COMMAND_FILE               → CLAUDE_RESUME_COMMAND_PATH
+ANALYSIS_TYPE                            → TASK_TYPE
+REVIEW_PROFILE                           → ANALYSIS_PROFILE
+SELECTED_REVIEWERS                       → RECOMMENDED_ANALYSERS
+```
+
+모든 매핑은 `\b` 단어 경계 기반 string replace.
+
+- [ ] **Step 1: Pre-flight grep — 옛 키들이 다른 식별자의 prefix 인지 확인**
+
+```bash
+grep -rnP '\b(TASK_MANIFEST_FILE|TASK_INDEX_FILE|INSTRUCTION_SET_DIR|RUN_MANIFEST_FILE|TIMELINE_FILE|FINAL_REPORT_FILE|FINAL_STATUS_FILE|TEAM_STATE_FILE|WORKER_RESULTS_DIR|RUN_VALIDATOR_SCRIPT|RUN_ERRORS_LOG_FILE|LEAD_MODEL_DISPLAY|CLAUDE_WORKER_MODEL_DISPLAY|CODEX_WORKER_MODEL_DISPLAY|GEMINI_WORKER_MODEL_DISPLAY|REPORT_WRITER_MODEL_DISPLAY|FINAL_REPORT_TEMPLATE_FILE|CLARIFICATION_RESPONSE_FILE|CLAUDE_RESUME_COMMAND_FILE|REVIEW_PROFILE|SELECTED_REVIEWERS|ANALYSIS_TYPE)[A-Z_]+\b' scripts/ tests/ validators/ 2>/dev/null
+```
+Expected: prefix-extended 식별자 후보가 출력됨 (예: `ANALYSIS_TYPE_SEGMENT`). 이들은 rename **대상 아님** — 본 task 의 grep 게이트에서 자연스럽게 보존됨 (단어 경계 `\b` 가 다음 글자 `_` 도 단어로 판정해 매치 안 됨). 결과를 보고 본 plan 의 메모란에 기록만 해두고 다음 단계로.
+
+- [ ] **Step 2: paths.py rename**
+
+`scripts/okstra_ctl/paths.py` 에서 위 표 좌측 키들을 우측으로 일괄 치환. `Edit(replace_all=true)` 또는 IDE multi-cursor 로 한 단어씩 정확히 치환. 끝나고:
+
+```bash
+grep -nP '\b(TASK_MANIFEST_FILE|TASK_INDEX_FILE|INSTRUCTION_SET_DIR|RUN_MANIFEST_FILE|TIMELINE_FILE|FINAL_REPORT_FILE|FINAL_STATUS_FILE|TEAM_STATE_FILE|WORKER_RESULTS_DIR|RUN_VALIDATOR_SCRIPT|RUN_ERRORS_LOG_FILE|LEAD_MODEL_DISPLAY|CLAUDE_WORKER_MODEL_DISPLAY|CODEX_WORKER_MODEL_DISPLAY|GEMINI_WORKER_MODEL_DISPLAY|REPORT_WRITER_MODEL_DISPLAY|FINAL_REPORT_TEMPLATE_FILE|CLARIFICATION_RESPONSE_FILE|CLAUDE_RESUME_COMMAND_FILE|REVIEW_PROFILE|SELECTED_REVIEWERS|ANALYSIS_TYPE)\b' scripts/okstra_ctl/paths.py
+```
+Expected: 0 hits.
+
+- [ ] **Step 3: run.py rename**
+
+`scripts/okstra_ctl/run.py` 동일 적용. ctx 에 `TASK_TYPE` 과 `ANALYSIS_TYPE` 둘 다 채우는 alias 라인이 있다면 `TASK_TYPE` 만 남기고 제거.
+
+```bash
+grep -nP '\b(TASK_MANIFEST_FILE|TASK_INDEX_FILE|INSTRUCTION_SET_DIR|RUN_MANIFEST_FILE|TIMELINE_FILE|FINAL_REPORT_FILE|FINAL_STATUS_FILE|TEAM_STATE_FILE|WORKER_RESULTS_DIR|RUN_VALIDATOR_SCRIPT|RUN_ERRORS_LOG_FILE|LEAD_MODEL_DISPLAY|CLAUDE_WORKER_MODEL_DISPLAY|CODEX_WORKER_MODEL_DISPLAY|GEMINI_WORKER_MODEL_DISPLAY|REPORT_WRITER_MODEL_DISPLAY|FINAL_REPORT_TEMPLATE_FILE|CLARIFICATION_RESPONSE_FILE|CLAUDE_RESUME_COMMAND_FILE|REVIEW_PROFILE|SELECTED_REVIEWERS|ANALYSIS_TYPE)\b' scripts/okstra_ctl/run.py
+```
+Expected: 0 hits.
+
+- [ ] **Step 4: render.py rename — 다른 render_* 함수 + mapping dict 모두**
+
+`scripts/okstra_ctl/render.py` 에서 동일 적용. 이번엔 `render_template_file` 함수 안의 mapping dict 도 포함 — `"{{TASK_TYPE}}": ctx.get("ANALYSIS_TYPE", "")` 같은 라인을 `"{{TASK_TYPE}}": ctx.get("TASK_TYPE", "")` 로. mapping dict 의 LHS 토큰은 그대로, RHS ctx key 만 rename. 
+
+또한 mapping dict 의 dead/duplicate entry (예: `{{ANALYSIS_TYPE}}` 토큰 자체가 launch.template.md 에 없으면 그 entry 자체는 그대로 두지 말고 Task 5 에서 함께 제거 — 여기서는 RHS rename 만).
+
+```bash
+grep -nP '\b(TASK_MANIFEST_FILE|TASK_INDEX_FILE|INSTRUCTION_SET_DIR|RUN_MANIFEST_FILE|TIMELINE_FILE|FINAL_REPORT_FILE|FINAL_STATUS_FILE|TEAM_STATE_FILE|WORKER_RESULTS_DIR|RUN_VALIDATOR_SCRIPT|RUN_ERRORS_LOG_FILE|LEAD_MODEL_DISPLAY|CLAUDE_WORKER_MODEL_DISPLAY|CODEX_WORKER_MODEL_DISPLAY|GEMINI_WORKER_MODEL_DISPLAY|REPORT_WRITER_MODEL_DISPLAY|FINAL_REPORT_TEMPLATE_FILE|CLARIFICATION_RESPONSE_FILE|CLAUDE_RESUME_COMMAND_FILE|REVIEW_PROFILE|SELECTED_REVIEWERS|ANALYSIS_TYPE)\b' scripts/okstra_ctl/render.py
+```
+Expected: 0 hits.
+
+- [ ] **Step 5: index.py rename**
+
+```bash
+grep -nP '\b(TASK_MANIFEST_FILE|...전체 패턴 동일...|ANALYSIS_TYPE)\b' scripts/okstra_ctl/index.py
+```
+Expected: 0.
+
+- [ ] **Step 6: Shell entry points rename**
+
+`scripts/okstra.sh`, `scripts/okstra-central.sh`, `scripts/lib/okstra/{cli,globals,interactive}.sh` 에서 동일 치환. 이 파일들은 보통 `jq` 또는 환경변수로 ctx-render-context JSON 의 키를 읽으므로, `.TASK_MANIFEST_FILE` → `.TASK_MANIFEST_PATH` 형태가 됨.
+
+```bash
+grep -nE '(TASK_MANIFEST_FILE|TASK_INDEX_FILE|INSTRUCTION_SET_DIR|RUN_MANIFEST_FILE|TIMELINE_FILE|FINAL_REPORT_FILE|FINAL_STATUS_FILE|TEAM_STATE_FILE|WORKER_RESULTS_DIR|RUN_VALIDATOR_SCRIPT|RUN_ERRORS_LOG_FILE|LEAD_MODEL_DISPLAY|CLAUDE_WORKER_MODEL_DISPLAY|CODEX_WORKER_MODEL_DISPLAY|GEMINI_WORKER_MODEL_DISPLAY|REPORT_WRITER_MODEL_DISPLAY|FINAL_REPORT_TEMPLATE_FILE|CLARIFICATION_RESPONSE_FILE|CLAUDE_RESUME_COMMAND_FILE|REVIEW_PROFILE|SELECTED_REVIEWERS)' scripts/okstra.sh scripts/okstra-central.sh scripts/lib/okstra/*.sh
+```
+(쉘 파일에서는 `ANALYSIS_TYPE` 이 `ANALYSIS_TYPE_SEGMENT` 같이 등장할 수 있으므로 단어 경계는 `grep -E` 의 한계상 별도 검토 — Step 1 의 결과 활용.)
+Expected: 0 hits (Step 1 의 EXCLUDE 식별자 제외).
+
+- [ ] **Step 7: validators rename**
+
+```bash
+grep -nE '(TASK_MANIFEST_FILE|...|SELECTED_REVIEWERS)' validators/validate-workflow.sh validators/lib/runners.sh
+```
+Expected: 0.
+
+- [ ] **Step 8: Tests rename**
+
+기존 단위 테스트의 fixture / assertion 을 새 키로:
+- `tests/test_okstra_run_context.py`
+- `tests/test_render_phase_blocks.py`
+- `tests/test_okstra_central_record_start.py`
+- `tests/test_okstra_ctl_frontmatter.py`
+- `tests/test_plan_body_verification.py`
+
+```bash
+grep -rnP '\b(TASK_MANIFEST_FILE|TASK_INDEX_FILE|INSTRUCTION_SET_DIR|RUN_MANIFEST_FILE|TIMELINE_FILE|FINAL_REPORT_FILE|FINAL_STATUS_FILE|TEAM_STATE_FILE|WORKER_RESULTS_DIR|RUN_VALIDATOR_SCRIPT|RUN_ERRORS_LOG_FILE|LEAD_MODEL_DISPLAY|CLAUDE_WORKER_MODEL_DISPLAY|CODEX_WORKER_MODEL_DISPLAY|GEMINI_WORKER_MODEL_DISPLAY|REPORT_WRITER_MODEL_DISPLAY|FINAL_REPORT_TEMPLATE_FILE|CLARIFICATION_RESPONSE_FILE|CLAUDE_RESUME_COMMAND_FILE|REVIEW_PROFILE|SELECTED_REVIEWERS|ANALYSIS_TYPE)\b' tests/
+```
+Expected: 0.
+
+- [ ] **Step 9: 전체 회귀 통과 + 코드베이스 leftover 게이트**
+
+```bash
+python3 -m pytest tests/ -x
+```
+Expected: PASS (옛 키 회귀 없음).
+
+전체 leftover 게이트:
+
+```bash
+grep -rnP '\b(TASK_MANIFEST_FILE|TASK_INDEX_FILE|INSTRUCTION_SET_DIR|RUN_MANIFEST_FILE|TIMELINE_FILE|FINAL_REPORT_FILE|FINAL_STATUS_FILE|TEAM_STATE_FILE|WORKER_RESULTS_DIR|RUN_VALIDATOR_SCRIPT|RUN_ERRORS_LOG_FILE|LEAD_MODEL_DISPLAY|CLAUDE_WORKER_MODEL_DISPLAY|CODEX_WORKER_MODEL_DISPLAY|GEMINI_WORKER_MODEL_DISPLAY|REPORT_WRITER_MODEL_DISPLAY|FINAL_REPORT_TEMPLATE_FILE|CLARIFICATION_RESPONSE_FILE|CLAUDE_RESUME_COMMAND_FILE|REVIEW_PROFILE|SELECTED_REVIEWERS|ANALYSIS_TYPE)\b' scripts/ tests/ validators/ 2>/dev/null
+```
+Expected: 0 hits.
+
+- [ ] **Step 10: Commit**
+
+```bash
+git add -A
+git commit -m "refactor(ctx): rename lead-prompt ctx keys to match token names (no behavior change)"
+```
+
+---
+
+## Task 2: `inject_lead_prompt_computed_tokens(ctx)` 분리 (TDD)
+
+**Files:**
+- Modify: `scripts/okstra_ctl/render.py` — 기존 `render_template_file` 함수 내부 (현재 ~1358–1467 라인의 compute 블록) 의 로직을 새 함수로 분리. 분리만, 호출은 기존 `render_template_file` 에서 계속.
+- Create: `tests/test_render_inject_computed_tokens.py`
+
+이 task commit 후에도 외부에서 본 산출물은 동일 (compute 가 inject 안으로만 이동). mapping dict 의 9 개 compute + 4 개 default 항목은 ctx 에서 미리 머지된 값을 그대로 통과시키도록 갱신.
+
+- [ ] **Step 1: Failing test**
+
+`tests/test_render_inject_computed_tokens.py` 생성:
+
+```python
+"""inject_lead_prompt_computed_tokens — render.py 의 compute 블록 분리 검증."""
+from __future__ import annotations
+
+from okstra_ctl.render import inject_lead_prompt_computed_tokens
+
+
+def _base_ctx() -> dict:
+    """렌더러가 compute 블록을 채우는 데 필요한 최소 입력 (Task 1 rename 이후 키 사용)."""
+    return {
+        "TASK_KEY": "demo/task-a",
+        "TASK_TYPE": "error-analysis",
+        "PROJECT_ROOT": "/tmp/project-x",
+        "LEAD_MODEL": "claude-opus-4-7",
+        "LEAD_MODEL_EXECUTION_VALUE": "claude-opus-4-7",
+        "CLAUDE_WORKER_MODEL": "claude-sonnet-4-6",
+        "CLAUDE_WORKER_MODEL_EXECUTION_VALUE": "claude-sonnet-4-6",
+        "CODEX_WORKER_MODEL": "gpt-5",
+        "CODEX_WORKER_MODEL_EXECUTION_VALUE": "gpt-5",
+        "GEMINI_WORKER_MODEL": "gemini-2.5-pro",
+        "GEMINI_WORKER_MODEL_EXECUTION_VALUE": "gemini-2.5-pro",
+        "REPORT_WRITER_MODEL": "claude-haiku-4-5",
+        "REPORT_WRITER_MODEL_EXECUTION_VALUE": "claude-haiku-4-5",
+        "RECOMMENDED_ANALYSERS": "claude,codex,gemini",
+        # worker result path (relative — paths.py 결과 형태)
+        "CLAUDE_WORKER_RESULT_RELATIVE_PATH": "runs/error-analysis/results/claude-worker-001.md",
+        "CODEX_WORKER_RESULT_RELATIVE_PATH":  "runs/error-analysis/results/codex-worker-001.md",
+        "GEMINI_WORKER_RESULT_RELATIVE_PATH": "runs/error-analysis/results/gemini-worker-001.md",
+        "REPORT_WRITER_WORKER_RESULT_RELATIVE_PATH": "runs/error-analysis/results/report-writer-worker-001.md",
+    }
+
+
+def test_inject_adds_team_creation_gate_for_multi_worker_phase():
+    ctx = _base_ctx()
+    inject_lead_prompt_computed_tokens(ctx)
+    assert "TEAM_CREATION_GATE" in ctx
+    assert "Team Creation Gate (BLOCKING)" in ctx["TEAM_CREATION_GATE"]
+    assert "okstra-demo/task-a" in ctx["TEAM_CREATION_GATE"]
+
+
+def test_inject_uses_single_lead_block_for_release_handoff():
+    ctx = _base_ctx()
+    ctx["TASK_TYPE"] = "release-handoff"
+    ctx["RECOMMENDED_ANALYSERS"] = ""
+    inject_lead_prompt_computed_tokens(ctx)
+    assert ctx["TEAM_CREATION_GATE"].startswith("## Single-Lead Phase")
+
+
+def test_inject_fills_worker_role_sentences_and_table():
+    ctx = _base_ctx()
+    inject_lead_prompt_computed_tokens(ctx)
+    assert ctx["REQUIRED_WORKER_ROLE_SENTENCE"].startswith("- ")
+    assert "Claude worker" in ctx["TEAM_ROLE_LINES"]
+    assert "EXECUTION_STATUS_TABLE_ROWS" in ctx
+    assert "Claude lead" in ctx["EXECUTION_STATUS_TABLE_ROWS"]
+
+
+def test_inject_sets_default_fallbacks():
+    ctx = _base_ctx()
+    inject_lead_prompt_computed_tokens(ctx)
+    assert ctx["VALIDATION_STATUS"] == "not-run"
+    assert ctx["RELATED_TASKS_BULLETS"] == "- None recorded"
+    assert ctx["RELATED_TASKS_INLINE"] == "None"
+    assert ctx["AVAILABLE_MCP_SERVERS"]   # 비어있지 않음
+
+
+def test_inject_preserves_existing_overrides():
+    ctx = _base_ctx()
+    ctx["VALIDATION_STATUS"] = "ok"
+    ctx["RELATED_TASKS_BULLETS"] = "- foo"
+    inject_lead_prompt_computed_tokens(ctx)
+    assert ctx["VALIDATION_STATUS"] == "ok"
+    assert ctx["RELATED_TASKS_BULLETS"] == "- foo"
+```
+
+- [ ] **Step 2: 테스트 실패 확인**
+
+```bash
+python3 -m pytest tests/test_render_inject_computed_tokens.py -v
+```
+Expected: `ImportError: cannot import name 'inject_lead_prompt_computed_tokens'`.
+
+- [ ] **Step 3: `inject_lead_prompt_computed_tokens` 구현**
+
+`scripts/okstra_ctl/render.py` 의 `render_template_file` 함수 정의 위에 다음 함수 신규 추가:
+
+```python
+def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
+    """Populate ctx in-place with computed lead-prompt tokens (C3) and
+    default fallbacks (C4). This is the part of the old `render_template_file`
+    mapping dict that did not have a 1:1 ctx key — it now lives in ctx itself
+    so the new pure-lookup renderer can resolve it.
+
+    Idempotent: existing values are preserved (setdefault for C4 defaults;
+    plain assignment for C3 compute blocks, which are deterministic from ctx).
+    """
+    selected = _resolve_workers(ctx)
+    catalog = _worker_catalog(ctx)
+    lead_model = ctx.get("LEAD_MODEL", "")
+    lead_model_execution = ctx.get("LEAD_MODEL_EXECUTION_VALUE", "")
+
+    def fmt_assignment(role: str, model: str, execution: str) -> str:
+        if execution and execution != model:
+            return f"- `{role}`: `{model}` (launch value: `{execution}`)"
+        return f"- `{role}`: `{model}`"
+
+    worker_result_lines: list[str] = []
+    team_role_lines = [f"  1. `Claude lead` (assigned model: `{lead_model}`)"]
+    model_assignment_lines = [
+        fmt_assignment("Claude lead", lead_model, lead_model_execution)
+    ]
+    worker_role_labels: list[str] = []
+    execution_status_entries = ["`Claude lead`"]
+    execution_status_table_lines = [
+        "| 에이전트 | 역할 | 모델 | 상태 | 핵심 발견 요약 |",
+        "|----------|------|------|------|----------------|",
+        f"| Claude Code | Claude lead | {lead_model} | completed / timeout / error / not-run | 최종 synthesis 작성 상태와 핵심 판단 |",
+    ]
+    for index, worker in enumerate(selected, start=2):
+        m = catalog[worker]
+        worker_result_lines.append(
+            f"- {m['role']} result path: `{m['resultPath']}` (assigned model: `{m['model']}`)"
+        )
+        team_role_lines.append(
+            f"  {index}. `{m['role']}` (assigned model: `{m['model']}`)"
+        )
+        model_assignment_lines.append(
+            fmt_assignment(m["role"], m["model"], m["modelExecutionValue"])
+        )
+        worker_role_labels.append(f"`{m['role']}`")
+        execution_status_entries.append(f"`{m['role']}`")
+        execution_status_table_lines.append(
+            f"| {m['agentLabel']} | {m['role']} | {m['model']} | completed / timeout / error / not-run | {m['role']}의 핵심 발견 요약 |"
+        )
+
+    if worker_role_labels:
+        if len(worker_role_labels) == 1:
+            worker_role_sentence = f"- {worker_role_labels[0]} is the required worker role."
+        else:
+            worker_role_sentence = (
+                f"- {', '.join(worker_role_labels[:-1])}, "
+                f"and {worker_role_labels[-1]} are the required worker roles."
+            )
+        preferred_results_sentence = (
+            f"- Aim to collect completed results from all "
+            f"{len(worker_role_labels)} required workers."
+        )
+    else:
+        worker_role_sentence = "- No worker roles were selected for this run."
+        preferred_results_sentence = "- No worker results are expected for this run."
+    worker_attempt_sentence = (
+        "- `Gemini worker` is mandatory to attempt for this workflow."
+        if "gemini" in selected
+        else "- `Gemini worker` is not selected for this run, so no Gemini attempt is required."
+    )
+
+    task_type = ctx.get("TASK_TYPE", "")
+    if task_type == "release-handoff" or not selected:
+        team_creation_gate_block = (
+            "## Single-Lead Phase (no team creation)\n"
+            "\n"
+            "This run is single-lead. There is no worker roster, no\n"
+            "`TeamCreate` call, no `Agent(...)` worker dispatch, and no\n"
+            "convergence loop. The Claude lead performs every step inline\n"
+            "(reading inputs, drafting commit / PR text when applicable,\n"
+            "asking the user, running git / gh, and writing the final\n"
+            "report). Do NOT call `TeamCreate` or dispatch any sub-agent\n"
+            "from this run — that would be a contract violation."
+        )
+    else:
+        team_creation_gate_block = (
+            "## Team Creation Gate (BLOCKING)\n"
+            "\n"
+            "Before any `Agent` dispatch for workers, you MUST perform Phase 3 of the\n"
+            '`okstra` skill (`agents/SKILL.md` → "Phase 3 — Team creation"). Skipping\n'
+            "this gate silently degrades the run to in-process background dispatch and\n"
+            "loses the Teams split-pane observability surface, even though worker\n"
+            "outputs may still appear correct on disk.\n"
+            "\n"
+            "Required actions, in order, regardless of how many workers are selected\n"
+            "for this run (roster comes from `resultContract.requiredWorkerRoles` in\n"
+            "`task-manifest.json` — it may be 1, 2, 3, or more workers):\n"
+            "\n"
+            "1. Invoke the `okstra-team-contract` skill and verify the selected worker\n"
+            "   roster against `task-manifest.json`'s `resultContract.requiredWorkerRoles`.\n"
+            f'2. Call `TeamCreate(team_name: "okstra-{ctx.get("TASK_KEY", "")}", description: ...)`.\n'
+            "3. Record the outcome in team-state under\n"
+            '   `teamCreate: { attempted: true, status: "ok" | "error", error?: <msg> }`\n'
+            "   BEFORE any `Agent(...)` worker dispatch.\n"
+            "4. Only after `teamCreate` is persisted may you dispatch workers — with\n"
+            "   `team_name` on success, or with `run_in_background: true` and no\n"
+            '   `team_name` ONLY when `teamCreate.status == "error"` was recorded.\n'
+            "\n"
+            'If the Agent tool rejects a dispatch with `"team must be created first"` /\n'
+            '`"team을 먼저 생성하거나 team_name 없이 호출해야 합니다"`, the correct\n'
+            "response is to go back to step 2 — NOT to strip `team_name` and retry."
+        )
+
+    # C3 — compute results (deterministic from ctx, 덮어쓰기)
+    ctx["TEAM_CREATION_GATE"] = team_creation_gate_block
+    ctx["WORKER_RESULT_PATH_LINES"] = "\n".join(worker_result_lines)
+    ctx["MODEL_ASSIGNMENT_LINES"] = "\n".join(model_assignment_lines)
+    ctx["TEAM_ROLE_LINES"] = "\n".join(team_role_lines)
+    ctx["REQUIRED_WORKER_ROLE_SENTENCE"] = worker_role_sentence
+    ctx["GEMINI_ATTEMPT_SENTENCE"] = worker_attempt_sentence
+    ctx["PREFERRED_WORKER_RESULTS_SENTENCE"] = preferred_results_sentence
+    ctx["EXECUTION_STATUS_EXACT_ENTRIES"] = ", ".join(execution_status_entries)
+    ctx["EXECUTION_STATUS_TABLE_ROWS"] = "\n".join(execution_status_table_lines)
+
+    # C4 — defaults (override 보존)
+    ctx.setdefault("VALIDATION_STATUS", "not-run")
+    ctx.setdefault("RELATED_TASKS_BULLETS", "- None recorded")
+    ctx.setdefault("RELATED_TASKS_INLINE", "None")
+    ctx.setdefault(
+        "AVAILABLE_MCP_SERVERS",
+        build_available_mcp_servers_block(Path(ctx.get("PROJECT_ROOT", "."))),
+    )
+```
+
+- [ ] **Step 4: 기존 `render_template_file` 안의 compute 블록 제거**
+
+`scripts/okstra_ctl/render.py` 의 `render_template_file` 함수 본문 시작 직후에 `inject_lead_prompt_computed_tokens(ctx)` 호출 추가. 그 뒤 compute 코드 (selected/catalog 선언 ~ team_creation_gate_block 정의) 와 mapping dict 의 9 개 compute + 4 개 default 항목을 ctx 직접 lookup 으로 단순화:
+
+```python
+def render_template_file(template_path: str, output_path: str, ctx: dict) -> None:
+    inject_lead_prompt_computed_tokens(ctx)
+    template = Path(template_path).read_text(encoding="utf-8")
+    mapping = {
+        # compute + default 13 항목 — 이제 ctx 에 직접 키로 존재
+        "{{TEAM_CREATION_GATE}}": ctx["TEAM_CREATION_GATE"],
+        "{{WORKER_RESULT_PATH_LINES}}": ctx["WORKER_RESULT_PATH_LINES"],
+        "{{MODEL_ASSIGNMENT_LINES}}": ctx["MODEL_ASSIGNMENT_LINES"],
+        "{{TEAM_ROLE_LINES}}": ctx["TEAM_ROLE_LINES"],
+        "{{REQUIRED_WORKER_ROLE_SENTENCE}}": ctx["REQUIRED_WORKER_ROLE_SENTENCE"],
+        "{{GEMINI_ATTEMPT_SENTENCE}}": ctx["GEMINI_ATTEMPT_SENTENCE"],
+        "{{PREFERRED_WORKER_RESULTS_SENTENCE}}": ctx["PREFERRED_WORKER_RESULTS_SENTENCE"],
+        "{{EXECUTION_STATUS_EXACT_ENTRIES}}": ctx["EXECUTION_STATUS_EXACT_ENTRIES"],
+        "{{EXECUTION_STATUS_TABLE_ROWS}}": ctx["EXECUTION_STATUS_TABLE_ROWS"],
+        "{{VALIDATION_STATUS}}": ctx["VALIDATION_STATUS"],
+        "{{RELATED_TASKS_BULLETS}}": ctx["RELATED_TASKS_BULLETS"],
+        "{{RELATED_TASKS_INLINE}}": ctx["RELATED_TASKS_INLINE"],
+        "{{AVAILABLE_MCP_SERVERS}}": ctx["AVAILABLE_MCP_SERVERS"],
+        # 나머지 ~90 개 1:1 매핑은 그대로 (Task 5 에서 일괄 제거)
+        # ... (기존 mapping 의 나머지 항목 그대로) ...
+    }
+    fm_ctx = dict(ctx)
+    fm_ctx.setdefault("DOC_TYPE", _doc_type_from_template_path(template_path))
+    mapping.update(_frontmatter_mapping(fm_ctx))
+    rendered = template
+    for k, v in mapping.items():
+        rendered = rendered.replace(k, v)
+    rendered = _strip_phase_blocks(rendered, ctx.get("TASK_TYPE", ""))
+    _write_text(Path(output_path), rendered.rstrip() + "\n")
+```
+
+- [ ] **Step 5: 단위 테스트 + 회귀 통과 확인**
+
+```bash
+python3 -m pytest tests/test_render_inject_computed_tokens.py -v
+python3 -m pytest tests/ -x
+```
+Expected: 5 PASS + 전체 회귀 PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add scripts/okstra_ctl/render.py tests/test_render_inject_computed_tokens.py
+git commit -m "refactor(render): extract lead-prompt computed tokens into inject_lead_prompt_computed_tokens()"
+```
+
+---
+
+## Task 3: `render_template_with_ctx()` 추가 (TDD)
+
+**Files:**
+- Modify: `scripts/okstra_ctl/render.py` — 새 함수 추가, 아직 caller 없음
+- Create: `tests/test_render_template_with_ctx.py`
+
+- [ ] **Step 1: Failing test**
+
+`tests/test_render_template_with_ctx.py` 생성:
+
+```python
+"""render_template_with_ctx — pure ctx[token] 렌더러."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from okstra_ctl.render import RenderError, render_template_with_ctx
+
+
+def test_substitutes_known_tokens(tmp_path: Path):
+    template = tmp_path / "tpl.md"
+    template.write_text("project at {{PROJECT_ROOT}}\nkey: {{TASK_KEY}}\n")
+    out = tmp_path / "out.md"
+
+    render_template_with_ctx(str(template), str(out), {
+        "PROJECT_ROOT": "/p/x",
+        "TASK_KEY": "demo/t1",
+        "TASK_TYPE": "error-analysis",   # phase strip 에 필요
+    })
+
+    text = out.read_text()
+    assert "project at /p/x" in text
+    assert "key: demo/t1" in text
+    assert "{{" not in text
+
+
+def test_raises_on_undefined_token(tmp_path: Path):
+    template = tmp_path / "tpl.md"
+    template.write_text("missing: {{NOT_IN_CTX}}\n")
+    out = tmp_path / "out.md"
+
+    with pytest.raises(RenderError) as exc_info:
+        render_template_with_ctx(str(template), str(out), {"TASK_TYPE": ""})
+    assert "NOT_IN_CTX" in str(exc_info.value)
+    assert "tpl.md" in str(exc_info.value)
+    assert not out.exists()   # 실패 시 출력 파일 생성 안 함
+
+
+def test_phase_strip_still_applies(tmp_path: Path):
+    template = tmp_path / "tpl.md"
+    template.write_text(
+        "before\n"
+        "<!-- phase:error-analysis -->\nEA block\n<!-- /phase:error-analysis -->\n"
+        "<!-- phase:implementation -->\nIMPL block\n<!-- /phase:implementation -->\n"
+        "after\n"
+    )
+    out = tmp_path / "out.md"
+
+    render_template_with_ctx(str(template), str(out), {"TASK_TYPE": "error-analysis"})
+
+    text = out.read_text()
+    assert "EA block" in text
+    assert "IMPL block" not in text
+
+
+def test_frontmatter_overlay_applied(tmp_path: Path):
+    """frontmatter mapping (기존 _frontmatter_mapping) 가 그대로 적용되어야 한다."""
+    template = tmp_path / "tpl.md"
+    template.write_text(
+        "---\n"
+        "title: {{DOC_TITLE}}\n"
+        "---\n"
+        "body {{PROJECT_ROOT}}\n"
+    )
+    out = tmp_path / "out.md"
+
+    render_template_with_ctx(str(template), str(out), {
+        "PROJECT_ROOT": "/p",
+        "TASK_TYPE": "",
+        "DOC_TITLE": "X",
+    })
+
+    text = out.read_text()
+    assert "title: X" in text
+    assert "body /p" in text
+```
+
+- [ ] **Step 2: 테스트 실패 확인**
+
+```bash
+python3 -m pytest tests/test_render_template_with_ctx.py -v
+```
+Expected: 4 FAIL (`ImportError: cannot import name 'RenderError'` 또는 `'render_template_with_ctx'`).
+
+- [ ] **Step 3: 구현**
+
+`scripts/okstra_ctl/render.py` 상단(다른 import / exception 정의 근처)에 `RenderError` 추가:
+
+```python
+class RenderError(Exception):
+    """Raised when a template references a token not present in ctx."""
+```
+
+`render_template_file` 정의 아래에 신규 함수 추가:
+
+```python
+_TOKEN_RE = re.compile(r"\{\{([A-Z][A-Z0-9_]*)\}\}")
+
+
+def render_template_with_ctx(template_path: str, output_path: str, ctx: dict) -> None:
+    """Render a `{{TOKEN}}` template with pure ctx[token] lookup.
+
+    - Tokens match regex `_TOKEN_RE` (uppercase snake).
+    - Each token MUST exist in ctx. Missing → `RenderError` (fail-fast).
+    - Phase block stripping (`<!-- phase:X --> ... -->`) is applied per `ctx['TASK_TYPE']`.
+    - Frontmatter mapping (`_frontmatter_mapping`) is overlaid (same as legacy renderer).
+
+    Callers that need computed tokens (team_creation_gate etc.) MUST call
+    `inject_lead_prompt_computed_tokens(ctx)` BEFORE invoking this function.
+    """
+    template = Path(template_path).read_text(encoding="utf-8")
+
+    fm_ctx = dict(ctx)
+    fm_ctx.setdefault("DOC_TYPE", _doc_type_from_template_path(template_path))
+    fm_overlay = _frontmatter_mapping(fm_ctx)   # {"{{DOC_TITLE}}": "...", ...}
+
+    # frontmatter overlay 가 채우는 키들도 lookup 대상 — 단일 lookup 으로 통일
+    lookup: dict[str, str] = {}
+    for tok_with_braces, value in fm_overlay.items():
+        key = tok_with_braces[2:-2]   # "{{X}}" -> "X"
+        lookup[key] = value
+
+    rendered = template
+    missing: list[str] = []
+    for match in _TOKEN_RE.finditer(template):
+        token = match.group(1)
+        if token in lookup:
+            value = lookup[token]
+        elif token in ctx:
+            value = str(ctx[token])
+        else:
+            missing.append(token)
+            continue
+        rendered = rendered.replace("{{" + token + "}}", value)
+
+    if missing:
+        names = ", ".join(sorted(set(missing)))
+        raise RenderError(
+            f"undefined lead-prompt token(s): {names} (template={template_path}). "
+            f"Add the key(s) to ctx in run.py / inject_lead_prompt_computed_tokens()."
+        )
+
+    rendered = _strip_phase_blocks(rendered, ctx.get("TASK_TYPE", ""))
+    _write_text(Path(output_path), rendered.rstrip() + "\n")
+```
+
+- [ ] **Step 4: 테스트 통과 확인**
+
+```bash
+python3 -m pytest tests/test_render_template_with_ctx.py -v
+python3 -m pytest tests/ -x
+```
+Expected: 4 PASS + 회귀 PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add scripts/okstra_ctl/render.py tests/test_render_template_with_ctx.py
+git commit -m "feat(render): add render_template_with_ctx() pure-lookup renderer"
+```
+
+---
+
+## Task 4: launch.template.md 토큰 정적 검증 게이트
+
+**Files:**
+- Create: `tests/test_lead_prompt_token_resolution.py`
+
+합성 ctx (모든 토큰 키 포함) 로 실제 `prompts/launch.template.md` 를 `render_template_with_ctx` 로 dry-render → 미치환 `{{...}}` 잔여 0 확인.
+
+- [ ] **Step 1: 합성 ctx 빌더 작성 + Failing test**
+
+`tests/test_lead_prompt_token_resolution.py` 생성:
+
+```python
+"""launch.template.md token resolution — CI 게이트.
+
+`prompts/launch.template.md` 안의 모든 `{{TOKEN}}` 이 ctx 로부터 해석돼야 한다.
+하나라도 누락 시 `render_template_with_ctx` 가 `RenderError` 로 fail 한다.
+이 테스트가 PASS 한다는 것은 "템플릿 추가/수정 시 ctx 빌드 코드 갱신 누락이 없다"
+는 SOT 동기화 보증.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import pytest
+
+from okstra_ctl.render import (
+    RenderError,
+    inject_lead_prompt_computed_tokens,
+    render_template_with_ctx,
+)
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+LAUNCH_TEMPLATE = REPO_ROOT / "prompts" / "launch.template.md"
+TOKEN_RE = re.compile(r"\{\{([A-Z][A-Z0-9_]*)\}\}")
+
+
+def _synthetic_ctx(task_type: str = "error-analysis") -> dict:
+    """launch.template.md 가 참조하는 모든 token 에 placeholder 값을 채운 ctx.
+
+    이 함수는 `prompts/launch.template.md` 와 명시적으로 동기화돼야 한다.
+    템플릿에 새 토큰을 추가할 때 본 함수에도 키 한 줄을 추가하면
+    `inject_lead_prompt_computed_tokens()` 와 결합해 ctx 가 완전해진다.
+    """
+    return {
+        "TASK_KEY": "demo/t1",
+        "TASK_TYPE": task_type,
+        "PROJECT_ID": "demo-project",
+        "PROJECT_ROOT": "/tmp/demo",
+        "CLAUDE_SESSION_ID": "session-abc",
+        "CLARIFICATION_RESPONSE_RELATIVE_PATH": "",
+        "CLAUDE_RESUME_COMMAND_RELATIVE_PATH": "runs/error-analysis/sessions/resume-001.sh",
+        "INSTRUCTION_SET_RELATIVE_PATH": "runs/error-analysis/instruction-set-001",
+        "TASK_MANIFEST_RELATIVE_PATH": "task-manifest.json",
+        "RUN_MANIFEST_RELATIVE_PATH": "runs/error-analysis/manifests/run-manifest-001.json",
+        "TEAM_STATE_RELATIVE_PATH": "runs/error-analysis/state/team-state-001.json",
+        "FINAL_REPORT_RELATIVE_PATH": "runs/error-analysis/reports/final-report-001.md",
+        "FINAL_STATUS_RELATIVE_PATH": "runs/error-analysis/status/final-001.status",
+        "RUN_VALIDATOR_RELATIVE_PATH": "validators/validate-run.py",
+        "RUN_ERRORS_LOG_PATH": "/tmp/demo/runs/error-analysis/errors-log-001.jsonl",
+        "RUN_ERRORS_LOG_RELATIVE_PATH": "runs/error-analysis/errors-log-001.jsonl",
+        "CLAUDE_WORKER_ERRORS_SIDECAR_PATH": "/tmp/demo/runs/error-analysis/sidecar-claude.jsonl",
+        "CODEX_WORKER_ERRORS_SIDECAR_PATH":  "/tmp/demo/runs/error-analysis/sidecar-codex.jsonl",
+        "GEMINI_WORKER_ERRORS_SIDECAR_PATH": "/tmp/demo/runs/error-analysis/sidecar-gemini.jsonl",
+        "REPORT_WRITER_WORKER_ERRORS_SIDECAR_PATH": "/tmp/demo/runs/error-analysis/sidecar-report-writer.jsonl",
+        "EXECUTOR_WORKTREE_STATUS": "skipped-not-git",
+        "EXECUTOR_WORKTREE_PATH": "",
+        "EXECUTOR_WORKTREE_BRANCH": "",
+        "EXECUTOR_WORKTREE_BASE_REF": "",
+        "EXECUTOR_WORKTREE_NOTE": "",
+        "WORKFLOW_CURRENT_PHASE": task_type,
+        "WORKFLOW_NEXT_RECOMMENDED_PHASE": "implementation-planning",
+        "PHASE_ALLOWED_OUTPUTS": "  - final-report",
+        "PHASE_FORBIDDEN_ACTIONS": "  - source-code-modification",
+        # worker result paths (inject 가 catalog 채울 때 사용)
+        "CLAUDE_WORKER_RESULT_RELATIVE_PATH": "runs/error-analysis/results/claude-worker-001.md",
+        "CODEX_WORKER_RESULT_RELATIVE_PATH":  "runs/error-analysis/results/codex-worker-001.md",
+        "GEMINI_WORKER_RESULT_RELATIVE_PATH": "runs/error-analysis/results/gemini-worker-001.md",
+        "REPORT_WRITER_WORKER_RESULT_RELATIVE_PATH": "runs/error-analysis/results/report-writer-worker-001.md",
+        # models
+        "LEAD_MODEL": "claude-opus-4-7",
+        "LEAD_MODEL_EXECUTION_VALUE": "claude-opus-4-7",
+        "CLAUDE_WORKER_MODEL": "claude-sonnet-4-6",
+        "CLAUDE_WORKER_MODEL_EXECUTION_VALUE": "claude-sonnet-4-6",
+        "CODEX_WORKER_MODEL": "gpt-5",
+        "CODEX_WORKER_MODEL_EXECUTION_VALUE": "gpt-5",
+        "GEMINI_WORKER_MODEL": "gemini-2.5-pro",
+        "GEMINI_WORKER_MODEL_EXECUTION_VALUE": "gemini-2.5-pro",
+        "REPORT_WRITER_MODEL": "claude-haiku-4-5",
+        "REPORT_WRITER_MODEL_EXECUTION_VALUE": "claude-haiku-4-5",
+        # selection
+        "RECOMMENDED_ANALYSERS": "claude,codex,gemini",
+    }
+
+
+def test_launch_template_all_tokens_resolved(tmp_path: Path):
+    ctx = _synthetic_ctx()
+    inject_lead_prompt_computed_tokens(ctx)
+
+    out = tmp_path / "claude-execution-prompt.md"
+    render_template_with_ctx(str(LAUNCH_TEMPLATE), str(out), ctx)
+
+    text = out.read_text(encoding="utf-8")
+    leftovers = sorted(set(TOKEN_RE.findall(text)))
+    assert not leftovers, f"unresolved tokens in rendered template: {leftovers}"
+
+
+def test_launch_template_release_handoff_renders(tmp_path: Path):
+    """release-handoff 는 single-lead — worker 없이도 렌더돼야 함."""
+    ctx = _synthetic_ctx(task_type="release-handoff")
+    ctx["RECOMMENDED_ANALYSERS"] = ""
+    inject_lead_prompt_computed_tokens(ctx)
+
+    out = tmp_path / "claude-execution-prompt.md"
+    render_template_with_ctx(str(LAUNCH_TEMPLATE), str(out), ctx)
+
+    text = out.read_text(encoding="utf-8")
+    assert "Single-Lead Phase" in text
+    leftovers = sorted(set(TOKEN_RE.findall(text)))
+    assert not leftovers, f"unresolved tokens: {leftovers}"
+
+
+def test_launch_template_fails_with_missing_token(tmp_path: Path):
+    ctx = _synthetic_ctx()
+    inject_lead_prompt_computed_tokens(ctx)
+    del ctx["TASK_KEY"]   # 강제 누락
+
+    out = tmp_path / "x.md"
+    with pytest.raises(RenderError) as exc:
+        render_template_with_ctx(str(LAUNCH_TEMPLATE), str(out), ctx)
+    assert "TASK_KEY" in str(exc.value)
+```
+
+- [ ] **Step 2: 테스트 실행 — 일부 실패 가능**
+
+```bash
+python3 -m pytest tests/test_lead_prompt_token_resolution.py -v
+```
+
+Expected: `test_launch_template_fails_with_missing_token` 은 PASS. 나머지 두 테스트는 `_synthetic_ctx()` 가 템플릿 토큰을 완전히 커버하면 PASS. 만약 FAIL 시 — 에러 메시지가 짚는 토큰을 `_synthetic_ctx()` 에 추가. inject 의 compute 항목이거나 frontmatter overlay 가 채우는 항목이면 추가 불요 (이미 채워짐).
+
+- [ ] **Step 3: synthetic_ctx 보강 후 테스트 통과 확인**
+
+```bash
+python3 -m pytest tests/test_lead_prompt_token_resolution.py -v
+```
+Expected: 3 PASS.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add tests/test_lead_prompt_token_resolution.py
+git commit -m "test(render): static gate — launch.template.md token resolution"
+```
+
+---
+
+## Task 5: caller 전환 + 옛 `render_template_file` 제거
+
+**Files:**
+- Modify: `scripts/okstra_ctl/render.py` — 옛 `render_template_file` 제거, CLI dispatcher 의 `template` subcommand 가 새 함수 사용
+- Modify: `scripts/okstra_ctl/run.py` — lead prompt 렌더 호출 교체
+
+- [ ] **Step 1: run.py 의 lead-prompt 렌더 caller 교체**
+
+`scripts/okstra_ctl/run.py:778` 부근:
+
+```python
+# 변경 전
+render_template_file(
+    str(prompt_template), str(instruction_set / "claude-execution-prompt.md"), ctx,
+)
+
+# 변경 후
+inject_lead_prompt_computed_tokens(ctx)
+render_template_with_ctx(
+    str(prompt_template), str(instruction_set / "claude-execution-prompt.md"), ctx,
+)
+```
+
+상단 import:
+
+```python
+from .render import (
+    ...,
+    inject_lead_prompt_computed_tokens,
+    render_template_with_ctx,
+)
+```
+
+`render_template_file` import 가 다른 곳에서 쓰이지 않는다면 제거. `final_report_template` 렌더 호출 (`run.py:775`) 은 그대로 — 그 템플릿은 Jinja2 `{{ var }}` (스페이스 있음) 사용이라 `_TOKEN_RE` 와 매치 안 됨. `render_template_with_ctx` 로 교체해도 동작은 동일 (regex 가 매치 안 하면 leftover 도 없음 → 통과). SOT 일관성을 위해 함께 교체 권장:
+
+```python
+inject_lead_prompt_computed_tokens(ctx)   # 위에서 이미 호출했다면 idempotent — 중복 호출 OK
+render_template_with_ctx(
+    str(final_report_template), ctx["FINAL_REPORT_TEMPLATE_PATH"], ctx,
+)
+```
+
+- [ ] **Step 2: render.py — CLI dispatcher 갱신**
+
+`scripts/okstra_ctl/render.py` 의 `template` subcommand:
+
+```python
+# 변경 전
+elif sub == "template":
+    ctx_path, template_path, output_path = rest
+    render_template_file(template_path, output_path, _load_ctx(ctx_path))
+
+# 변경 후
+elif sub == "template":
+    ctx_path, template_path, output_path = rest
+    ctx = _load_ctx(ctx_path)
+    inject_lead_prompt_computed_tokens(ctx)
+    render_template_with_ctx(template_path, output_path, ctx)
+```
+
+- [ ] **Step 3: 옛 `render_template_file` 제거**
+
+`render_template_file` 함수 전체 삭제. 미사용 import 정리.
+
+```bash
+grep -rnE '\brender_template_file\b' scripts/ tests/
+```
+Expected: 0 hits.
+
+- [ ] **Step 4: 전체 회귀 통과**
+
+```bash
+python3 -m pytest tests/ -x
+```
+Expected: PASS.
+
+- [ ] **Step 5: smoke run**
+
+```bash
+node bin/okstra --version
+node bin/okstra doctor
+```
+Expected: 성공.
+
+```bash
+bash tests-e2e/scenario-01-record-start-reconcile.sh
+```
+Expected: PASS — 시나리오가 lead prompt 렌더에 도달하면 새 함수가 통과.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add scripts/okstra_ctl/render.py scripts/okstra_ctl/run.py
+git commit -m "refactor(render): drop legacy render_template_file; lead prompt uses render_template_with_ctx"
+```
+
+---
+
+## Task 6: E2E grep 게이트 추가
+
+**Files:**
+- Modify: `tests-e2e/scenario-01-record-start-reconcile.sh` (가장 일반적 phase 한 개에 한정)
+
+렌더된 `claude-execution-prompt.md` 에 미치환 `{{...}}` 가 없는지 e2e 레벨에서도 확인.
+
+- [ ] **Step 1: 시나리오의 변수 흐름 확인**
+
+```bash
+grep -nE 'INSTRUCTION_SET|claude-execution-prompt' tests-e2e/scenario-01-record-start-reconcile.sh
+```
+이 결과로 시나리오가 어떤 변수에 instruction-set 경로를 담는지 (예: `INSTRUCTION_SET_DIR`, `TASK_ROOT`) 확인.
+
+- [ ] **Step 2: scenario 끝부분에 grep 게이트 추가**
+
+`tests-e2e/scenario-01-record-start-reconcile.sh` 의 task bundle 생성 직후 (예: `okstra render-bundle ... --render-only` 호출 직후) 다음 블록 추가 (`<INSTRUCTION_SET_VAR>` 는 Step 1 에서 식별된 시나리오 변수로 대체):
+
+```bash
+# Lead prompt token resolution gate — `{{TOKEN}}` 잔여 0 검증
+LEAD_PROMPT=$(find "$<INSTRUCTION_SET_VAR>" -name 'claude-execution-prompt.md' -type f | head -1)
+if [ -z "$LEAD_PROMPT" ]; then
+  echo "FAIL: lead prompt not rendered" >&2
+  exit 1
+fi
+if grep -nE '\{\{[A-Z_]+\}\}' "$LEAD_PROMPT"; then
+  echo "FAIL: unresolved tokens in $LEAD_PROMPT" >&2
+  exit 1
+fi
+```
+
+- [ ] **Step 3: 시나리오 실행**
+
+```bash
+bash tests-e2e/scenario-01-record-start-reconcile.sh
+```
+Expected: PASS — 게이트가 통과.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add tests-e2e/scenario-01-record-start-reconcile.sh
+git commit -m "test(e2e): assert lead prompt has no unresolved tokens"
+```
+
+---
+
+## Task 7: CHANGES.md + npm build 확인
+
+**Files:**
+- Modify: `CHANGES.md`
+
+- [ ] **Step 1: CHANGES.md 항목 추가**
+
+`CHANGES.md` 의 최상단 (또는 진행 중 섹션) 에:
+
+```markdown
+### Lead prompt 토큰 SOT 단일화 (2026-05-20)
+
+- `claude-execution-prompt.md` 의 `{{TOKEN}}` 들이 `prompts/launch.template.md` 단독 권위가 되도록 변경.
+- `scripts/okstra_ctl/render.py` 의 hand-maintained mapping dict 제거. ctx 키 = 토큰 명 정합화 (`*_FILE`/`*_DIR`/`*_SCRIPT` → `*_PATH`, `*_DISPLAY` 접미사 제거, `ANALYSIS_TYPE`/`REVIEW_PROFILE`/`SELECTED_REVIEWERS` 통일).
+- 누락 시 `RenderError` 로 fail-fast — silent drift 차단.
+- 사용자 영향: 없음 (산출물 동일). 컨트리뷰터 영향: 새 토큰 추가 시 `prompts/launch.template.md` + ctx 빌드 함수 (`paths.py` / `run.py` / `render.py` `inject_lead_prompt_computed_tokens`) 만 손대면 됨 (이전엔 mapping dict 도 같이).
+```
+
+- [ ] **Step 2: npm build smoke**
+
+```bash
+npm run build
+```
+Expected: `runtime/` 가 최신 source 와 동기화됨. 에러 없음.
+
+- [ ] **Step 3: 최종 회귀**
+
+```bash
+python3 -m pytest tests/ -v
+bash validators/validate-workflow.sh
+bash tests-e2e/scenario-01-record-start-reconcile.sh
+```
+Expected: 전부 PASS.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add CHANGES.md
+git commit -m "docs(changes): note lead-prompt token SOT unification"
+```
+
+---
+
+## Self-Review 체크리스트
+
+- [x] **Spec coverage**: design 문서 §2 (Phase B1) 의 모든 항목이 task 로 포함 — 2.1 토큰 카테고리 (Task 2: C3/C4 분리), 2.2 ctx 키 rename (Task 1), 2.3 데이터 흐름 (Task 2+3+5), 2.4 변경 파일 (Task 2·3·5), 2.5 검증 (Task 2·3·4·6), 2.6 마이그레이션 순서 (1→2→3→4→5→6→7), 2.7 실패모드 (Task 3 의 RenderError 테스트), 2.8 롤백 (각 task 가 별 commit — atomic revert).
+- [x] **Placeholder scan**: TBD/TODO 없음. 모든 step 에 실제 명령·코드·grep 패턴 명시. Task 6 의 `<INSTRUCTION_SET_VAR>` 은 시나리오 스크립트 grep 결과로 채우는 명시적 슬롯 (placeholder 가 아니라 lookup 지시).
+- [x] **Type consistency**: `inject_lead_prompt_computed_tokens(ctx) -> None` / `render_template_with_ctx(template, output, ctx) -> None` / `RenderError(Exception)` — 모든 task 에서 동일 시그니처 사용.
+- [x] **Atomic rename**: Task 1 한 commit (Step 2~10) 로 모든 caller 동시 변경. caller 가 새 키로 ctx 쓰기 시작하므로 옛 키 잔존 위험 없음. Task 2 이후의 inject() 함수는 처음부터 새 키를 읽음.
+- [x] **Task 순서 정합성**: rename 먼저 → inject 분리 → 새 렌더러 추가 → 정적 게이트 → caller 전환 → e2e → docs. 각 task 의 작업 commit 후에도 시스템 동작 동일성 유지 (Task 5 까지) 또는 산출물 동일 (전 task).
+
+---
+
+## 실행 옵션
+
+Plan complete and saved to [docs/superpowers/plans/2026-05-20-okstra-run-prompt-sot-b1.md](docs/superpowers/plans/2026-05-20-okstra-run-prompt-sot-b1.md). 두 가지 실행 방식:
+
+1. **Subagent-Driven (recommended)** — task 마다 새로운 subagent 가 들어가 작업, task 사이에서 review, 빠른 iteration
+2. **Inline Execution** — 본 세션 안에서 executing-plans 로 batch 실행, checkpoint 마다 review
+
+어떤 방식으로 진행할까요?