okstra 0.205.1 → 0.206.0

package/{docs/task-process/final-verification.md → runtime/python/okstra_ctl/phases/final_verification/spec.md}

@@ -1,6 +1,19 @@
-# final-verification process
+# final-verification
 
-## Index
+This directory is the canonical home of the final-verification phase. Report field shapes stay in `schemas/final-report-v2.0.schema.json` and `schemas/final-report-v3.0.schema.json` under `finalVerification`. The next phase is chosen in `prompts/lead/phase-routing.md`.
+
+## Guarantees
+
+| ID | Guarantee | Enforcement |
+|---|---|---|
+| FV-1 | A report that does not match the prepared verification target is rejected | `scripts/okstra_ctl/phases/final_verification/validation.py::validate_verification_target_match` |
+| FV-2 | A release-handoff route requires a release-ready verdict | `validators/validate-run.py::_refuse_unsuitable_final_verification_route` |
+| FV-3 | The final-verification destination list matches the report schema | `tests/contract/test_phase_catalog.py::test_final_verification_routing_targets_match_the_report_schema` |
+| FV-4 | The phase profile is not also stored under prompts/profiles | `tests/contract/test_phase_catalog.py::test_migrated_profile_is_absent_from_the_legacy_directory` |
+
+## Process
+
+### Index
 
 - [1. Purpose](#1-purpose)
 - [2. okstra-run wizard flow](#2-okstra-run-wizard-flow)
@@ -11,11 +24,11 @@
 - [7. Forbidden actions](#7-forbidden-actions)
 - [8. Verified code](#8-verified-code)
 
-## 1. Purpose
+### 1. Purpose
 
 `final-verification` determines whether the committed diff produced by `implementation` can be finally accepted. Without performing any source edit or follow-up fix, it confirms that the implementation report matches the actual checkout, then records acceptance blockers, residual risk, and a release recommendation.
 
-## 2. okstra-run wizard flow
+### 2. okstra-run wizard flow
 
 ```mermaid
 flowchart TD
@@ -36,7 +49,7 @@ Launch selection uses role slots and model refs only: current-session lead is th
 
 This phase does not ask for `base-ref` directly. The wizard selects whole-task or a single stage from the approved plan's Stage Map, and prepare resolves `VERIFICATION_TARGET` from the registry / `consumers.jsonl` / git state.
 
-## 3. entry gate
+### 3. entry gate
 
 ```mermaid
 sequenceDiagram
@@ -69,7 +82,7 @@ prepare fixes the verification target before worker dispatch. If any of the foll
 
 Once started, the lead treats `VERIFICATION_TARGET` as authoritative. It does not re-pick worktree/base/head/stage/source report from the brief.
 
-## 4. Verification execution flow
+### 4. Verification execution flow
 
 ```mermaid
 flowchart TD
@@ -104,29 +117,30 @@ flowchart LR
 
 The runtime validates the `project.json` `qaCommands` deny-list at the prepare stage for both `implementation` and `final-verification` (`okstra_ctl.run.validate_project_qa_commands`), so a Tier 2 declaration carrying a mutating token stops the run before it starts. Tier 1 comes from the brief or the approved plan and is not covered by that gate — the lead self-checks those commands right before execution.
 
-## 5. Verdict and routing
+### 5. Verdict and routing
 
 ```mermaid
 flowchart TD
     Verdict{Verdict Token}
-    Verdict -->|accepted| Release[route to release-handoff or done]
+    Verdict -->|accepted| Ready[release-ready verdict recorded]
     Verdict -->|conditional-accept| Conditions[conditions listed exhaustively]
-    Conditions --> Followup[route by cause, direction, or detailed-plan defect]
     Verdict -->|blocked| Blockers[acceptance blockers with evidence]
-    Blockers --> Followup
+    Ready --> Routing[lead reads phase-routing.md]
+    Conditions --> Routing
+    Blockers --> Routing
 ```
 
 `## 7. Final Verdict` must contain exactly one `Verdict Token` field, and its value is one of the following three.
 
-- `accepted`: a state that becomes a release-handoff candidate — whole-task for every stage it covers, single-stage for that one stage's PR
-- `conditional-accept`: all conditions must be stated explicitly, and when a condition is a gate it blocks the next phase
-- `blocked`: a state that has acceptance blockers and cannot proceed to release-handoff
+- `accepted`: the delivered work meets the acceptance gates
+- `conditional-accept`: every condition is stated
+- `blocked`: at least one acceptance blocker is recorded
 
-A blocked or conditional run routes to the phase that owns the defect. When every remaining blocker is an environment or configuration fault this report already diagnosed - a `qaCommands` entry naming a path that no longer exists, a missing credential, a stale fixture - the target is `final-verification` itself: repair the configuration and re-verify the same head, rather than spending a root-cause phase on a cause that is already known.
+The lead chooses the destination from `prompts/lead/phase-routing.md` using this verdict and the blocker facts. This phase does not choose it.
 
 Vague phrasings such as "looks good" or "mostly ready" are not allowed.
 
-## 6. Deliverables
+### 6. Deliverables
 
 ```mermaid
 flowchart TD
@@ -155,7 +169,7 @@ The final report requires at least the following.
 - read-only command log and exit code
 - next safe phase recommendation
 
-## 7. Forbidden actions
+### 7. Forbidden actions
 
 ```mermaid
 flowchart TD
@@ -168,14 +182,17 @@ flowchart TD
     FV -. forbidden .-> Hide[hide verifier dissent]
 ```
 
-The stage merge of whole-task mode is a runtime-owned integration step that prepare performs; the matching teardown is a runtime-owned step too, but it runs after the verdict (Phase 7 `teardown-stages`) and only when the verdict clears the work for release. After that, lead verification is read-only. Source edit, follow-up fix, and scope expansion are all forbidden. When a defect is found, it is not fixed within the current run. Cause defects route to `error-analysis`, selected-direction defects route to `implementation-option-selection`, and detailed-plan defects route to `implementation-planning`.
+The stage merge of whole-task mode is a runtime-owned integration step that prepare performs; the matching teardown is a runtime-owned step too, but it runs after the verdict (Phase 7 `teardown-stages`) and only when the verdict clears the work for release. After that, lead verification is read-only. Source edit, follow-up fix, and scope expansion are all forbidden. When a defect is found, it is not fixed within the current run. The lead chooses the next phase from `prompts/lead/phase-routing.md` using the blocker facts this phase recorded.
 
-## 8. Verified code
+### 8. Verified code
 
-- [`prompts/profiles/final-verification.md`](../../prompts/profiles/final-verification.md)
-- [`templates/reports/final-verification-input.template.md`](../../templates/reports/final-verification-input.template.md)
-- [`scripts/okstra_ctl/wizard/`](../../scripts/okstra_ctl/wizard/)
-- [`scripts/okstra_ctl/run.py`](../../scripts/okstra_ctl/run.py)
-- [`scripts/okstra_ctl/workflow.py`](../../scripts/okstra_ctl/workflow.py)
-- [`scripts/okstra_ctl/render.py`](../../scripts/okstra_ctl/render.py)
-- [`prompts/lead/okstra-lead-contract.md`](../../prompts/lead/okstra-lead-contract.md)
+- `scripts/okstra_ctl/phases/final_verification/profile.md`
+- `scripts/okstra_ctl/phases/final_verification/profile.json`
+- `scripts/okstra_ctl/phases/final_verification/entry.py`
+- `scripts/okstra_ctl/phases/final_verification/report.py`
+- `scripts/okstra_ctl/phases/final_verification/validation.py` `_validate_added_surface_audit`
+- `prompts/lead/phase-routing.md`
+- `schemas/final-report-v2.0.schema.json` and `schemas/final-report-v3.0.schema.json` (`finalVerification`, `finalVerdict`, `routingRecommendation.target`)
+- `templates/reports/final-verification-input.template.md`
+- `validators/validate-run.py`
+- `scripts/okstra_ctl/release_gate.py`

package/runtime/python/okstra_ctl/phases/final_verification/target.py

@@ -0,0 +1,296 @@
+"""final-verification 이 검증할 대상을 고른다.
+
+단일 stage 검증은 그 stage 의 worktree 를 읽기만 한다. 전체 작업 검증은 완료된
+stage 전부를 담은 stage 브랜치가 있으면 그것을 쓰고, 없으면 task 브랜치에 통합한
+결과를 쓴다. 원장·registry·Git·통합은 공통 모듈이 제공하고, 여기서는 어느 것을
+언제 부를지만 정한다. 전체 과정은 task 키 잠금 하나 안에서 돈다.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from pathlib import Path
+from typing import Any
+
+from okstra_project.dirs import okstra_home
+from okstra_project.slug import slugify
+
+from okstra_ctl import worktree_registry
+from okstra_ctl.consumers import (
+    backfill_done_from_carry,
+    latest_done_by_stage,
+    read_stage_consumer_state,
+)
+from okstra_ctl.locks import worktree_provision_mutex
+from okstra_ctl.plan_run_root import plan_run_root_from_approved_plan
+from okstra_ctl.prepare_error import PrepareError
+from okstra_ctl.stage_integrate import IntegrateResult
+from okstra_ctl.stage_reconcile import auto_reconcile_best_effort
+from okstra_ctl.stage_targets import (
+    FinalVerificationTarget,
+    StageTargetError,
+    _resolve_and_integrate_whole_task_unlocked,
+    containing_stage,
+    relocate_nested_stage_worktrees,
+)
+from okstra_ctl.worktree import _git, is_dirty_excluding_okstra
+
+
+@dataclass(frozen=True)
+class FinalVerificationTargetRequest:
+    """Semantic inputs needed to acquire one final-verification target."""
+
+    project_root: Path
+    project_id: str
+    task_group: str
+    task_id: str
+    work_category: str
+    approved_plan_path: Path
+    stage: int | None
+    stage_map: tuple[dict[str, Any], ...]
+
+
+@dataclass(frozen=True)
+class FinalVerificationTargetAcquisition:
+    """Resolved target facts returned to the prepare adapter."""
+
+    target: FinalVerificationTarget
+    worktree_branch: str
+    integration_result: IntegrateResult | None
+    # whole-task 진입이 task worktree 안에서 꺼낸 중첩 stage worktree.
+    # `{"stage": N, "from": <old path>, "to": <new path>}` 행.
+    relocations: tuple[dict[str, Any], ...] = ()
+
+
+def _resolve_single_stage_target(
+    *,
+    requested_stage: int,
+    done_rows: list[dict[str, Any]],
+    stage_base: str,
+    stage_worktree_path: str,
+    stage_head: str,
+    stage_dirty: bool,
+) -> FinalVerificationTarget:
+    """Resolve single-stage final-verification target, enforcing all gates."""
+    n = requested_stage
+    done_by_stage = latest_done_by_stage(done_rows)
+    if n not in done_by_stage:
+        raise StageTargetError(
+            f"final-verification(single-stage): stage {n} not done — "
+            f"run implementation --stage {n} first"
+        )
+    if not stage_worktree_path:
+        raise StageTargetError(
+            f"final-verification(single-stage): stage worktree not found for "
+            f"stage {n} (torn down?) — use whole-task mode (--stage auto)"
+        )
+    if stage_dirty:
+        raise StageTargetError(
+            "final-verification: worktree has uncommitted source changes "
+            "(outside .okstra/) — commit or stash before verifying"
+        )
+    return FinalVerificationTarget(
+        scope="single-stage",
+        base=stage_base,
+        head=stage_head,
+        worktree_path=stage_worktree_path,
+        stages=[n],
+        reports=[done_by_stage[n].get("report_path", "")],
+    )
+
+
+def _read_final_verification_done_rows(
+    request: FinalVerificationTargetRequest,
+    registry_coordinates: tuple[str, str, str],
+) -> list[dict[str, Any]]:
+    plan_run_root = plan_run_root_from_approved_plan(request.approved_plan_path)
+    backfill_done_from_carry(plan_run_root)
+    project_id, task_group, task_id = registry_coordinates
+    auto_reconcile_best_effort(
+        replace(
+            request,
+            project_id=project_id,
+            task_group=task_group,
+            task_id=task_id,
+        ),
+        plan_run_root,
+    )
+    return read_stage_consumer_state(plan_run_root).done_rows
+
+
+def _final_verification_registry_coordinates(
+    request: FinalVerificationTargetRequest,
+) -> tuple[str, str, str]:
+
+    def segment(value: str) -> str:
+        return slugify(value) or "_"
+
+    return (
+        segment(request.project_id),
+        segment(request.task_group),
+        segment(request.task_id),
+    )
+
+
+def _acquire_single_stage_target(
+    request: FinalVerificationTargetRequest,
+    done_rows: list[dict[str, Any]],
+    registry_coordinates: tuple[str, str, str],
+) -> FinalVerificationTargetAcquisition:
+    stage = request.stage
+    assert stage is not None
+    row = worktree_registry.get_stage_row(*registry_coordinates, stage)
+    worktree_path = (row or {}).get("worktree_path", "")
+    head = ""
+    if worktree_path and Path(worktree_path).is_dir():
+        head_result = _git(worktree_path, "rev-parse", "HEAD")
+        if head_result.returncode == 0:
+            head = head_result.stdout.strip()
+    if not head:
+        worktree_path = ""
+    target = _resolve_single_stage_target(
+        requested_stage=stage,
+        done_rows=done_rows,
+        stage_base=(row or {}).get("base_ref", ""),
+        stage_worktree_path=worktree_path,
+        stage_head=head,
+        stage_dirty=(
+            is_dirty_excluding_okstra(worktree_path) if worktree_path else False
+        ),
+    )
+    return FinalVerificationTargetAcquisition(
+        target=target,
+        worktree_branch=(row or {}).get("branch", ""),
+        integration_result=None,
+    )
+
+
+def _acquire_tip_stage_target(
+    request: FinalVerificationTargetRequest,
+    done_rows: list[dict[str, Any]],
+    registry_coordinates: tuple[str, str, str],
+) -> FinalVerificationTargetAcquisition | None:
+    """전체를 담은 단일 stage 브랜치가 있으면 그것을 whole-task 검증 대상으로
+    삼는다 — 머지 없이. 없거나 그 워크트리가 쓸 수 없으면 None 을 돌려 기존
+    task 브랜치 통합 경로로 넘긴다."""
+    done = latest_done_by_stage(done_rows)
+    planned = [int(s["stage_number"]) for s in request.stage_map]
+    if any(n not in done for n in planned):
+        return None  # 미완 stage 의 거부 메시지는 기존 경로가 낸다
+    tip = containing_stage(request.project_root,
+                          {n: done[n] for n in planned})
+    if tip is None:
+        return None
+    row = worktree_registry.get_stage_row(*registry_coordinates, tip) or {}
+    worktree_path = row.get("worktree_path", "")
+    if not worktree_path or not Path(worktree_path).is_dir():
+        return None
+    head_result = _git(worktree_path, "rev-parse", "HEAD")
+    if head_result.returncode != 0:
+        return None
+    head = head_result.stdout.strip()
+    if head != done[tip].get("head_commit", ""):
+        # 브랜치 tip 이 done 기록과 갈라져 있다. 검증 대상이 무엇인지 모호하므로
+        # 판정을 기존 경로로 넘긴다.
+        return None
+    if is_dirty_excluding_okstra(worktree_path):
+        raise StageTargetError(
+            "final-verification: worktree has uncommitted source changes "
+            "(outside .okstra/) — commit or stash before verifying"
+        )
+    anchor_base = worktree_registry.get_implementation_base(
+        *registry_coordinates) or ""
+    stages = sorted(planned)
+    return FinalVerificationTargetAcquisition(
+        target=FinalVerificationTarget(
+            scope="whole-task",
+            base=anchor_base,
+            head=head,
+            worktree_path=worktree_path,
+            stages=stages,
+            reports=[done[n].get("report_path", "") for n in stages],
+        ),
+        relocations=(),
+        worktree_branch=row.get("branch", ""),
+        integration_result=None,
+    )
+
+
+def _acquire_whole_task_target(
+    request: FinalVerificationTargetRequest,
+    done_rows: list[dict[str, Any]],
+    registry_coordinates: tuple[str, str, str],
+) -> FinalVerificationTargetAcquisition:
+    tip = _acquire_tip_stage_target(request, done_rows, registry_coordinates)
+    if tip is not None:
+        return tip
+
+    project_id, task_group, task_id = registry_coordinates
+    entry = worktree_registry.lookup(project_id, task_group, task_id)
+    worktree_path = (
+        entry.worktree_path if entry is not None else str(request.project_root)
+    )
+    relocations = (
+        relocate_nested_stage_worktrees(
+            project_id, task_group, task_id, worktree_path,
+            stages=[int(row["stage_number"]) for row in request.stage_map],
+        )
+        if entry is not None
+        else []
+    )
+    whole = _resolve_and_integrate_whole_task_unlocked(
+        project_id=project_id,
+        task_group=task_group,
+        task_id=task_id,
+        task_worktree_path=worktree_path,
+        stage_map=list(request.stage_map),
+        done_rows=done_rows,
+        anchor_base=(
+            worktree_registry.get_implementation_base(
+                project_id, task_group, task_id
+            )
+            or ""
+        ),
+        # 정리는 판정 뒤로 미룬다(Phase 7 `teardown-stages`). 되돌릴 수 없는 정리를
+        # 판정 앞에 두면, 재작업이 가장 필요한 blocked 판정에서 stage 작업물이 이미
+        # 사라져 있다. 여기서는 통합만 하고 worktree/registry 키는 남긴다.
+        teardown=False,
+    )
+    return FinalVerificationTargetAcquisition(
+        target=whole["target"],
+        relocations=tuple(relocations),
+        worktree_branch=entry.branch if entry is not None else "",
+        integration_result=whole["integrate_result"],
+    )
+
+
+def acquire_final_verification_target(
+    request: FinalVerificationTargetRequest,
+) -> FinalVerificationTargetAcquisition:
+    """Acquire a stable final-verification target behind one task-key lock."""
+    try:
+        with worktree_provision_mutex(
+            okstra_home(),
+            request.project_id,
+            slugify(request.task_group),
+            slugify(request.task_id),
+        ):
+            registry_coordinates = _final_verification_registry_coordinates(request)
+            done_rows = _read_final_verification_done_rows(
+                request,
+                registry_coordinates,
+            )
+            if request.stage is not None:
+                return _acquire_single_stage_target(
+                    request,
+                    done_rows,
+                    registry_coordinates,
+                )
+            return _acquire_whole_task_target(
+                request,
+                done_rows,
+                registry_coordinates,
+            )
+    except PrepareError:
+        raise
+    except (OSError, RuntimeError, StageTargetError, ValueError) as exc:
+        raise PrepareError(str(exc)) from exc

package/runtime/python/okstra_ctl/phases/final_verification/validation.py

@@ -0,0 +1,190 @@
+"""final-verification 이 소유하는 보고서 내용 판정.
+
+추가 표면·판정·검증 범위의 일관성과, 보고서가 준비된 검증 대상을 그대로
+비추는지를 본다. 이동 적합성은 공통 검증이 이어서 본다. 이 모듈은 공통 실행 조립부를
+가져오지 않는다.
+"""
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from pathlib import Path
+
+from okstra_ctl.verification_target import TARGET_FIELD_RES, read_verification_target
+
+_ADDED_SURFACE_NO_CALLER_RE = re.compile(r"^\s*none\b", re.IGNORECASE)
+
+
+def validate_final_verification_content(data: dict, failures: list[str]) -> None:
+    """판정·차단 항목·검증 범위가 서로 맞는지 본다. 다른 작업 유형은 건너뛴다."""
+    if (data.get("header") or {}).get("taskType") != "final-verification":
+        return
+    _validate_added_surface_audit(data, failures)
+    _validate_verdict_consistency(data, failures)
+    _validate_verification_scope(data, failures)
+
+
+def _validate_added_surface_audit(data: dict, failures: list[str]) -> None:
+    """Every surface the diff added is traced to a requirement, exempted, or paid for.
+
+    The coverage table proves each requirement reached the diff. Nothing proved
+    the reverse — that each thing the diff added answers a requirement — so work
+    nobody asked for passed every gate. This check reads the reverse table and
+    refuses a row that calls itself over-delivery without the blocker or
+    condition it became: a caller-less surface is an acceptance blocker, and a
+    surface with callers but no requirement is a conditional-acceptance
+    condition (ADR-0009 grades the two differently on purpose).
+    """
+    fv = data.get("finalVerification")
+    if not isinstance(fv, Mapping):
+        return
+    rows = fv.get("addedSurfaceAudit")
+    if not isinstance(rows, list):
+        return
+    blocker_ids = _row_ids(fv.get("acceptanceBlockers"))
+    condition_ids = _row_ids(
+        (data.get("finalVerdict") or {}).get("conditionalAcceptanceConditions")
+    )
+    for row in rows:
+        if isinstance(row, Mapping):
+            failures.extend(_added_surface_row_failures(row, blocker_ids, condition_ids))
+
+
+def _row_ids(rows: object) -> set[str]:
+    if not isinstance(rows, list):
+        return set()
+    return {str(row.get("id")) for row in rows if isinstance(row, Mapping)}
+
+
+def _added_surface_row_failures(
+    row: Mapping,
+    blocker_ids: set[str],
+    condition_ids: set[str],
+) -> list[str]:
+    row_id = str(row.get("id") or "<id 없음>")
+    disposition = str(row.get("disposition") or "")
+    note = str(row.get("note") or "")
+    if disposition == "traced" and not str(row.get("requirement") or "").strip():
+        return [
+            f"final-verification: addedSurfaceAudit {row_id} is `traced` but "
+            "names no requirement — a surface is traced to something the "
+            "brief asked for, or it is not traced."
+        ]
+    if disposition != "over-delivery":
+        return []
+    caller_less = bool(_ADDED_SURFACE_NO_CALLER_RE.match(str(row.get("callers") or "")))
+    expected, known = ("AB", blocker_ids) if caller_less else ("CA", condition_ids)
+    cited = set(re.findall(rf"\b{expected}-\d{{3,}}\b", note))
+    if not cited:
+        detail = (
+            "a caller-less surface is an acceptance blocker"
+            if caller_less
+            else "a surface with callers but no requirement is a "
+                 "conditional-acceptance condition"
+        )
+        callers = "none" if caller_less else "recorded"
+        return [
+            f"final-verification: addedSurfaceAudit {row_id} is "
+            f"`over-delivery` with callers {callers}, so its note MUST cite "
+            f"the `{expected}-NNN` row it became — {detail}."
+        ]
+    missing = sorted(cited - known)
+    if missing:
+        return [
+            f"final-verification: addedSurfaceAudit {row_id} cites "
+            f"{missing}, which the report does not carry."
+        ]
+    return []
+
+
+def _validate_verdict_consistency(data: dict, failures: list[str]) -> None:
+    verdict = data.get("finalVerdict") or {}
+    token = (verdict.get("verdictToken") or "").strip().lower()
+    blockers = (data.get("finalVerification") or {}).get("acceptanceBlockers") or []
+    conditions = verdict.get("conditionalAcceptanceConditions") or []
+    if token == "accepted" and blockers:
+        failures.append(
+            "final-verification: verdict `accepted` but acceptanceBlockers is "
+            "non-empty — an accepted verdict must have zero blockers."
+        )
+    if token == "blocked" and not blockers:
+        failures.append(
+            "final-verification: verdict `blocked` but acceptanceBlockers is "
+            "empty — a blocked verdict must list at least one blocker."
+        )
+    if token == "conditional-accept" and not conditions:
+        failures.append(
+            "final-verification: verdict `conditional-accept` but "
+            "conditionalAcceptanceConditions is empty — list every condition."
+        )
+
+
+def _validate_verification_scope(data: dict, failures: list[str]) -> None:
+    scope = data.get("verificationScope", "whole-task")
+    if scope not in ("whole-task", "single-stage"):
+        failures.append(
+            f"final-verification: verificationScope must be `whole-task` or "
+            f"`single-stage`, got {scope!r}."
+        )
+
+
+def validate_verification_target_match(
+    data: dict,
+    run_manifest: dict,
+    project_root: Path,
+    failures: list[str],
+) -> None:
+    """The verification report must mirror the target it was prepared against.
+
+    `verificationScope`, the worktree, and the base/head refs were entirely
+    self-declared: the schema required the fields to exist but nothing compared
+    them to the digest-verified snapshot written at prep time. That matters
+    because both `handoff.compute_eligibility` and the `release-handoff`
+    routing check read `verificationScope` — a single-stage run that writes
+    `whole-task` passes both, and an `accepted` verdict can be rendered against
+    a worktree or head nobody verified.
+    """
+    # 스냅샷의 다이제스트 규칙과 파싱은 `okstra_ctl.verification_target` 한 곳이
+    # 쥔다. 조립도 같은 파일을 읽어 `verificationScope` 를 기록한다.
+    # 최상위 `verificationTargetPath` 가 run 매니페스트의 실물 키다(render.py).
+    # `instructionSet` 블록은 active-run-context 의 것이라 여기서 읽으면 검사가
+    # 통째로 건너뛰어졌다(실측 2026-09-06, dev-10626 final-verification 001).
+    relative = str(run_manifest.get("verificationTargetPath") or "").strip()
+    if not relative:
+        return
+    target = read_verification_target(project_root, relative)
+    if target is None:
+        return
+
+    source = (data.get("finalVerification") or {}).get("sourceImplementationReport") or {}
+    declared = {
+        "scope": str(data.get("verificationScope") or "").strip(),
+        "worktree": str(source.get("worktreePath") or "").strip(),
+        "base": str(source.get("implementationBaseRef") or "").strip(),
+        "head": str(source.get("capturedHeadSha") or "").strip(),
+    }
+    for key, expected in ((k, target[k]) for k in TARGET_FIELD_RES):
+        actual = declared[key]
+        if expected and actual and actual != expected:
+            failures.append(
+                f"final-verification report declares {key} `{actual}` but the "
+                f"prepared verification target says `{expected}` "
+                f"(`{relative}`). The report must mirror the target it was "
+                "prepared against — `verificationScope` in particular gates "
+                "both stage-group eligibility and release-handoff routing, so "
+                "a self-declared value lets a run be judged as something it "
+                "was not."
+            )
+
+    declared_stages = {
+        row.get("stage")
+        for row in ((data.get("finalVerification") or {}).get("stageReports") or [])
+        if isinstance(row, dict) and isinstance(row.get("stage"), int)
+    }
+    if target["stages"] and declared_stages and declared_stages != target["stages"]:
+        failures.append(
+            f"final-verification report covers stages {sorted(declared_stages)} "
+            f"but the prepared target names {sorted(target['stages'])} "
+            f"(`{relative}`). A verdict must not be rendered for a stage set "
+            "nobody prepared evidence for."
+        )

package/runtime/python/okstra_ctl/phases/final_verification/wizard.py

@@ -0,0 +1,38 @@
+"""final-verification 이 위저드의 stage 선택에 거는 조건."""
+from __future__ import annotations
+
+
+def whole_task_verification_allowed(
+    *,
+    stage_numbers: tuple[int, ...],
+    done_stages: set[int],
+) -> bool:
+    """승인된 계획의 stage 가 전부 done 일 때만 전체 작업 검증을 고를 수 있다."""
+    if not stage_numbers:
+        return False
+    return all(number in done_stages for number in stage_numbers)
+
+
+class StageAnswerError(ValueError):
+    """stage 선택 답이 final-verification 이 받을 수 있는 값이 아니다."""
+
+
+def validate_stage_answer(
+    answer: str, *, whole_task_token: str, whole_task_allowed: bool
+) -> str:
+    """전체 작업 토큰 또는 stage 번호 하나만 받는다. 여러 개나 auto 는 받지 않는다."""
+    if not answer:
+        raise StageAnswerError("value required")
+    if answer == whole_task_token:
+        if not whole_task_allowed:
+            raise StageAnswerError(
+                "whole-task verification requires final-verification "
+                "with all stages done")
+        return answer
+    try:
+        int(answer)
+    except ValueError:
+        raise StageAnswerError(
+            f"answer must be whole-task or a stage number, got {answer!r}"
+        ) from None
+    return answer

package/runtime/python/okstra_ctl/profile_show.py

@@ -19,6 +19,7 @@ import sys
 from pathlib import Path
 
 from .paths import find_asset_root
+from .phases.catalog import PhaseAssetError, UnknownTaskType, profile_markdown
 from .role_requirements import RoleProfileError, load_role_profile
 from .run import PrepareError, _expand_profile_includes
 
@@ -44,7 +45,12 @@ def workspace_root(start: Path | None = None) -> Path:
 
 
 def profile_path(root: Path, task_type: str) -> Path:
-    path = root.joinpath(*_PROFILES_REL, f"{task_type}.md")
+    try:
+        path = profile_markdown(root, task_type)
+    except UnknownTaskType as exc:
+        raise PrepareError(f"unknown task-type: {task_type}") from exc
+    except PhaseAssetError as exc:
+        raise PrepareError(str(exc)) from exc
     if not path.is_file():
         raise PrepareError(f"unknown task-type: {task_type} (no {path})")
     return path