okstra 0.75.0 → 0.77.0

package/runtime/python/okstra_ctl/lead_events.py

@@ -0,0 +1,129 @@
+"""Structured JSONL events emitted by non-Claude lead runtimes."""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Mapping
+
+
+REQUIRED_FIELDS = (
+    "eventType",
+    "leadRuntime",
+    "taskKey",
+    "taskType",
+    "runSeq",
+    "timestamp",
+    "details",
+)
+
+
+class LeadEventParseError(ValueError):
+    """Raised when a lead-events JSONL file contains an invalid row."""
+
+    def __init__(self, path: Path, line_number: int, message: str) -> None:
+        super().__init__(f"{path}:{line_number}: {message}")
+        self.path = path
+        self.line_number = line_number
+
+
+@dataclass(frozen=True)
+class LeadEvent:
+    event_type: str
+    lead_runtime: str
+    task_key: str
+    task_type: str
+    run_seq: str
+    timestamp: str
+    details: Mapping[str, Any] = field(default_factory=dict)
+
+    def to_record(self) -> dict[str, Any]:
+        return {
+            "eventType": self.event_type,
+            "leadRuntime": self.lead_runtime,
+            "taskKey": self.task_key,
+            "taskType": self.task_type,
+            "runSeq": self.run_seq,
+            "timestamp": self.timestamp,
+            "details": _stable_json_value(dict(self.details)),
+        }
+
+    @classmethod
+    def from_record(cls, record: Mapping[str, Any]) -> "LeadEvent":
+        missing = [field_name for field_name in REQUIRED_FIELDS
+                   if field_name not in record]
+        if missing:
+            raise ValueError(
+                "missing required lead event field(s): " + ", ".join(missing)
+            )
+        details = record["details"]
+        if not isinstance(details, Mapping):
+            raise ValueError("lead event details must be a JSON object")
+        return cls(
+            event_type=_require_string(record, "eventType"),
+            lead_runtime=_require_string(record, "leadRuntime"),
+            task_key=_require_string(record, "taskKey"),
+            task_type=_require_string(record, "taskType"),
+            run_seq=_require_string(record, "runSeq"),
+            timestamp=_require_string(record, "timestamp"),
+            details=dict(details),
+        )
+
+
+def append_lead_event(path: Path, event: LeadEvent) -> None:
+    """Append one lead event as compact JSONL, creating parent directories."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a", encoding="utf-8") as f:
+        f.write(_event_json(event) + "\n")
+
+
+def read_lead_events(path: Path) -> list[LeadEvent]:
+    """Parse a lead-events JSONL file.
+
+    Missing files read as an empty log. Blank lines are ignored. Malformed JSON
+    and malformed event objects fail loudly with path and line number context.
+    """
+    if not path.is_file():
+        return []
+    events: list[LeadEvent] = []
+    for line_number, line in enumerate(
+        path.read_text(encoding="utf-8").splitlines(), start=1
+    ):
+        stripped = line.strip()
+        if not stripped:
+            continue
+        try:
+            record = json.loads(stripped)
+        except json.JSONDecodeError as exc:
+            raise LeadEventParseError(path, line_number, "invalid JSON") from exc
+        if not isinstance(record, Mapping):
+            raise LeadEventParseError(
+                path, line_number, "lead event row must be a JSON object"
+            )
+        try:
+            events.append(LeadEvent.from_record(record))
+        except ValueError as exc:
+            raise LeadEventParseError(path, line_number, str(exc)) from exc
+    return events
+
+
+def _event_json(event: LeadEvent) -> str:
+    return json.dumps(event.to_record(), ensure_ascii=False, separators=(",", ":"))
+
+
+def _require_string(record: Mapping[str, Any], field_name: str) -> str:
+    value = record[field_name]
+    if not isinstance(value, str) or not value:
+        raise ValueError(f"lead event {field_name} must be a non-empty string")
+    return value
+
+
+def _stable_json_value(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        return {
+            key: _stable_json_value(value[key])
+            for key in sorted(value)
+        }
+    if isinstance(value, list):
+        return [_stable_json_value(item) for item in value]
+    return value

package/runtime/python/okstra_ctl/paths.py

@@ -175,6 +175,7 @@ def compute_run_paths(
     final_status = run_status / f"final{suffixes['status']}.status"
     team_state = run_state / f"team-state{suffixes['state']}.json"
     active_run_context = run_state / f"active-run-context{suffixes['state']}.json"
+    lead_events = run_state / f"lead-events-{task_type_segment}-{seqs['state']}.jsonl"
     final_report_template = instruction_set / "final-report-template.md"
     final_report_schema = instruction_set / "final-report-schema.json"
     reference_expectations = instruction_set / "reference-expectations.md"
@@ -241,6 +242,7 @@ def compute_run_paths(
         "FINAL_STATUS_PATH": str(final_status),
         "TEAM_STATE_PATH": str(team_state),
         "ACTIVE_RUN_CONTEXT_PATH": str(active_run_context),
+        "LEAD_EVENTS_PATH": str(lead_events),
         "FINAL_REPORT_TEMPLATE_PATH": str(final_report_template),
         "FINAL_REPORT_SCHEMA_PATH": str(final_report_schema),
         "REFERENCE_EXPECTATIONS_FILE": str(reference_expectations),
@@ -301,6 +303,7 @@ def compute_run_paths(
         ("FINAL_STATUS_RELATIVE_PATH", final_status),
         ("TEAM_STATE_RELATIVE_PATH", team_state),
         ("ACTIVE_RUN_CONTEXT_RELATIVE_PATH", active_run_context),
+        ("LEAD_EVENTS_RELATIVE_PATH", lead_events),
         ("WORKER_RESULTS_RELATIVE_PATH", worker_results),
         ("RUN_CARRY_RELATIVE_PATH", run_carry),
         ("FINAL_REPORT_TEMPLATE_RELATIVE_PATH", final_report_template),

package/runtime/python/okstra_ctl/pr_template.py

@@ -6,7 +6,7 @@ release-handoff 단계에서 lead 가 PR 본문을 작성할 때 사용하는
     1. per-run override (okstra-run Step 6 에서 입력)
     2. project: <project_root>/.okstra/project.json 의 ``prTemplatePath``
     3. global:  ~/.okstra/config.json 의 ``prTemplatePath``
-    4. default: 스킬 설치 디렉터리의 ``okstra-run/templates/pr-body.template.md``
+    4. default: 스킬 설치 디렉터리의 ``templates/prd/pr-body.template.md``
 
 경로는 절대경로 또는 ``~`` 시작 경로를 권장한다. 상대경로일 경우 project
 스코프는 ``project_root`` 기준, override 는 호출자 cwd 기준으로 해석한다.

package/runtime/python/okstra_ctl/render.py

@@ -66,6 +66,37 @@ def _write_json(path: Path, payload: dict) -> None:
     _write_text(path, json.dumps(payload, indent=2, ensure_ascii=False) + "\n")
 
 
+def _lead_runtime(ctx: dict) -> str:
+    return ctx.get("LEAD_RUNTIME", "") or "claude-code"
+
+
+def _lead_agent(ctx: dict) -> str:
+    return "codex" if _lead_runtime(ctx) == "codex" else "claude"
+
+
+def _lead_agent_label(ctx: dict) -> str:
+    return "Codex CLI" if _lead_runtime(ctx) == "codex" else "Claude Code"
+
+
+def _lead_role(ctx: dict) -> str:
+    return "Codex lead" if _lead_runtime(ctx) == "codex" else "Claude lead"
+
+
+def _lead_adapter(ctx: dict) -> dict:
+    runtime = _lead_runtime(ctx)
+    if runtime == "codex":
+        return {
+            "name": "codex",
+            "dispatchMode": "render-only",
+            "sessionAccounting": "artifact-only",
+        }
+    return {
+        "name": "claude-code",
+        "dispatchMode": "team",
+        "sessionAccounting": "claude-jsonl",
+    }
+
+
 _PHASE_BLOCK_RE = re.compile(
     r"\{% if header\.taskType == '(implementation-planning|release-handoff|implementation|final-verification)' %\}\n(.*?)\{% endif %\}\n",
     re.DOTALL,
@@ -415,11 +446,14 @@ def render_team_state(team_state_path: str, ctx: dict) -> None:
         "schemaVersion": "1.0",
         "taskKey": ctx.get("TASK_KEY", ""),
         "taskType": ctx.get("TASK_TYPE", ""),
+        "leadRuntime": _lead_runtime(ctx),
+        "leadAdapter": _lead_adapter(ctx),
+        "leadEventsPath": ctx.get("LEAD_EVENTS_RELATIVE_PATH", ""),
         "runDirectoryPath": ctx.get("RUN_DIR_RELATIVE_PATH", ""),
         "workflowState": ctx.get("CURRENT_RUN_STATUS", ""),
         "lead": {
-            "role": "Claude lead",
-            "agent": "claude",
+            "role": _lead_role(ctx),
+            "agent": _lead_agent(ctx),
             "model": ctx.get("LEAD_MODEL", ""),
             "modelExecutionValue": ctx.get("LEAD_MODEL_EXECUTION_VALUE", ""),
             "status": ctx.get("CURRENT_RUN_STATUS", ""),
@@ -876,7 +910,9 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
     catalog = _worker_catalog(ctx)
     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"] + [
+    lead_agent = _lead_agent(ctx)
+    lead_role = _lead_role(ctx)
+    required_agent_status_entries = [lead_role] + [
         catalog[item]["role"] for item in reviewers
     ]
     related_tasks = json.loads(ctx.get("RELATED_TASKS_JSON", "[]"))
@@ -925,6 +961,8 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
         "taskIdPathSegment": ctx.get("TASK_ID_SEGMENT", ""),
         "projectRoot": ctx.get("PROJECT_ROOT", ""),
         "taskType": ctx.get("TASK_TYPE", ""),
+        "leadRuntime": _lead_runtime(ctx),
+        "leadAdapter": _lead_adapter(ctx),
         "workCategory": work_category,
         "taskBriefPath": ctx.get("BRIEF_RELATIVE_PATH", ""),
         "recommendedWorkers": reviewers,
@@ -984,16 +1022,17 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
             "resumeCommandPath": ctx.get("CLAUDE_RESUME_COMMAND_RELATIVE_PATH", ""),
             "teamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
             "activeRunContextPath": ctx.get("ACTIVE_RUN_CONTEXT_RELATIVE_PATH", ""),
+            "leadEventsPath": ctx.get("LEAD_EVENTS_RELATIVE_PATH", ""),
             "workerResultsDirectoryPath": ctx.get("WORKER_RESULTS_RELATIVE_PATH", ""),
             "validatorScriptPath": ctx.get("RUN_VALIDATOR_RELATIVE_PATH", ""),
         },
         "resultContract": {
-            "leadAgent": "claude",
-            "leadRole": "Claude lead",
+            "leadAgent": lead_agent,
+            "leadRole": lead_role,
             "leadModel": ctx.get("LEAD_MODEL", ""),
             "leadModelExecutionValue": ctx.get("LEAD_MODEL_EXECUTION_VALUE", ""),
             "leadExecutionMode": "synthesis-only",
-            "finalSynthesisOwner": "Claude lead",
+            "finalSynthesisOwner": lead_role,
             "artifactFirst": True,
             "resultCollectionMode": "claude-managed",
             "finalReportFormat": "markdown",
@@ -1127,6 +1166,8 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
     catalog = _worker_catalog(ctx)
     required_worker_roles = _required_worker_roles(ctx, reviewers)
     worker_prompt_paths = {item: catalog[item]["promptPath"] for item in reviewers}
+    lead_agent = _lead_agent(ctx)
+    lead_role = _lead_role(ctx)
     related_tasks = json.loads(ctx.get("RELATED_TASKS_JSON", "[]"))
     workflow = (
         task_manifest.get("workflow", {})
@@ -1149,6 +1190,8 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
         "taskId": ctx.get("TASK_ID", ""),
         "taskKey": ctx.get("TASK_KEY", ""),
         "taskType": ctx.get("TASK_TYPE", ""),
+        "leadRuntime": _lead_runtime(ctx),
+        "leadAdapter": _lead_adapter(ctx),
         "workCategory": task_manifest.get(
             "workCategory", ctx.get("WORKFLOW_WORK_CATEGORY", "unknown")
         ),
@@ -1174,6 +1217,7 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
             "workerResults": ctx.get("WORKER_RESULTS_SEQ", ""),
         },
         "runManifestPath": ctx.get("RUN_MANIFEST_RELATIVE_PATH", ""),
+        "leadEventsPath": ctx.get("LEAD_EVENTS_RELATIVE_PATH", ""),
         "promptSnapshotPath": ctx.get("RUN_PROMPT_SNAPSHOT_RELATIVE_PATH", ""),
         "workerPromptsDirectoryPath": ctx.get("RUN_PROMPTS_RELATIVE_PATH", ""),
         "workerPromptPathByWorkerId": worker_prompt_paths,
@@ -1216,15 +1260,15 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
             "lastSafeCheckpoint": workflow.get("lastSafeCheckpoint", {}),
         },
         "teamContract": {
-            "leadAgent": "claude",
-            "leadRole": "Claude lead",
+            "leadAgent": lead_agent,
+            "leadRole": lead_role,
             "leadModel": ctx.get("LEAD_MODEL", ""),
             "leadModelExecutionValue": ctx.get("LEAD_MODEL_EXECUTION_VALUE", ""),
             "leadExecutionMode": "synthesis-only",
-            "finalSynthesisOwner": "Claude lead",
+            "finalSynthesisOwner": lead_role,
             "requiredWorkerAttempts": reviewers,
             "requiredWorkerRoles": required_worker_roles,
-            "requiredAgentStatusEntries": ["Claude lead"]
+            "requiredAgentStatusEntries": [lead_role]
             + [catalog[item]["role"] for item in reviewers],
             "requireDistinctLeadFromClaudeWorker": True,
             "requireAllRequiredWorkerAttempts": True,
@@ -1425,6 +1469,12 @@ def render_task_index(template_path: str, output_path: str, ctx: dict) -> None:
         if isinstance(task_manifest.get("artifacts"), dict)
         else {}
     )
+    lead_role = rc.get("leadRole", _lead_role(ctx))
+    latest_resume_command = (
+        task_manifest.get("latestResumeCommandPath")
+        or ctx.get("CLAUDE_RESUME_COMMAND_RELATIVE_PATH", "")
+        or "--"
+    )
     mapping = {
         "{{TASK_KEY}}": task_manifest.get("taskKey", ctx.get("TASK_KEY", "")),
         "{{TASK_TYPE}}": task_manifest.get("taskType", ctx.get("TASK_TYPE", "")),
@@ -1456,13 +1506,10 @@ def render_task_index(template_path: str, output_path: str, ctx: dict) -> None:
         "{{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", ""),
-        ),
+        "{{CLAUDE_RESUME_COMMAND_RELATIVE_PATH}}": latest_resume_command,
         "{{MODEL_ASSIGNMENT_LINES}}": "\n".join(
             [
-                f"- `Claude lead`: `{rc.get('leadModel', ctx.get('LEAD_MODEL', ''))}`",
+                f"- `{lead_role}`: `{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', '')}`",
@@ -1597,22 +1644,22 @@ def build_available_mcp_servers_block(project_root: Path) -> str:
 
 
 def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
-    """Populate ctx in-place with the 9 derived lead-prompt tokens.
+    """Populate ctx in-place with 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.
+    Tokens that are not 1:1 with a ctx key (TEAM_CREATION_GATE, lead identity
+    blocks, worker dispatch guidance, worker result/status summaries, etc.) 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
+    Always overwrites — caller-supplied values for these computed 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_runtime = _lead_runtime(ctx)
+    lead_role = _lead_role(ctx)
+    lead_agent_label = _lead_agent_label(ctx)
     lead_model = ctx.get("LEAD_MODEL", "")
     lead_model_execution = ctx.get("LEAD_MODEL_EXECUTION_VALUE", "")
 
@@ -1622,16 +1669,16 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
         return f"- `{role}`: `{model}`"
 
     worker_result_lines: list[str] = []
-    team_role_lines = [f"  1. `Claude lead` (assigned model: `{lead_model}`)"]
+    team_role_lines = [f"  1. `{lead_role}` (assigned model: `{lead_model}`)"]
     model_assignment_lines = [
-        fmt_assignment("Claude lead", lead_model, lead_model_execution)
+        fmt_assignment(lead_role, lead_model, lead_model_execution)
     ]
     worker_role_labels: list[str] = []
-    execution_status_entries = ["`Claude lead`"]
+    execution_status_entries = [f"`{lead_role}`"]
     execution_status_table_lines = [
         "| 에이전트 | 역할 | 모델 | 상태 | 핵심 발견 요약 |",
         "|----------|------|------|------|----------------|",
-        f"| Claude Code | Claude lead | {lead_model} | completed / timeout / error / not-run | 최종 synthesis 작성 상태와 핵심 판단 |",
+        f"| {lead_agent_label} | {lead_role} | {lead_model} | completed / timeout / error / not-run | 최종 synthesis 작성 상태와 핵심 판단 |",
     ]
     for index, worker in enumerate(selected, start=2):
         m = catalog[worker]
@@ -1682,18 +1729,50 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
     # - All other phases keep the full team-creation contract.
     task_type = ctx.get("TASK_TYPE", "")
     concurrent_stages = str(ctx.get("CONCURRENT_RUN_STAGES", "") or "").strip()
+    codex_dispatch_command = (
+        "okstra codex-dispatch "
+        f"--project-root {ctx.get('PROJECT_ROOT', '')} "
+        f"--run-manifest {ctx.get('RUN_MANIFEST_RELATIVE_PATH', '')}"
+    )
     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"
+            f"convergence loop. The {lead_role} 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."
         )
+    elif lead_runtime == "codex":
+        team_creation_gate_block = (
+            "## Codex Dispatch Gate (BLOCKING)\n"
+            "\n"
+            "This run was prepared for `leadRuntime=codex`. Do NOT call\n"
+            "`TeamCreate`, do NOT call Claude Code `Agent(...)`, and do NOT\n"
+            "invoke Claude slash skills. Codex dispatch is artifact-first and\n"
+            "uses the prepared run manifest plus CLI-backed worker wrappers.\n"
+            "\n"
+            "Required actions, in order:\n"
+            "\n"
+            "1. Inspect the run manifest and team-state paths listed below.\n"
+            "2. Emit `PROGRESS: phase-3-team-create skipped (codex-dispatch)`;\n"
+            "   there is no Claude Teams surface in this adapter.\n"
+            "3. Plan worker execution with:\n"
+            f"   `{codex_dispatch_command} --dry-run`\n"
+            "4. Dispatch supported Codex-side workers with:\n"
+            f"   `{codex_dispatch_command}`\n"
+            "   When `--workers` is omitted, unsupported roster entries such as\n"
+            "   `claude` are skipped with explicit `not-run` reasons.\n"
+            "5. Run `report-writer` only with explicit opt-in:\n"
+            f"   `{codex_dispatch_command} --enable-codex-report-writer --report-writer-codex-model <model>`\n"
+            "\n"
+            "`okstra codex-dispatch` records `team-state.dispatchMode`, writes\n"
+            "worker prompt histories when missing, persists worker results, and\n"
+            "runs post-report validation for the Codex report-writer path."
+        )
     elif task_type == "implementation" and concurrent_stages:
         team_creation_gate_block = (
             "## Concurrent-run: no-team background (BLOCKING)\n"
@@ -1773,8 +1852,60 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
             "response is to go back to step 2 — NOT to strip `team_name` and retry."
         )
 
+    if lead_runtime == "codex":
+        lead_intro_line = f"You are `{lead_role}` for project `{ctx.get('PROJECT_ID', '')}`."
+        lead_bootstrap_instruction = (
+            "Read the manifests below for all task metadata, paths, model "
+            "assignments, and worker roster. Use the Codex dispatch gate in this "
+            "prompt; do not invoke Claude Code skills."
+        )
+        lead_session_block = (
+            "## Session\n"
+            "\n"
+            "- Lead runtime: `codex`\n"
+            "- Codex run resume is artifact/checkpoint based; `okstra codex-run` "
+            "does not create a Claude session id."
+        )
+        worker_dispatch_guidance = (
+            "## Codex Worker Dispatch\n"
+            "\n"
+            "- Worker prompt paths in `task-manifest.json` are assigned history "
+            "locations. `okstra codex-dispatch` materializes missing prompt files "
+            "from the run manifest and active-run-context; existing prompt files "
+            "are never overwritten.\n"
+            "- Do not call `TeamCreate` or `Agent(...)`. Use the command in the "
+            "Codex Dispatch Gate above for worker execution.\n"
+            "- File presence is not a signal to skip. Worker selection and skipped "
+            "statuses come from `team-state`, never from the prompts directory."
+        )
+    else:
+        lead_intro_line = f"You are `{lead_role}` for project `{ctx.get('PROJECT_ID', '')}`."
+        lead_bootstrap_instruction = (
+            "Invoke the `okstra` skill now. Read the manifests below for all task "
+            "metadata, paths, model assignments, and worker roster."
+        )
+        lead_session_block = (
+            "## Session\n"
+            "\n"
+            f"- Session ID: `{ctx.get('CLAUDE_SESSION_ID', '')}`\n"
+            f"- Resume: `{ctx.get('CLAUDE_RESUME_COMMAND_RELATIVE_PATH', '')}`"
+        )
+        worker_dispatch_guidance = (
+            "## Worker Prompt Files (not pre-rendered)\n"
+            "\n"
+            "- The `runs/<phase>/prompts/<worker>-worker-prompt-*.md` files referenced in `task-manifest.json → artifacts.workerPromptPathByWorkerId` are **NOT** rendered by the okstra runtime. Those paths are the *assigned* locations where the prompt history MUST be written at dispatch time.\n"
+            "- Therefore: at the start of every phase the prompts/ directory is normally empty (or contains only previously-dispatched workers' files). This is expected. Do NOT narrate it as \"missing\", \"누락\", or \"not yet rendered\" — it just means dispatch has not happened yet.\n"
+            "- Before dispatching any required worker, **you (the lead) construct the worker prompt and persist it to the assigned absolute path using `Write`** (per `okstra-team-contract` rule 6). Only after persisting do you call the worker subagent (Agent tool / Codex / Gemini wrapper). The wrapper subagents will also re-write the same file on their end; the double-write is intentional and idempotent.\n"
+            "- Do not \"check if the file exists and skip dispatch\" — file presence is not a signal to skip. Worker selection and skipping rules come from team-state, never from prompts/ directory contents.\n"
+            f"- **Worker Preamble Path (single anchor — replaces inlined `[Required reading]` and `[Error reporting]` blocks).** Every worker prompt you construct MUST include the anchor header `**Worker Preamble Path:** {ctx.get('WORKER_PROMPT_PREAMBLE_PATH', str(Path.home() / '.okstra' / 'templates' / 'worker-prompt-preamble.md'))}`. The file at that path is the canonical SSOT for Required Reading + Error Reporting + Output sections; workers Read it end-to-end before producing output. Do NOT re-inline those blocks into worker prompt bodies — that is the legacy ~80-line dispatch boilerplate that this anchor is designed to replace."
+        )
+
     # Compute results (deterministic from ctx, 덮어쓰기)
+    ctx["LEAD_INTRO_LINE"] = lead_intro_line
+    ctx["LEAD_BOOTSTRAP_INSTRUCTION"] = lead_bootstrap_instruction
+    ctx["LEAD_SESSION_BLOCK"] = lead_session_block
     ctx["TEAM_CREATION_GATE"] = team_creation_gate_block
+    ctx["WORKER_DISPATCH_GUIDANCE"] = worker_dispatch_guidance
     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)