okstra 0.206.0 → 0.207.0

package/runtime/python/okstra_ctl/run.py

@@ -14,9 +14,15 @@ state passing, and are read once at the start.
 """
 from __future__ import annotations
 
-from .technical_verification import (
-    resolve_technical_verification_input,
-    write_technical_verification_input,
+from okstra_ctl.phases.feature_analysis.entry import (
+    resolve_analysis_target, validate_feature_target_input,
+)
+
+from okstra_ctl.phases.implementation_planning.validation import validate_selected_direction_plan
+
+from .phases.technical_verification.entry import (
+    prepare_technical_verification_input,
+    materialize_technical_input_packet,
 )
 
 from argparse import (
@@ -40,6 +46,13 @@ from typing import Mapping, Sequence
 
 from okstra_project import project_json_path, upsert_project_json
 from okstra_project.slug import slugify
+from .phases.catalog import host_rules
+from .phases.implementation_planning.entry import (
+    _resolve_planning_input_path,
+    _validate_planning_entry_inputs,
+    _resolve_planning_direction,
+    _validate_reverify_scope,
+)
 from . import fix_cycles
 from .analysis_packet import build_analysis_packet
 from . import group_context
@@ -55,7 +68,6 @@ from .analysis_inputs import (
     load_candidate_map,
     parse_evidence_paths,
     resolve_analysis_head,
-    resolve_analysis_target,
     resolve_evidence_inputs,
 )
 from .stage_fix_carry import derive_stage_fix_carry
@@ -67,13 +79,11 @@ from .clarification_items import (
     scan_approval_gate,
 )
 from .error_report import prior_run_error_digest
-from .incremental_scope import ReverifyScopeError, parse_user_reverify_scope
+from .incremental_scope import parse_user_reverify_scope
 from .implementation_direction import (
     DirectionSelectionError,
     SelectedDirection,
     lexical_absolute_path,
-    resolve_selected_direction,
-    validate_selected_direction_plan,
     validate_task_artifact_path,
     write_selected_direction_snapshot,
 )
@@ -205,7 +215,9 @@ from .session import (
     resolve_inproc_lead_session_id,
     write_claude_resume_command_file,
 )
-from .pr_template import PrTemplateError, resolve_pr_template_path
+from .phases.release_handoff.entry import (
+    materialize_handoff_input, resolve_pr_template,
+)
 from .worker_artifacts import worker_provider_id
 from .workers import (
     normalize_workers,
@@ -213,7 +225,7 @@ from .workers import (
     resolve_profile_workers,
     validate_workers_against_profile,
 )
-from .workflow import compute_workflow_state, load_phase_forbidden
+from .workflow import compute_workflow_state, load_phase_boundary
 from .locks import worktree_provision_mutex
 from . import stage_targets as _stage_targets
 from .phases.catalog import PhaseAssetError, profile_markdown, resolve_include
@@ -225,8 +237,7 @@ from .phases.final_verification.entry import (
     verification_target_request,
     write_verification_target_snapshot,
 )
-from .plan_run_root import plan_run_root_from_approved_plan
-from . import implementation_stage as _implementation_stage
+from .phases.implementation import entry as _implementation_stage
 from .work_categories import resolve_work_category
 from .worktree import (
     WorktreeProvision,
@@ -236,7 +247,6 @@ from .brief_frontmatter import (
     has_reporter_confirmation_contract,
     read_brief_frontmatter,
 )
-from .scope_provenance import brief_end_state_id_sequence
 
 # Frontmatter approval-flag matcher.
 #
@@ -517,6 +527,9 @@ def _set_data_json_approved_true_if_present(path: Path) -> bool:
 # PrepareError 는 stage_targets(저수준)에 정의돼 final-verification 과 container
 # 가 whole-task 통합 실패를 동일 타입으로 받는다. run.py 는 재노출만 한다.
 PrepareError = _stage_targets.PrepareError
+from .phases.implementation_option_selection.entry import (
+    validate_analyser_roster, validate_brief_requirements,
+)
 
 
 def _normalize_lead_runtime(value: str) -> str:
@@ -696,17 +709,7 @@ def _validate_stage_structure(plan_path: str) -> None:
 RUN_STEP_BUDGET = _stage_targets.RUN_STEP_BUDGET
 
 
-def _parse_stage_map_into_ctx(plan_path: str) -> list:
-    """Parse the approved plan into context records for execution consumers."""
-    from .stage_map import StageMapError, parse_stage_map_file, stage_map_records
-
-    try:
-        return stage_map_records(parse_stage_map_file(Path(plan_path)))
-    except StageMapError as exc:
-        raise PrepareError(
-            "approved-plan 의 Stage Map 을 신뢰할 수 없어 거부합니다 "
-            f"({plan_path}): {exc.reason}. plan 의 Stage Map 을 점검하세요."
-        ) from exc
+from .stage_map import parse_stage_map_for_prepare as _parse_stage_map_into_ctx
 
 
 def _apply_cli_approval(path: str) -> None:
@@ -1352,9 +1355,7 @@ def _resolve_runtime_assets(workspace_root: Path, inp: PrepareInputs) -> _Resolv
             raise PrepareError(
                 f"required okstra template or lead contract missing: {required}.{_INSTALL_HINT}"
             )
-    host_rules_file = (
-        workspace_root / "prompts" / "host-orchestration" / f"{inp.task_type}.md"
-    )
+    host_rules_file = host_rules(workspace_root, inp.task_type)
     return _ResolvedAssets(
         profile_file=profile_file,
         prompt_template=prompt_template,
@@ -1434,17 +1435,12 @@ def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
     if inp.task_type == "release-handoff":
         # brief 는 entry phase 의 입력물 — release-handoff 는 검증 보고서를
         # 인용하는 input 문서를 prepare 가 직접 생성해 brief 자리에 채운다
-        # (_materialize_release_handoff_input, 이 검증 직후 실행).
+        # (materialize_handoff_input, 이 검증 직후 실행).
         pass
     elif not inp.brief_path.is_file():
         raise PrepareError(f"task brief not found: {inp.brief_path}")
-    elif inp.task_type == "implementation-option-selection" and not brief_end_state_id_sequence(
-        inp.brief_path
-    ):
-        raise PrepareError(
-            "regenerate the brief with stable end-state IDs before starting "
-            "implementation-option-selection"
-        )
+    elif inp.task_type == "implementation-option-selection":
+        validate_brief_requirements(inp.brief_path)
     ctx_stage_map: list = []
     # implementation 과 final-verification 은 둘 다 승인된 plan 의 Stage Map 을
     # 입력으로 받는다(전자는 실행 scope, 후자는 검증 scope).
@@ -1491,143 +1487,6 @@ def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
     return ctx_stage_map
 
 
-_PLANNING_REPORT_RE = re.compile(
-    r"^final-report-implementation-planning-\d{3,}\.(?:md|data\.json)$"
-)
-
-
-def _resolve_planning_input_path(
-    path_value: str, project_root: Path
-) -> Path | None:
-    """Resolve cwd-first planning inputs without following symbolic links."""
-    raw_path = Path(path_value).expanduser()
-    cwd_candidate = lexical_absolute_path(raw_path)
-    if cwd_candidate.is_file():
-        return cwd_candidate
-    if not raw_path.is_absolute():
-        project_candidate = lexical_absolute_path(project_root / raw_path)
-        if project_candidate.is_file():
-            return project_candidate
-    return None
-
-
-def _is_existing_planning_report(
-    path_value: str, project_root: Path, inp: PrepareInputs
-) -> bool:
-    from .paths import task_dir
-
-    try:
-        report = lexical_absolute_path(Path(path_value))
-        task_root = lexical_absolute_path(
-            task_dir(project_root, inp.task_group, inp.task_id)
-        )
-        relative = report.relative_to(task_root)
-    except ValueError:
-        return False
-    has_planning_layout = (
-        _PLANNING_REPORT_RE.fullmatch(report.name) is not None
-        and relative.parts[:3] == (
-            "runs",
-            "implementation-planning",
-            "reports",
-        )
-        and len(relative.parts) == 4
-    )
-    if not has_planning_layout:
-        return False
-    try:
-        validate_task_artifact_path(report, task_root, "planning report")
-    except DirectionSelectionError:
-        return False
-    return True
-
-
-def _validate_planning_entry_inputs(
-    project_root: Path, inp: PrepareInputs
-) -> None:
-    if inp.task_type != "implementation-planning":
-        if inp.selected_direction_path:
-            raise PrepareError(
-                "--selected-direction is only meaningful with --task-type "
-                f"implementation-planning; got {inp.task_type}"
-            )
-        return
-    if inp.selected_direction_path and inp.clarification_response_path:
-        raise PrepareError(
-            "implementation-planning accepts either --selected-direction for a "
-            "new plan or --clarification-response for a rerun, not both"
-        )
-    if inp.selected_direction_path:
-        return
-    if inp.clarification_response_path:
-        if not _is_existing_planning_report(
-            inp.clarification_response_path, project_root, inp
-        ):
-            raise PrepareError(
-                "implementation-planning rerun --clarification-response must point "
-                "to an existing implementation-planning report for the same task"
-            )
-        return
-    raise PrepareError(
-        "implementation-planning requires --selected-direction for a new plan or "
-        "--clarification-response to an existing implementation-planning report"
-    )
-
-
-def _resolve_planning_direction(inp: PrepareInputs) -> SelectedDirection | None:
-    if inp.task_type != "implementation-planning" or not inp.selected_direction_path:
-        return None
-    from .paths import task_dir
-
-    try:
-        report = lexical_absolute_path(Path(inp.selected_direction_path))
-        expected_task_root = lexical_absolute_path(
-            task_dir(Path(inp.project_root), inp.task_group, inp.task_id)
-        )
-        report.relative_to(expected_task_root)
-    except ValueError as exc:
-        raise PrepareError(
-            "selected direction report must belong to the same task"
-        ) from exc
-    try:
-        validate_task_artifact_path(
-            report, expected_task_root, "selected direction report"
-        )
-        return resolve_selected_direction(
-            report,
-            expected_task_key=(
-                f"{inp.project_id}:{inp.task_group}:{inp.task_id}"
-            ),
-        )
-    except DirectionSelectionError as exc:
-        raise PrepareError(str(exc)) from exc
-
-
-def _validate_reverify_scope(inp: PrepareInputs) -> None:
-    """A pinned re-verification scope is only actionable on a planning re-run.
-
-    Every other phase renders the tokens too (the template always reads them),
-    but nothing consumes them there — so a value outside the one phase that
-    acts on it is a caller mistake, not a preference to honour silently.
-    """
-    if not (inp.reverify_scope or "").strip():
-        return
-    if inp.task_type != "implementation-planning":
-        raise PrepareError(
-            "--reverify-scope is only meaningful with --task-type "
-            f"implementation-planning; got {inp.task_type}"
-        )
-    if not inp.clarification_response_path:
-        raise PrepareError(
-            "--reverify-scope needs --clarification-response: there is no prior "
-            "report to narrow re-verification against"
-        )
-    try:
-        parse_user_reverify_scope(inp.reverify_scope)
-    except ReverifyScopeError as exc:
-        raise PrepareError(str(exc)) from exc
-
-
 def _implementation_plan_contract(
     inp: PrepareInputs,
 ) -> tuple[str, Path, dict | None]:
@@ -1773,13 +1632,12 @@ def _validate_analysis_prepare_inputs(project_root: Path, inp: PrepareInputs) ->
             )
         return
     if inp.task_type == "project-analysis":
-        if inp.analysis_target:
-            raise PrepareError("project-analysis does not accept an analysis target")
-        if inp.evidence_inputs_raw:
-            raise PrepareError("project-analysis does not accept evidence inputs")
+        from .phases.project_analysis.entry import validate_project_analysis_inputs
+
+        validate_project_analysis_inputs(inp.analysis_target, inp.evidence_inputs_raw)
         return
-    if inp.task_type == "feature-analysis" and not inp.analysis_target.strip():
-        raise PrepareError("feature-analysis requires --analysis-target")
+    if inp.task_type == "feature-analysis":
+        validate_feature_target_input(inp.analysis_target)
     if inp.task_type != "feature-analysis" and inp.analysis_target:
         raise PrepareError(f"{inp.task_type} does not accept an analysis target")
     paths = parse_evidence_paths(inp.evidence_inputs_raw, project_root)
@@ -1794,127 +1652,10 @@ def _validate_analysis_prepare_inputs(project_root: Path, inp: PrepareInputs) ->
         raise PrepareError(str(exc)) from exc
 
 
-def _collect_handoff_source_report_rows(
-    rows: list, nums: list,
-) -> list:
-    """선택 stage 들의 마지막 verified 행에서 인용 표 행을 만든다 (last-wins)."""
-    last_verified: dict = {}
-    for r in rows:
-        if r.get("status") == "verified" and isinstance(r.get("stage"), int):
-            last_verified[r["stage"]] = r
-    return [(str(n), Path(last_verified[n]["report_path"])) for n in nums]
-
-
-def _render_handoff_sources(sources: list, project_root: Path) -> tuple[str, str]:
-    """인용 표와 미해결 조건은 같은 원본 판정에서 렌더한다."""
-    from .release_gate import release_handoff_allowed, verdict_token
-
-    rows, conditions = [], []
-    for stage, report in sources:
-        data = load_owned_object(report, artifact="handoff verification report")
-        if not release_handoff_allowed(data):
-            raise PrepareError(f"verification no longer release-ready: {report}")
-        relative = relative_to_project_root(report, project_root) or str(report)
-        rows.append(f"| {stage} | {relative} | `{verdict_token(data)}` |")
-        if verdict_token(data) == "conditional-accept":
-            for condition in data["finalVerdict"]["conditionalAcceptanceConditions"]:
-                conditions.append(
-                    f"- Stage {stage}, `{condition.get('id', '')}`\n"
-                    f"  - Condition: {condition.get('condition', '')}\n"
-                    f"  - Evidence required: {condition.get('evidenceRequired', '')}\n"
-                    f"  - blocksReleaseHandoff: {json.dumps(condition['blocksReleaseHandoff'])}"
-                )
-    section = "## Unresolved Conditional Acceptance Conditions\n\n" + "\n".join(conditions) if conditions else ""
-    return "\n".join(rows), section
 
 
-def _materialize_release_handoff_input(
-    workspace_root: Path, project_root: Path, inp: "PrepareInputs",
-) -> dict:
-    """release-handoff 의 입력 문서를 검증 보고서 인용으로 자동 생성한다.
-
-    brief 는 entry phase 의 입력물이라 release-handoff 에는 없다 — 이 run 의
-    `--task-brief` 자리는 여기서 생성된 input 문서가 채운다. stage 자격은
-    okstra_ctl.handoff 의 SSOT 판정을 prepare 에서도 그대로 강제한다.
-    반환: ctx 에 올릴 {"HANDOFF_STAGES": ...}."""
-    from .consumers import read_consumers
-    from .handoff import HandoffError, _require_eligible, compute_eligibility
-    from .paths import task_dir
-    from .render import render_template_with_ctx
-    from .run_context import _now_task_date
 
-    # Path("") 는 "." 로 정규화된다 — 빈 brief 센티널은 둘 다로 들어올 수 있다.
-    if str(inp.brief_path).strip() not in ("", "."):
-        raise PrepareError(
-            "--task-brief is not accepted for --task-type release-handoff — "
-            "the input document is generated from the cited final-verification "
-            "reports (pick stages via --stages, or leave it empty to take "
-            "every eligible stage)"
-        )
-    if not inp.approved_plan_path:
-        raise PrepareError(
-            "release-handoff requires --approved-plan "
-            "<implementation-planning final-report> — the Stage Map and the "
-            "consumers ledger drive stage eligibility"
-        )
-    plan = Path(inp.approved_plan_path)
-    if not plan.is_file():
-        raise PrepareError(f"approved plan not found: {plan}")
-    stage_map = _parse_stage_map_into_ctx(str(plan))
-    rows = read_consumers(plan_run_root_from_approved_plan(plan))
 
-    if inp.stages:
-        try:
-            nums = sorted({int(x) for x in inp.stages.split(",") if x.strip()})
-        except ValueError:
-            raise PrepareError(
-                f"--stages must be a comma-separated int list, got {inp.stages!r}"
-            )
-        if not nums:
-            raise PrepareError("--stages must select at least one stage")
-        try:
-            _require_eligible(stage_map, rows, nums)
-        except HandoffError as exc:
-            raise PrepareError(str(exc)) from exc
-    else:
-        eligibility = compute_eligibility(stage_map, rows)
-        nums = [e["stage"] for e in eligibility if e["eligible"]]
-        if not nums:
-            blocked = "; ".join(
-                f"stage {e['stage']}: {', '.join(e['reasons'])}"
-                for e in eligibility) or "(no stage in the Stage Map)"
-            raise PrepareError(
-                "release-handoff has no eligible stage — every stage must "
-                "carry a release-ready single-stage final-verification of its "
-                f"recorded implementation commit. {blocked}"
-            )
-    stages_csv = ",".join(str(n) for n in nums)
-    report_rows = _collect_handoff_source_report_rows(rows, nums)
-
-    source_rows, source_conditions = _render_handoff_sources(report_rows, project_root)
-
-    template = (workspace_root / "templates" / "reports"
-                / "release-handoff-input.template.md")
-    if not template.is_file():
-        raise PrepareError(
-            f"release-handoff input template missing: {template}.{_INSTALL_HINT}"
-        )
-    out = (task_dir(project_root, inp.task_group, inp.task_id)
-           / "release-handoff-input.md")
-    out.parent.mkdir(parents=True, exist_ok=True)
-    render_template_with_ctx(str(template), str(out), {
-        "TASK_KEY": f"{inp.project_id}:{inp.task_group}:{inp.task_id}",
-        "TASK_ID": inp.task_id,
-        "TASK_GROUP": inp.task_group,
-        "PROJECT_ID": inp.project_id,
-        "TASK_TYPE": inp.task_type,
-        "TASK_DATE": _now_task_date(),
-        "HANDOFF_STAGES": stages_csv,
-        "HANDOFF_SOURCE_REPORTS": source_rows,
-        "HANDOFF_CONDITIONS": source_conditions,
-    })
-    inp.brief_path = out
-    return {"HANDOFF_STAGES": stages_csv}
 
 
 QA_COMMAND_EXECUTING_TASK_TYPES = ("implementation", "final-verification")
@@ -2659,28 +2400,11 @@ def _read_model_defaults(path: Path) -> dict[str, tuple[str, ...]]:
     return defaults
 
 
-def _validate_option_selection_roster(
-    task_type: str, workers: Sequence[str]
-) -> None:
-    """Require independent analysis from three workers before option selection."""
-    if task_type != "implementation-option-selection":
-        return
-    analyser_count = sum(worker != "report-writer" for worker in workers)
-    if analyser_count < 3:
-        raise PrepareError(
-            "implementation-option-selection requires at least 3 analyser workers"
-        )
+def _validate_option_selection_roster(task_type: str, workers: Sequence[str]) -> None:
+    if task_type == "implementation-option-selection":
+        validate_analyser_roster(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
 
 
 @dataclass
@@ -2774,7 +2498,7 @@ def recommended_role_models(
     codex 이고 다른 provider 요청은 거부된다(`resolve_lead_provider`). 그래서
     `lead_provider` 를 받아 그 provider 의 기본값으로 해소한다. 받지 않으면
     role 별 레거시 기본값(claude 계열)으로 떨어지는데, 그 값을 codex 호스트
-    화면에 그대로 쓰면 안내는 `opus` 인데 prepare 는 `gpt-6-sol` 을 배정한다.
+    화면에 그대로 쓰면 안내는 `opus` 인데 prepare 는 `gpt-6.1-sol` 을 배정한다.
     """
     lead_provider_id = lead_provider or "claude"
     report_writer_provider_id = report_writer_provider or "claude"
