okstra 0.50.0 → 0.52.0

package/runtime/python/okstra_ctl/run.py

@@ -27,6 +27,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 
 from okstra_project import project_json_path, upsert_project_json
+from .analysis_packet import build_analysis_packet
 from .clarification_items import unresolved_approval_blockers
 from .qa_commands import format_errors as _format_qa_errors, validate_qa_commands
 from .material import (
@@ -36,12 +37,13 @@ from .material import (
     resolve_related_tasks,
 )
 from .final_report_schema import load_schema
-from .models import resolve_model_metadata
+from .models import ModelAssignment, resolve_model_metadata
 from .schema_excerpt import build_schema_excerpt
 from .path_resolve import relative_to_project_root, resolve_user_file
 from .render import (
     apply_lead_prompt_defaults,
     inject_lead_prompt_computed_tokens,
+    render_active_run_context,
     render_latest_task_discovery,
     render_reference_expectations,
     render_run_manifest,
@@ -86,6 +88,17 @@ APPROVED_FRONTMATTER_PATTERN = re.compile(
     re.IGNORECASE | re.MULTILINE,
 )
 
+# Frontmatter implementation-option matcher.
+#
+# `approved:` 바로 아래 줄의 `implementation-option:` 한 줄을 식별한다.
+# report-writer 가 빈 값으로 항상 emit 하므로 라인은 존재하되 값은 비어 있을
+# 수 있다. `--implementation-option <name>` CLI 가 이 줄의 값만 치환한다.
+# 값이 비면 implementation 은 plan 의 `Recommended Option` 으로 폴백한다.
+IMPLEMENTATION_OPTION_FRONTMATTER_PATTERN = re.compile(
+    r"^implementation-option:[ \t]*(.*)$",
+    re.MULTILINE,
+)
+
 _FRONTMATTER_BLOCK_PATTERN = re.compile(r"\A---\n(.*?)\n---\n", re.DOTALL)
 
 
@@ -132,6 +145,11 @@ class PrepareInputs:
     pr_template_path: str = ""
     render_only: bool = False
     approve_plan_ack: bool = False
+    # implementation 전용: 유저가 implementation-planning final-report 에서 고른
+    # Option Candidate 이름. `--implementation-option <name>` 으로 전달되어
+    # approved-plan frontmatter 의 `implementation-option:` 라인을 채운다. 빈
+    # 문자열이면 implementation 은 plan 의 `Recommended Option` 으로 폴백한다.
+    implementation_option: str = ""
     # Phase 6 plan-body verification opt-out. Default True (round runs after
     # report-writer draft). Flipped to False by CLI `--no-plan-verification`.
     # Only meaningful for `--task-type implementation-planning`; the manifest
@@ -345,6 +363,62 @@ def _apply_cli_approval(path: str) -> str:
     return "frontmatter-flipped"
 
 
+def _apply_cli_implementation_option(path: str, option_name: str) -> str:
+    """`--implementation-option <name>` 이 지정된 경우 approved-plan frontmatter 의
+    `implementation-option:` 라인 값을 `option_name` 으로 치환한다.
+
+    동작 요약:
+      - frontmatter 의 `implementation-option:` 라인을
+        `implementation-option: <option_name>` 으로 교체 → `"frontmatter-set"`.
+      - audit 라인을 한 번 append (idempotent: 동일 audit 라인은 한 번만).
+      - frontmatter 가 없거나 `implementation-option:` 라인이 없으면 PrepareError
+        (report-writer 가 빈 값으로 이 라인을 항상 emit 하므로 라인은 존재해야 한다).
+
+    `--approve` (`_apply_cli_approval`) 의 frontmatter-치환 + audit-append 패턴을
+    그대로 미러한다.
+    """
+    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"--implementation-option was given but the approved-plan file has no YAML frontmatter: {path}\n"
+            "  expected the report to begin with `---\\n...\\n---\\n`."
+        )
+    if not IMPLEMENTATION_OPTION_FRONTMATTER_PATTERN.search(frontmatter):
+        raise PrepareError(
+            f"--implementation-option was given but the approved-plan frontmatter has no "
+            f"`implementation-option:` field: {path}\n"
+            "  expected a single line of the form `implementation-option:` "
+            "(report-writer worker emits this empty by default)."
+        )
+
+    audit_iso = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    audit_line = (
+        f"- 선택 옵션 (CLI): {audit_iso} — `{option_name}` recorded by "
+        "`okstra --implementation-option` (user-selected Option Candidate)"
+    )
+
+    # 렌더 경로(`final-report.template.md` 의 `yaml_scalar`)와 동일하게 값을
+    # YAML 따옴표 처리한다. 옵션명은 보통 `: `(콜론+공백)를 포함하므로 따옴표
+    # 없이 쓰면 frontmatter 가 invalid YAML 이 되고 CLI/렌더 출력이 어긋난다.
+    # 함수 치환을 써서 quoted 값 안의 백슬래시/그룹 참조가 re 치환 문법으로
+    # 재해석되는 것까지 막는다 (리터럴 치환).
+    from .render_final_report import _yaml_scalar
+
+    quoted = _yaml_scalar(option_name)
+    set_frontmatter = IMPLEMENTATION_OPTION_FRONTMATTER_PATTERN.sub(
+        lambda _m: f"implementation-option: {quoted}", frontmatter, count=1,
+    )
+    new_body = body.replace(frontmatter, set_frontmatter, 1)
+    if audit_line.split(" — ")[1] not in new_body:
+        new_body = new_body.rstrip("\n") + "\n" + audit_line + "\n"
+    p.write_text(new_body, encoding="utf-8")
+    return "frontmatter-set"
+
+
 def _ensure_task_directories(ctx: dict) -> None:
     for key in (
         "TASK_ROOT", "INSTRUCTION_SET_PATH", "RUNS_DIR", "HISTORY_DIR",
@@ -492,6 +566,7 @@ def _canonical_argv(inp: PrepareInputs, ctx: dict) -> list[str]:
         ("--task-brief", str(inp.brief_path)),
         ("--directive", inp.directive),
         ("--approved-plan", inp.approved_plan_path),
+        ("--implementation-option", inp.implementation_option),
         ("--clarification-response", inp.clarification_response_path),
         ("--workers", workers),
         ("--lead-model", inp.lead_model or ctx.get("LEAD_MODEL", "")),
@@ -546,23 +621,42 @@ def _expand_profile_includes(profile_path: Path, _depth: int = 0) -> str:
     return _INCLUDE_DIRECTIVE.sub(_sub, text)
 
 
-def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
-    """Produce a complete okstra task bundle on disk. See module docstring."""
-    workspace_root = Path(inp.workspace_root)
-    project_root = Path(inp.project_root)
+# ---------------------------------------------------------------------------
+# prepare_task_bundle 의 단계(phase) 헬퍼.
+#
+# 왜 분리하는가: prepare_task_bundle 은 input 검증 → 에셋 해소 → 프로젝트 등록
+# → roster/model/executor 해소 → run-context/worktree → stage 예약 →
+# instruction-set/manifest 렌더 → central record 까지 8개 독립 책임을 순차로
+# 수행한다. 각 책임을 명시적 입력/반환을 갖는 헬퍼로 빼내면 (a) 개별 단위
+# 테스트가 가능해지고 (b) prepare_task_bundle 본문이 "무엇을 어떤 순서로
+# 엮는가" 만 드러내는 thin orchestrator 로 남는다. ctx dict 조립은 의도적으로
+# orchestrator 에 남겨 데이터 흐름을 한눈에 보이게 한다.
+# ---------------------------------------------------------------------------
+
+_INSTALL_HINT = (
+    " This file ships with the okstra package; its absence usually means a stale "
+    "or partial install. Run 'okstra ensure-installed' (or 'okstra install' again) "
+    "to repair the runtime. If the problem persists, run 'okstra doctor' for a "
+    "fuller diagnostic."
+)
 
-    # ---- validate inputs ----
-    # Hint suffix added to every "okstra runtime asset missing" PrepareError below.
-    # These files ship with the package and live under runtime/ — if any are
-    # missing the install is incomplete or stale, not a user-content issue.
-    _INSTALL_HINT = (
-        " This file ships with the okstra package; its absence usually means a stale "
-        "or partial install. Run 'okstra ensure-installed' (or 'okstra install' again) "
-        "to repair the runtime. If the problem persists, run 'okstra doctor' for a "
-        "fuller diagnostic."
-    )
-    profile_dir = workspace_root / "prompts" / "profiles"
-    profile_file = profile_dir / f"{inp.task_type}.md"
+
+@dataclass
+class _ResolvedAssets:
+    """런타임 에셋 경로 묶음. 모든 파일은 패키지와 함께 배포되며, 누락은
+    user-content 문제가 아니라 설치 불완전을 뜻한다 (_INSTALL_HINT)."""
+
+    profile_file: Path
+    prompt_template: Path
+    task_index_template: Path
+    final_report_template: Path
+    source_skill: Path
+    run_validator: Path
+
+
+def _resolve_runtime_assets(workspace_root: Path, inp: PrepareInputs) -> _ResolvedAssets:
+    """task-type 별 profile + 공통 템플릿/스킬/validator 경로를 해소하고 존재를 확인한다."""
+    profile_file = workspace_root / "prompts" / "profiles" / f"{inp.task_type}.md"
     if not profile_file.is_file():
         raise PrepareError(
             f"analysis profile file not found for task-type {inp.task_type}: "
@@ -586,10 +680,24 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
             raise PrepareError(
                 f"required okstra template or source skill missing: {required}.{_INSTALL_HINT}"
             )
+    return _ResolvedAssets(
+        profile_file=profile_file,
+        prompt_template=prompt_template,
+        task_index_template=task_index_template,
+        final_report_template=final_report_template,
+        source_skill=source_skill,
+        run_validator=run_validator,
+    )
+
+
+def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
+    """project_root/brief 존재와 task-type 별 입력 의미(plan 승인·stage·clarification)
+    를 검증하고, implementation 일 때 stage map 을 파싱해 돌려준다 (그 외엔 빈 리스트)."""
     if not project_root.is_dir():
         raise PrepareError(f"project root not found: {project_root}")
     if not inp.brief_path.is_file():
         raise PrepareError(f"task brief not found: {inp.brief_path}")
+    ctx_stage_map: list = []
     if inp.task_type == "implementation":
         if not inp.approved_plan_path:
             raise PrepareError(
@@ -600,6 +708,13 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
             # 파일의 frontmatter approved 를 true 로 toggle 한 뒤 동일한 검증
             # 경로(`_validate_approved_plan`) 를 그대로 통과시킨다.
             _apply_cli_approval(inp.approved_plan_path)
+        if inp.implementation_option:
+            # 유저가 고른 Option Candidate 이름을 approved-plan frontmatter 의
+            # `implementation-option:` 라인에 기록한다. 빈 값이면 implementation 이
+            # plan 의 `Recommended Option` 으로 폴백하므로 호출하지 않는다.
+            _apply_cli_implementation_option(
+                inp.approved_plan_path, inp.implementation_option
+            )
         _validate_approved_plan(inp.approved_plan_path)
         _validate_stage_structure(inp.approved_plan_path)
         ctx_stage_map = _parse_stage_map_into_ctx(inp.approved_plan_path)
@@ -611,6 +726,13 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
                 "--approve is only meaningful with --task-type implementation "
                 "and --approved-plan <path>"
             )
+        if inp.implementation_option:
+            # implementation 외 task-type 에서 `--implementation-option` 도 의미가
+            # 없다 (`--approve` 와 동일). 조용히 무시하지 않고 즉시 거부한다.
+            raise PrepareError(
+                "--implementation-option 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; "
@@ -620,11 +742,11 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         raise PrepareError(
             f"clarification response file not found: {inp.clarification_response_path}"
         )
+    return ctx_stage_map
 
-    # ---- installation check ----
-    verify_installation(workspace_root)
 
-    # ---- project.json upsert (self-registration) ----
+def _register_and_check_project(project_root: Path, inp: PrepareInputs) -> None:
+    """project.json self-registration + (implementation 한정) qaCommands gate 검증."""
     from okstra_project import ResolverError
 
     try:
@@ -652,95 +774,375 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
             if qa_errors:
                 raise PrepareError(_format_qa_errors(qa_errors))
 
-    # ---- workers resolution ----
-    # release-handoff is intentionally single-lead (no worker dispatch, no
-    # TeamCreate, no convergence). The profile has no `- Required workers:`
-    # block; force an empty roster regardless of any user override so the
-    # rendered task bundle stays consistent with the profile contract.
-    if inp.task_type == "release-handoff":
-        workers: list[str] = []
-    else:
-        profile_workers = resolve_profile_workers(profile_file)
-        profile_workers_csv = ",".join(profile_workers)
-        workers = normalize_workers(inp.workers_override or profile_workers_csv)
-        if inp.workers_override.strip():
-            validate_workers_against_profile(workers, profile_workers)
-        if not workers:
-            raise PrepareError(f"no workers resolved for profile: {inp.task_type}")
-    selected_reviewers = ",".join(workers)
-
-    # ---- PR template resolution (release-handoff only) ----
-    pr_template_path_str = ""
-    pr_template_source = ""
+
+def _resolve_roster(inp: PrepareInputs, profile_file: Path) -> tuple[list[str], str]:
+    """profile 의 `Required workers:` 블록을 권위로 roster 를 해소한다.
+
+    release-handoff 은 의도적으로 single-lead (worker dispatch / TeamCreate /
+    convergence 없음). profile 에 `- Required workers:` 블록이 없으므로 어떤
+    override 가 와도 빈 roster 를 강제해 profile 계약과 일관성을 유지한다."""
     if inp.task_type == "release-handoff":
-        try:
-            resolved_tpl = resolve_pr_template_path(
-                Path(inp.project_root), inp.pr_template_path
-            )
-        except PrTemplateError as exc:
-            raise PrepareError(f"PR template resolution failed: {exc}") from exc
-        pr_template_path_str = str(resolved_tpl.path)
-        pr_template_source = resolved_tpl.source
+        return [], ""
+    profile_workers = resolve_profile_workers(profile_file)
+    profile_workers_csv = ",".join(profile_workers)
+    workers = normalize_workers(inp.workers_override or profile_workers_csv)
+    if inp.workers_override.strip():
+        validate_workers_against_profile(workers, profile_workers)
+    if not workers:
+        raise PrepareError(f"no workers resolved for profile: {inp.task_type}")
+    return workers, ",".join(workers)
+
+
+def _resolve_pr_template(inp: PrepareInputs) -> tuple[str, str]:
+    """release-handoff 전용 PR 본문 템플릿 경로 + 출처를 해소한다 (그 외엔 빈 값)."""
+    if inp.task_type != "release-handoff":
+        return "", ""
+    try:
+        resolved_tpl = resolve_pr_template_path(Path(inp.project_root), inp.pr_template_path)
+    except PrTemplateError as exc:
+        raise PrepareError(f"PR template resolution failed: {exc}") from exc
+    return str(resolved_tpl.path), resolved_tpl.source
 
-    # ---- model assignments ----
+
+@dataclass
+class _ModelBindings:
+    """이 run 의 lead/worker 모델 + critic + executor 바인딩."""
+
+    lead: ModelAssignment
+    cw: ModelAssignment
+    co: ModelAssignment
+    ge: ModelAssignment
+    rw: ModelAssignment
+    critic_choice: str
+    executor_provider: str
+    executor_display_name: str
+    executor_worker_agent: str
+    executor_model_meta: ModelAssignment
+
+
+def _resolve_worker_models(inp: PrepareInputs) -> dict:
+    """lead/claude/codex/gemini/report-writer 모델을 alias → (display, execution) 로 해소."""
     lead_default = _default("OKSTRA_DEFAULT_LEAD_MODEL", "opus")
     claude_default = _default("OKSTRA_DEFAULT_CLAUDE_MODEL", "opus")
     codex_default = _default("OKSTRA_DEFAULT_CODEX_MODEL", "gpt-5.5")
     gemini_default = _default("OKSTRA_DEFAULT_GEMINI_MODEL", "auto")
     report_writer_default = _default("OKSTRA_DEFAULT_REPORT_WRITER_MODEL", lead_default)
-    lead = resolve_model_metadata(
-        provider="claude", raw_value=inp.lead_model,
-        default_display=lead_default, default_execution=lead_default,
-    )
-    cw = resolve_model_metadata(
-        provider="claude", raw_value=inp.claude_model,
-        default_display=claude_default, default_execution=claude_default,
-    )
-    co = resolve_model_metadata(
-        provider="codex", raw_value=inp.codex_model,
-        default_display=codex_default, default_execution=codex_default,
-    )
-    ge = resolve_model_metadata(
-        provider="gemini", raw_value=inp.gemini_model,
-        default_display=gemini_default, default_execution=gemini_default,
-    )
-    rw = resolve_model_metadata(
-        provider="claude", raw_value=inp.report_writer_model,
-        default_display=report_writer_default, default_execution=report_writer_default,
-    )
+    return {
+        "lead": resolve_model_metadata(
+            provider="claude", raw_value=inp.lead_model,
+            default_display=lead_default, default_execution=lead_default,
+        ),
+        "cw": resolve_model_metadata(
+            provider="claude", raw_value=inp.claude_model,
+            default_display=claude_default, default_execution=claude_default,
+        ),
+        "co": resolve_model_metadata(
+            provider="codex", raw_value=inp.codex_model,
+            default_display=codex_default, default_execution=codex_default,
+        ),
+        "ge": resolve_model_metadata(
+            provider="gemini", raw_value=inp.gemini_model,
+            default_display=gemini_default, default_execution=gemini_default,
+        ),
+        "rw": resolve_model_metadata(
+            provider="claude", raw_value=inp.report_writer_model,
+            default_display=report_writer_default, default_execution=report_writer_default,
+        ),
+    }
+
 
-    # ---- coverage critic choice (validated; phase-gating happens in render) ----
+def _resolve_model_bindings(inp: PrepareInputs, workers: list[str]) -> _ModelBindings:
+    """worker 모델 + critic 선택 + executor 바인딩을 한 묶음으로 해소·검증한다."""
+    m = _resolve_worker_models(inp)
     critic_choice = (inp.critic or "").strip().lower()
     if critic_choice not in ("", "off", "claude", "codex", "gemini"):
         raise PrepareError(
             f"--critic must be one of: off, claude, codex, gemini (got: {critic_choice!r})"
         )
-
-    # ---- executor binding (implementation phase only; recorded universally for manifest consistency) ----
     executor_default = _default("OKSTRA_DEFAULT_EXECUTOR", "claude")
     executor_provider = (inp.executor or executor_default).strip().lower()
     if executor_provider not in ("claude", "codex", "gemini"):
         raise PrepareError(
             f"--executor must be one of: claude, codex, gemini (got: {executor_provider!r})"
         )
-    if (
-        inp.task_type == "implementation"
-        and executor_provider not in workers
-    ):
+    if inp.task_type == "implementation" and executor_provider not in workers:
         raise PrepareError(
             f"--executor {executor_provider} requires {executor_provider!r} in "
             f"--workers, but resolved roster is {workers!r}. "
             f"Add it explicitly, e.g. --workers {','.join(sorted(set(workers + [executor_provider])))}."
         )
-    executor_provider_to_meta = {
-        "claude": ("Claude executor", "claude-worker", cw),
-        "codex": ("Codex executor", "codex-worker", co),
-        "gemini": ("Gemini executor", "gemini-worker", ge),
+    provider_to_meta = {
+        "claude": ("Claude executor", "claude-worker", m["cw"]),
+        "codex": ("Codex executor", "codex-worker", m["co"]),
+        "gemini": ("Gemini executor", "gemini-worker", m["ge"]),
     }
-    executor_display_name, executor_worker_agent, executor_model_meta = (
-        executor_provider_to_meta[executor_provider]
+    display_name, worker_agent, model_meta = provider_to_meta[executor_provider]
+    return _ModelBindings(
+        lead=m["lead"], cw=m["cw"], co=m["co"], ge=m["ge"], rw=m["rw"],
+        critic_choice=critic_choice,
+        executor_provider=executor_provider,
+        executor_display_name=display_name,
+        executor_worker_agent=worker_agent,
+        executor_model_meta=model_meta,
+    )
+
+
+def _reserve_implementation_stages(inp: PrepareInputs, ctx: dict, ctx_stage_map: list) -> None:
+    """implementation run 의 ready-set 배치를 선택하고 consumers.jsonl 에 stage 별
+    `started` 행을 예약한다. ctx 에 effective_stages / STAGE_BATCH_DIRECTIVE 를 채우고
+    inp.stage 를 확정된 배치 CSV 로 덮어쓴다."""
+    from .consumers import read_consumers, append_consumer
+    import datetime as _dt
+
+    ctx["parsed_stage_map"] = ctx_stage_map
+    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_stages(ctx["parsed_stage_map"], done_stages, inp.stage)
+    ctx["effective_stages"] = effective
+    csv = ",".join(str(n) for n in effective)
+    ctx["EFFECTIVE_STAGES"] = csv
+    ctx["STAGE_BATCH_DIRECTIVE"] = (
+        f"- **Stage batch for this implementation run:** `{csv}` "
+        "(comma-separated stage numbers, ascending). Execute exactly these "
+        "Stage Map stages in this order — this is the authoritative scope. "
+        "Do NOT recompute the start stage from `consumers.jsonl`; the runtime "
+        "already selected and reserved this batch."
+    )
+    inp.stage = csv
+    print(f"selected stages: {csv}", 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 ""
+    now = _dt.datetime.now(_dt.timezone.utc).isoformat()
+    for stage_n in effective:
+        append_consumer(
+            plan_run_root,
+            impl_task_key=ctx["TASK_KEY"],
+            stage=stage_n,
+            status="started",
+            started_at=now,
+            head_commit=head_sha,
+        )
+
+
+def _write_instruction_set_sources(
+    inp: PrepareInputs, ctx: dict, profile_content: str, review_material: str
+) -> Path:
+    """instruction-set 디렉터리에 profile/material/brief/clarification/directive 와
+    reference-expectations 를 기록하고 디렉터리 경로를 돌려준다."""
+    instruction_set = Path(ctx["INSTRUCTION_SET_PATH"])
+    instruction_set.mkdir(parents=True, exist_ok=True)
+    profile_rendered = profile_content
+    for key in (
+        "EXECUTOR_PROVIDER",
+        "EXECUTOR_DISPLAY_NAME",
+        "EXECUTOR_WORKER_AGENT",
+        "EXECUTOR_MODEL_DISPLAY",
+        "EXECUTOR_MODEL_EXECUTION_VALUE",
+        "EXECUTOR_WORKTREE_PATH",
+        "EXECUTOR_WORKTREE_BRANCH",
+        "EXECUTOR_WORKTREE_BASE_REF",
+        "EXECUTOR_WORKTREE_STATUS",
+        "EXECUTOR_WORKTREE_NOTE",
+    ):
+        profile_rendered = profile_rendered.replace("{{" + key + "}}", ctx.get(key, ""))
+    (instruction_set / "analysis-profile.md").write_text(profile_rendered, encoding="utf-8")
+    (instruction_set / "analysis-material.md").write_text(review_material, encoding="utf-8")
+    shutil.copyfile(inp.brief_path, instruction_set / "task-brief.md")
+    if inp.clarification_response_path:
+        shutil.copyfile(
+            inp.clarification_response_path,
+            instruction_set / "clarification-response.md",
+        )
+    if inp.directive:
+        (instruction_set / "directive.txt").write_text(inp.directive + "\n", encoding="utf-8")
+    render_reference_expectations(
+        str(inp.brief_path), str(instruction_set / "reference-expectations.md"), ctx,
+    )
+    packet = build_analysis_packet(
+        task_key=ctx["TASK_KEY"],
+        task_type=ctx["TASK_TYPE"],
+        task_brief_path=instruction_set / "task-brief.md",
+        analysis_profile_path=instruction_set / "analysis-profile.md",
+        reference_expectations_path=instruction_set / "reference-expectations.md",
+        clarification_response_path=(
+            instruction_set / "clarification-response.md"
+            if inp.clarification_response_path else None
+        ),
+        directive=inp.directive,
+        instruction_set_relative_path=ctx["INSTRUCTION_SET_RELATIVE_PATH"],
+    )
+    (instruction_set / "analysis-packet.md").write_text(packet, encoding="utf-8")
+    return instruction_set
+
+
+def _render_lead_prompt_and_snapshot(
+    inp: PrepareInputs,
+    ctx: dict,
+    instruction_set: Path,
+    final_report_template: Path,
+    prompt_template: Path,
+) -> str:
+    """compute/default 토큰을 ctx 에 주입한 뒤 final-report 템플릿 사본과 lead 실행
+    프롬프트를 렌더하고, 프롬프트 스냅샷을 기록한 후 prompt_text 를 돌려준다."""
+    # 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,
+    )
+    # Per-task-type schema excerpt for the report-writer worker. The full
+    # schema validates the data.json post-hoc (load_schema); the worker only
+    # needs the common structure + this run's task-type block, so we write a
+    # scoped excerpt into the instruction-set rather than make the worker read
+    # the whole 44 KB / all-task-types schema (whose repo `schemas/...` path is
+    # not resolvable from a consumer project's task bundle anyway).
+    #
+    # Guarded: a missing/unreadable schema must NOT break bundle preparation.
+    # If the excerpt cannot be produced (e.g. an older install that predates
+    # the schemas/ copy step), prep proceeds without it — the report-writer
+    # still has the phase-stripped template + skill structure guide, and
+    # validation runs against the full schema regardless.
+    try:
+        _excerpt = build_schema_excerpt(load_schema(), inp.task_type)
+        Path(ctx["FINAL_REPORT_SCHEMA_PATH"]).write_text(
+            json.dumps(_excerpt, indent=2, ensure_ascii=False) + "\n",
+            encoding="utf-8",
+        )
+    except Exception:  # noqa: BLE001 — advisory artifact; never fail prep over it
+        pass
+    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")
+    Path(ctx["RUN_PROMPT_SNAPSHOT_FILE"]).parent.mkdir(parents=True, exist_ok=True)
+    Path(ctx["RUN_PROMPT_SNAPSHOT_FILE"]).write_text(prompt_text, encoding="utf-8")
+    return prompt_text
+
+
+def _persist_run_inputs(
+    inp: PrepareInputs,
+    ctx: dict,
+    models: _ModelBindings,
+    selected_reviewers: str,
+    brief_relative: str,
+) -> None:
+    """이 run 의 입력 스냅샷(run-inputs-*.json)을 run-manifests 디렉터리에 기록."""
+    run_inputs_path = write_run_inputs(
+        project_root=Path(inp.project_root),
+        run_manifests_dir=Path(ctx["RUN_MANIFESTS_DIR"]),
+        task_type_segment=ctx["TASK_TYPE_SEGMENT"],
+        seq=ctx["RUN_MANIFESTS_SEQ"],
+        inputs={
+            "taskBriefPath": brief_relative,
+            "taskBriefAbsolutePath": str(inp.brief_path),
+            "directive": inp.directive,
+            "workers": selected_reviewers,
+            "leadModel": models.lead.display,
+            "claudeModel": models.cw.display,
+            "codexModel": models.co.display,
+            "geminiModel": models.ge.display,
+            "reportWriterModel": models.rw.display,
+            "executor": models.executor_provider,
+            "relatedTasks": inp.related_tasks_raw,
+            "approvedPlanPath": inp.approved_plan_path,
+            "clarificationResponsePath": inp.clarification_response_path,
+            "renderOnly": inp.render_only,
+        },
+    )
+    ctx["RUN_INPUTS_PATH"] = str(run_inputs_path)
+    ctx["RUN_INPUTS_RELATIVE_PATH"] = relative_to_project_root(
+        run_inputs_path, Path(inp.project_root)
     )
 
+
+def _finalize_status_and_render_manifests(
+    inp: PrepareInputs, ctx: dict, task_index_template: Path
+) -> None:
+    """최종 task/run status 를 확정하고 workflow state 를 재계산한 뒤 team-state,
+    task-manifest, task-index, run-manifest, timeline, discovery 산출물을 렌더한다."""
+    if inp.render_only:
+        ctx["CURRENT_TASK_STATUS"] = "instruction-set-generated"
+        ctx["CURRENT_RUN_STATUS"] = "prepared"
+    else:
+        ctx["CURRENT_TASK_STATUS"] = "claude-session-started"
+        ctx["CURRENT_RUN_STATUS"] = "in-progress"
+    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,
+        current_run_status=ctx["CURRENT_RUN_STATUS"],
+        current_task_status=ctx["CURRENT_TASK_STATUS"],
+        render_only=inp.render_only,
+        work_category=inp.work_category,
+    ))
+    render_team_state(ctx["TEAM_STATE_PATH"], ctx)
+    render_active_run_context(ctx["ACTIVE_RUN_CONTEXT_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)
+
+
+def _provision_settings_symlink(inp: PrepareInputs) -> None:
+    """non-render-only run 에서 project settings symlink 를 idempotent 하게 보장한다.
+    실패해도 prepare 를 막지 않고 경고만 출력한다 (worker dispatch 권한 이슈)."""
+    try:
+        link = ensure_project_settings_symlink(project_root=Path(inp.project_root))
+    except SettingsLinkError as exc:
+        print(
+            f"okstra-settings: failed to provision project settings symlink — "
+            f"worker dispatch may be blocked by Claude Code permissions. ({exc})",
+            file=sys.stderr,
+        )
+    else:
+        if link is None:
+            print(
+                "okstra-settings: ~/.okstra/templates/settings.local.json missing — "
+                "re-run 'npx okstra@latest install' (0.14.0+) to provision the symlink target.",
+                file=sys.stderr,
+            )
+
+
+def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
+    """Produce a complete okstra task bundle on disk. See module docstring."""
+    workspace_root = Path(inp.workspace_root)
+    project_root = Path(inp.project_root)
+
+    # ---- input validation + asset resolution + roster/model 해소 ----
+    # 각 단계는 명시적 입력/반환을 갖는 헬퍼로 분리되어 있다 (상단 phase 헬퍼
+    # 블록 참조). 아래 orchestrator 는 그 결과를 지역 변수로 언팩해 이후 ctx
+    # 조립 코드가 단일 흐름으로 읽히도록 유지한다.
+    assets = _resolve_runtime_assets(workspace_root, inp)
+    profile_file = assets.profile_file
+    prompt_template = assets.prompt_template
+    task_index_template = assets.task_index_template
+    final_report_template = assets.final_report_template
+    ctx_stage_map = _validate_prepare_inputs(project_root, inp)
+
+    verify_installation(workspace_root)
+    _register_and_check_project(project_root, inp)
+
+    workers, selected_reviewers = _resolve_roster(inp, profile_file)
+    pr_template_path_str, pr_template_source = _resolve_pr_template(inp)
+
+    models = _resolve_model_bindings(inp, workers)
+    lead, cw, co, ge, rw = models.lead, models.cw, models.co, models.ge, models.rw
+    critic_choice = models.critic_choice
+    executor_provider = models.executor_provider
+    executor_display_name = models.executor_display_name
+    executor_worker_agent = models.executor_worker_agent
+    executor_model_meta = models.executor_model_meta
+
     # ---- paths under per-task mutex (writes run-context-*.json) ----
     # OKSTRA_RUN_SEQ_OVERRIDE: okstra-ctl rerun / 테스트 hook 이 미리 reserve
     # 한 seq 를 강제하는 user-knob 환경 변수.
@@ -867,43 +1269,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         **workflow_state,
     })
     if inp.task_type == "implementation":
-        ctx["parsed_stage_map"] = ctx_stage_map
-        # Resolve the ready-set batch and append a `started` row per batched stage.
-        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_stages(
-            ctx["parsed_stage_map"], done_stages, inp.stage
-        )
-        ctx["effective_stages"] = effective
-        csv = ",".join(str(n) for n in effective)
-        ctx["EFFECTIVE_STAGES"] = csv
-        ctx["STAGE_BATCH_DIRECTIVE"] = (
-            f"- **Stage batch for this implementation run:** `{csv}` "
-            "(comma-separated stage numbers, ascending). Execute exactly these "
-            "Stage Map stages in this order — this is the authoritative scope. "
-            "Do NOT recompute the start stage from `consumers.jsonl`; the runtime "
-            "already selected and reserved this batch."
-        )
-        inp.stage = csv
-        print(f"selected stages: {csv}", 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 ""
-        now = _dt.datetime.now(_dt.timezone.utc).isoformat()
-        for stage_n in effective:
-            append_consumer(
-                plan_run_root,
-                impl_task_key=ctx["TASK_KEY"],
-                stage=stage_n,
-                status="started",
-                started_at=now,
-                head_commit=head_sha,
-            )
+        _reserve_implementation_stages(inp, ctx, ctx_stage_map)
 
     # ---- prepare directories + cleanup ----
     _ensure_task_directories(ctx)
@@ -927,122 +1293,19 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         prompt_seq=ctx["RUN_PROMPTS_SEQ"],
     )
 
-    # ---- write instruction-set scaffolding ----
-    instruction_set = Path(ctx["INSTRUCTION_SET_PATH"])
-    instruction_set.mkdir(parents=True, exist_ok=True)
-    profile_rendered = profile_content
-    for key in (
-        "EXECUTOR_PROVIDER",
-        "EXECUTOR_DISPLAY_NAME",
-        "EXECUTOR_WORKER_AGENT",
-        "EXECUTOR_MODEL_DISPLAY",
-        "EXECUTOR_MODEL_EXECUTION_VALUE",
-        "EXECUTOR_WORKTREE_PATH",
-        "EXECUTOR_WORKTREE_BRANCH",
-        "EXECUTOR_WORKTREE_BASE_REF",
-        "EXECUTOR_WORKTREE_STATUS",
-        "EXECUTOR_WORKTREE_NOTE",
-    ):
-        profile_rendered = profile_rendered.replace("{{" + key + "}}", ctx.get(key, ""))
-    (instruction_set / "analysis-profile.md").write_text(profile_rendered, encoding="utf-8")
-    (instruction_set / "analysis-material.md").write_text(review_material, encoding="utf-8")
-    shutil.copyfile(inp.brief_path, instruction_set / "task-brief.md")
-    if inp.clarification_response_path:
-        shutil.copyfile(
-            inp.clarification_response_path,
-            instruction_set / "clarification-response.md",
-        )
-    if inp.directive:
-        (instruction_set / "directive.txt").write_text(inp.directive + "\n", encoding="utf-8")
-    render_reference_expectations(
-        str(inp.brief_path), str(instruction_set / "reference-expectations.md"), 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,
+    # ---- write instruction-set scaffolding + lead prompt ----
+    instruction_set = _write_instruction_set_sources(
+        inp, ctx, profile_content, review_material
     )
-    # Per-task-type schema excerpt for the report-writer worker. The full
-    # schema validates the data.json post-hoc (load_schema); the worker only
-    # needs the common structure + this run's task-type block, so we write a
-    # scoped excerpt into the instruction-set rather than make the worker read
-    # the whole 44 KB / all-task-types schema (whose repo `schemas/...` path is
-    # not resolvable from a consumer project's task bundle anyway).
-    #
-    # Guarded: a missing/unreadable schema must NOT break bundle preparation.
-    # If the excerpt cannot be produced (e.g. an older install that predates
-    # the schemas/ copy step), prep proceeds without it — the report-writer
-    # still has the phase-stripped template + skill structure guide, and
-    # validation runs against the full schema regardless.
-    try:
-        _excerpt = build_schema_excerpt(load_schema(), inp.task_type)
-        Path(ctx["FINAL_REPORT_SCHEMA_PATH"]).write_text(
-            json.dumps(_excerpt, indent=2, ensure_ascii=False) + "\n",
-            encoding="utf-8",
-        )
-    except Exception:  # noqa: BLE001 — advisory artifact; never fail prep over it
-        pass
-    render_template_with_ctx(
-        str(prompt_template), str(instruction_set / "claude-execution-prompt.md"), ctx,
+    prompt_text = _render_lead_prompt_and_snapshot(
+        inp, ctx, instruction_set, final_report_template, prompt_template
     )
-    prompt_text = (instruction_set / "claude-execution-prompt.md").read_text(encoding="utf-8")
-    Path(ctx["RUN_PROMPT_SNAPSHOT_FILE"]).parent.mkdir(parents=True, exist_ok=True)
-    Path(ctx["RUN_PROMPT_SNAPSHOT_FILE"]).write_text(prompt_text, encoding="utf-8")
 
     # ---- run-inputs persistence ----
-    write_run_inputs(
-        project_root=project_root,
-        run_manifests_dir=Path(ctx["RUN_MANIFESTS_DIR"]),
-        task_type_segment=ctx["TASK_TYPE_SEGMENT"],
-        seq=ctx["RUN_MANIFESTS_SEQ"],
-        inputs={
-            "taskBriefPath": brief_relative,
-            "taskBriefAbsolutePath": str(inp.brief_path),
-            "directive": inp.directive,
-            "workers": selected_reviewers,
-            "leadModel": lead.display,
-            "claudeModel": cw.display,
-            "codexModel": co.display,
-            "geminiModel": ge.display,
-            "reportWriterModel": rw.display,
-            "executor": executor_provider,
-            "relatedTasks": inp.related_tasks_raw,
-            "approvedPlanPath": inp.approved_plan_path,
-            "clarificationResponsePath": inp.clarification_response_path,
-            "renderOnly": inp.render_only,
-        },
-    )
+    _persist_run_inputs(inp, ctx, models, selected_reviewers, brief_relative)
 
-    # ---- final status before manifest writes ----
-    if inp.render_only:
-        ctx["CURRENT_TASK_STATUS"] = "instruction-set-generated"
-        ctx["CURRENT_RUN_STATUS"] = "prepared"
-        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_PATH"]
-        ctx["LATEST_REPORT_RELATIVE_PATH"] = ctx["FINAL_REPORT_RELATIVE_PATH"]
-    ctx.update(compute_workflow_state(
-        task_type=inp.task_type,
-        current_run_status=ctx["CURRENT_RUN_STATUS"],
-        current_task_status=ctx["CURRENT_TASK_STATUS"],
-        render_only=inp.render_only,
-        work_category=inp.work_category,
-    ))
-    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)
+    # ---- final status + manifest/discovery renders ----
+    _finalize_status_and_render_manifests(inp, ctx, task_index_template)
 
     # ---- central index ----
     initial_status = "prepared" if inp.render_only else "running"
@@ -1063,21 +1326,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         )
 
     if not inp.render_only:
-        try:
-            link = ensure_project_settings_symlink(project_root=Path(inp.project_root))
-        except SettingsLinkError as exc:
-            print(
-                f"okstra-settings: failed to provision project settings symlink — "
-                f"worker dispatch may be blocked by Claude Code permissions. ({exc})",
-                file=__import__("sys").stderr,
-            )
-        else:
-            if link is None:
-                print(
-                    "okstra-settings: ~/.okstra/templates/settings.local.json missing — "
-                    "re-run 'npx okstra@latest install' (0.14.0+) to provision the symlink target.",
-                    file=__import__("sys").stderr,
-                )
+        _provision_settings_symlink(inp)
 
     return PrepareOutputs(
         ctx=ctx,
@@ -1129,6 +1378,18 @@ def main(argv: list[str]) -> int:
             "YAML frontmatter and appends an audit line."
         ),
     )
+    p.add_argument(
+        "--implementation-option",
+        default="",
+        dest="implementation_option",
+        help=(
+            "implementation task only. Name of the Option Candidate the user "
+            "chose from the implementation-planning final-report. Written into "
+            "the --approved-plan file's `implementation-option:` frontmatter "
+            "line. When omitted, implementation falls back to the plan's "
+            "`Recommended Option`."
+        ),
+    )
     p.add_argument("--clarification-response", default="", dest="clarification_response_path")
     p.add_argument(
         "--pr-template-path",
@@ -1219,6 +1480,7 @@ def main(argv: list[str]) -> int:
         pr_template_path=args.pr_template_path,
         render_only=args.render_only,
         approve_plan_ack=args.approve_plan_ack,
+        implementation_option=args.implementation_option,
         plan_verification_enabled=args.plan_verification_enabled,
     )
     try: