okstra 0.34.0 → 0.36.0

package/runtime/python/okstra_ctl/run.py

@@ -15,10 +15,13 @@ state passing, and are read once at the start.
 """
 from __future__ import annotations
 
+import importlib.util
 import json
 import os
 import re
 import shutil
+import subprocess as _subprocess
+import sys
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from pathlib import Path
@@ -35,6 +38,8 @@ from .material import (
 from .models import resolve_model_metadata
 from .path_resolve import relative_to_project_root, resolve_user_file
 from .render import (
+    apply_lead_prompt_defaults,
+    inject_lead_prompt_computed_tokens,
     render_latest_task_discovery,
     render_reference_expectations,
     render_run_manifest,
@@ -42,13 +47,17 @@ from .render import (
     render_task_index,
     render_task_manifest,
     render_team_state,
-    render_template_file,
+    render_template_with_ctx,
     render_timeline,
 )
 from .run_context import compute_and_write_run_context, write_run_inputs
 from .seeding import (
+    AgentsMdLinkError,
+    ClaudeMdLinkError,
     SettingsLinkError,
     cleanup_obsolete_generated_docs,
+    ensure_project_agents_md,
+    ensure_project_claude_md,
     ensure_project_settings_symlink,
     installed_version,
     verify_installation,
@@ -67,21 +76,30 @@ from .workers import (
 from .workflow import compute_workflow_state
 from .worktree import provision_task_worktree
 
-# Validator regex for the approval marker.
+# Frontmatter approval-flag matcher.
 #
-# Tolerates a single optional backtick on either side of the approval token,
-# because the report template instructs the user to flip `[ ]` to `[x]` inside
-# a markdown code span and the report-writer worker often emits a standalone
-# marker line wrapped the same way (e.g. `- ` + backtick + `[x] Approved` +
-# backtick). Backticks carry no semantic content here — stripping them at the
-# parser level is simpler than threading a "please remove formatting" rule
-# through every authoring surface.
-APPROVED_PLAN_PATTERN = re.compile(
-    r"^[ \t]*(?:[-*+][ \t]+)?`?(APPROVED([ \t]|:|$|`)|\[x\][ \t]*Approved`?|"
-    r"User[ \t]+Approval[ \t]*:[ \t]*(APPROVED|granted|yes)`?)",
+# Final-report 의 YAML frontmatter 안에서 `approved: true` / `approved: false`
+# 한 줄만 식별한다. report-writer 가 항상 이 한 줄을 출력하고, 사용자가
+# 직접 편집하거나 `--approve` CLI 가 이 줄만 toggle 한다. 본문(body) 의 다른
+# `approved:` 등장과 충돌하지 않도록 호출자는 frontmatter 블록을 먼저 추출
+# (`_extract_frontmatter_block`) 한 뒤 이 패턴을 적용한다.
+APPROVED_FRONTMATTER_PATTERN = re.compile(
+    r"^approved:[ \t]+(true|false)[ \t]*$",
     re.IGNORECASE | re.MULTILINE,
 )
 
+_FRONTMATTER_BLOCK_PATTERN = re.compile(r"\A---\n(.*?)\n---\n", re.DOTALL)
+
+
+def _extract_frontmatter_block(body: str) -> str | None:
+    """final-report 의 leading `---` 펜스 사이에 든 YAML 블록 텍스트를 반환.
+
+    펜스가 없거나 닫히지 않으면 None. report-writer 의 표준 산출물은 항상
+    `---\\n...frontmatter...\\n---\\n` 로 시작한다.
+    """
+    m = _FRONTMATTER_BLOCK_PATTERN.match(body)
+    return m.group(1) if m else None
+
 
 class PrepareError(Exception):
     """surface to caller — task bundle prepare failed."""
@@ -108,6 +126,7 @@ class PrepareInputs:
     work_category: str = ""
     base_ref: str = ""
     approved_plan_path: str = ""
+    stage: str = "auto"
     clarification_response_path: str = ""  # absolute or empty
     # release-handoff 전용: PR 본문 템플릿 1회성 override. 빈 문자열이면
     # project.json → global config → 스킬 디폴트 순으로 해석된다.
@@ -137,25 +156,35 @@ def _validate_approved_plan(path: str) -> None:
     if not p.is_file():
         raise PrepareError(f"approved plan file not found: {path}")
     body = p.read_text(encoding="utf-8", errors="replace")
-    if not APPROVED_PLAN_PATTERN.search(body):
+    frontmatter = _extract_frontmatter_block(body)
+    if frontmatter is None:
         raise PrepareError(
-            f"approved plan has no recognised user-approval marker: {path}\n"
-            '  canonical form (single line, top-of-report block): "- [x] Approved"\n'
-            '  also accepted (case-insensitive, line-anchored, optional leading bullet): '
-            '"APPROVED", "[x] Approved", "User Approval: APPROVED|granted|yes"\n'
-            "  shortcut: re-run okstra with --approve to have the CLI itself "
-            "record the approval marker on this file."
+            f"approved plan has no YAML frontmatter block: {path}\n"
+            "  expected the report to begin with `---\\n...\\n---\\n`. "
+            "report-writer worker emits this header on every run; "
+            "regenerate the report if the header is missing."
         )
-    # The approval marker is set. Cross-check the §5 Clarification Items
-    # table: any row with Blocks=approval that is still open/answered
-    # invalidates the approval. Legacy reports (no unified §5 with a
-    # Blocks column) return None — soft-pass to preserve compatibility
-    # during the transitional release.
+    m = APPROVED_FRONTMATTER_PATTERN.search(frontmatter)
+    if not m:
+        raise PrepareError(
+            f"approved plan frontmatter has no `approved:` field: {path}\n"
+            "  expected a single line of the form `approved: true` "
+            "(or `approved: false` for the unflipped state)."
+        )
+    if m.group(1).lower() != "true":
+        raise PrepareError(
+            f"approved plan is not yet approved (frontmatter `approved: {m.group(1)}`): {path}\n"
+            "  open the report and change the frontmatter line to `approved: true`, "
+            "or re-run okstra with `--approve` to flip it from the CLI.\n"
+            "  resolve any `Blocks=approval` rows in `## 5. Clarification Items` first."
+        )
+    # frontmatter approved == true 상태. §5 Clarification Items 의
+    # Blocks=approval 행이 아직 open/answered 면 승인을 무효화한다.
     blockers = unresolved_approval_blockers(body)
     if blockers:
         lines = [
-            f"approved plan marker is set but §5 has {len(blockers)} unresolved "
-            f"`Blocks=approval` row(s); resolve them or mark them obsolete before approving:",
+            f"approved plan frontmatter has `approved: true` but §5 has {len(blockers)} "
+            f"unresolved `Blocks=approval` row(s); resolve them or mark them obsolete first:",
         ]
         for b in blockers:
             lines.append(f"  - {b.row_id} (Status={b.raw_status})")
@@ -163,31 +192,121 @@ def _validate_approved_plan(path: str) -> None:
         raise PrepareError("\n".join(lines))
 
 
-# `- [ ] Approved` 라인을 정확히 한 번만 매치한다. 좌측 leading whitespace 와
-# 옵션 bullet 은 보존된 채 체크박스 안쪽 공백만 `x` 로 갱신된다.
-#
-# Group 1: leading whitespace + optional bullet + optional opening backtick.
-# Group 2: optional closing backtick + trailing whitespace.
-# Both groups are preserved verbatim in the replacement so a backtick-wrapped
-# `- \`[ ] Approved\`` flips to `- \`[x] Approved\`` without losing the
-# surrounding code span — the validator regex tolerates either form.
-APPROVAL_UNCHECKED_PATTERN = re.compile(
-    r"^([ \t]*(?:[-*+][ \t]+)?`?)\[[ \t]\][ \t]*Approved(`?[ \t]*)$",
-    re.IGNORECASE | re.MULTILINE,
+_STAGE_VALIDATOR_PATH = (
+    Path(__file__).resolve().parents[2] / "validators"
+    / "validate-implementation-plan-stages.py"
 )
 
 
+def _validate_stage_structure(plan_path: str) -> None:
+    """Run validators/validate-implementation-plan-stages.py against the approved plan."""
+    r = _subprocess.run(
+        [sys.executable, str(_STAGE_VALIDATOR_PATH), "--plan", plan_path],
+        capture_output=True, text=True,
+    )
+    if r.returncode != 0:
+        raise PrepareError(
+            f"approved plan failed stage validation:\n{r.stderr.strip()}"
+        )
+
+
+def _resolve_effective_stage(
+    stages: list,
+    done_stages: set,
+    requested: str,
+) -> int:
+    """Return the stage number to execute.
+
+    `requested` is either "auto" or a decimal string.
+    Raises PrepareError on all rejection cases.
+    """
+    if requested == "auto":
+        for s in stages:
+            if s["stage_number"] in done_stages:
+                continue
+            if all(d in done_stages for d in s["depends_on"]):
+                return s["stage_number"]
+        raise PrepareError(
+            "no stage is ready: every remaining stage has unsatisfied depends-on"
+        )
+    try:
+        n = int(requested)
+    except ValueError:
+        raise PrepareError(
+            f"--stage must be 'auto' or an integer, got {requested!r}"
+        )
+    target = next((s for s in stages if s["stage_number"] == n), None)
+    if target is None:
+        raise PrepareError(
+            f"--stage {n} not in Stage Map "
+            f"(have {[s['stage_number'] for s in stages]})"
+        )
+    if n in done_stages:
+        raise PrepareError(
+            f"--stage {n} already completed (consumers.jsonl status:done exists)"
+        )
+    return n
+
+
+def _parse_stage_map_into_ctx(plan_path: str) -> list:
+    """Reuse the validator's parser to extract StageMeta dicts for the ctx."""
+    text = Path(plan_path).read_text(encoding="utf-8")
+    spec = importlib.util.spec_from_file_location(
+        "_ip_stage_validator", _STAGE_VALIDATOR_PATH
+    )
+    if spec is None or spec.loader is None:
+        raise PrepareError(f"cannot load stage validator at {_STAGE_VALIDATOR_PATH}")
+    mod = importlib.util.module_from_spec(spec)
+    # Register before exec_module so dataclass field-type resolution can find
+    # the module in sys.modules (required on Python 3.9).
+    sys.modules["_ip_stage_validator"] = mod
+    try:
+        spec.loader.exec_module(mod)
+    finally:
+        sys.modules.pop("_ip_stage_validator", None)
+    stages, _errs = mod._parse_stage_map(text)
+    return [
+        {
+            "stage_number": s.stage_number,
+            "title": s.title,
+            "depends_on": list(s.depends_on),
+            "step_count": s.step_count,
+            "exit_contract_summary": s.exit_contract_summary,
+        }
+        for s in stages
+    ]
+
+
 def _apply_cli_approval(path: str) -> str:
