okstra 0.1.0

package/runtime/python/okstra_ctl/render.py

@@ -0,0 +1,1065 @@
+"""All run-artifact rendering, in one module.
+
+이 모듈은 기존에 `scripts/lib/okstra/{template,team-state,manifest,discovery,
+directories}.sh` 의 python heredoc 으로 흩어져 있던 렌더 로직을 한 곳으로 모은다.
+bash 측은 이제 heredoc 없이 `python3 -m okstra_ctl.render <subcommand> <args>`
+형태의 한 줄 호출로 같은 산출물을 만든다.
+
+설계 원칙:
+  - 각 함수는 (ctx dict, 추가 path 인자) 만 받아서 파일을 쓴다.
+  - 환경 변수에 의존하지 않는다 (ctx 가 권위).
+  - 단일 진입점 `main()` 이 subcommand 를 dispatcher 로 라우팅한다.
+
+ctx dict 의 schema 는 `okstra_ctl.paths.compute_run_paths()` 의 반환값을
+기본으로, 호출자가 추가 키 (workflow state / model display / related tasks /
+session id 등) 를 덧붙여 전달한다.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+
+# --------------------------------------------------------------------------- #
+# helpers
+# --------------------------------------------------------------------------- #
+
+
+def _load_ctx(ctx_arg: str) -> dict:
+    """Accept either an inline JSON string or a path to a JSON file.
+
+    bash 는 보통 `build_render_context_json` 의 결과를 그대로 inline 으로 넘기고,
+    skill 은 디스크의 run-context 파일 경로를 넘긴다.
+    """
+    s = ctx_arg.lstrip()
+    if s.startswith("{"):
+        return json.loads(ctx_arg)
+    return json.loads(Path(ctx_arg).read_text(encoding="utf-8"))
+
+
+def _write_text(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text, encoding="utf-8")
+
+
+def _write_json(path: Path, payload: dict) -> None:
+    _write_text(path, json.dumps(payload, indent=2, ensure_ascii=False) + "\n")
+
+
+def _resolve_workers(ctx: dict) -> list[str]:
+    return [w.strip() for w in ctx.get("SELECTED_REVIEWERS", "").split(",") if w.strip()]
+
+
+def _worker_catalog(ctx: dict) -> dict:
+    return {
+        "claude": {
+            "workerId": "claude",
+            "role": "Claude worker",
+            "agent": "claude",
+            "agentLabel": "Claude Code",
+            "model": ctx.get("CLAUDE_WORKER_MODEL_DISPLAY", ""),
+            "modelExecutionValue": ctx.get("CLAUDE_WORKER_MODEL_EXECUTION_VALUE", ""),
+            "resultPath": ctx.get("CLAUDE_WORKER_RESULT_RELATIVE_PATH", ""),
+            "promptPath": ctx.get("CLAUDE_WORKER_PROMPT_RELATIVE_PATH", ""),
+        },
+        "codex": {
+            "workerId": "codex",
+            "role": "Codex worker",
+            "agent": "codex",
+            "agentLabel": "Codex",
+            "model": ctx.get("CODEX_WORKER_MODEL_DISPLAY", ""),
+            "modelExecutionValue": ctx.get("CODEX_WORKER_MODEL_EXECUTION_VALUE", ""),
+            "resultPath": ctx.get("CODEX_WORKER_RESULT_RELATIVE_PATH", ""),
+            "promptPath": ctx.get("CODEX_WORKER_PROMPT_RELATIVE_PATH", ""),
+        },
+        "gemini": {
+            "workerId": "gemini",
+            "role": "Gemini worker",
+            "agent": "gemini",
+            "agentLabel": "Gemini",
+            "model": ctx.get("GEMINI_WORKER_MODEL_DISPLAY", ""),
+            "modelExecutionValue": ctx.get("GEMINI_WORKER_MODEL_EXECUTION_VALUE", ""),
+            "resultPath": ctx.get("GEMINI_WORKER_RESULT_RELATIVE_PATH", ""),
+            "promptPath": ctx.get("GEMINI_WORKER_PROMPT_RELATIVE_PATH", ""),
+        },
+        "report-writer": {
+            "workerId": "report-writer",
+            "role": "Report writer worker",
+            "agent": "claude",
+            "agentLabel": "Claude Code",
+            "model": ctx.get("REPORT_WRITER_MODEL_DISPLAY", ""),
+            "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", ""),
+        },
+    }
+
+
+# --------------------------------------------------------------------------- #
+# team-state
+# --------------------------------------------------------------------------- #
+
+
+def render_team_state(team_state_path: str, ctx: dict) -> None:
+    selected = _resolve_workers(ctx)
+    catalog = _worker_catalog(ctx)
+    workers = []
+    for w in selected:
+        m = catalog[w]
+        workers.append({
+            "workerId": m["workerId"],
+            "role": m["role"],
+            "agent": m["agent"],
+            "model": m["model"],
+            "modelExecutionValue": m["modelExecutionValue"],
+            "status": "not-run",
+            "resultPath": m["resultPath"],
+            "promptPath": m["promptPath"],
+            "reason": "",
+        })
+    payload = {
+        "schemaVersion": "1.0",
+        "taskKey": ctx.get("TASK_KEY", ""),
+        "taskType": ctx.get("ANALYSIS_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", ""),
+            "modelExecutionValue": ctx.get("LEAD_MODEL_EXECUTION_VALUE", ""),
+            "status": ctx.get("CURRENT_RUN_STATUS", ""),
+            "sessionId": ctx.get("CLAUDE_SESSION_ID", ""),
+        },
+        "workers": workers,
+        "validator": {
+            "scriptPath": ctx.get("RUN_VALIDATOR_RELATIVE_PATH", ""),
+            "status": ctx.get("VALIDATION_STATUS", "not-run"),
+            "lastValidatedAt": ctx.get("VALIDATION_UPDATED_AT", ""),
+            "failures": json.loads(ctx.get("VALIDATION_FAILURES_JSON", "[]")),
+        },
+        "artifacts": {
+            "leadPromptSnapshotPath": ctx.get("RUN_PROMPT_SNAPSHOT_RELATIVE_PATH", ""),
+            "workerPromptsDirectoryPath": ctx.get("RUN_PROMPTS_RELATIVE_PATH", ""),
+            "finalReportPath": ctx.get("FINAL_REPORT_RELATIVE_PATH", ""),
+            "finalStatusPath": ctx.get("FINAL_STATUS_RELATIVE_PATH", ""),
+            "workerResultsDirectoryPath": ctx.get("WORKER_RESULTS_RELATIVE_PATH", ""),
+        },
+    }
+    _write_json(Path(team_state_path), payload)
+
+
+# --------------------------------------------------------------------------- #
+# reference expectations + discovery
+# --------------------------------------------------------------------------- #
+
+
+def render_reference_expectations(brief_path: str, output_path: str, ctx: dict) -> None:
+    section_map = {
+        "Configuration References and Expected Values": "config",
+        "Deployment Manifests and Expected Values": "deployment",
+    }
+    captured = {"config": [], "deployment": []}
+    current_section = None
+    for line in Path(brief_path).read_text(encoding="utf-8").splitlines():
+        if line.startswith("## "):
+            current_section = section_map.get(line[3:].strip())
+            continue
+        if current_section:
+            captured[current_section].append(line)
+
+    config_text = "\n".join(captured["config"]).strip()
+    deployment_text = "\n".join(captured["deployment"]).strip()
+    brief_relative = ctx.get("INSTRUCTION_SET_RELATIVE_PATH", "") + "/task-brief.md"
+
+    parts = [
+        "# Task Reference Expectations",
+        "",
+        f"- Task Key: `{ctx.get('TASK_KEY', '')}`",
+        f"- Task Type: `{ctx.get('ANALYSIS_TYPE', '')}`",
+        f"- Source brief snapshot: `{brief_relative}`",
+        "",
+        "## Usage Rules",
+        "",
+        "- Treat this file as the canonical task-level reference for config files and deployment manifests that carry expected values for the current task.",
+        "- If a section below is empty, that means the task brief did not provide explicit expected-state guidance for that category.",
+        "- Missing expectations are missing information, not confirmed current state.",
+        "",
+        "## Configuration References and Expected Values",
+        "",
+    ]
+    parts.append(config_text or "- No explicit configuration-file expectations were provided in the task brief.")
+    parts.extend(["", "## Deployment Manifests and Expected Values", ""])
+    parts.append(deployment_text or "- No explicit deployment-manifest expectations were provided in the task brief.")
+    _write_text(Path(output_path), "\n".join(parts).rstrip() + "\n")
+
+
+def render_task_catalog_discovery(output_path: str, ctx: dict) -> None:
+    project_root = Path(ctx["PROJECT_ROOT"])
+    tasks_root = Path(ctx["OKSTRA_TASKS_ROOT"])
+
+    def s(payload, key):
+        if not isinstance(payload, dict):
+            return ""
+        v = payload.get(key, "")
+        return v if isinstance(v, str) else ""
+
+    def rel(p):
+        try:
+            return p.relative_to(project_root).as_posix()
+        except ValueError:
+            return str(p)
+
+    entries = []
+    for manifest_path in sorted(tasks_root.rglob("task-manifest.json")):
+        try:
+            manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+        except Exception:
+            continue
+        if not isinstance(manifest, dict):
+            continue
+        task_key = s(manifest, "taskKey").strip()
+        if not task_key:
+            continue
+        task_root = manifest_path.parent
+        timeline_relative = s(manifest, "historyTimelinePath").strip()
+        timeline_path = (project_root / timeline_relative) if timeline_relative else (task_root / "history" / "timeline.json")
+        latest_run = {}
+        if timeline_path.is_file():
+            try:
+                payload = json.loads(timeline_path.read_text(encoding="utf-8"))
+            except Exception:
+                payload = {}
+            runs = payload.get("runs", []) if isinstance(payload, dict) else []
+            if isinstance(runs, list):
+                for item in reversed(runs):
+                    if isinstance(item, dict):
+                        latest_run = item
+                        break
+        workflow = manifest.get("workflow") if isinstance(manifest.get("workflow"), dict) else {}
+        entries.append({
+            "taskKey": task_key,
+            "taskGroup": s(manifest, "taskGroup"),
+            "taskId": s(manifest, "taskId"),
+            "taskGroupPathSegment": s(manifest, "taskGroupPathSegment"),
+            "taskIdPathSegment": s(manifest, "taskIdPathSegment"),
+            "taskType": s(manifest, "taskType"),
+            "workCategory": s(manifest, "workCategory"),
+            "currentStatus": s(manifest, "currentStatus"),
+            "updatedAt": s(manifest, "updatedAt"),
+            "currentPhase": (workflow or {}).get("currentPhase", "") if isinstance(workflow, dict) else "",
+            "currentPhaseState": (workflow or {}).get("currentPhaseState", "") if isinstance(workflow, dict) else "",
+            "lastCompletedPhase": (workflow or {}).get("lastCompletedPhase", "") if isinstance(workflow, dict) else "",
+            "nextRecommendedPhase": (workflow or {}).get("nextRecommendedPhase", "") if isinstance(workflow, dict) else "",
+            "awaitingApproval": (workflow or {}).get("awaitingApproval", False) if isinstance(workflow, dict) else False,
+            "routingStatus": (workflow or {}).get("routingStatus", "") if isinstance(workflow, dict) else "",
+            "taskRootPath": s(manifest, "taskRootPath") or rel(task_root),
+            "taskManifestPath": s(manifest, "taskManifestPath") or rel(manifest_path),
+            "taskIndexPath": s(manifest, "taskIndexPath"),
+            "instructionSetPath": s(manifest, "instructionSetPath"),
+            "referenceExpectationsPath": s(manifest, "referenceExpectationsPath"),
+            "taskBriefPath": s(manifest, "taskBriefPath"),
+            "latestRunPath": s(manifest, "latestRunPath") or s(latest_run, "runDirectoryPath"),
+            "latestRunManifestPath": s(latest_run, "runManifestPath"),
+            "latestRunPromptsPath": s(manifest, "latestRunPromptsPath") or s(latest_run, "workerPromptDirectoryPath"),
+            "latestPromptSnapshotPath": s(latest_run, "promptSnapshotPath"),
+            "latestTeamStatePath": s(latest_run, "teamStatePath"),
+            "latestRunStatus": s(manifest, "latestRunStatus") or s(latest_run, "status"),
+            "latestReportPath": s(manifest, "latestReportPath") or s(latest_run, "reportPath"),
+            "latestResumeCommandPath": s(manifest, "latestResumeCommandPath") or s(latest_run, "resumeCommandPath"),
+            "historyTimelinePath": timeline_relative or rel(timeline_path),
+        })
+    entries.sort(key=lambda x: (x.get("updatedAt", ""), x.get("taskKey", "")), reverse=True)
+    payload = {
+        "schemaVersion": "1.0",
+        "projectId": ctx.get("PROJECT_ID", ""),
+        "updatedAt": ctx.get("RUN_TIMESTAMP_ISO", ""),
+        "latestTaskKey": ctx.get("TASK_KEY", ""),
+        "latestTaskDiscoveryPath": ctx.get("OKSTRA_LATEST_TASK_RELATIVE_PATH", ""),
+        "taskCount": len(entries),
+        "tasks": entries,
+    }
+    _write_json(Path(output_path), payload)
+
+
+def render_latest_task_discovery(output_path: str, ctx: dict) -> None:
+    task_manifest_path = Path(ctx.get("TASK_MANIFEST_FILE", ""))
+    task_manifest = {}
+    if task_manifest_path.exists():
+        try:
+            task_manifest = json.loads(task_manifest_path.read_text(encoding="utf-8"))
+        except Exception:
+            task_manifest = {}
+    workflow = task_manifest.get("workflow") if isinstance(task_manifest.get("workflow"), dict) else {}
+    payload = {
+        "schemaVersion": "1.0",
+        "updatedAt": ctx.get("RUN_TIMESTAMP_ISO", ""),
+        "taskKey": ctx.get("TASK_KEY", ""),
+        "taskType": ctx.get("ANALYSIS_TYPE", ""),
+        "workCategory": task_manifest.get("workCategory", ctx.get("WORKFLOW_WORK_CATEGORY", "unknown")),
+        "currentStatus": task_manifest.get("currentStatus", ctx.get("CURRENT_TASK_STATUS", "")),
+        "latestRunStatus": task_manifest.get("latestRunStatus", ctx.get("CURRENT_RUN_STATUS", "")),
+        "workflow": workflow,
+        "taskRootPath": ctx.get("TASK_ROOT_RELATIVE_PATH", ""),
+        "taskManifestPath": ctx.get("TASK_MANIFEST_RELATIVE_PATH", ""),
+        "taskIndexPath": ctx.get("TASK_INDEX_RELATIVE_PATH", ""),
+        "instructionSetPath": ctx.get("INSTRUCTION_SET_RELATIVE_PATH", ""),
+        "taskCatalogPath": ctx.get("OKSTRA_TASK_CATALOG_RELATIVE_PATH", ""),
+        "referenceExpectationsPath": ctx.get("REFERENCE_EXPECTATIONS_RELATIVE_PATH", ""),
+        "latestRunPath": ctx.get("LATEST_RUN_RELATIVE_PATH", ""),
+        "latestRunManifestPath": ctx.get("RUN_MANIFEST_RELATIVE_PATH", ""),
+        "latestRunPromptsPath": ctx.get("RUN_PROMPTS_RELATIVE_PATH", ""),
+        "latestPromptSnapshotPath": ctx.get("RUN_PROMPT_SNAPSHOT_RELATIVE_PATH", ""),
+        "latestTeamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
+        "latestReportPath": ctx.get("LATEST_REPORT_RELATIVE_PATH", ""),
+        "expectedReportPath": ctx.get("FINAL_REPORT_RELATIVE_PATH", ""),
+        "expectedStatusPath": ctx.get("FINAL_STATUS_RELATIVE_PATH", ""),
+        "latestResumeCommandPath": ctx.get("CLAUDE_RESUME_COMMAND_RELATIVE_PATH", ""),
+        "historyTimelinePath": ctx.get("TIMELINE_RELATIVE_PATH", ""),
+    }
+    _write_json(Path(output_path), payload)
+
+
+# --------------------------------------------------------------------------- #
+# directories migration
+# --------------------------------------------------------------------------- #
+
+
+def migrate_legacy_run_artifacts(ctx: dict) -> None:
+    import shutil
+
+    project_root = Path(ctx["PROJECT_ROOT"])
+    task_root = Path(ctx["TASK_ROOT"])
+    run_dir = Path(ctx["RUN_DIR"])
+    legacy_targets = [
+        ("run-manifest-", ".json", Path(ctx["RUN_MANIFESTS_DIR"])),
+        ("team-state-", ".json", Path(ctx["RUN_STATE_DIR"])),
+        ("claude-execution-prompt-", ".md", Path(ctx["RUN_PROMPTS_DIR"])),
+        ("final-report-", ".md", Path(ctx["RUN_REPORTS_DIR"])),
+        ("final-", ".status", Path(ctx["RUN_STATUS_DIR"])),
+        ("claude-resume-", ".sh", Path(ctx["RUN_SESSIONS_DIR"])),
+    ]
+    if not run_dir.is_dir():
+        return
+    path_rewrites = {}
+    for entry in run_dir.iterdir():
+        if not entry.is_file():
+            continue
+        for prefix, suffix, target_dir in legacy_targets:
+            if not entry.name.startswith(prefix) or not entry.name.endswith(suffix):
+                continue
+            target_dir.mkdir(parents=True, exist_ok=True)
+            destination = target_dir / entry.name
+            old_relative = str(entry.relative_to(project_root))
+            new_relative = str(destination.relative_to(project_root))
+            if destination.exists():
+                try:
+                    if entry.read_bytes() == destination.read_bytes():
+                        entry.unlink()
+                        path_rewrites[old_relative] = new_relative
+                except Exception:
+                    pass
+                break
+            shutil.move(str(entry), str(destination))
+            path_rewrites[old_relative] = new_relative
+            break
+    if not path_rewrites:
+        return
+    text_suffixes = {".json", ".md", ".txt", ".sh"}
+    for path in task_root.rglob("*"):
+        if not path.is_file() or path.suffix not in text_suffixes:
+            continue
+        try:
+            original = path.read_text(encoding="utf-8")
+        except Exception:
+            continue
+        updated = original
+        for old_rel, new_rel in path_rewrites.items():
+            updated = updated.replace(old_rel, new_rel)
+        if updated != original:
+            path.write_text(updated, encoding="utf-8")
+
+
+# --------------------------------------------------------------------------- #
+# task / run manifest + timeline + task-index
+# --------------------------------------------------------------------------- #
+
+
+def _required_worker_roles(ctx: dict, reviewers: list[str]) -> list[dict]:
+    catalog = _worker_catalog(ctx)
+    return [
+        {
+            "workerId": catalog[item]["workerId"],
+            "role": catalog[item]["role"],
+            "agent": catalog[item]["agent"],
+            "model": catalog[item]["model"],
+            "modelExecutionValue": catalog[item]["modelExecutionValue"],
+            "resultPath": catalog[item]["resultPath"],
+            "promptPath": catalog[item]["promptPath"],
+            "attemptRequired": True,
+        }
+        for item in reviewers
+    ]
+
+
+def render_task_manifest(manifest_path: str, ctx: dict) -> None:
+    path = Path(manifest_path)
+    existing = {}
+    if path.exists():
+        try:
+            existing = json.loads(path.read_text(encoding="utf-8"))
+        except Exception:
+            existing = {}
+    reviewers = _resolve_workers(ctx)
+    catalog = _worker_catalog(ctx)
+    phase_sequence = [
+        "requirements-discovery", "error-analysis", "implementation-planning",
+        "implementation", "final-verification",
+    ]
+    default_next_phase = {
+        "requirements-discovery": "pending-routing-decision",
+        "error-analysis": "implementation-planning",
+        "implementation-planning": "implementation",
+        "implementation": "final-verification",
+        "final-verification": "done-or-follow-up",
+    }
+    required_worker_roles = _required_worker_roles(ctx, reviewers)
+    worker_prompt_paths = {item: catalog[item]["promptPath"] for item in reviewers}
+    required_agent_status_entries = ["Claude lead"] + [catalog[item]["role"] for item in reviewers]
+    related_tasks = json.loads(ctx.get("RELATED_TASKS_JSON", "[]"))
+    current_report_relative = ctx.get("LATEST_REPORT_RELATIVE_PATH") or ctx.get("FINAL_REPORT_RELATIVE_PATH", "")
+    workflow = existing.get("workflow", {}) if isinstance(existing.get("workflow"), dict) else {}
+    phase_states = workflow.get("phaseStates", {}) if isinstance(workflow.get("phaseStates"), dict) else {}
+    current_phase = ctx.get("WORKFLOW_CURRENT_PHASE", ctx.get("ANALYSIS_TYPE", ""))
+    current_phase_state = ctx.get("WORKFLOW_CURRENT_PHASE_STATE", "not-started")
+    for phase in phase_sequence:
+        phase_states.setdefault(phase, "not-started")
+    if current_phase:
+        phase_states[current_phase] = current_phase_state
+    work_category = existing.get("workCategory") or ctx.get("WORKFLOW_WORK_CATEGORY", "unknown")
+    next_recommended_phase = (
+        workflow.get("nextRecommendedPhase")
+        or default_next_phase.get(current_phase, ctx.get("WORKFLOW_NEXT_RECOMMENDED_PHASE", "unknown"))
+    )
+    last_completed_phase = workflow.get("lastCompletedPhase") or ctx.get("WORKFLOW_LAST_COMPLETED_PHASE", "")
+    routing_status = workflow.get("routingStatus") or ctx.get("WORKFLOW_ROUTING_STATUS", "not-applicable")
+    awaiting_approval = workflow.get("awaitingApproval")
+    if not isinstance(awaiting_approval, bool):
+        awaiting_approval = ctx.get("WORKFLOW_AWAITING_APPROVAL", "false") == "true"
+    render_only = ctx.get("RENDER_ONLY", "") == "true"
+    existing_checkpoint = existing.get("workflow", {}).get("lastSafeCheckpoint", {}) if isinstance(existing.get("workflow"), dict) else {}
+    if not isinstance(existing_checkpoint, dict):
+        existing_checkpoint = {}
+    if render_only:
+        last_safe_checkpoint = {
+            "label": existing_checkpoint.get("label", ""),
+            "taskManifestPath": existing_checkpoint.get("taskManifestPath", ctx.get("TASK_MANIFEST_RELATIVE_PATH", "")),
+            "taskIndexPath": existing_checkpoint.get("taskIndexPath", ctx.get("TASK_INDEX_RELATIVE_PATH", "")),
+            "latestRunPath": existing_checkpoint.get("latestRunPath", existing.get("latestRunPath", "")),
+            "latestRunManifestPath": existing_checkpoint.get("latestRunManifestPath", ""),
+            "latestTeamStatePath": existing_checkpoint.get("latestTeamStatePath", existing.get("teamStatePath", "")),
+            "latestReportPath": existing_checkpoint.get("latestReportPath", existing.get("latestReportPath", "")),
+            "latestResumeCommandPath": existing_checkpoint.get("latestResumeCommandPath", existing.get("latestResumeCommandPath", "")),
+        }
+        latest_run_relative = existing.get("latestRunPath", "") or ctx.get("LATEST_RUN_RELATIVE_PATH", "")
+        latest_run_status = existing.get("latestRunStatus", "") or ctx.get("CURRENT_RUN_STATUS", "")
+        latest_run_prompts_relative = existing.get("latestRunPromptsPath", "") or ctx.get("RUN_PROMPTS_RELATIVE_PATH", "")
+        latest_report_relative = existing.get("latestReportPath", "") or current_report_relative
+        latest_team_state_relative = existing.get("teamStatePath", "") or ctx.get("TEAM_STATE_RELATIVE_PATH", "")
+        latest_resume_command_relative = existing.get("latestResumeCommandPath", "")
+    else:
+        last_safe_checkpoint = {
+            "label": ctx.get("WORKFLOW_LAST_SAFE_CHECKPOINT_LABEL", ""),
+            "taskManifestPath": ctx.get("TASK_MANIFEST_RELATIVE_PATH", ""),
+            "taskIndexPath": ctx.get("TASK_INDEX_RELATIVE_PATH", ""),
+            "latestRunPath": ctx.get("LATEST_RUN_RELATIVE_PATH", ""),
+            "latestRunManifestPath": ctx.get("RUN_MANIFEST_RELATIVE_PATH", ""),
+            "latestTeamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
+            "latestReportPath": current_report_relative,
+            "latestResumeCommandPath": ctx.get("CLAUDE_RESUME_COMMAND_RELATIVE_PATH", ""),
+        }
+        latest_run_relative = ctx.get("LATEST_RUN_RELATIVE_PATH", "")
+        latest_run_status = ctx.get("CURRENT_RUN_STATUS", "")
+        latest_run_prompts_relative = ctx.get("RUN_PROMPTS_RELATIVE_PATH", "")
+        latest_report_relative = current_report_relative or existing.get("latestReportPath", "")
+        latest_team_state_relative = ctx.get("TEAM_STATE_RELATIVE_PATH", "")
+        latest_resume_command_relative = ctx.get("CLAUDE_RESUME_COMMAND_RELATIVE_PATH", "") or existing.get("latestResumeCommandPath", "")
+    payload = {
+        "schemaVersion": "1.0",
+        "projectId": ctx.get("PROJECT_ID", ""),
+        "taskGroup": ctx.get("TASK_GROUP", ""),
+        "taskId": ctx.get("TASK_ID", ""),
+        "taskKey": ctx.get("TASK_KEY", ""),
+        "taskGroupPathSegment": ctx.get("TASK_GROUP_SEGMENT", ""),
+        "taskIdPathSegment": ctx.get("TASK_ID_SEGMENT", ""),
+        "projectRoot": ctx.get("PROJECT_ROOT", ""),
+        "taskType": ctx.get("ANALYSIS_TYPE", ""),
+        "workCategory": work_category,
+        "taskBriefPath": ctx.get("BRIEF_RELATIVE_PATH", ""),
+        "recommendedWorkers": reviewers,
+        "relatedTasks": related_tasks,
+        "currentStatus": ctx.get("CURRENT_TASK_STATUS", ""),
+        "renderOnly": ctx.get("RENDER_ONLY", ""),
+        "taskRootPath": ctx.get("TASK_ROOT_RELATIVE_PATH", ""),
+        "instructionSetPath": ctx.get("INSTRUCTION_SET_RELATIVE_PATH", ""),
+        "taskManifestPath": ctx.get("TASK_MANIFEST_RELATIVE_PATH", ""),
+        "taskIndexPath": ctx.get("TASK_INDEX_RELATIVE_PATH", ""),
+        "runsPath": ctx.get("RUNS_RELATIVE_PATH", ""),
+        "historyPath": ctx.get("HISTORY_RELATIVE_PATH", ""),
+        "historyTimelinePath": ctx.get("TIMELINE_RELATIVE_PATH", ""),
+        "taskCatalogPath": ctx.get("OKSTRA_TASK_CATALOG_RELATIVE_PATH", ""),
+        "referenceExpectationsPath": ctx.get("REFERENCE_EXPECTATIONS_RELATIVE_PATH", ""),
+        "latestRunPath": latest_run_relative,
+        "latestRunStatus": latest_run_status,
+        "latestRunPromptsPath": latest_run_prompts_relative,
+        "latestReportPath": latest_report_relative,
+        "latestResumeCommandPath": latest_resume_command_relative,
+        "teamStatePath": latest_team_state_relative,
+        "workflow": {
+            "phaseSequence": phase_sequence,
+            "currentPhase": current_phase,
+            "currentPhaseState": phase_states.get(current_phase, current_phase_state),
+            "phaseStates": phase_states,
+            "lastCompletedPhase": last_completed_phase,
+            "nextRecommendedPhase": next_recommended_phase,
+            "awaitingApproval": awaiting_approval,
+            "routingStatus": routing_status,
+            "lastSafeCheckpoint": last_safe_checkpoint,
+        },
+        "artifacts": {
+            "analysisProfilePath": ctx.get("INSTRUCTION_SET_RELATIVE_PATH", "") + "/analysis-profile.md",
+            "analysisMaterialPath": ctx.get("INSTRUCTION_SET_RELATIVE_PATH", "") + "/analysis-material.md",
+            "taskBriefCopyPath": ctx.get("INSTRUCTION_SET_RELATIVE_PATH", "") + "/task-brief.md",
+            "referenceExpectationsPath": ctx.get("REFERENCE_EXPECTATIONS_RELATIVE_PATH", ""),
+            "claudeExecutionPromptPath": ctx.get("INSTRUCTION_SET_RELATIVE_PATH", "") + "/claude-execution-prompt.md",
+            "leadPromptSnapshotPath": ctx.get("RUN_PROMPT_SNAPSHOT_RELATIVE_PATH", ""),
+            "workerPromptsDirectoryPath": ctx.get("RUN_PROMPTS_RELATIVE_PATH", ""),
+            "workerPromptPathByWorkerId": worker_prompt_paths,
+            "finalReportTemplatePath": ctx.get("FINAL_REPORT_TEMPLATE_RELATIVE_PATH", ""),
+            "resumeCommandPath": ctx.get("CLAUDE_RESUME_COMMAND_RELATIVE_PATH", ""),
+            "teamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
+            "workerResultsDirectoryPath": ctx.get("WORKER_RESULTS_RELATIVE_PATH", ""),
+            "validatorScriptPath": ctx.get("RUN_VALIDATOR_RELATIVE_PATH", ""),
+        },
+        "resultContract": {
+            "leadAgent": "claude",
+            "leadRole": "Claude lead",
+            "leadModel": ctx.get("LEAD_MODEL_DISPLAY", ""),
+            "leadModelExecutionValue": ctx.get("LEAD_MODEL_EXECUTION_VALUE", ""),
+            "leadExecutionMode": "synthesis-only",
+            "finalSynthesisOwner": "Claude lead",
+            "artifactFirst": True,
+            "resultCollectionMode": "claude-managed",
+            "finalReportFormat": "markdown",
+            "finalReportFilename": ctx.get("FINAL_REPORT_FILENAME", ""),
+            "finalStatusFilename": ctx.get("FINAL_STATUS_FILENAME", ""),
+            "minimumPreferredWorkerResults": len(reviewers),
+            "requiredWorkerAttempts": reviewers,
+            "requiredWorkerRoles": required_worker_roles,
+            "requiredAgentStatusEntries": required_agent_status_entries,
+            "requireDistinctLeadFromClaudeWorker": True,
+            "requireAllRequiredWorkerAttempts": True,
+            "requireGeminiWorkerAttempt": "gemini" in reviewers,
+            "requireCollectedWorkerStatusesBeforeFinalVerdict": True,
+            "disallowLeadSoloAnalysisAsWorkerResult": True,
+            "disallowGenericParallelOnlyExecution": True,
+            "workerOutputSections": [
+                "Findings", "Missing Information or Assumptions",
+                "Safe or Reasonable Areas", "Uncertain Points",
+                "Recommended Next Actions",
+            ],
+            "finalReportSections": [
+                "Problem or Validation Summary", "Agent Execution Status",
+                "Cross Verification Result", "Final Verdict",
+                "Evidence and Detailed Analysis",
+                "Missing Information and Risk", "Recommended Next Actions",
+            ],
+            "statusLabels": [
+                "prepared", "team-created", "workers-dispatched",
+                "worker-results-collected", "synthesis-written", "in-progress",
+                "completed", "contract-violated", "timeout", "error", "not-run",
+            ],
+        },
+        "contractValidation": {
+            "required": True,
+            "status": ctx.get("VALIDATION_STATUS", "not-run"),
+            "lastCheckedAt": ctx.get("VALIDATION_UPDATED_AT", ""),
+            "passed": ctx.get("VALIDATION_STATUS", "not-run") == "passed",
+            "failures": json.loads(ctx.get("VALIDATION_FAILURES_JSON", "[]")),
+            "teamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
+            "validatorScriptPath": ctx.get("RUN_VALIDATOR_RELATIVE_PATH", ""),
+        },
+        "claudeSession": {
+            "sessionId": ctx.get("CLAUDE_SESSION_ID", ""),
+            "resumeCommandPath": ctx.get("CLAUDE_RESUME_COMMAND_RELATIVE_PATH", ""),
+        },
+        "createdAt": existing.get("createdAt") or ctx.get("RUN_TIMESTAMP_ISO", ""),
+        "updatedAt": ctx.get("RUN_TIMESTAMP_ISO", ""),
+    }
+    _write_json(path, payload)
+
+
+def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
+    task_manifest_path = Path(ctx.get("TASK_MANIFEST_FILE", ""))
+    task_manifest = {}
+    if task_manifest_path.exists():
+        try:
+            task_manifest = json.loads(task_manifest_path.read_text(encoding="utf-8"))
+        except Exception:
+            task_manifest = {}
+    reviewers = _resolve_workers(ctx)
+    catalog = _worker_catalog(ctx)
+    required_worker_roles = _required_worker_roles(ctx, reviewers)
+    worker_prompt_paths = {item: catalog[item]["promptPath"] for item in reviewers}
+    related_tasks = json.loads(ctx.get("RELATED_TASKS_JSON", "[]"))
+    workflow = task_manifest.get("workflow", {}) if isinstance(task_manifest.get("workflow"), dict) else {}
+    payload = {
+        "schemaVersion": "1.0",
+        "projectId": ctx.get("PROJECT_ID", ""),
+        "taskGroup": ctx.get("TASK_GROUP", ""),
+        "taskId": ctx.get("TASK_ID", ""),
+        "taskKey": ctx.get("TASK_KEY", ""),
+        "taskType": ctx.get("ANALYSIS_TYPE", ""),
+        "workCategory": task_manifest.get("workCategory", ctx.get("WORKFLOW_WORK_CATEGORY", "unknown")),
+        "taskBriefPath": ctx.get("BRIEF_RELATIVE_PATH", ""),
+        "relatedTasks": related_tasks,
+        "recommendedWorkers": reviewers,
+        "taskRootPath": ctx.get("TASK_ROOT_RELATIVE_PATH", ""),
+        "taskManifestPath": ctx.get("TASK_MANIFEST_RELATIVE_PATH", ""),
+        "instructionSetPath": ctx.get("INSTRUCTION_SET_RELATIVE_PATH", ""),
+        "taskCatalogPath": ctx.get("OKSTRA_TASK_CATALOG_RELATIVE_PATH", ""),
+        "referenceExpectationsPath": ctx.get("REFERENCE_EXPECTATIONS_RELATIVE_PATH", ""),
+        "runDirectoryPath": ctx.get("RUN_DIR_RELATIVE_PATH", ""),
+        "runDateTimeSegment": ctx.get("RUN_DATETIME_SEGMENT", ""),
+        "runSequencesByCategory": {
+            "manifests": ctx.get("RUN_MANIFESTS_SEQ", ""),
+            "prompts": ctx.get("RUN_PROMPTS_SEQ", ""),
+            "reports": ctx.get("RUN_REPORTS_SEQ", ""),
+            "status": ctx.get("RUN_STATUS_SEQ", ""),
+            "state": ctx.get("RUN_STATE_SEQ", ""),
+            "sessions": ctx.get("RUN_SESSIONS_SEQ", ""),
+            "workerResults": ctx.get("WORKER_RESULTS_SEQ", ""),
+        },
+        "runManifestPath": ctx.get("RUN_MANIFEST_RELATIVE_PATH", ""),
+        "promptSnapshotPath": ctx.get("RUN_PROMPT_SNAPSHOT_RELATIVE_PATH", ""),
+        "workerPromptsDirectoryPath": ctx.get("RUN_PROMPTS_RELATIVE_PATH", ""),
+        "workerPromptPathByWorkerId": worker_prompt_paths,
+        "expectedReportPath": ctx.get("FINAL_REPORT_RELATIVE_PATH", ""),
+        "expectedStatusPath": ctx.get("FINAL_STATUS_RELATIVE_PATH", ""),
+        "teamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
+        "workerResultsDirectoryPath": ctx.get("WORKER_RESULTS_RELATIVE_PATH", ""),
+        "reportTemplatePath": ctx.get("FINAL_REPORT_TEMPLATE_RELATIVE_PATH", ""),
+        "validatorScriptPath": ctx.get("RUN_VALIDATOR_RELATIVE_PATH", ""),
+        "claudeSessionId": ctx.get("CLAUDE_SESSION_ID", ""),
+        "resumeCommandPath": ctx.get("CLAUDE_RESUME_COMMAND_RELATIVE_PATH", ""),
+        "workflowSnapshot": {
+            "phaseSequence": workflow.get("phaseSequence", []),
+            "currentPhase": workflow.get("currentPhase", ctx.get("WORKFLOW_CURRENT_PHASE", "")),
+            "currentPhaseState": workflow.get("currentPhaseState", ctx.get("WORKFLOW_CURRENT_PHASE_STATE", "")),
+            "phaseStates": workflow.get("phaseStates", {}),
+            "lastCompletedPhase": workflow.get("lastCompletedPhase", ctx.get("WORKFLOW_LAST_COMPLETED_PHASE", "")),
+            "nextRecommendedPhase": workflow.get("nextRecommendedPhase", ctx.get("WORKFLOW_NEXT_RECOMMENDED_PHASE", "")),
+            "awaitingApproval": workflow.get("awaitingApproval", ctx.get("WORKFLOW_AWAITING_APPROVAL", "false") == "true"),
+            "routingStatus": workflow.get("routingStatus", ctx.get("WORKFLOW_ROUTING_STATUS", "")),
+            "lastSafeCheckpoint": workflow.get("lastSafeCheckpoint", {}),
+        },
+        "teamContract": {
+            "leadAgent": "claude",
+            "leadRole": "Claude lead",
+            "leadModel": ctx.get("LEAD_MODEL_DISPLAY", ""),
+            "leadModelExecutionValue": ctx.get("LEAD_MODEL_EXECUTION_VALUE", ""),
+            "leadExecutionMode": "synthesis-only",
+            "finalSynthesisOwner": "Claude lead",
+            "requiredWorkerAttempts": reviewers,
+            "requiredWorkerRoles": required_worker_roles,
+            "requiredAgentStatusEntries": ["Claude lead"] + [catalog[item]["role"] for item in reviewers],
+            "requireDistinctLeadFromClaudeWorker": True,
+            "requireAllRequiredWorkerAttempts": True,
+            "requireGeminiWorkerAttempt": "gemini" in reviewers,
+            "requireCollectedWorkerStatusesBeforeFinalVerdict": True,
+            "disallowLeadSoloAnalysisAsWorkerResult": True,
+            "disallowGenericParallelOnlyExecution": True,
+            "preferredCompletedWorkerResults": len(reviewers),
+        },
+        "validation": {
+            "required": True,
+            "status": ctx.get("VALIDATION_STATUS", "not-run"),
+            "lastCheckedAt": ctx.get("VALIDATION_UPDATED_AT", ""),
+            "passed": ctx.get("VALIDATION_STATUS", "not-run") == "passed",
+            "failures": json.loads(ctx.get("VALIDATION_FAILURES_JSON", "[]")),
+        },
+        "status": ctx.get("CURRENT_RUN_STATUS", ""),
+        "renderOnly": ctx.get("RENDER_ONLY", ""),
+        "createdAt": ctx.get("RUN_TIMESTAMP_ISO", ""),
+    }
+    _write_json(Path(run_manifest_path), payload)
+
+
+def render_timeline(timeline_path: str, ctx: dict) -> None:
+    task_manifest_path = Path(ctx.get("TASK_MANIFEST_FILE", ""))
+    task_manifest = {}
+    if task_manifest_path.exists():
+        try:
+            task_manifest = json.loads(task_manifest_path.read_text(encoding="utf-8"))
+        except Exception:
+            task_manifest = {}
+    reviewers = _resolve_workers(ctx)
+    worker_prompt_paths = {
+        "claude": ctx.get("CLAUDE_WORKER_PROMPT_RELATIVE_PATH", ""),
+        "codex": ctx.get("CODEX_WORKER_PROMPT_RELATIVE_PATH", ""),
+        "gemini": ctx.get("GEMINI_WORKER_PROMPT_RELATIVE_PATH", ""),
+        "report-writer": ctx.get("REPORT_WRITER_WORKER_PROMPT_RELATIVE_PATH", ""),
+    }
+    path = Path(timeline_path)
+    existing = {}
+    if path.exists():
+        try:
+            existing = json.loads(path.read_text(encoding="utf-8"))
+        except Exception:
+            existing = {}
+    runs = existing.get("runs", [])
+    current_run_manifest_path = ctx.get("RUN_MANIFEST_FILE", "")
+    current_run_manifest_relative_path = ctx.get("RUN_MANIFEST_RELATIVE_PATH", "")
+    filtered = [
+        item for item in runs
+        if item.get("runManifestPath") != current_run_manifest_relative_path
+        and item.get("runManifestPath") != current_run_manifest_path
+    ]
+    workflow = task_manifest.get("workflow") if isinstance(task_manifest.get("workflow"), dict) else {}
+    workflow = workflow or {}
+    filtered.append({
+        "runTimestamp": ctx.get("RUN_TIMESTAMP_ISO", ""),
+        "runDirectoryPath": ctx.get("RUN_DIR_RELATIVE_PATH", ""),
+        "runManifestPath": ctx.get("RUN_MANIFEST_RELATIVE_PATH", ""),
+        "runDateTimeSegment": ctx.get("RUN_DATETIME_SEGMENT", ""),
+        "runSequencesByCategory": {
+            "manifests": ctx.get("RUN_MANIFESTS_SEQ", ""),
+            "prompts": ctx.get("RUN_PROMPTS_SEQ", ""),
+            "reports": ctx.get("RUN_REPORTS_SEQ", ""),
+            "status": ctx.get("RUN_STATUS_SEQ", ""),
+            "state": ctx.get("RUN_STATE_SEQ", ""),
+            "sessions": ctx.get("RUN_SESSIONS_SEQ", ""),
+            "workerResults": ctx.get("WORKER_RESULTS_SEQ", ""),
+        },
+        "taskType": ctx.get("ANALYSIS_TYPE", ""),
+        "workCategory": task_manifest.get("workCategory", ctx.get("WORKFLOW_WORK_CATEGORY", "unknown")),
+        "status": ctx.get("CURRENT_RUN_STATUS", ""),
+        "taskBriefPath": ctx.get("BRIEF_RELATIVE_PATH", ""),
+        "promptSnapshotPath": ctx.get("RUN_PROMPT_SNAPSHOT_RELATIVE_PATH", ""),
+        "workerPromptDirectoryPath": ctx.get("RUN_PROMPTS_RELATIVE_PATH", ""),
+        "workerPromptPathByWorkerId": {item: worker_prompt_paths[item] for item in reviewers},
+        "reportPath": ctx.get("LATEST_REPORT_RELATIVE_PATH") or ctx.get("FINAL_REPORT_RELATIVE_PATH", ""),
+        "teamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
+        "resumeCommandPath": ctx.get("CLAUDE_RESUME_COMMAND_RELATIVE_PATH", ""),
+        "relatedTasks": json.loads(ctx.get("RELATED_TASKS_JSON", "[]")),
+        "workflowSnapshot": {
+            "phaseSequence": workflow.get("phaseSequence", []),
+            "currentPhase": workflow.get("currentPhase", ""),
+            "currentPhaseState": workflow.get("currentPhaseState", ""),
+            "phaseStates": workflow.get("phaseStates", {}),
+            "lastCompletedPhase": workflow.get("lastCompletedPhase", ""),
+            "nextRecommendedPhase": workflow.get("nextRecommendedPhase", ""),
+            "awaitingApproval": workflow.get("awaitingApproval", False),
+            "routingStatus": workflow.get("routingStatus", ""),
+            "lastSafeCheckpoint": workflow.get("lastSafeCheckpoint", {}),
+        },
+    })
+    payload = {
+        "schemaVersion": "1.0",
+        "projectId": ctx.get("PROJECT_ID", ""),
+        "taskGroup": ctx.get("TASK_GROUP", ""),
+        "taskId": ctx.get("TASK_ID", ""),
+        "taskKey": ctx.get("TASK_KEY", ""),
+        "runs": filtered,
+    }
+    _write_json(path, payload)
+
+
+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 = {}
+    if task_manifest_path.exists():
+        try:
+            task_manifest = json.loads(task_manifest_path.read_text(encoding="utf-8"))
+        except Exception:
+            task_manifest = {}
+    workflow = task_manifest.get("workflow", {}) if isinstance(task_manifest.get("workflow"), dict) else {}
+    phase_states = workflow.get("phaseStates", {}) if isinstance(workflow.get("phaseStates"), dict) else {}
+    phase_order = workflow.get("phaseSequence", [])
+    if not isinstance(phase_order, list) or not phase_order:
+        phase_order = [
+            "requirements-discovery", "error-analysis",
+            "implementation-planning", "implementation", "final-verification",
+        ]
+    phase_state_lines = [
+        f"- `{phase}`: `{phase_states.get(phase, 'not-started')}`"
+        for phase in phase_order
+    ]
+    checkpoint = workflow.get("lastSafeCheckpoint", {}) if isinstance(workflow.get("lastSafeCheckpoint"), dict) else {}
+    checkpoint_lines = [
+        f"- Label: `{checkpoint.get('label', 'unknown')}`",
+        f"- Run manifest: `{checkpoint.get('latestRunManifestPath', ctx.get('RUN_MANIFEST_RELATIVE_PATH', ''))}`",
+        f"- Team state: `{checkpoint.get('latestTeamStatePath', ctx.get('TEAM_STATE_RELATIVE_PATH', ''))}`",
+        f"- Report: `{checkpoint.get('latestReportPath', task_manifest.get('latestReportPath', '--')) or '--'}`",
+        f"- Resume command: `{checkpoint.get('latestResumeCommandPath', task_manifest.get('latestResumeCommandPath', '--')) or '--'}`",
+    ]
+    rc = task_manifest.get("resultContract") if isinstance(task_manifest.get("resultContract"), dict) else {}
+    cv = task_manifest.get("contractValidation") if isinstance(task_manifest.get("contractValidation"), dict) else {}
+    art = task_manifest.get("artifacts") if isinstance(task_manifest.get("artifacts"), dict) else {}
+    mapping = {
+        "{{TASK_KEY}}": task_manifest.get("taskKey", ctx.get("TASK_KEY", "")),
+        "{{TASK_TYPE}}": task_manifest.get("taskType", ctx.get("ANALYSIS_TYPE", "")),
+        "{{CURRENT_TASK_STATUS}}": task_manifest.get("currentStatus", ctx.get("CURRENT_TASK_STATUS", "")),
+        "{{CURRENT_RUN_STATUS}}": task_manifest.get("latestRunStatus", ctx.get("CURRENT_RUN_STATUS", "")),
+        "{{RELATED_TASKS_INLINE}}": ctx.get("RELATED_TASKS_INLINE", "None"),
+        "{{RECOMMENDED_ANALYSERS}}": ", ".join(task_manifest.get("recommendedWorkers", [])),
+        "{{LEAD_MODEL}}": rc.get("leadModel", ctx.get("LEAD_MODEL_DISPLAY", "")),
+        "{{LATEST_RUN_RELATIVE_PATH}}": task_manifest.get("latestRunPath", ctx.get("LATEST_RUN_RELATIVE_PATH", "")),
+        "{{LATEST_REPORT_RELATIVE_PATH}}": task_manifest.get("latestReportPath", ctx.get("LATEST_REPORT_RELATIVE_PATH", "")),
+        "{{TEAM_STATE_RELATIVE_PATH}}": task_manifest.get("teamStatePath", ctx.get("TEAM_STATE_RELATIVE_PATH", "")),
+        "{{VALIDATION_STATUS}}": cv.get("status", ctx.get("VALIDATION_STATUS", "not-run")),
+        "{{CLAUDE_RESUME_COMMAND_RELATIVE_PATH}}": task_manifest.get("latestResumeCommandPath", ctx.get("CLAUDE_RESUME_COMMAND_RELATIVE_PATH", "")),
+        "{{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', '')}`",
+        ]),
+        "{{TASK_MANIFEST_RELATIVE_PATH}}": task_manifest.get("taskManifestPath", ctx.get("TASK_MANIFEST_RELATIVE_PATH", "")),
+        "{{OKSTRA_LATEST_TASK_RELATIVE_PATH}}": ctx.get("OKSTRA_LATEST_TASK_RELATIVE_PATH", ""),
+        "{{INSTRUCTION_SET_RELATIVE_PATH}}": task_manifest.get("instructionSetPath", ctx.get("INSTRUCTION_SET_RELATIVE_PATH", "")),
+        "{{REFERENCE_EXPECTATIONS_RELATIVE_PATH}}": task_manifest.get("referenceExpectationsPath", ctx.get("REFERENCE_EXPECTATIONS_RELATIVE_PATH", "")),
+        "{{FINAL_REPORT_TEMPLATE_RELATIVE_PATH}}": art.get("finalReportTemplatePath", ctx.get("FINAL_REPORT_TEMPLATE_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}}": task_manifest.get("latestRunPromptsPath", 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", ""),
+        "{{WORKER_RESULTS_RELATIVE_PATH}}": art.get("workerResultsDirectoryPath", ctx.get("WORKER_RESULTS_RELATIVE_PATH", "")),
+        "{{RUN_VALIDATOR_RELATIVE_PATH}}": cv.get("validatorScriptPath", ctx.get("RUN_VALIDATOR_RELATIVE_PATH", "")),
+        "{{WORK_CATEGORY}}": task_manifest.get("workCategory", ctx.get("WORKFLOW_WORK_CATEGORY", "unknown")),
+        "{{WORKFLOW_CURRENT_PHASE}}": workflow.get("currentPhase", ctx.get("WORKFLOW_CURRENT_PHASE", "")),
+        "{{WORKFLOW_CURRENT_PHASE_STATE}}": workflow.get("currentPhaseState", ctx.get("WORKFLOW_CURRENT_PHASE_STATE", "")),
+        "{{WORKFLOW_LAST_COMPLETED_PHASE}}": workflow.get("lastCompletedPhase", ctx.get("WORKFLOW_LAST_COMPLETED_PHASE", "")) or "--",
+        "{{WORKFLOW_NEXT_RECOMMENDED_PHASE}}": workflow.get("nextRecommendedPhase", ctx.get("WORKFLOW_NEXT_RECOMMENDED_PHASE", "")),
+        "{{WORKFLOW_AWAITING_APPROVAL}}": "yes" if workflow.get("awaitingApproval", False) else "no",
+        "{{WORKFLOW_ROUTING_STATUS}}": workflow.get("routingStatus", ctx.get("WORKFLOW_ROUTING_STATUS", "")),
+        "{{WORKFLOW_PHASE_STATE_LINES}}": "\n".join(phase_state_lines),
+        "{{WORKFLOW_LAST_SAFE_CHECKPOINT_LINES}}": "\n".join(checkpoint_lines),
+    }
+    rendered = template
+    for k, v in mapping.items():
+        rendered = rendered.replace(k, v)
+    _write_text(Path(output_path), rendered.rstrip() + "\n")
+
+
+# --------------------------------------------------------------------------- #
+# launch.template.md rendering
+# --------------------------------------------------------------------------- #
+
+
+def render_template_file(template_path: str, output_path: str, ctx: dict) -> None:
+    template = Path(template_path).read_text(encoding="utf-8")
+    selected = _resolve_workers(ctx)
+    catalog = _worker_catalog(ctx)
+    lead_model = ctx.get("LEAD_MODEL_DISPLAY", "")
+    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 = []
+    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 = []
+    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."
+    )
+
+    mapping = {
+        "{{PROJECT_ID}}": ctx.get("PROJECT_ID", ""),
+        "{{TASK_GROUP}}": ctx.get("TASK_GROUP", ""),
+        "{{TASK_ID}}": ctx.get("TASK_ID", ""),
+        "{{TASK_KEY}}": ctx.get("TASK_KEY", ""),
+        "{{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", ""),
+        "{{LEAD_MODEL}}": lead_model,
+        "{{LEAD_MODEL_EXECUTION_VALUE}}": lead_model_execution,
+        "{{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", ""),
+    }
+    rendered = template
+    for k, v in mapping.items():
+        rendered = rendered.replace(k, v)
+    _write_text(Path(output_path), rendered.rstrip() + "\n")
+
+
+# --------------------------------------------------------------------------- #
+# CLI dispatcher
+# --------------------------------------------------------------------------- #
+
+
+def main(argv: list[str]) -> int:
+    if not argv:
+        print("usage: python3 -m okstra_ctl.render <subcommand> ...", file=sys.stderr)
+        return 2
+    sub = argv[0]
+    rest = argv[1:]
+    try:
+        if sub == "team-state":
+            ctx_path, team_state_path = rest
+            render_team_state(team_state_path, _load_ctx(ctx_path))
+        elif sub == "reference-expectations":
+            ctx_path, brief_path, output_path = rest
+            render_reference_expectations(brief_path, output_path, _load_ctx(ctx_path))
+        elif sub == "task-catalog-discovery":
+            ctx_path, output_path = rest
+            render_task_catalog_discovery(output_path, _load_ctx(ctx_path))
+        elif sub == "latest-task-discovery":
+            ctx_path, output_path = rest
+            render_latest_task_discovery(output_path, _load_ctx(ctx_path))
+        elif sub == "migrate-legacy":
+            (ctx_path,) = rest
+            migrate_legacy_run_artifacts(_load_ctx(ctx_path))
+        elif sub == "task-manifest":
+            ctx_path, manifest_path = rest
+            render_task_manifest(manifest_path, _load_ctx(ctx_path))
+        elif sub == "run-manifest":
+            ctx_path, run_manifest_path = rest
+            render_run_manifest(run_manifest_path, _load_ctx(ctx_path))
+        elif sub == "timeline":
+            ctx_path, timeline_path = rest
+            render_timeline(timeline_path, _load_ctx(ctx_path))
+        elif sub == "task-index":
+            ctx_path, template_path, output_path = rest
+            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))
+        else:
+            print(f"unknown subcommand: {sub}", file=sys.stderr)
+            return 2
+    except Exception as exc:
+        print(f"render {sub} failed: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))