okstra 0.34.1 → 0.36.1

package/runtime/python/okstra_ctl/render.py

@@ -22,6 +22,16 @@ import re
 import sys
 from pathlib import Path
 
+
+class TokenRenderError(Exception):
+    """Raised when a template references a `{{TOKEN}}` not present in ctx.
+
+    Specific to the pure-token renderer in this module. Distinct from
+    `okstra_ctl.render_final_report.FinalReportRenderError` which wraps
+    jinja2 / IO failures during final-report rendering.
+    """
+
+
 # --------------------------------------------------------------------------- #
 # helpers
 # --------------------------------------------------------------------------- #
@@ -152,9 +162,7 @@ def _frontmatter_mapping(ctx: dict) -> dict:
     task_key = (ctx.get("TASK_KEY") or "").strip()
     task_date = (ctx.get("TASK_DATE") or "").strip()
     doc_type = (ctx.get("DOC_TYPE") or "").strip()
-    # task_type 은 ctx 키가 두 곳에 분포 — 직접 키(`TASK_TYPE`), 또는
-    # `ANALYSIS_TYPE` fallback (workflow 의 render mapping 과 동일 우선순위).
-    task_type = (ctx.get("TASK_TYPE") or ctx.get("ANALYSIS_TYPE") or "").strip()
+    task_type = (ctx.get("TASK_TYPE") or "").strip()
 
     fm_id = _frontmatter_id_from_task_key(task_key)
     fm_id_scalar = f'"{fm_id}"' if fm_id else f'"{_FM_DEFAULT}"'
@@ -179,7 +187,7 @@ def _frontmatter_mapping(ctx: dict) -> dict:
 
 def _resolve_workers(ctx: dict) -> list[str]:
     return [
-        w.strip() for w in ctx.get("SELECTED_REVIEWERS", "").split(",") if w.strip()
+        w.strip() for w in ctx.get("RECOMMENDED_ANALYSERS", "").split(",") if w.strip()
     ]
 
 
@@ -190,7 +198,7 @@ def _worker_catalog(ctx: dict) -> dict:
             "role": "Claude worker",
             "agent": "claude",
             "agentLabel": "Claude Code",
-            "model": ctx.get("CLAUDE_WORKER_MODEL_DISPLAY", ""),
+            "model": ctx.get("CLAUDE_WORKER_MODEL", ""),
             "modelExecutionValue": ctx.get("CLAUDE_WORKER_MODEL_EXECUTION_VALUE", ""),
             "resultPath": ctx.get("CLAUDE_WORKER_RESULT_RELATIVE_PATH", ""),
             "promptPath": ctx.get("CLAUDE_WORKER_PROMPT_RELATIVE_PATH", ""),
@@ -200,7 +208,7 @@ def _worker_catalog(ctx: dict) -> dict:
             "role": "Codex worker",
             "agent": "codex",
             "agentLabel": "Codex",
-            "model": ctx.get("CODEX_WORKER_MODEL_DISPLAY", ""),
+            "model": ctx.get("CODEX_WORKER_MODEL", ""),
             "modelExecutionValue": ctx.get("CODEX_WORKER_MODEL_EXECUTION_VALUE", ""),
             "resultPath": ctx.get("CODEX_WORKER_RESULT_RELATIVE_PATH", ""),
             "promptPath": ctx.get("CODEX_WORKER_PROMPT_RELATIVE_PATH", ""),
@@ -210,7 +218,7 @@ def _worker_catalog(ctx: dict) -> dict:
             "role": "Gemini worker",
             "agent": "gemini",
             "agentLabel": "Gemini",
-            "model": ctx.get("GEMINI_WORKER_MODEL_DISPLAY", ""),
+            "model": ctx.get("GEMINI_WORKER_MODEL", ""),
             "modelExecutionValue": ctx.get("GEMINI_WORKER_MODEL_EXECUTION_VALUE", ""),
             "resultPath": ctx.get("GEMINI_WORKER_RESULT_RELATIVE_PATH", ""),
             "promptPath": ctx.get("GEMINI_WORKER_PROMPT_RELATIVE_PATH", ""),
@@ -220,7 +228,7 @@ def _worker_catalog(ctx: dict) -> dict:
             "role": "Report writer worker",
             "agent": "claude",
             "agentLabel": "Claude Code",
-            "model": ctx.get("REPORT_WRITER_MODEL_DISPLAY", ""),
+            "model": ctx.get("REPORT_WRITER_MODEL", ""),
             "modelExecutionValue": ctx.get("REPORT_WRITER_MODEL_EXECUTION_VALUE", ""),
             "resultPath": ctx.get("REPORT_WRITER_WORKER_RESULT_RELATIVE_PATH", ""),
             "promptPath": ctx.get("REPORT_WRITER_WORKER_PROMPT_RELATIVE_PATH", ""),
