okstra 0.205.1 → 0.206.1

package/runtime/python/okstra_ctl/run.py

@@ -14,12 +14,17 @@ 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,
 )
 
-import hashlib
 from argparse import (
     Action,
     ArgumentError,
@@ -41,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
@@ -56,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
@@ -68,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,
 )
@@ -206,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,
@@ -214,11 +225,19 @@ 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 .plan_run_root import plan_run_root_from_approved_plan
-from . import implementation_stage as _implementation_stage
+from .phases.catalog import PhaseAssetError, profile_markdown, resolve_include
+from .phases.final_verification.target import acquire_final_verification_target
+from .phases.final_verification.entry import (
+    apply_verification_target,
+    reject_prepare_flags,
+    single_stage_worktree,
+    verification_target_request,
+    write_verification_target_snapshot,
+)
+from .phases.implementation import entry as _implementation_stage
 from .work_categories import resolve_work_category
 from .worktree import (
     WorktreeProvision,
@@ -228,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.
 #
@@ -509,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:
@@ -688,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:
@@ -1215,8 +1226,11 @@ _HTML_COMMENT = re.compile(r"<!--.*?-->", re.DOTALL)
 def _expand_profile_includes(profile_path: Path, _depth: int = 0) -> str:
     """Resolve `{{INCLUDE:<name>}}` directives in a profile file.
 
-    Includes are resolved relative to the profile's directory. A maximum
-    recursion depth of 4 prevents accidental cycles; the included file
+    `phases.catalog.resolve_include` picks the search root: an unmigrated
+    profile resolves beside itself, and a phase package's `profile.md`
+    resolves through the logical paths of the asset root that holds it.
+    Recursion stops at depth 4
+    so a cycle fails instead of looping; the included file
     contents replace the directive line in-place. Missing include targets
     raise PrepareError so a bad reference fails fast instead of silently
     leaving a `{{INCLUDE:...}}` token in the rendered profile.
@@ -1235,7 +1249,10 @@ def _expand_profile_includes(profile_path: Path, _depth: int = 0) -> str:
 
     def _sub(match: "re.Match[str]") -> str:
         target_name = match.group(1).strip()
-        target = profile_path.parent / target_name
+        try:
+            target = resolve_include(profile_path, target_name)
+        except PhaseAssetError as exc:
+            raise PrepareError(str(exc)) from exc
         if not target.is_file():
             raise PrepareError(
                 f"profile include target missing: {target} (referenced from {profile_path})"
@@ -1289,7 +1306,10 @@ class _ResolvedAssets:
 
 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"
+    try:
+        profile_file = profile_markdown(workspace_root, inp.task_type)
+    except PhaseAssetError as exc:
+        raise PrepareError(str(exc)) from exc
     if not profile_file.is_file():
         raise PrepareError(
             f"analysis profile file not found for task-type {inp.task_type}: "
@@ -1335,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,
@@ -1417,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).
@@ -1438,18 +1451,10 @@ def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
                 "--approved-plan <path-to-final-report.md>"
             )
         if inp.task_type == "final-verification":
-            # final-verification 에서 --approve / --implementation-option 은
-            # 의미가 없다 (승인은 implementation 진입 시 이미 끝났다).
-            if inp.approve_plan_ack:
-                raise PrepareError(
-                    "--approve is only meaningful with --task-type implementation "
-                    "and --approved-plan <path>"
-                )
-            if inp.implementation_option:
-                raise PrepareError(
-                    "--implementation-option is only meaningful with --task-type "
-                    "implementation and --approved-plan <path>"
-                )
+            reject_prepare_flags(
+                approve_plan_ack=inp.approve_plan_ack,
+                implementation_option=inp.implementation_option,
+            )
             ctx_stage_map = _parse_stage_map_into_ctx(inp.approved_plan_path)
     else:
         if inp.approve_plan_ack:
@@ -1482,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]:
@@ -1764,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)
@@ -1785,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")
@@ -2650,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
@@ -3460,139 +3193,6 @@ def _git_out(cwd, *args) -> str:
     return r.stdout.strip() if r.returncode == 0 else ""
 
 
-def _single_stage_final_verification_worktree(inp: "PrepareInputs") -> WorktreeProvision:
-    """Placeholder until the selected stage registry row is resolved."""
-    return WorktreeProvision(
-        status="deferred-final-verification",
-        note=(
-            "final-verification single-stage uses the selected implementation "
-            "stage worktree from the registry"
-        ),
-    )
-
-
-def _format_integration(integ) -> str:
-    """stage 자동 통합 결과를 사람이 읽을 한국어 마크다운 블록으로 만든다."""
-    def _csv(xs):
-        return ", ".join(str(x) for x in xs) if xs else "없음"
-
-    skipped = "; ".join(f"stage {n}({why})" for n, why in integ.teardown_skipped)
-    lines = [
-        "- **Stage 자동 통합 결과** (whole-task final-verification):",
-        "- **머지된 stage:** " + _csv(integ.merged),
-        "- **이미 머지됨:** " + _csv(integ.already_merged),
-        "- **정리(teardown)된 stage:** " + _csv(integ.torn_down),
-        "- **정리 보류:** " + (skipped or "없음"),
-    ]
-    for w in integ.warnings:
-        lines.append("- **경고:** " + w)
-    return "\n".join(lines)
-
-
-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:
-    """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 {stage} worktree"
-        )
-    if acquisition.integration_result is not None:
-        ctx["STAGE_INTEGRATION"] = _format_integration(
-            acquisition.integration_result
-        )
-    if acquisition.relocations:
-        moved = "\n".join(
-            f"- stage {row['stage']}: `{row['from']}` → `{row['to']}`"
-            for row in acquisition.relocations
-        )
-        ctx["STAGE_INTEGRATION"] = (
-            f"{ctx.get('STAGE_INTEGRATION', '')}\n"
-            "Nested stage worktrees moved out of the verification worktree "
-            "(registry updated; contents and branches unchanged):\n"
-            f"{moved}"
-        ).strip()
-    diff_stat = _git_out(target.worktree_path, "diff", "--stat",
-                         f"{target.base}..{target.head}")
-    ctx["VERIFICATION_SCOPE"] = target.scope
-    ctx["VERIFICATION_WORKTREE_PATH"] = target.worktree_path
-    ctx["VERIFICATION_BASE_REF"] = target.base
-    ctx["VERIFICATION_HEAD_REF"] = target.head
-    ctx["VERIFICATION_TARGET"] = _format_verification_target(target, diff_stat)
-
-
-def _format_verification_target(
-    target: _stage_targets.FinalVerificationTarget,
-    diff_stat: str,
-) -> str:
-    reports = "\n".join(
-        f"  - stage {s}: `{rp or '(report_path unrecorded)'}`"
-        for s, rp in zip(target.stages, target.reports)
-    )
-    return (
-        f"- **Verification scope:** `{target.scope}`\n"
-        f"- **Worktree:** `{target.worktree_path}`\n"
-        f"- **Verification base ref:** `{target.base}`\n"
-        f"- **Verification head ref:** `{target.head}`\n"
-        f"- **Stages under verification:** {target.stages}\n"
-        f"- **Source implementation reports:**\n{reports}\n"
-        f"- **Verification diff stat:**\n```\n{diff_stat}\n```"
-    )
-
-
-def write_verification_target_snapshot(
-    instruction_set: Path,
-    target_markdown: str,
-) -> tuple[Path, str]:
-    """Persist one normalized final-verification target and return its digest."""
-    normalized = target_markdown.replace("\r\n", "\n").replace("\r", "\n")
-    normalized = normalized.rstrip() + "\n"
-    digest = "sha256:" + hashlib.sha256(normalized.encode("utf-8")).hexdigest()
-    path = instruction_set / "verification-target.md"
-    # 계산 규칙을 값과 함께 적는다. 워커는 이 다이제스트를 프롬프트 앵커로도
-    # 받는데, 규칙을 모르면 파일 전체 바이트로 재고 반드시 불일치를 본다 —
-    # 실측(2026-08-26): 그렇게 잰 검증자가 스냅샷이 변조됐다고 보고했다.
-    # 다이제스트 줄은 줄머리 앵커로 잘리므로(`_TARGET_DIGEST_RE`) 그 뒤에
-    # 붙는 이 줄은 본문에 들어가지 않는다.
-    path.write_text(
-        normalized
-        + f"- **Verification target digest:** `{digest}`\n"
-        + "- **Digest rule:** `sha256` of the text above this line, with CRLF "
-          "and CR normalized to LF, trailing whitespace stripped, and exactly "
-          "one closing newline. This line and the digest line are not covered.\n",
-        encoding="utf-8",
-    )
-    return path, digest
-
-
 def _write_verification_target_artifact(
     inp: PrepareInputs,
     ctx: dict,
@@ -3686,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",
@@ -3708,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, "")
@@ -3824,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"
@@ -4145,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 산출물을 렌더한다."""
@@ -4162,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)
@@ -4453,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.
 
@@ -4470,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,
         ),
     }
 
@@ -4595,7 +4192,7 @@ def _provision_task_and_stage(
         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)
+            worktree = single_stage_worktree()
             # Single-stage final-verification namespaces its run path under
             # runs/final-verification/stage-<N> (same isolation as
             # implementation) so concurrent per-stage verifications never
@@ -4824,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)
 
@@ -4841,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,
@@ -5006,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({
@@ -5032,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": "[]",
@@ -5053,10 +4647,26 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         ctx["CLAUDE_RESUME_COMMAND_RELATIVE_PATH"] = ""
         ctx["CLAUDE_RESUME_COMMAND_FILENAME"] = ""
     if inp.task_type == "final-verification":
-        acquisition = _stage_targets.acquire_final_verification_target(
-            _final_verification_target_request(inp, ctx_stage_map)
+        acquisition = acquire_final_verification_target(
+            verification_target_request(
+                project_root=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=inp.approved_plan_path,
+                stage=inp.stage,
+                stage_map=ctx_stage_map,
+            )
+        )
+        target = acquisition.target
+        diff_stat = _git_out(
+            target.worktree_path,
+            "diff",
+            "--stat",
+            f"{target.base}..{target.head}",
         )
-        _apply_final_verification_target(ctx, acquisition)
+        apply_verification_target(ctx, acquisition, diff_stat)
 
     _write_bundle_artifacts(
         inp, ctx, project_root, lead_runtime, claude_session_id,
@@ -5083,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"]),