okstra 0.136.0 → 0.138.0

package/runtime/python/okstra_ctl/run.py

@@ -96,11 +96,7 @@ from .workflow import compute_workflow_state, load_phase_forbidden
 from .locks import worktree_provision_mutex
 from . import stage_targets as _stage_targets
 from .plan_run_root import plan_run_root_from_approved_plan
-from . import stage_integrate as _stage_integrate
 from . import implementation_stage as _implementation_stage
-from .stage_reconcile import (
-    auto_reconcile_best_effort as _stage_auto_reconcile_best_effort,
-)
 from .work_categories import resolve_work_category
 from .worktree import (
     WorktreeProvision,
@@ -437,117 +433,13 @@ def _validate_stage_structure(plan_path: str) -> None:
 
 
 RUN_STEP_BUDGET = _stage_targets.RUN_STEP_BUDGET
-_FVTarget = _stage_targets.FinalVerificationTarget
-
-
-def _stage_target_prepare_error(exc: _stage_targets.StageTargetError) -> PrepareError:
-    return PrepareError(str(exc))
-
-
-def _resolve_effective_stages(
-    stages: list,
-    done_stages: set,
-    requested: str,
-    budget: int = RUN_STEP_BUDGET,
-    started_stages: set = None,
-    reserved_stages: set = None,
-) -> list:
-    """Compatibility wrapper for the public stage-target policy module."""
-    try:
-        return _stage_targets.resolve_effective_stages(
-            stages,
-            done_stages,
-            requested,
-            budget=budget,
-            started_stages=started_stages,
-            reserved_stages=reserved_stages,
-        )
-    except _stage_targets.StageTargetError as exc:
-        raise _stage_target_prepare_error(exc) from exc
-
-
-def _check_multi_dep_merged(project_root, plan_run_root, latest,
-                            pred_commits: dict, candidate_base: str,
-                            stage_n: int) -> None:
-    """Compatibility wrapper for the stage-target dependency gate."""
-    try:
-        _stage_targets.check_multi_dep_merged(
-            project_root,
-            plan_run_root,
-            latest,
-            pred_commits,
-            candidate_base,
-            stage_n,
-        )
-    except _stage_targets.StageTargetError as exc:
-        raise _stage_target_prepare_error(exc) from exc
-
-
-def _resolve_stage_base_commit(
-    stage: dict,
-    consumer_done_rows: list,
-    anchor_base_commit: str,
-    candidate_base: str = "",
-    project_root=None,
-    plan_run_root=None,
-) -> str:
-    """Compatibility wrapper for stage worktree base selection."""
-    try:
-        return _stage_targets.resolve_stage_base_commit(
-            stage,
-            consumer_done_rows,
-            anchor_base_commit,
-            candidate_base=candidate_base,
-            project_root=project_root,
-            plan_run_root=plan_run_root,
-        )
-    except _stage_targets.StageTargetError as exc:
-        raise _stage_target_prepare_error(exc) from exc
-
-
-def _resolve_whole_task_target(
-    *, stage_map: list, done_rows: list, anchor_base: str,
-    task_worktree_path: str, task_head: str, task_dirty: bool,
-    merged: dict,
-) -> "_FVTarget":
-    """Compatibility wrapper for whole-task verification target selection."""
-    try:
-        return _stage_targets.resolve_whole_task_target(
-            stage_map=stage_map,
-            done_rows=done_rows,
-            anchor_base=anchor_base,
-            task_worktree_path=task_worktree_path,
-            task_head=task_head,
-            task_dirty=task_dirty,
-            merged=merged,
-        )
-    except _stage_targets.StageTargetError as exc:
-        raise _stage_target_prepare_error(exc) from exc
-
-
-def _resolve_single_stage_target(
-    *, requested_stage: str, done_rows: list, stage_base: str,
-    stage_worktree_path: str, stage_head: str, stage_dirty: bool,
-) -> "_FVTarget":
-    """Compatibility wrapper for single-stage verification target selection."""
-    try:
-        return _stage_targets.resolve_single_stage_target(
-            requested_stage=requested_stage,
-            done_rows=done_rows,
-            stage_base=stage_base,
-            stage_worktree_path=stage_worktree_path,
-            stage_head=stage_head,
-            stage_dirty=stage_dirty,
-        )
-    except _stage_targets.StageTargetError as exc:
-        raise _stage_target_prepare_error(exc) from exc
 
 
 def _stage_map_reject_detail(stages, errs):
     """빈/손상 Stage Map 의 거부 사유 문자열을 돌려준다. 정상이면 None.
 
     빈/손상 Stage Map 을 흘려보내면 whole-task 완료 게이트
-    (resolve_whole_task_target 의 `for stage in stage_map`)가 0회 순회로 vacuous
+    (`_resolve_whole_task_target`의 `for stage in stage_map`)가 0회 순회로 vacuous
     통과해 미완 task 를 '완성'으로 배포·검증한다. 빈 파싱(heading rename·표 손상)과
     stage 번호 비단조(중간 행 누락 → S2)의 판정을 한 곳에 모아, run.py 의 prepare
     게이트와 wizard 의 stage picker 가 같은 기준을 상속하게 한다(single-reference)."""
@@ -1509,20 +1401,6 @@ def _git_out(cwd, *args) -> str:
     return r.stdout.strip() if r.returncode == 0 else ""
 
 
-def _auto_reconcile_best_effort(inp: "PrepareInputs", plan_run_root: Path) -> None:
-    _stage_auto_reconcile_best_effort(inp, plan_run_root)
-
-
-def _is_ancestor(cwd, commit, head) -> bool:
-    from .worktree import is_ancestor
-    return is_ancestor(cwd, commit, head)
-
-
-def _is_dirty_excluding_okstra(cwd) -> bool:
-    from .worktree import is_dirty_excluding_okstra
-    return is_dirty_excluding_okstra(cwd)
-
-
 def _single_stage_final_verification_worktree(inp: "PrepareInputs") -> WorktreeProvision:
     """Placeholder until the selected stage registry row is resolved."""
     return WorktreeProvision(
@@ -1552,57 +1430,46 @@ def _format_integration(integ) -> str:
     return "\n".join(lines)
 
 
-def _reserve_final_verification_target(
-    inp: "PrepareInputs", ctx: dict, ctx_stage_map: list,
+def _final_verification_target_request(
+    inp: "PrepareInputs",
+    ctx_stage_map: list[dict],
+) -> _stage_targets.FinalVerificationTargetRequest:
+    stage = (
+        int(inp.stage)
+        if inp.stage and inp.stage != "auto"
+        else None
+    )
+    return _stage_targets.FinalVerificationTargetRequest(
+        project_root=Path(inp.project_root),
+        project_id=inp.project_id,
+        task_group=inp.task_group,
+        task_id=inp.task_id,
+        work_category=inp.work_category,
+        approved_plan_path=Path(inp.approved_plan_path),
+        stage=stage,
+        stage_map=tuple(ctx_stage_map),
+    )
+
+
+def _apply_final_verification_target(
+    ctx: dict,
+    acquisition: _stage_targets.FinalVerificationTargetAcquisition,
 ) -> None:
-    """final-verification 의 검증 target 을 registry/consumers/git 에서
-    해소하고 gate 를 강제한다. 위반 시 PrepareError. 결과를 ctx 의
-    VERIFICATION_* 키로 주입한다."""
-    from .consumers import backfill_done_from_carry, read_stage_consumer_state
-    from . import worktree_registry as _reg
-
-    plan_run_root = plan_run_root_from_approved_plan(inp.approved_plan_path)
-    # carry sidecars are the SSOT for stage completion — recover missing `done`
-    # rows before the whole-task gate checks every stage.
-    backfill_done_from_carry(plan_run_root)
-    _auto_reconcile_best_effort(inp, plan_run_root)
-    done_rows = read_stage_consumer_state(plan_run_root).done_rows
-
-    if inp.stage and inp.stage != "auto":
-        n = int(inp.stage)
-        row = _reg.get_stage_row(inp.project_id, inp.task_group, inp.task_id, n)
-        wt_path = (row or {}).get("worktree_path", "")
-        stage_base = (row or {}).get("base_ref", "")
-        stage_branch = (row or {}).get("branch", "")
-        head = _git_out(wt_path, "rev-parse", "HEAD") if wt_path else ""
-        target = _resolve_single_stage_target(
-            requested_stage=inp.stage, done_rows=done_rows,
-            stage_base=stage_base, stage_worktree_path=wt_path,
-            stage_head=head,
-            stage_dirty=_is_dirty_excluding_okstra(wt_path) if wt_path else False,
-        )
-        ctx["EXECUTOR_WORKTREE_PATH"] = wt_path
-        ctx["EXECUTOR_WORKTREE_BRANCH"] = stage_branch
-        ctx["EXECUTOR_WORKTREE_BASE_REF"] = stage_base
+    """Translate acquired domain facts into render-context fields."""
+    target = acquisition.target
+    if target.scope == "single-stage":
+        stage = target.stages[0]
+        ctx["EXECUTOR_WORKTREE_PATH"] = target.worktree_path
+        ctx["EXECUTOR_WORKTREE_BRANCH"] = acquisition.worktree_branch
+        ctx["EXECUTOR_WORKTREE_BASE_REF"] = target.base
         ctx["EXECUTOR_WORKTREE_STATUS"] = "reused-stage"
         ctx["EXECUTOR_WORKTREE_NOTE"] = (
-            f"final-verification uses implementation stage {n} worktree"
+            f"final-verification uses implementation stage {stage} worktree"
         )
-    else:
-        wt_path = ctx["EXECUTOR_WORKTREE_PATH"]
-        anchor = _reg.get_implementation_base(
-            inp.project_id, inp.task_group, inp.task_id) or ""
-        # whole-task 통합(머지+teardown)+게이트 강제는 container 와 공유하는
-        # 순수 헬퍼가 단일 책임. ctx 주입만 run.py 측에 남긴다.
-        whole = _stage_targets.resolve_and_integrate_whole_task(
-            project_id=inp.project_id, task_group=inp.task_group,
-            task_id=inp.task_id, task_worktree_path=wt_path,
-            stage_map=ctx_stage_map, done_rows=done_rows,
-            anchor_base=anchor, teardown=True,
+    if acquisition.integration_result is not None:
+        ctx["STAGE_INTEGRATION"] = _format_integration(
+            acquisition.integration_result
         )
-        ctx["STAGE_INTEGRATION"] = _format_integration(whole["integrate_result"])
-        target = whole["target"]
-
     diff_stat = _git_out(target.worktree_path, "diff", "--stat",
                          f"{target.base}..{target.head}")
     ctx["VERIFICATION_SCOPE"] = target.scope
@@ -1969,6 +1836,215 @@ def _provision_settings_symlink(inp: PrepareInputs) -> None:
             )
 
 
+@dataclass
+class _ProvisionedTask:
+    """What one task-key's provisioning critical section hands to run-path compute."""
+
+    worktree: WorktreeProvision
+    stage_run_claim: object | None
+    stage_arg: int | None
+
+
+def _write_bundle_artifacts(
+    inp: PrepareInputs,
+    ctx: dict,
+    project_root: Path,
+    lead_runtime: str,
+    claude_session_id: str,
+) -> None:
+    """Create the task/run directories and the artifacts the lead reads at launch.
+
+    Order is contractual. The fix-cycle ledger runs LAST here but still *before*
+    the instruction-set build in the caller, so a cycle opened by this run shows
+    up in the analysis packet's Fix History; finalize rewrites the manifest after
+    that, which keeps the lazy-close invariant that the on-disk manifest holds
+    pre-rewrite values when the cycle is judged.
+    """
+    _ensure_task_directories(ctx)
+    migrate_legacy_run_artifacts(ctx)
+    cleanup_obsolete_generated_docs(
+        project_root=project_root, instruction_set_dir=Path(ctx["INSTRUCTION_SET_PATH"]),
+    )
+    if lead_runtime == "claude-code":
+        # Always materialise the resume command script for Claude Code. Even in
+        # --render-only preparation flows the user (or a later non-interactive
+        # runner) may invoke it manually; deferring its creation until
+        # interactive launch leaves runs/<phase>/sessions/ empty and the
+        # manifest pointing at a path that does not exist. Codex runs resume via
+        # artifacts/checkpoints instead, so they intentionally leave this empty.
+        write_claude_resume_command_file(
+            resume_command_path=Path(ctx["CLAUDE_RESUME_COMMAND_PATH"]),
+            project_root=project_root,
+            claude_session_id=claude_session_id,
+            task_key=ctx["TASK_KEY"],
+            task_type=ctx["TASK_TYPE"],
+            phase_state=ctx["CURRENT_RUN_STATUS"],
+            worker_prompts_dir_relative=ctx["RUN_PROMPTS_RELATIVE_PATH"],
+            prompt_seq=ctx["RUN_PROMPTS_SEQ"],
+        )
+    ctx["FIX_CYCLE_ID"] = _record_fix_cycle_events(inp, ctx)
+
+
+def _record_run_in_central_index(
+    inp: PrepareInputs,
+    ctx: dict,
+    workspace_root: Path,
+    run_seq_override: int | None,
+) -> None:
+    """Publish this run to ~/.okstra/{recent,active}.jsonl. Never fatal.
+
+    A failure here leaves the central index incomplete but the bundle on disk is
+    already usable, so prepare reports and continues. The rerun path pre-stamps a
+    'reserving' row before spawning (OKSTRA_RUN_SEQ_OVERRIDE forces that seq); if
+    the promotion to 'running' fails, that row would sit in active.jsonl forever
+    and inflate activeCount, so it is cleaned up whenever the reserved seq is known.
+    """
+    try:
+        _record_start(
+            workspace_root=workspace_root,
+            ctx=ctx,
+            initial_status="prepared" if inp.render_only else "running",
+            canonical_argv=_canonical_argv(inp, ctx),
+            cwd=os.getcwd(),
+            brief_sha256=_brief_sha256(inp.brief_path),
+        )
+    except Exception as exc:
+        print(
+            f"okstra-central: record_start failed; central index will be incomplete ({exc})",
+            file=sys.stderr,
+        )
+        if run_seq_override is not None:
+            _remove_leaked_reservation(ctx, run_seq_override)
+
+
+def _initial_workflow_ctx(
+    inp: PrepareInputs, forbidden_by_phase: dict
+) -> dict[str, str]:
+    """Workflow tokens for a run that has been prepared but not started.
+
+    The run status is not known yet, so both statuses are the pre-launch
+    constants; `_finalize_status_and_render_manifests` recomputes the block once
+    the real status is settled.
+    """
+    task_status, run_status = "ready-for-claude", "not-run"
+    return {
+        "CURRENT_TASK_STATUS": task_status,
+        "CURRENT_RUN_STATUS": run_status,
+        **compute_workflow_state(
+            task_type=inp.task_type,
+            current_run_status=run_status,
+            current_task_status=task_status,
+            render_only=inp.render_only,
+            forbidden_by_phase=forbidden_by_phase,
+        ),
+    }
+
+
+def _related_tasks_ctx(ctx: dict, inp: PrepareInputs) -> dict[str, str]:
+    """Render tokens for the tasks this run declares a relation to."""
+    items = resolve_related_tasks(
+        task_manifest_path=Path(ctx["TASK_MANIFEST_PATH"]),
+        raw_related=inp.related_tasks_raw,
+    )
+    return {
+        "RELATED_TASKS_JSON": json.dumps(items, ensure_ascii=False),
+        "RELATED_TASKS_BULLETS": related_tasks_bullets(items),
+        "RELATED_TASKS_INLINE": related_tasks_inline(items),
+    }
+
+
+def _model_ctx(models: "_ModelBindings") -> dict[str, str]:
+    """Render tokens for every model binding this run resolved."""
+    return {
+        "LEAD_MODEL": models.lead.display,
+        "LEAD_MODEL_EXECUTION_VALUE": models.lead.execution,
+        "CLAUDE_WORKER_MODEL": models.cw.display,
+        "CLAUDE_WORKER_MODEL_EXECUTION_VALUE": models.cw.execution,
+        "CODEX_WORKER_MODEL": models.co.display,
+        "CODEX_WORKER_MODEL_EXECUTION_VALUE": models.codex_worker_execution,
+        "ANTIGRAVITY_WORKER_MODEL": models.ge.display,
+        "ANTIGRAVITY_WORKER_MODEL_EXECUTION_VALUE": models.antigravity_worker_execution,
+        "REPORT_WRITER_MODEL": models.rw.display,
+        "REPORT_WRITER_MODEL_EXECUTION_VALUE": models.rw.execution,
+        "EXECUTOR_PROVIDER": models.executor_provider,
+        "EXECUTOR_DISPLAY_NAME": models.executor_display_name,
+        "EXECUTOR_WORKER_AGENT": models.executor_worker_agent,
+        "EXECUTOR_MODEL_DISPLAY": models.executor_model_meta.display,
+        "EXECUTOR_MODEL_EXECUTION_VALUE": models.executor_execution,
+        "CRITIC_CHOICE": models.critic_choice,
+    }
+
+
+def _provision_task_and_stage(
+    inp: PrepareInputs,
+    project_root: Path,
+    ctx_stage_map: list,
+    task_group_segment: str,
+    task_id_segment: str,
+    task_key: str,
+) -> _ProvisionedTask:
+    """Reserve this run's worktree and, for implementation, its Stage Map stage.
+
+    One worktree per task-key: requirements-discovery, error-analysis,
+    implementation-planning and implementation phases of the same task all share
+    this directory and branch. Runs BEFORE run-path compute: the worktree's
+    degrade status (skipped-*) feeds the implementation Stage Run Claim, and the
+    resolved stage namespaces the run path.
+
+    The whole check→select→`git worktree add`→reserve sequence (task worktree AND
+    implementation stage) is one critical section per task-key: the registry lock
+    alone only covers the reserve row, so without this mutex two concurrent runs
+    can pick the same stage or race the same path/branch at the git level (TOCTOU).
+    """
+    with worktree_provision_mutex(
+        okstra_home(), inp.project_id, task_group_segment, task_id_segment,
+    ):
+        if inp.task_type == "final-verification" and inp.stage and inp.stage != "auto":
+            worktree = _single_stage_final_verification_worktree(inp)
+            # Single-stage final-verification namespaces its run path under
+            # runs/final-verification/stage-<N> (same isolation as
+            # implementation) so concurrent per-stage verifications never
+            # share state/reports/worker-results.
+            fv_stage_arg = int(inp.stage)
+        else:
+            fv_stage_arg = None
+            try:
+                worktree = provision_task_worktree(
+                    task_type=inp.task_type,
+                    project_root=project_root,
+                    project_id=inp.project_id,
+                    task_group_segment=task_group_segment,
+                    task_id_segment=task_id_segment,
+                    work_category=inp.work_category,
+                    base_ref=inp.base_ref,
+                    require_base_ref=True,
+                )
+            except RuntimeError as exc:
+                raise PrepareError(
+                    f"task worktree provisioning failed: {exc}"
+                ) from exc
+
+        # ---- implementation Stage Run Claim (path-independent) ----
+        # Resolve + provision the stage BEFORE run-path compute so RUN_DIR
+        # lands in runs/implementation/stage-<N>. The registry stage-key is
+        # reserved exactly once here (inside provision_stage_worktree), and
+        # the surrounding mutex makes the registry read in the claim
+        # and that reserve atomic. Other task-types skip this claim;
+        # single-stage final-verification threads its explicit stage via
+        # fv_stage_arg, everything else keeps stage_arg=None (flat paths).
+        if inp.task_type == "implementation":
+            stage_run_claim = _claim_implementation_stage_run(
+                inp, ctx_stage_map, task_group_segment, task_id_segment,
+                task_key, worktree.status,
+            )
+            # Drop any stale waiver on this stage so the run actually verifies
+            # conformance (kept inside the per-task-key mutex so concurrent
+            # same-task runs don't race the manifest write).
+            _clear_stale_stage_waiver(inp, project_root, stage_run_claim.stage)
+            return _ProvisionedTask(worktree, stage_run_claim, stage_run_claim.stage)
+        return _ProvisionedTask(worktree, None, fv_stage_arg)
+
+
 def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     """Produce a complete okstra task bundle on disk. See module docstring."""
     workspace_root = Path(inp.workspace_root)
@@ -2011,12 +2087,6 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     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
@@ -2043,67 +2113,13 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         task_id=inp.task_id,
     )
 
-    # ---- task worktree provisioning (every phase, every task-type) ----
-    # One worktree per task-key: requirements-discovery, error-analysis,
-    # implementation-planning and implementation phases of the same task
-    # all share this directory and branch. Runs BEFORE run-path compute: its
-    # degrade status (skipped-*) feeds implementation Stage Run Claim, and
-    # the resolved stage namespaces the run path.
-    #
-    # The whole check→select→`git worktree add`→reserve sequence (task
-    # worktree AND implementation stage) is one critical section per
-    # task-key: the registry lock alone only covers the reserve row, so
-    # without this mutex two concurrent runs can pick the same stage or
-    # race the same path/branch at the git level (TOCTOU).
-    with worktree_provision_mutex(
-        okstra_home(), inp.project_id, task_group_segment, task_id_segment,
-    ):
-        if inp.task_type == "final-verification" and inp.stage and inp.stage != "auto":
-            worktree = _single_stage_final_verification_worktree(inp)
-            # Single-stage final-verification namespaces its run path under
-            # runs/final-verification/stage-<N> (same isolation as
-            # implementation) so concurrent per-stage verifications never
-            # share state/reports/worker-results.
-            fv_stage_arg = int(inp.stage)
-        else:
-            fv_stage_arg = None
-            try:
-                worktree = provision_task_worktree(
-                    task_type=inp.task_type,
-                    project_root=project_root,
-                    project_id=inp.project_id,
-                    task_group_segment=task_group_segment,
-                    task_id_segment=task_id_segment,
-                    work_category=inp.work_category,
-                    base_ref=inp.base_ref,
-                    require_base_ref=True,
-                )
-            except RuntimeError as exc:
-                raise PrepareError(
-                    f"task worktree provisioning failed: {exc}"
-                ) from exc
-
-        # ---- implementation Stage Run Claim (path-independent) ----
-        # Resolve + provision the stage BEFORE run-path compute so RUN_DIR
-        # lands in runs/implementation/stage-<N>. The registry stage-key is
-        # reserved exactly once here (inside provision_stage_worktree), and
-        # the surrounding mutex makes the registry read in the claim
-        # and that reserve atomic. Other task-types skip this claim;
-        # single-stage final-verification threads its explicit stage via
-        # fv_stage_arg, everything else keeps stage_arg=None (flat paths).
-        if inp.task_type == "implementation":
-            stage_run_claim = _claim_implementation_stage_run(
-                inp, ctx_stage_map, task_group_segment, task_id_segment,
-                task_key, worktree.status,
-            )
-            stage_arg = stage_run_claim.stage
-            # Drop any stale waiver on this stage so the run actually verifies
-            # conformance (kept inside the per-task-key mutex so concurrent
-            # same-task runs don't race the manifest write).
-            _clear_stale_stage_waiver(inp, project_root, stage_run_claim.stage)
-        else:
-            stage_run_claim = None
-            stage_arg = fv_stage_arg
+    provisioned = _provision_task_and_stage(
+        inp, project_root, ctx_stage_map,
+        task_group_segment, task_id_segment, task_key,
+    )
+    worktree = provisioned.worktree
+    stage_run_claim = provisioned.stage_run_claim
+    stage_arg = provisioned.stage_arg
 
     ctx = compute_and_write_run_context(
         workspace_root=workspace_root, project_root=project_root,
@@ -2154,13 +2170,6 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     # ---- material + related-tasks ----
     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_PATH"]),
-        raw_related=inp.related_tasks_raw,
-    )
-    related_tasks_json_str = json.dumps(related_items, ensure_ascii=False)
-    bullets = related_tasks_bullets(related_items)
-    inline = related_tasks_inline(related_items)
 
     # ---- relative paths for brief + clarification ----
     brief_relative = relative_to_project_root(inp.brief_path, project_root)
@@ -2169,17 +2178,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         if inp.clarification_response_path else ""
     )
 
-    # ---- initial workflow state (current_run_status not yet known) ----
-    initial_task_status = "ready-for-claude"
-    initial_run_status = "not-run"
     forbidden_by_phase = load_phase_forbidden(workspace_root)
-    workflow_state = compute_workflow_state(
-        task_type=inp.task_type,
-        current_run_status=initial_run_status,
-        current_task_status=initial_task_status,
-        render_only=inp.render_only,
-        forbidden_by_phase=forbidden_by_phase,
-    )
 
     # ---- assemble full ctx (the values render functions expect) ----
     ctx.update({
@@ -2196,27 +2195,9 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         "CLARIFICATION_RESPONSE_RELATIVE_PATH": clarification_relative,
         "BRIEF_FILE_PATH": str(inp.brief_path),
         "BRIEF_RELATIVE_PATH": brief_relative,
-        "LEAD_MODEL": lead.display,
-        "LEAD_MODEL_EXECUTION_VALUE": lead.execution,
-        "CLAUDE_WORKER_MODEL": cw.display,
-        "CLAUDE_WORKER_MODEL_EXECUTION_VALUE": cw.execution,
-        "CODEX_WORKER_MODEL": co.display,
-        "CODEX_WORKER_MODEL_EXECUTION_VALUE": models.codex_worker_execution,
-        "ANTIGRAVITY_WORKER_MODEL": ge.display,
-        "ANTIGRAVITY_WORKER_MODEL_EXECUTION_VALUE": models.antigravity_worker_execution,
-        "REPORT_WRITER_MODEL": rw.display,
-        "REPORT_WRITER_MODEL_EXECUTION_VALUE": rw.execution,
-        "EXECUTOR_PROVIDER": executor_provider,
-        "EXECUTOR_DISPLAY_NAME": executor_display_name,
-        "EXECUTOR_WORKER_AGENT": executor_worker_agent,
-        "EXECUTOR_MODEL_DISPLAY": executor_model_meta.display,
-        "EXECUTOR_MODEL_EXECUTION_VALUE": models.executor_execution,
-        "CRITIC_CHOICE": critic_choice,
-        "RELATED_TASKS_JSON": related_tasks_json_str,
-        "RELATED_TASKS_BULLETS": bullets,
-        "RELATED_TASKS_INLINE": inline,
-        "CURRENT_TASK_STATUS": initial_task_status,
-        "CURRENT_RUN_STATUS": initial_run_status,
+        **_model_ctx(models),
+        **_related_tasks_ctx(ctx, inp),
+        **_initial_workflow_ctx(inp, forbidden_by_phase),
         "VALIDATION_STATUS": "not-run",
         "VALIDATION_UPDATED_AT": "",
         "VALIDATION_FAILURES_JSON": "[]",
@@ -2224,45 +2205,20 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         "LATEST_REPORT_RELATIVE_PATH": "",
         "RENDER_ONLY": "true" if inp.render_only else "false",
         "OKSTRA_VERSION": installed_version(),
-        **workflow_state,
     })
     if lead_runtime == "codex":
         ctx["CLAUDE_RESUME_COMMAND_PATH"] = ""
         ctx["CLAUDE_RESUME_COMMAND_RELATIVE_PATH"] = ""
         ctx["CLAUDE_RESUME_COMMAND_FILENAME"] = ""
     if inp.task_type == "final-verification":
-        _reserve_final_verification_target(inp, ctx, ctx_stage_map)
-
-    # ---- 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_PATH"]),
-    )
-    if lead_runtime == "claude-code":
-        # Always materialise the resume command script for Claude Code. Even in
-        # --render-only preparation flows the user (or a later non-interactive
-        # runner) may invoke it manually; deferring its creation until
-        # interactive launch leaves runs/<phase>/sessions/ empty and the
-        # manifest pointing at a path that does not exist. Codex runs resume via
-        # artifacts/checkpoints instead, so they intentionally leave this empty.
-        write_claude_resume_command_file(
-            resume_command_path=Path(ctx["CLAUDE_RESUME_COMMAND_PATH"]),
-            project_root=project_root,
-            claude_session_id=claude_session_id,
-            task_key=ctx["TASK_KEY"],
-            task_type=ctx["TASK_TYPE"],
-            phase_state=ctx["CURRENT_RUN_STATUS"],
-            worker_prompts_dir_relative=ctx["RUN_PROMPTS_RELATIVE_PATH"],
-            prompt_seq=ctx["RUN_PROMPTS_SEQ"],
+        acquisition = _stage_targets.acquire_final_verification_target(
+            _final_verification_target_request(inp, ctx_stage_map)
         )
+        _apply_final_verification_target(ctx, acquisition)
 
-    # ---- fix-cycle 기록 (manifest 재작성 전 디스크 값으로 lazy-close 판정) ----
-    # instruction-set 빌드보다 *앞*에서 호출해 이번 run 에서 새로 open 되는
-    # cycle 도 analysis-packet 의 Fix History 에 보이도록 한다. finalize 가
-    # 여전히 이후에 manifest 를 재작성하므로 lazy-close 의 "디스크 manifest 는
-    # prepare 재작성 전 값" 불변식은 유지된다.
-    ctx["FIX_CYCLE_ID"] = _record_fix_cycle_events(inp, ctx)
+    _write_bundle_artifacts(
+        inp, ctx, project_root, lead_runtime, claude_session_id,
+    )
 
     # ---- write instruction-set scaffolding + lead prompt ----
     instruction_set = _write_instruction_set_sources(
@@ -2281,29 +2237,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     )
     _record_artifact_runtime_render_only_event(inp, ctx)
 
-    # ---- central index ----
-    initial_status = "prepared" if inp.render_only else "running"
-    canonical_argv = _canonical_argv(inp, ctx)
-    try:
-        _record_start(
-            workspace_root=workspace_root,
-            ctx=ctx,
-            initial_status=initial_status,
-            canonical_argv=canonical_argv,
-            cwd=os.getcwd(),
-            brief_sha256=_brief_sha256(inp.brief_path),
-        )
-    except Exception as exc:
-        print(
-            f"okstra-central: record_start failed; central index will be incomplete ({exc})",
-            file=sys.stderr,
-        )
-        # rerun 경로는 spawn 전에 'reserving' row 를 미리 박아 둔다
-        # (OKSTRA_RUN_SEQ_OVERRIDE 가 그 seq 를 강제한다). record_start 가
-        # 'reserving' → 'running' 승격에 실패하면 그 row 가 active.jsonl 에
-        # 영구히 남아 activeCount 를 부풀린다. 예약 seq 를 알 때만 정리한다.
-        if run_seq_override is not None:
-            _remove_leaked_reservation(ctx, run_seq_override)
+    _record_run_in_central_index(inp, ctx, workspace_root, run_seq_override)
 
     if not inp.render_only:
         _provision_settings_symlink(inp)