@@ -255,13 +263,13 @@ def render_team_state(team_state_path: str, ctx: dict) -> None:
     payload = {
         "schemaVersion": "1.0",
         "taskKey": ctx.get("TASK_KEY", ""),
-        "taskType": ctx.get("ANALYSIS_TYPE", ""),
+        "taskType": ctx.get("TASK_TYPE", ""),
         "runDirectoryPath": ctx.get("RUN_DIR_RELATIVE_PATH", ""),
         "workflowState": ctx.get("CURRENT_RUN_STATUS", ""),
         "lead": {
             "role": "Claude lead",
             "agent": "claude",
-            "model": ctx.get("LEAD_MODEL_DISPLAY", ""),
+            "model": ctx.get("LEAD_MODEL", ""),
             "modelExecutionValue": ctx.get("LEAD_MODEL_EXECUTION_VALUE", ""),
             "status": ctx.get("CURRENT_RUN_STATUS", ""),
             "sessionId": ctx.get("CLAUDE_SESSION_ID", ""),
@@ -311,7 +319,7 @@ def render_reference_expectations(brief_path: str, output_path: str, ctx: dict)
         "# Task Reference Expectations",
         "",
         f"- Task Key: `{ctx.get('TASK_KEY', '')}`",
-        f"- Task Type: `{ctx.get('ANALYSIS_TYPE', '')}`",
+        f"- Task Type: `{ctx.get('TASK_TYPE', '')}`",
         f"- Source brief snapshot: `{brief_relative}`",
         "",
         "## Usage Rules",
@@ -457,7 +465,7 @@ def render_task_catalog_discovery(output_path: str, ctx: dict) -> None:
 
 
 def render_latest_task_discovery(output_path: str, ctx: dict) -> None:
-    task_manifest_path = Path(ctx.get("TASK_MANIFEST_FILE", ""))
+    task_manifest_path = Path(ctx.get("TASK_MANIFEST_PATH", ""))
     task_manifest = {}
     if task_manifest_path.exists():
         try:
@@ -473,7 +481,7 @@ def render_latest_task_discovery(output_path: str, ctx: dict) -> None:
         "schemaVersion": "1.0",
         "updatedAt": ctx.get("RUN_TIMESTAMP_ISO", ""),
         "taskKey": ctx.get("TASK_KEY", ""),
-        "taskType": ctx.get("ANALYSIS_TYPE", ""),
+        "taskType": ctx.get("TASK_TYPE", ""),
         "workCategory": task_manifest.get(
             "workCategory", ctx.get("WORKFLOW_WORK_CATEGORY", "unknown")
         ),
@@ -633,7 +641,7 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
         if isinstance(workflow.get("phaseStates"), dict)
         else {}
     )
-    current_phase = ctx.get("WORKFLOW_CURRENT_PHASE", ctx.get("ANALYSIS_TYPE", ""))
+    current_phase = ctx.get("WORKFLOW_CURRENT_PHASE", ctx.get("TASK_TYPE", ""))
     current_phase_state = ctx.get("WORKFLOW_CURRENT_PHASE_STATE", "not-started")
     for phase in phase_sequence:
         phase_states.setdefault(phase, "not-started")
@@ -643,15 +651,25 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
         "WORKFLOW_WORK_CATEGORY", "unknown"
     )
     # Compute the canonical next phase from current_phase deterministically.
-    # Only preserve `existing.workflow.nextRecommendedPhase` when it is a
-    # legitimate forward pointer — i.e. NOT equal to `current_phase` itself
-    # (which would mean the lifecycle pointer has stalled on the current
-    # phase and would loop forever).
+    # Only advance past `current_phase` when its state is terminal-success
+    # (`completed`). For `prepared` / `in-progress` / `blocked` / `error` /
+    # `contract-violated` states the recommendation MUST stay on
+    # `current_phase` — advancing prematurely makes wizards (and humans)
+    # think the current phase is done when it has merely been provisioned.
+    # Historical bug: implementation provisioned in `prepared` state caused
+    # the wizard to recommend `final-verification` as the default task_type.
     canonical_next = default_next_phase.get(
         current_phase, ctx.get("WORKFLOW_NEXT_RECOMMENDED_PHASE", "unknown")
     )
     existing_next = workflow.get("nextRecommendedPhase") or ""
-    if existing_next and existing_next != current_phase:
+    terminal_success_states = {"completed"}
+    if current_phase_state not in terminal_success_states:
+        # Current phase has not finished — recommend staying on it. Suppress
+        # any stale `existing_next` that points further forward in the
+        # sequence; only honour a stale value if it points to the SAME
+        # current_phase (i.e. encodes "re-enter current phase").
+        next_recommended_phase = current_phase
+    elif existing_next and existing_next != current_phase:
         next_recommended_phase = existing_next
     else:
         next_recommended_phase = canonical_next
@@ -746,7 +764,7 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
         "taskGroupPathSegment": ctx.get("TASK_GROUP_SEGMENT", ""),
         "taskIdPathSegment": ctx.get("TASK_ID_SEGMENT", ""),
         "projectRoot": ctx.get("PROJECT_ROOT", ""),
-        "taskType": ctx.get("ANALYSIS_TYPE", ""),
+        "taskType": ctx.get("TASK_TYPE", ""),
         "workCategory": work_category,
         "taskBriefPath": ctx.get("BRIEF_RELATIVE_PATH", ""),
         "recommendedWorkers": reviewers,
@@ -807,7 +825,7 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
         "resultContract": {
             "leadAgent": "claude",
             "leadRole": "Claude lead",
-            "leadModel": ctx.get("LEAD_MODEL_DISPLAY", ""),
+            "leadModel": ctx.get("LEAD_MODEL", ""),
             "leadModelExecutionValue": ctx.get("LEAD_MODEL_EXECUTION_VALUE", ""),
             "leadExecutionMode": "synthesis-only",
             "finalSynthesisOwner": "Claude lead",
@@ -890,7 +908,7 @@ def _build_convergence_block(ctx: dict) -> dict:
     - `OKSTRA_PLAN_VERIFICATION`: "true" | "false" | "" (empty → default True).
       Wired from CLI `--no-plan-verification` (sets "false").
     """
-    task_type = ctx.get("ANALYSIS_TYPE", "")
+    task_type = ctx.get("TASK_TYPE", "")
     default_max_rounds = 1 if task_type == "requirements-discovery" else 2
     raw_plan_verify = (ctx.get("OKSTRA_PLAN_VERIFICATION", "") or "").strip().lower()
     plan_verify_enabled = raw_plan_verify != "false"
@@ -907,7 +925,7 @@ def _build_convergence_block(ctx: dict) -> dict:
 
 
 def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
-    task_manifest_path = Path(ctx.get("TASK_MANIFEST_FILE", ""))
+    task_manifest_path = Path(ctx.get("TASK_MANIFEST_PATH", ""))
     task_manifest = {}
     if task_manifest_path.exists():
         try:
@@ -931,7 +949,7 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
         "taskGroup": ctx.get("TASK_GROUP", ""),
         "taskId": ctx.get("TASK_ID", ""),
         "taskKey": ctx.get("TASK_KEY", ""),
-        "taskType": ctx.get("ANALYSIS_TYPE", ""),
+        "taskType": ctx.get("TASK_TYPE", ""),
         "workCategory": task_manifest.get(
             "workCategory", ctx.get("WORKFLOW_WORK_CATEGORY", "unknown")
         ),
@@ -995,7 +1013,7 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
         "teamContract": {
             "leadAgent": "claude",
             "leadRole": "Claude lead",
-            "leadModel": ctx.get("LEAD_MODEL_DISPLAY", ""),
+            "leadModel": ctx.get("LEAD_MODEL", ""),
             "leadModelExecutionValue": ctx.get("LEAD_MODEL_EXECUTION_VALUE", ""),
             "leadExecutionMode": "synthesis-only",
             "finalSynthesisOwner": "Claude lead",
@@ -1034,7 +1052,7 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
 
 
 def render_timeline(timeline_path: str, ctx: dict) -> None:
-    task_manifest_path = Path(ctx.get("TASK_MANIFEST_FILE", ""))
+    task_manifest_path = Path(ctx.get("TASK_MANIFEST_PATH", ""))
     task_manifest = {}
     if task_manifest_path.exists():
         try:
@@ -1056,7 +1074,7 @@ def render_timeline(timeline_path: str, ctx: dict) -> None:
         except Exception:
             existing = {}
     runs = existing.get("runs", [])
-    current_run_manifest_path = ctx.get("RUN_MANIFEST_FILE", "")
+    current_run_manifest_path = ctx.get("RUN_MANIFEST_PATH", "")
     current_run_manifest_relative_path = ctx.get("RUN_MANIFEST_RELATIVE_PATH", "")
     filtered = [
         item
@@ -1085,7 +1103,7 @@ def render_timeline(timeline_path: str, ctx: dict) -> None:
                 "sessions": ctx.get("RUN_SESSIONS_SEQ", ""),
                 "workerResults": ctx.get("WORKER_RESULTS_SEQ", ""),
             },
-            "taskType": ctx.get("ANALYSIS_TYPE", ""),
+            "taskType": ctx.get("TASK_TYPE", ""),
             "workCategory": task_manifest.get(
                 "workCategory", ctx.get("WORKFLOW_WORK_CATEGORY", "unknown")
             ),
@@ -1127,7 +1145,7 @@ def render_timeline(timeline_path: str, ctx: dict) -> None:
 
 def render_task_index(template_path: str, output_path: str, ctx: dict) -> None:
     template = Path(template_path).read_text(encoding="utf-8")
-    task_manifest_path = Path(ctx["TASK_MANIFEST_FILE"])
+    task_manifest_path = Path(ctx["TASK_MANIFEST_PATH"])
     task_manifest = {}
     if task_manifest_path.exists():
         try:
@@ -1187,7 +1205,7 @@ def render_task_index(template_path: str, output_path: str, ctx: dict) -> None:
     )
     mapping = {
         "{{TASK_KEY}}": task_manifest.get("taskKey", ctx.get("TASK_KEY", "")),
-        "{{TASK_TYPE}}": task_manifest.get("taskType", ctx.get("ANALYSIS_TYPE", "")),
+        "{{TASK_TYPE}}": task_manifest.get("taskType", ctx.get("TASK_TYPE", "")),
         "{{TASK_DATE}}": ctx.get("TASK_DATE", ""),
         "{{PROJECT_ID}}": ctx.get("PROJECT_ID", ""),
         "{{TASK_GROUP}}": ctx.get("TASK_GROUP", ""),
@@ -1202,7 +1220,7 @@ def render_task_index(template_path: str, output_path: str, ctx: dict) -> None:
         "{{RECOMMENDED_ANALYSERS}}": ", ".join(
             task_manifest.get("recommendedWorkers", [])
         ),
-        "{{LEAD_MODEL}}": rc.get("leadModel", ctx.get("LEAD_MODEL_DISPLAY", "")),
+        "{{LEAD_MODEL}}": rc.get("leadModel", ctx.get("LEAD_MODEL", "")),
         "{{OKSTRA_VERSION}}": ctx.get("OKSTRA_VERSION", ""),
         "{{LATEST_RUN_RELATIVE_PATH}}": task_manifest.get(
             "latestRunPath", ctx.get("LATEST_RUN_RELATIVE_PATH", "")
@@ -1222,11 +1240,11 @@ def render_task_index(template_path: str, output_path: str, ctx: dict) -> None:
         ),
         "{{MODEL_ASSIGNMENT_LINES}}": "\n".join(
             [
-                f"- `Claude lead`: `{rc.get('leadModel', ctx.get('LEAD_MODEL_DISPLAY', ''))}`",
-                f"- `Claude worker`: `{ctx.get('CLAUDE_WORKER_MODEL_DISPLAY', '')}`",
-                f"- `Codex worker`: `{ctx.get('CODEX_WORKER_MODEL_DISPLAY', '')}`",
-                f"- `Gemini worker`: `{ctx.get('GEMINI_WORKER_MODEL_DISPLAY', '')}`",
-                f"- `Report writer worker`: `{ctx.get('REPORT_WRITER_MODEL_DISPLAY', '')}`",
+                f"- `Claude lead`: `{rc.get('leadModel', ctx.get('LEAD_MODEL', ''))}`",
+                f"- `Claude worker`: `{ctx.get('CLAUDE_WORKER_MODEL', '')}`",
+                f"- `Codex worker`: `{ctx.get('CODEX_WORKER_MODEL', '')}`",
+                f"- `Gemini worker`: `{ctx.get('GEMINI_WORKER_MODEL', '')}`",
+                f"- `Report writer worker`: `{ctx.get('REPORT_WRITER_MODEL', '')}`",
             ]
         ),
         "{{TASK_MANIFEST_RELATIVE_PATH}}": task_manifest.get(
@@ -1291,7 +1309,7 @@ def render_task_index(template_path: str, output_path: str, ctx: dict) -> None:
     rendered = template
     for k, v in mapping.items():
         rendered = rendered.replace(k, v)
-    rendered = _strip_phase_blocks(rendered, ctx.get("ANALYSIS_TYPE", ""))
+    rendered = _strip_phase_blocks(rendered, ctx.get("TASK_TYPE", ""))
     _write_text(Path(output_path), rendered.rstrip() + "\n")
 
 
@@ -1355,11 +1373,24 @@ def build_available_mcp_servers_block(project_root: Path) -> str:
 # --------------------------------------------------------------------------- #
 
 
-def render_template_file(template_path: str, output_path: str, ctx: dict) -> None:
-    template = Path(template_path).read_text(encoding="utf-8")
+def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
+    """Populate ctx in-place with the 9 derived lead-prompt tokens.
+
+    Tokens that are not 1:1 with a ctx key (TEAM_CREATION_GATE,
+    WORKER_RESULT_PATH_LINES, TEAM_ROLE_LINES, MODEL_ASSIGNMENT_LINES,
+    REQUIRED_WORKER_ROLE_SENTENCE, GEMINI_ATTEMPT_SENTENCE,
+    PREFERRED_WORKER_RESULTS_SENTENCE, EXECUTION_STATUS_EXACT_ENTRIES,
+    EXECUTION_STATUS_TABLE_ROWS) are computed deterministically from ctx
+    so the pure-lookup renderer (`render_template_with_ctx`) can resolve
+    them via plain `ctx[token]` lookup.
+
+    Always overwrites — caller-supplied values for these 9 keys are replaced
+    on every call. For optional defaults (VALIDATION_STATUS etc.) use the
+    companion `apply_lead_prompt_defaults` which preserves caller values.
+    """
     selected = _resolve_workers(ctx)
     catalog = _worker_catalog(ctx)
-    lead_model = ctx.get("LEAD_MODEL_DISPLAY", "")
+    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:
@@ -1367,12 +1398,12 @@ def render_template_file(template_path: str, output_path: str, ctx: dict) -> Non
             return f"- `{role}`: `{model}` (launch value: `{execution}`)"
         return f"- `{role}`: `{model}`"
 
-    worker_result_lines = []
+    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 = []
+    worker_role_labels: list[str] = []
     execution_status_entries = ["`Claude lead`"]
     execution_status_table_lines = [
         "| 에이전트 | 역할 | 모델 | 상태 | 핵심 발견 요약 |",
@@ -1424,7 +1455,7 @@ def render_template_file(template_path: str, output_path: str, ctx: dict) -> Non
     #   selected) is single-lead and MUST NOT call `TeamCreate`. Emit a
     #   short notice instead of the BLOCKING gate.
     # - All other phases keep the full team-creation contract.
-    task_type = ctx.get("ANALYSIS_TYPE", "")
+    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"
@@ -1466,172 +1497,97 @@ def render_template_file(template_path: str, output_path: str, ctx: dict) -> Non
             "response is to go back to step 2 — NOT to strip `team_name` and retry."
         )
 
-    mapping = {
-        "{{TEAM_CREATION_GATE}}": team_creation_gate_block,
-        "{{TASK_TYPE}}": ctx.get("ANALYSIS_TYPE", ""),
-        "{{ANALYSIS_PROFILE}}": ctx.get("REVIEW_PROFILE", ""),
-        "{{ANALYSIS_TYPE}}": ctx.get("ANALYSIS_TYPE", ""),
-        "{{RECOMMENDED_ANALYSERS}}": ctx.get("SELECTED_REVIEWERS", ""),
-        "{{PROJECT_ROOT}}": ctx.get("PROJECT_ROOT", ""),
-        "{{BRIEF_RELATIVE_PATH}}": ctx.get("BRIEF_RELATIVE_PATH", ""),
-        "{{BRIEF_FILE_PATH}}": ctx.get("BRIEF_FILE_PATH", ""),
-        "{{CLARIFICATION_RESPONSE_PATH}}": ctx.get("CLARIFICATION_RESPONSE_FILE", ""),
-        "{{CLARIFICATION_RESPONSE_RELATIVE_PATH}}": ctx.get(
-            "CLARIFICATION_RESPONSE_RELATIVE_PATH", ""
-        ),
-        "{{RUN_DIR}}": ctx.get("RUN_DIR", ""),
-        "{{RUN_DIR_RELATIVE_PATH}}": ctx.get("RUN_DIR_RELATIVE_PATH", ""),
-        "{{RUN_MANIFESTS_RELATIVE_PATH}}": ctx.get("RUN_MANIFESTS_RELATIVE_PATH", ""),
-        "{{RUN_STATE_RELATIVE_PATH}}": ctx.get("RUN_STATE_RELATIVE_PATH", ""),
-        "{{RUN_PROMPTS_RELATIVE_PATH}}": ctx.get("RUN_PROMPTS_RELATIVE_PATH", ""),
-        "{{RUN_REPORTS_RELATIVE_PATH}}": ctx.get("RUN_REPORTS_RELATIVE_PATH", ""),
-        "{{RUN_STATUS_RELATIVE_PATH}}": ctx.get("RUN_STATUS_RELATIVE_PATH", ""),
-        "{{RUN_SESSIONS_RELATIVE_PATH}}": ctx.get("RUN_SESSIONS_RELATIVE_PATH", ""),
-        "{{TASK_ROOT}}": ctx.get("TASK_ROOT", ""),
-        "{{TASK_MANIFEST_PATH}}": ctx.get("TASK_MANIFEST_FILE", ""),
-        "{{TASK_INDEX_PATH}}": ctx.get("TASK_INDEX_FILE", ""),
-        "{{INSTRUCTION_SET_PATH}}": ctx.get("INSTRUCTION_SET_DIR", ""),
-        "{{RUN_MANIFEST_PATH}}": ctx.get("RUN_MANIFEST_FILE", ""),
-        "{{RUN_MANIFEST_RELATIVE_PATH}}": ctx.get("RUN_MANIFEST_RELATIVE_PATH", ""),
-        "{{TIMELINE_PATH}}": ctx.get("TIMELINE_FILE", ""),
-        "{{RUN_TIMESTAMP_ISO}}": ctx.get("RUN_TIMESTAMP_ISO", ""),
-        "{{FINAL_REPORT_PATH}}": ctx.get("FINAL_REPORT_FILE", ""),
-        "{{FINAL_REPORT_RELATIVE_PATH}}": ctx.get("FINAL_REPORT_RELATIVE_PATH", ""),
-        "{{FINAL_STATUS_PATH}}": ctx.get("FINAL_STATUS_FILE", ""),
-        "{{FINAL_STATUS_RELATIVE_PATH}}": ctx.get("FINAL_STATUS_RELATIVE_PATH", ""),
-        "{{TEAM_STATE_PATH}}": ctx.get("TEAM_STATE_FILE", ""),
-        "{{TEAM_STATE_RELATIVE_PATH}}": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
-        "{{WORKER_RESULTS_PATH}}": ctx.get("WORKER_RESULTS_DIR", ""),
-        "{{WORKER_RESULTS_RELATIVE_PATH}}": ctx.get("WORKER_RESULTS_RELATIVE_PATH", ""),
-        "{{RUN_VALIDATOR_PATH}}": ctx.get("RUN_VALIDATOR_SCRIPT", ""),
-        "{{RUN_VALIDATOR_RELATIVE_PATH}}": ctx.get("RUN_VALIDATOR_RELATIVE_PATH", ""),
-        "{{CLAUDE_WORKER_RESULT_RELATIVE_PATH}}": ctx.get(
-            "CLAUDE_WORKER_RESULT_RELATIVE_PATH", ""
-        ),
-        "{{CODEX_WORKER_RESULT_RELATIVE_PATH}}": ctx.get(
-            "CODEX_WORKER_RESULT_RELATIVE_PATH", ""
-        ),
-        "{{GEMINI_WORKER_RESULT_RELATIVE_PATH}}": ctx.get(
-            "GEMINI_WORKER_RESULT_RELATIVE_PATH", ""
-        ),
-        "{{REPORT_WRITER_WORKER_RESULT_RELATIVE_PATH}}": ctx.get(
-            "REPORT_WRITER_WORKER_RESULT_RELATIVE_PATH", ""
-        ),
-        "{{RUN_ERRORS_LOG_PATH}}": ctx.get("RUN_ERRORS_LOG_FILE", ""),
-        "{{RUN_ERRORS_LOG_RELATIVE_PATH}}": ctx.get("RUN_ERRORS_LOG_RELATIVE_PATH", ""),
-        "{{CLAUDE_WORKER_ERRORS_SIDECAR_PATH}}": ctx.get(
-            "CLAUDE_WORKER_ERRORS_SIDECAR_FILE", ""
-        ),
-        "{{CLAUDE_WORKER_ERRORS_SIDECAR_RELATIVE_PATH}}": ctx.get(
-            "CLAUDE_WORKER_ERRORS_SIDECAR_RELATIVE_PATH", ""
-        ),
-        "{{CODEX_WORKER_ERRORS_SIDECAR_PATH}}": ctx.get(
-            "CODEX_WORKER_ERRORS_SIDECAR_FILE", ""
-        ),
-        "{{CODEX_WORKER_ERRORS_SIDECAR_RELATIVE_PATH}}": ctx.get(
-            "CODEX_WORKER_ERRORS_SIDECAR_RELATIVE_PATH", ""
-        ),
-        "{{GEMINI_WORKER_ERRORS_SIDECAR_PATH}}": ctx.get(
-            "GEMINI_WORKER_ERRORS_SIDECAR_FILE", ""
-        ),
-        "{{GEMINI_WORKER_ERRORS_SIDECAR_RELATIVE_PATH}}": ctx.get(
-            "GEMINI_WORKER_ERRORS_SIDECAR_RELATIVE_PATH", ""
-        ),
-        "{{REPORT_WRITER_WORKER_ERRORS_SIDECAR_PATH}}": ctx.get(
-            "REPORT_WRITER_WORKER_ERRORS_SIDECAR_FILE", ""
-        ),
-        "{{REPORT_WRITER_WORKER_ERRORS_SIDECAR_RELATIVE_PATH}}": ctx.get(
-            "REPORT_WRITER_WORKER_ERRORS_SIDECAR_RELATIVE_PATH", ""
-        ),
-        "{{LEAD_MODEL}}": lead_model,
-        "{{LEAD_MODEL_EXECUTION_VALUE}}": lead_model_execution,
-        "{{OKSTRA_VERSION}}": ctx.get("OKSTRA_VERSION", ""),
-        "{{CLAUDE_WORKER_MODEL}}": ctx.get("CLAUDE_WORKER_MODEL_DISPLAY", ""),
-        "{{CLAUDE_WORKER_MODEL_EXECUTION_VALUE}}": ctx.get(
-            "CLAUDE_WORKER_MODEL_EXECUTION_VALUE", ""
-        ),
-        "{{CODEX_WORKER_MODEL}}": ctx.get("CODEX_WORKER_MODEL_DISPLAY", ""),
-        "{{CODEX_WORKER_MODEL_EXECUTION_VALUE}}": ctx.get(
-            "CODEX_WORKER_MODEL_EXECUTION_VALUE", ""
-        ),
-        "{{GEMINI_WORKER_MODEL}}": ctx.get("GEMINI_WORKER_MODEL_DISPLAY", ""),
-        "{{GEMINI_WORKER_MODEL_EXECUTION_VALUE}}": ctx.get(
-            "GEMINI_WORKER_MODEL_EXECUTION_VALUE", ""
-        ),
-        "{{REPORT_WRITER_MODEL}}": ctx.get("REPORT_WRITER_MODEL_DISPLAY", ""),
-        "{{REPORT_WRITER_MODEL_EXECUTION_VALUE}}": ctx.get(
-            "REPORT_WRITER_MODEL_EXECUTION_VALUE", ""
-        ),
-        "{{WORKER_RESULT_PATH_LINES}}": "\n".join(worker_result_lines),
-        "{{MODEL_ASSIGNMENT_LINES}}": "\n".join(model_assignment_lines),
-        "{{TEAM_ROLE_LINES}}": "\n".join(team_role_lines),
-        "{{REQUIRED_WORKER_ROLE_SENTENCE}}": worker_role_sentence,
-        "{{GEMINI_ATTEMPT_SENTENCE}}": worker_attempt_sentence,
-        "{{PREFERRED_WORKER_RESULTS_SENTENCE}}": preferred_results_sentence,
-        "{{EXECUTION_STATUS_EXACT_ENTRIES}}": ", ".join(execution_status_entries),
-        "{{EXECUTION_STATUS_TABLE_ROWS}}": "\n".join(execution_status_table_lines),
-        "{{FINAL_REPORT_TEMPLATE_PATH}}": ctx.get("FINAL_REPORT_TEMPLATE_FILE", ""),
-        "{{FINAL_REPORT_TEMPLATE_RELATIVE_PATH}}": ctx.get(
-            "FINAL_REPORT_TEMPLATE_RELATIVE_PATH", ""
-        ),
-        "{{REFERENCE_EXPECTATIONS_RELATIVE_PATH}}": ctx.get(
-            "REFERENCE_EXPECTATIONS_RELATIVE_PATH", ""
-        ),
-        "{{CLAUDE_SESSION_ID}}": ctx.get("CLAUDE_SESSION_ID", ""),
-        "{{CLAUDE_RESUME_COMMAND_PATH}}": ctx.get("CLAUDE_RESUME_COMMAND_FILE", ""),
-        "{{CLAUDE_RESUME_COMMAND_RELATIVE_PATH}}": ctx.get(
-            "CLAUDE_RESUME_COMMAND_RELATIVE_PATH", ""
-        ),
-        "{{TASK_ROOT_RELATIVE_PATH}}": ctx.get("TASK_ROOT_RELATIVE_PATH", ""),
-        "{{TASK_MANIFEST_RELATIVE_PATH}}": ctx.get("TASK_MANIFEST_RELATIVE_PATH", ""),
-        "{{TASK_INDEX_RELATIVE_PATH}}": ctx.get("TASK_INDEX_RELATIVE_PATH", ""),
-        "{{INSTRUCTION_SET_RELATIVE_PATH}}": ctx.get(
-            "INSTRUCTION_SET_RELATIVE_PATH", ""
-        ),
-        "{{RUNS_RELATIVE_PATH}}": ctx.get("RUNS_RELATIVE_PATH", ""),
-        "{{HISTORY_RELATIVE_PATH}}": ctx.get("HISTORY_RELATIVE_PATH", ""),
-        "{{OKSTRA_DISCOVERY_RELATIVE_PATH}}": ctx.get(
-            "OKSTRA_DISCOVERY_RELATIVE_PATH", ""
-        ),
-        "{{OKSTRA_LATEST_TASK_RELATIVE_PATH}}": ctx.get(
-            "OKSTRA_LATEST_TASK_RELATIVE_PATH", ""
-        ),
-        "{{OKSTRA_TASK_CATALOG_RELATIVE_PATH}}": ctx.get(
-            "OKSTRA_TASK_CATALOG_RELATIVE_PATH", ""
-        ),
-        "{{LATEST_RUN_RELATIVE_PATH}}": ctx.get("LATEST_RUN_RELATIVE_PATH", ""),
-        "{{LATEST_REPORT_RELATIVE_PATH}}": ctx.get("LATEST_REPORT_RELATIVE_PATH", ""),
-        "{{TIMELINE_RELATIVE_PATH}}": ctx.get("TIMELINE_RELATIVE_PATH", ""),
-        "{{CURRENT_TASK_STATUS}}": ctx.get("CURRENT_TASK_STATUS", ""),
-        "{{CURRENT_RUN_STATUS}}": ctx.get("CURRENT_RUN_STATUS", ""),
-        "{{VALIDATION_STATUS}}": ctx.get("VALIDATION_STATUS", "not-run"),
-        "{{RELATED_TASKS_BULLETS}}": ctx.get(
-            "RELATED_TASKS_BULLETS", "- None recorded"
-        ),
-        "{{RELATED_TASKS_INLINE}}": ctx.get("RELATED_TASKS_INLINE", "None"),
-        "{{WORKFLOW_CURRENT_PHASE}}": ctx.get("WORKFLOW_CURRENT_PHASE", ""),
-        "{{WORKFLOW_NEXT_RECOMMENDED_PHASE}}": ctx.get(
-            "WORKFLOW_NEXT_RECOMMENDED_PHASE", ""
-        ),
-        "{{PHASE_ALLOWED_OUTPUTS}}": ctx.get("PHASE_ALLOWED_OUTPUTS", ""),
-        "{{PHASE_FORBIDDEN_ACTIONS}}": ctx.get("PHASE_FORBIDDEN_ACTIONS", ""),
-        "{{AVAILABLE_MCP_SERVERS}}": ctx.get(
-            "AVAILABLE_MCP_SERVERS",
-            build_available_mcp_servers_block(Path(ctx.get("PROJECT_ROOT", "."))),
-        ),
-        "{{EXECUTOR_WORKTREE_PATH}}": ctx.get("EXECUTOR_WORKTREE_PATH", ""),
-        "{{EXECUTOR_WORKTREE_BRANCH}}": ctx.get("EXECUTOR_WORKTREE_BRANCH", ""),
-        "{{EXECUTOR_WORKTREE_BASE_REF}}": ctx.get("EXECUTOR_WORKTREE_BASE_REF", ""),
-        "{{EXECUTOR_WORKTREE_STATUS}}": ctx.get("EXECUTOR_WORKTREE_STATUS", ""),
-        "{{EXECUTOR_WORKTREE_NOTE}}": ctx.get("EXECUTOR_WORKTREE_NOTE", ""),
-    }
+    # 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)
+
+
+def apply_lead_prompt_defaults(ctx: dict) -> None:
+    """Apply default values for optional lead-prompt ctx fields.
+
+    Sets four optional tokens that the lead prompt template references but
+    which callers may legitimately leave unset (e.g., no validation has run
+    yet, no related tasks were declared). Caller-supplied values are
+    preserved via `setdefault` / `if-not-in` semantics — this function only
+    fills gaps, never overwrites.
+
+    Companion to `inject_lead_prompt_computed_tokens` (which always
+    overwrites with deterministically-derived values). The two functions
+    are kept separate so each has a single clear responsibility:
+    inject = compute-and-overwrite, apply_defaults = fill-if-missing.
+    """
+    ctx.setdefault("VALIDATION_STATUS", "not-run")
+    ctx.setdefault("RELATED_TASKS_BULLETS", "- None recorded")
+    ctx.setdefault("RELATED_TASKS_INLINE", "None")
+    ctx.setdefault(
+        "WORKER_PROMPT_PREAMBLE_PATH",
+        str(Path.home() / ".okstra" / "templates" / "worker-prompt-preamble.md"),
+    )
+    if "AVAILABLE_MCP_SERVERS" not in ctx:
+        ctx["AVAILABLE_MCP_SERVERS"] = build_available_mcp_servers_block(
+            Path(ctx.get("PROJECT_ROOT", "."))
+        )
+
+
+_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 → `TokenRenderError` (fail-fast).
+    - Phase block stripping (`{% if header.taskType == 'X' %} ... {% endif %}`)
+      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.
+    Optional defaults (VALIDATION_STATUS etc.) should be filled by calling
+    `apply_lead_prompt_defaults(ctx)` in the same setup step.
+    """
+    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))
-    mapping.update(_frontmatter_mapping(fm_ctx))
+    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
-    for k, v in mapping.items():
-        rendered = rendered.replace(k, v)
-    rendered = _strip_phase_blocks(rendered, ctx.get("ANALYSIS_TYPE", ""))
+    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 TokenRenderError(
+            f"undefined lead-prompt token(s): {names} (template={template_path}). "
+            f"Add the key(s) to ctx in run.py / "
+            f"inject_lead_prompt_computed_tokens() / apply_lead_prompt_defaults()."
+        )
+
+    rendered = _strip_phase_blocks(rendered, ctx.get("TASK_TYPE", ""))
     _write_text(Path(output_path), rendered.rstrip() + "\n")
 
 
@@ -1681,7 +1637,10 @@ def main(argv: list[str]) -> int:
             render_task_index(template_path, output_path, _load_ctx(ctx_path))
         elif sub == "template":
             ctx_path, template_path, output_path = rest
-            render_template_file(template_path, output_path, _load_ctx(ctx_path))
+            ctx = _load_ctx(ctx_path)
+            inject_lead_prompt_computed_tokens(ctx)
+            apply_lead_prompt_defaults(ctx)
+            render_template_with_ctx(template_path, output_path, ctx)
         else:
             print(f"unknown subcommand: {sub}", file=sys.stderr)
             return 2