-    """`--approve` 가 지정된 경우 approved-plan 파일에 사용자 승인 마커를 새겨 넣는다.
+    """`--approve` 가 지정된 경우 approved-plan 의 frontmatter `approved` 를 true 로 토글.
+
+    동작 요약:
+      - frontmatter 에 `approved: false` 가 있으면 `approved: true` 로 교체하고
+        audit 라인을 append → `"frontmatter-flipped"` 반환.
+      - 이미 `approved: true` 면 한 번도 기록되지 않은 audit 라인만 append →
+        `"already-approved-audit-appended"`, 이미 동일 audit 가 있으면
+        `"already-approved"` 로 no-op.
+      - frontmatter 가 없거나 `approved:` 라인이 없으면 PrepareError.
 
-    Returns a short human-readable description of the action taken (used in the
-    runtime audit line). Idempotent: if the file already carries a valid
-    approval marker, no edits are written and `"already-approved"` is returned.
+    Idempotent: 동일 audit 라인은 한 번만 기록된다.
     """
     p = Path(path)
     if not p.is_file():
         raise PrepareError(f"approved plan file not found: {path}")
     body = p.read_text(encoding="utf-8", errors="replace")
+    frontmatter = _extract_frontmatter_block(body)
+    if frontmatter is None:
+        raise PrepareError(
+            f"--approve was given but the approved-plan file has no YAML frontmatter: {path}\n"
+            "  expected the report to begin with `---\\n...\\n---\\n`."
+        )
+    m = APPROVED_FRONTMATTER_PATTERN.search(frontmatter)
+    if not m:
+        raise PrepareError(
+            f"--approve was given but the approved-plan frontmatter has no `approved:` field: {path}\n"
+            "  expected a single line of the form `approved: false` "
+            "(report-writer worker emits this by default)."
+        )
 
     audit_iso = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
     audit_line = (
@@ -195,37 +314,28 @@ def _apply_cli_approval(path: str) -> str:
         "(user CLI invocation treated as approval signal)"
     )
 
-    if APPROVED_PLAN_PATTERN.search(body):
-        # 이미 사용자(또는 이전 --approve 호출)가 마커를 남긴 상태. audit 라인이
-        # 없으면 보조적으로 한 줄만 추가하고 마커 자체는 건드리지 않는다.
+    if m.group(1).lower() == "true":
         if audit_line.split(" — ")[1] in body:
             return "already-approved"
         new_body = body.rstrip("\n") + "\n" + audit_line + "\n"
         p.write_text(new_body, encoding="utf-8")
         return "already-approved-audit-appended"
 
-    if APPROVAL_UNCHECKED_PATTERN.search(body):
-        new_body, count = APPROVAL_UNCHECKED_PATTERN.subn(
-            lambda m: f"{m.group(1)}[x] Approved{m.group(2)}", body, count=1,
-        )
-        new_body = new_body.rstrip("\n") + "\n" + audit_line + "\n"
-        p.write_text(new_body, encoding="utf-8")
-        return "checkbox-flipped"
-
-    raise PrepareError(
-        f"--approve was given but the approved-plan file has no `User Approval Request` "
-        f"checkbox to flip: {path}\n"
-        "  expected a line of the form `- [ ] Approved` near the top of the report "
-        "(see templates/reports/final-report.template.md)."
+    flipped_frontmatter = APPROVED_FRONTMATTER_PATTERN.sub(
+        "approved: true", frontmatter, count=1,
     )
+    new_body = body.replace(frontmatter, flipped_frontmatter, 1)
+    new_body = new_body.rstrip("\n") + "\n" + audit_line + "\n"
+    p.write_text(new_body, encoding="utf-8")
+    return "frontmatter-flipped"
 
 
 def _ensure_task_directories(ctx: dict) -> None:
     for key in (
-        "TASK_ROOT", "INSTRUCTION_SET_DIR", "RUNS_DIR", "HISTORY_DIR",
+        "TASK_ROOT", "INSTRUCTION_SET_PATH", "RUNS_DIR", "HISTORY_DIR",
         "RUN_DIR", "RUN_MANIFESTS_DIR", "RUN_STATE_DIR", "RUN_PROMPTS_DIR",
         "RUN_REPORTS_DIR", "RUN_STATUS_DIR", "RUN_SESSIONS_DIR",
-        "RUN_LOGS_DIR", "WORKER_RESULTS_DIR", "OKSTRA_DISCOVERY_DIR",
+        "RUN_LOGS_DIR", "WORKER_RESULTS_PATH", "RUN_CARRY_PATH", "OKSTRA_DISCOVERY_DIR",
     ):
         Path(ctx[key]).mkdir(parents=True, exist_ok=True)
 
@@ -329,11 +439,11 @@ def _record_start(
             project_root=ctx["PROJECT_ROOT"],
             task_group=ctx["TASK_GROUP"],
             task_id=ctx["TASK_ID"],
-            task_type=ctx.get("ANALYSIS_TYPE", ""),
+            task_type=ctx.get("TASK_TYPE", ""),
             run_seq=int(ctx["RUN_MANIFESTS_SEQ"]),
             when=ctx["RUN_TIMESTAMP_ISO"],
-            workers=[w for w in ctx.get("SELECTED_REVIEWERS", "").split(",") if w],
-            lead_model=ctx.get("LEAD_MODEL_DISPLAY", ""),
+            workers=[w for w in ctx.get("RECOMMENDED_ANALYSERS", "").split(",") if w],
+            lead_model=ctx.get("LEAD_MODEL", ""),
             run_dir_rel=ctx.get("RUN_DIR_RELATIVE_PATH", ""),
             final_report_rel=ctx.get("FINAL_REPORT_RELATIVE_PATH", ""),
             final_status_rel=ctx.get("FINAL_STATUS_RELATIVE_PATH", ""),
@@ -358,7 +468,7 @@ def _brief_sha256(path: Path) -> str:
 
 def _canonical_argv(inp: PrepareInputs, ctx: dict) -> list[str]:
     """rerun 충실 재현을 위한 canonical argv 재구성."""
-    workers = inp.workers_override or ctx.get("SELECTED_REVIEWERS", "")
+    workers = inp.workers_override or ctx.get("RECOMMENDED_ANALYSERS", "")
     pairs = [
         ("--task-type", inp.task_type),
         ("--project-id", inp.project_id),
@@ -369,11 +479,11 @@ def _canonical_argv(inp: PrepareInputs, ctx: dict) -> list[str]:
         ("--approved-plan", inp.approved_plan_path),
         ("--clarification-response", inp.clarification_response_path),
         ("--workers", workers),
-        ("--lead-model", inp.lead_model or ctx.get("LEAD_MODEL_DISPLAY", "")),
-        ("--claude-model", inp.claude_model or ctx.get("CLAUDE_WORKER_MODEL_DISPLAY", "")),
-        ("--codex-model", inp.codex_model or ctx.get("CODEX_WORKER_MODEL_DISPLAY", "")),
-        ("--gemini-model", inp.gemini_model or ctx.get("GEMINI_WORKER_MODEL_DISPLAY", "")),
-        ("--report-writer-model", inp.report_writer_model or ctx.get("REPORT_WRITER_MODEL_DISPLAY", "")),
+        ("--lead-model", inp.lead_model or ctx.get("LEAD_MODEL", "")),
+        ("--claude-model", inp.claude_model or ctx.get("CLAUDE_WORKER_MODEL", "")),
+        ("--codex-model", inp.codex_model or ctx.get("CODEX_WORKER_MODEL", "")),
+        ("--gemini-model", inp.gemini_model or ctx.get("GEMINI_WORKER_MODEL", "")),
+        ("--report-writer-model", inp.report_writer_model or ctx.get("REPORT_WRITER_MODEL", "")),
         ("--executor", inp.executor or ctx.get("EXECUTOR_PROVIDER", "")),
         ("--related-tasks", inp.related_tasks_raw),
         ("--work-category", inp.work_category),
@@ -471,17 +581,25 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
             )
         if inp.approve_plan_ack:
             # 사용자가 직접 `--approve` 를 입력한 행위 자체를 승인 의사로 모델링한다.
-            # 파일을 먼저 갱신한 뒤 동일한 검증 경로를 그대로 통과시킨다 — 검증
-            # 책임을 단일 지점(`_validate_approved_plan`)으로 유지한다.
+            # 파일의 frontmatter approved 를 true 로 toggle 한 뒤 동일한 검증
+            # 경로(`_validate_approved_plan`) 를 그대로 통과시킨다.
             _apply_cli_approval(inp.approved_plan_path)
         _validate_approved_plan(inp.approved_plan_path)
-    elif inp.approve_plan_ack:
-        # implementation 외 task-type 에서 `--approve` 는 의미가 없다. 사용자에게
-        # 정확한 시점을 알려주기 위해 조용히 무시하지 않고 즉시 거부한다.
-        raise PrepareError(
-            "--approve is only meaningful with --task-type implementation "
-            "and --approved-plan <path>"
-        )
+        _validate_stage_structure(inp.approved_plan_path)
+        ctx_stage_map = _parse_stage_map_into_ctx(inp.approved_plan_path)
+    else:
+        if inp.approve_plan_ack:
+            # implementation 외 task-type 에서 `--approve` 는 의미가 없다. 사용자에게
+            # 정확한 시점을 알려주기 위해 조용히 무시하지 않고 즉시 거부한다.
+            raise PrepareError(
+                "--approve is only meaningful with --task-type implementation "
+                "and --approved-plan <path>"
+            )
+        if inp.stage != "auto":
+            raise PrepareError(
+                f"--stage is only meaningful with --task-type implementation; "
+                f"got {inp.task_type}"
+            )
     if inp.clarification_response_path and not Path(inp.clarification_response_path).is_file():
         raise PrepareError(
             f"clarification response file not found: {inp.clarification_response_path}"
@@ -660,7 +778,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     profile_content = _expand_profile_includes(profile_file)
     review_material = build_analysis_material(inp.brief_path, inp.directive)
     related_items = resolve_related_tasks(
-        task_manifest_path=Path(ctx["TASK_MANIFEST_FILE"]),
+        task_manifest_path=Path(ctx["TASK_MANIFEST_PATH"]),
         raw_related=inp.related_tasks_raw,
     )
     related_tasks_json_str = json.dumps(related_items, ensure_ascii=False)
@@ -686,25 +804,24 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
 
     # ---- assemble full ctx (the values render functions expect) ----
     ctx.update({
-        "REVIEW_PROFILE": inp.task_type,
-        "SELECTED_REVIEWERS": selected_reviewers,
+        "ANALYSIS_PROFILE": inp.task_type,
+        "RECOMMENDED_ANALYSERS": selected_reviewers,
         "PR_TEMPLATE_PATH": pr_template_path_str,
         "PR_TEMPLATE_SOURCE": pr_template_source,
         "CLAUDE_SESSION_ID": claude_session_id,
         "CLARIFICATION_RESPONSE_PATH": inp.clarification_response_path,
-        "CLARIFICATION_RESPONSE_FILE": inp.clarification_response_path,
         "CLARIFICATION_RESPONSE_RELATIVE_PATH": clarification_relative,
         "BRIEF_FILE_PATH": str(inp.brief_path),
         "BRIEF_RELATIVE_PATH": brief_relative,
-        "LEAD_MODEL_DISPLAY": lead.display,
+        "LEAD_MODEL": lead.display,
         "LEAD_MODEL_EXECUTION_VALUE": lead.execution,
-        "CLAUDE_WORKER_MODEL_DISPLAY": cw.display,
+        "CLAUDE_WORKER_MODEL": cw.display,
         "CLAUDE_WORKER_MODEL_EXECUTION_VALUE": cw.execution,
-        "CODEX_WORKER_MODEL_DISPLAY": co.display,
+        "CODEX_WORKER_MODEL": co.display,
         "CODEX_WORKER_MODEL_EXECUTION_VALUE": co.execution,
-        "GEMINI_WORKER_MODEL_DISPLAY": ge.display,
+        "GEMINI_WORKER_MODEL": ge.display,
         "GEMINI_WORKER_MODEL_EXECUTION_VALUE": ge.execution,
-        "REPORT_WRITER_MODEL_DISPLAY": rw.display,
+        "REPORT_WRITER_MODEL": rw.display,
         "REPORT_WRITER_MODEL_EXECUTION_VALUE": rw.execution,
         "EXECUTOR_PROVIDER": executor_provider,
         "EXECUTOR_DISPLAY_NAME": executor_display_name,
@@ -725,12 +842,39 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         "OKSTRA_VERSION": installed_version(),
         **workflow_state,
     })
+    if inp.task_type == "implementation":
+        ctx["parsed_stage_map"] = ctx_stage_map
+        # Resolve effective stage and append `started` row to consumers.jsonl
+        from .consumers import read_consumers, append_consumer
+        import datetime as _dt
+        plan_run_root = Path(inp.approved_plan_path).resolve().parents[1]
+        consumed = read_consumers(plan_run_root)
+        done_stages = {r["stage"] for r in consumed if r.get("status") == "done"}
+        effective = _resolve_effective_stage(
+            ctx["parsed_stage_map"], done_stages, inp.stage
+        )
+        ctx["effective_stage"] = effective
+        inp.stage = str(effective)
+        print(f"selected stage: {inp.stage}", file=sys.stdout)
+        head_proc = _subprocess.run(
+            ["git", "rev-parse", "HEAD"],
+            cwd=inp.project_root, capture_output=True, text=True,
+        )
+        head_sha = head_proc.stdout.strip() if head_proc.returncode == 0 else ""
+        append_consumer(
+            plan_run_root,
+            impl_task_key=ctx["TASK_KEY"],
+            stage=effective,
+            status="started",
+            started_at=_dt.datetime.now(_dt.timezone.utc).isoformat(),
+            head_commit=head_sha,
+        )
 
     # ---- prepare directories + cleanup ----
     _ensure_task_directories(ctx)
     _migrate_legacy_run_artifacts(ctx)
     cleanup_obsolete_generated_docs(
-        project_root=project_root, instruction_set_dir=Path(ctx["INSTRUCTION_SET_DIR"]),
+        project_root=project_root, instruction_set_dir=Path(ctx["INSTRUCTION_SET_PATH"]),
     )
     # Always materialise the resume command script. Even in --render-only
     # preparation flows the user (or a later non-interactive runner) may
@@ -738,12 +882,12 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     # leaves runs/<phase>/sessions/ empty and the manifest pointing at a
     # path that does not exist.
     write_claude_resume_command_file(
-        resume_command_path=Path(ctx["CLAUDE_RESUME_COMMAND_FILE"]),
+        resume_command_path=Path(ctx["CLAUDE_RESUME_COMMAND_PATH"]),
         project_root=project_root, claude_session_id=claude_session_id,
     )
 
     # ---- write instruction-set scaffolding ----
-    instruction_set = Path(ctx["INSTRUCTION_SET_DIR"])
+    instruction_set = Path(ctx["INSTRUCTION_SET_PATH"])
     instruction_set.mkdir(parents=True, exist_ok=True)
     profile_rendered = profile_content
     for key in (
@@ -772,10 +916,17 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     render_reference_expectations(
         str(inp.brief_path), str(instruction_set / "reference-expectations.md"), ctx,
     )
-    render_template_file(
-        str(final_report_template), ctx["FINAL_REPORT_TEMPLATE_FILE"], ctx,
+    # inject populates ctx with compute + default tokens consumed by the lead
+    # prompt render below (claude-execution-prompt.md). The final-report
+    # template render is effectively a copy (Jinja2 `{{ var }}` syntax does
+    # not match `_TOKEN_RE`); routed through render_template_with_ctx for SOT
+    # consistency.
+    inject_lead_prompt_computed_tokens(ctx)
+    apply_lead_prompt_defaults(ctx)
+    render_template_with_ctx(
+        str(final_report_template), ctx["FINAL_REPORT_TEMPLATE_PATH"], ctx,
     )
-    render_template_file(
+    render_template_with_ctx(
         str(prompt_template), str(instruction_set / "claude-execution-prompt.md"), ctx,
     )
     prompt_text = (instruction_set / "claude-execution-prompt.md").read_text(encoding="utf-8")
@@ -810,12 +961,12 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     if inp.render_only:
         ctx["CURRENT_TASK_STATUS"] = "instruction-set-generated"
         ctx["CURRENT_RUN_STATUS"] = "prepared"
-        ctx["LATEST_REPORT_PATH"] = ctx["FINAL_REPORT_FILE"]
+        ctx["LATEST_REPORT_PATH"] = ctx["FINAL_REPORT_PATH"]
         ctx["LATEST_REPORT_RELATIVE_PATH"] = ctx["FINAL_REPORT_RELATIVE_PATH"]
     else:
         ctx["CURRENT_TASK_STATUS"] = "claude-session-started"
         ctx["CURRENT_RUN_STATUS"] = "in-progress"
-        ctx["LATEST_REPORT_PATH"] = ctx["FINAL_REPORT_FILE"]
+        ctx["LATEST_REPORT_PATH"] = ctx["FINAL_REPORT_PATH"]
         ctx["LATEST_REPORT_RELATIVE_PATH"] = ctx["FINAL_REPORT_RELATIVE_PATH"]
     ctx.update(compute_workflow_state(
         task_type=inp.task_type,
@@ -824,11 +975,11 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         render_only=inp.render_only,
         work_category=inp.work_category,
     ))
-    render_team_state(ctx["TEAM_STATE_FILE"], ctx)
-    render_task_manifest(ctx["TASK_MANIFEST_FILE"], ctx)
-    render_task_index(str(task_index_template), ctx["TASK_INDEX_FILE"], ctx)
-    render_run_manifest(ctx["RUN_MANIFEST_FILE"], ctx)
-    render_timeline(ctx["TIMELINE_FILE"], ctx)
+    render_team_state(ctx["TEAM_STATE_PATH"], ctx)
+    render_task_manifest(ctx["TASK_MANIFEST_PATH"], ctx)
+    render_task_index(str(task_index_template), ctx["TASK_INDEX_PATH"], ctx)
+    render_run_manifest(ctx["RUN_MANIFEST_PATH"], ctx)
+    render_timeline(ctx["TIMELINE_PATH"], ctx)
     render_task_catalog_discovery(ctx["OKSTRA_TASK_CATALOG_FILE"], ctx)
     render_latest_task_discovery(ctx["OKSTRA_LATEST_TASK_FILE"], ctx)
 
@@ -867,6 +1018,31 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
                     file=__import__("sys").stderr,
                 )
 
+        try:
+            claude_md_link = ensure_project_claude_md(project_root=Path(inp.project_root))
+        except ClaudeMdLinkError as exc:
+            print(
+                f"okstra-claude-md: failed to provision project CLAUDE.md import — "
+                f"Claude Code sessions in this project will not auto-load okstra guidance. ({exc})",
+                file=__import__("sys").stderr,
+            )
+        else:
+            if claude_md_link is None:
+                print(
+                    "okstra-claude-md: ~/.okstra/templates/okstra.CLAUDE.md missing — "
+                    "re-run 'npx okstra@latest install' to provision the symlink target.",
+                    file=__import__("sys").stderr,
+                )
+
+        try:
+            ensure_project_agents_md(project_root=Path(inp.project_root))
+        except AgentsMdLinkError as exc:
+            print(
+                f"okstra-agents-md: failed to provision <PROJECT>/AGENTS.md symlink — "
+                f"codex / aider sessions in this project will not auto-load okstra guidance. ({exc})",
+                file=__import__("sys").stderr,
+            )
+
     return PrepareOutputs(
         ctx=ctx,
         prompt_text=prompt_text,
@@ -898,14 +1074,22 @@ def main(argv: list[str]) -> int:
     p.add_argument("--executor", default="")
     p.add_argument("--related-tasks", default="", dest="related_tasks_raw")
     p.add_argument("--approved-plan", default="", dest="approved_plan_path")
+    p.add_argument(
+        "--stage", default="auto", dest="stage",
+        help=(
+            "implementation task only. Which Stage Map entry to execute. "
+            "'auto' (default) = lowest-numbered stage whose depends-on are all "
+            "consumers.jsonl status:done. Numeric '<N>' = force that stage."
+        ),
+    )
     p.add_argument(
         "--approve",
         action="store_true",
         dest="approve_plan_ack",
         help=(
             "Treat the CLI invocation itself as the plan approval signal. "
-            "Flips `- [ ] Approved` to `- [x] Approved` in the --approved-plan file "
-            "and appends an audit line."
+            "Flips `approved: false` to `approved: true` in the --approved-plan file's "
+            "YAML frontmatter and appends an audit line."
         ),
     )
     p.add_argument("--clarification-response", default="", dest="clarification_response_path")
@@ -992,6 +1176,7 @@ def main(argv: list[str]) -> int:
         work_category=args.work_category,
         base_ref=args.base_ref,
         approved_plan_path=args.approved_plan_path,
+        stage=args.stage,
         clarification_response_path=clarification_abs,
         pr_template_path=args.pr_template_path,
         render_only=args.render_only,
@@ -1010,18 +1195,18 @@ def main(argv: list[str]) -> int:
     print(f"okstra task root: {ctx['TASK_ROOT']}")
     print(f"okstra latest task discovery file: {ctx['OKSTRA_LATEST_TASK_FILE']}")
     print(f"okstra task catalog file: {ctx['OKSTRA_TASK_CATALOG_FILE']}")
-    print(f"okstra instruction-set: {ctx['INSTRUCTION_SET_DIR']}")
+    print(f"okstra instruction-set: {ctx['INSTRUCTION_SET_PATH']}")
     print(f"okstra reference expectations: {ctx['REFERENCE_EXPECTATIONS_FILE']}")
-    print(f"okstra final report template: {ctx['FINAL_REPORT_TEMPLATE_FILE']}")
+    print(f"okstra final report template: {ctx['FINAL_REPORT_TEMPLATE_PATH']}")
     if inputs.render_only:
         print()
         print(out.prompt_text, end="")
     else:
         print(f"okstra current run dir: {ctx['RUN_DIR']}")
-        print(f"final report path: {ctx['FINAL_REPORT_FILE']}")
-        print(f"lead model: {ctx['LEAD_MODEL_DISPLAY']}")
+        print(f"final report path: {ctx['FINAL_REPORT_PATH']}")
+        print(f"lead model: {ctx['LEAD_MODEL']}")
         print(f"claude session id: {ctx['CLAUDE_SESSION_ID']}")
-        print(f"resume command file: {ctx['CLAUDE_RESUME_COMMAND_FILE']}")
+        print(f"resume command file: {ctx['CLAUDE_RESUME_COMMAND_PATH']}")
         print("launch mode: interactive Claude handoff")
         print(f"claude working directory: {ctx['PROJECT_ROOT']}")
         print()
@@ -1031,7 +1216,7 @@ def main(argv: list[str]) -> int:
             "claudeSessionId": ctx["CLAUDE_SESSION_ID"],
             "leadModelExecutionValue": ctx["LEAD_MODEL_EXECUTION_VALUE"],
             "projectRoot": ctx["PROJECT_ROOT"],
-            "promptFile": str(Path(ctx["INSTRUCTION_SET_DIR"]) / "claude-execution-prompt.md"),
+            "promptFile": str(Path(ctx["INSTRUCTION_SET_PATH"]) / "claude-execution-prompt.md"),
         }
         print(f"__OKSTRA_LAUNCH__ {json.dumps(machine)}")
     return 0