@@ -3562,6 +3286,9 @@ def _write_instruction_set_sources(
     profile_rendered = profile_content
     if inp.task_type == "implementation":
         profile_rendered += "\n\n{{DESIGN_PREP_CONTEXT}}\n\n{{FIX_RUN_CONTEXT}}"
+        profile_rendered = _implementation_stage.resolve_instruction_paths(
+            profile_rendered, Path(ctx["WORKSPACE_ROOT"])
+        )
     profile_tokens = (
         "EXECUTOR_WORKER_ID",
         "EXECUTOR_PROVIDER",
@@ -3584,13 +3311,14 @@ def _write_instruction_set_sources(
         profile_rendered = profile_rendered.replace("{{" + key + "}}", ctx.get(key, ""))
     (instruction_set / "analysis-profile.md").write_text(profile_rendered, encoding="utf-8")
     if inp.task_type == "implementation":
-        executor_source = (
-            Path(ctx["WORKSPACE_ROOT"])
-            / "prompts"
-            / "profiles"
-            / "_implementation-executor.md"
+        from .phases.catalog import profile_sidecar
+
+        executor_source = profile_sidecar(
+            Path(ctx["WORKSPACE_ROOT"]), "prompts/profiles/_implementation-executor.md"
+        )
+        executor_rendered = _implementation_stage.resolve_instruction_paths(
+            executor_source.read_text(encoding="utf-8"), Path(ctx["WORKSPACE_ROOT"])
         )
-        executor_rendered = executor_source.read_text(encoding="utf-8")
         for key in profile_tokens:
             executor_rendered = executor_rendered.replace(
                 "{{" + key + "}}", ctx.get(key, "")
@@ -3700,17 +3428,10 @@ def _write_instruction_set_sources(
         ),
     )
     if inp.task_type == "technical-verification":
-        verification_path = write_technical_verification_input(
-            json.loads(ctx["TECHNICAL_VERIFICATION_INPUT_JSON"]),
+        packet += materialize_technical_input_packet(
+            ctx["TECHNICAL_VERIFICATION_INPUT_JSON"],
             Path(ctx["RUN_DIR"]), ctx["RUN_MANIFESTS_SEQ"],
         )
-        packet += (
-            "\n## Technical Verification Input\n\n"
-            f"- Frozen input: `{verification_path}`\n"
-            f"- Experiment copies only: `{ctx['RUN_DIR']}/experiments/{ctx['RUN_MANIFESTS_SEQ']}/<worker-id>/`\n"
-            "- Read the input before planning experiments; copy each fact identity verbatim into results.\n"
-            + "\n```json\n" + ctx["TECHNICAL_VERIFICATION_INPUT_JSON"] + "\n```\n"
-        )
     if inp.task_type in ANALYSIS_TASK_TYPES:
         packet += (
             "\n## Analysis Evidence\n\n"
@@ -4021,7 +3742,7 @@ def _record_fix_cycle_events(inp: PrepareInputs, ctx: dict) -> str:
 
 def _finalize_status_and_render_manifests(
     inp: PrepareInputs, ctx: dict, task_index_template: Path,
-    forbidden_by_phase: dict[str, str],
+    boundary: dict[str, str],
 ) -> None:
     """최종 task/run status 를 확정하고 workflow state 를 재계산한 뒤 team-state,
     task-manifest, task-index, run-manifest, timeline, discovery 산출물을 렌더한다."""
@@ -4038,7 +3759,7 @@ def _finalize_status_and_render_manifests(
         current_run_status=ctx["CURRENT_RUN_STATUS"],
         current_task_status=ctx["CURRENT_TASK_STATUS"],
         render_only=inp.render_only,
-        forbidden_by_phase=forbidden_by_phase,
+        boundary=boundary,
         work_category=inp.work_category,
     ))
     render_team_state(ctx["TEAM_STATE_PATH"], ctx)
@@ -4329,7 +4050,7 @@ def _reconcile_prior_runs(ctx: dict) -> None:
 
 
 def _initial_workflow_ctx(
-    inp: PrepareInputs, forbidden_by_phase: dict
+    inp: PrepareInputs, boundary: dict
 ) -> dict[str, str]:
     """Workflow tokens for a run that has been prepared but not started.
 
@@ -4346,7 +4067,7 @@ def _initial_workflow_ctx(
             current_run_status=run_status,
             current_task_status=task_status,
             render_only=inp.render_only,
-            forbidden_by_phase=forbidden_by_phase,
+            boundary=boundary,
         ),
     }
 
@@ -4700,16 +4421,11 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     technical_input = None
     from .paths import task_dir
     if inp.task_type == "technical-verification":
-        if not inp.clarification_response_path:
-            raise PrepareError("technical-verification requires --clarification-response pointing to this task's option-selection record")
-        try:
-            technical_input = resolve_technical_verification_input(
-                Path(inp.clarification_response_path), project_root,
-                task_dir(project_root, inp.task_group, inp.task_id),
-                f"{inp.project_id}:{inp.task_group}:{inp.task_id}",
-            )
-        except ValueError as exc:
-            raise PrepareError(str(exc)) from exc
+        technical_input = prepare_technical_verification_input(
+            inp.clarification_response_path, project_root,
+            task_dir(project_root, inp.task_group, inp.task_id),
+            f"{inp.project_id}:{inp.task_group}:{inp.task_id}",
+        )
     if inp.task_type == "implementation":
         ctx_stage_map = _prepare_implementation_approved_plan(inp)
 
@@ -4717,11 +4433,13 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     # 이후의 모든 brief 소비 경로(material/instruction-set 복사)는 그대로 동작한다.
     handoff_tokens = {"HANDOFF_STAGES": ""}
     if inp.task_type == "release-handoff":
-        handoff_tokens = _materialize_release_handoff_input(
-            workspace_root, project_root, inp)
+        handoff_tokens = materialize_handoff_input(
+            workspace_root, project_root, inp, install_hint=_INSTALL_HINT)
 
     workers, selected_reviewers = _resolve_roster(inp, profile_file)
-    pr_template_path_str, pr_template_source = _resolve_pr_template(inp)
+    pr_template_path_str, pr_template_source = (
+        resolve_pr_template(inp) if inp.task_type == "release-handoff" else ("", "")
+    )
 
     assignment_context, assignment_plan = _resolve_prepare_assignments(
         inp=inp,
@@ -4882,7 +4600,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         if inp.approved_plan_path else ""
     )
 
-    forbidden_by_phase = load_phase_forbidden(workspace_root)
+    boundary = load_phase_boundary(workspace_root, inp.task_type)
 
     # ---- assemble full ctx (the values render functions expect) ----
     ctx.update({
@@ -4908,7 +4626,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         "BRIEF_RELATIVE_PATH": brief_relative,
         **_model_ctx(models),
         **_related_tasks_ctx(ctx, inp),
-        **_initial_workflow_ctx(inp, forbidden_by_phase),
+        **_initial_workflow_ctx(inp, boundary),
         "VALIDATION_STATUS": "not-run",
         "VALIDATION_UPDATED_AT": "",
         "VALIDATION_FAILURES_JSON": "[]",
@@ -4975,7 +4693,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
 
     # ---- final status + manifest/discovery renders ----
     _finalize_status_and_render_manifests(
-        inp, ctx, task_index_template, forbidden_by_phase
+        inp, ctx, task_index_template, boundary
     )
     persist_static_execution_identity(
         run_manifest_path=Path(ctx["RUN_MANIFEST_PATH"]),