okstra 0.205.1 → 0.206.1

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

@@ -0,0 +1,166 @@
+"""final-verification 준비 중 이 단계가 소유하는 대상 고정.
+
+공통 조립부는 CLI 값과 diff 요약을 넘긴다. 대상 요청, 렌더 문맥 기록,
+스냅샷 다이제스트는 여기서 계산한다. 이 모듈은 공통 실행 조립부를 import
+하지 않는다.
+"""
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+from okstra_ctl.phases.final_verification.target import (
+    FinalVerificationTargetAcquisition,
+    FinalVerificationTargetRequest,
+)
+from okstra_ctl.prepare_error import PrepareError
+from okstra_ctl.stage_targets import FinalVerificationTarget
+from okstra_ctl.worktree import WorktreeProvision
+
+
+def reject_prepare_flags(*, approve_plan_ack: bool, implementation_option: str) -> None:
+    """승인과 구현 방향 적용은 implementation 준비의 일이다."""
+    if approve_plan_ack:
+        raise PrepareError(
+            "--approve is only meaningful with --task-type implementation "
+            "and --approved-plan <path>"
+        )
+    if implementation_option:
+        raise PrepareError(
+            "--implementation-option is only meaningful with --task-type "
+            "implementation and --approved-plan <path>"
+        )
+
+
+def single_stage_worktree() -> WorktreeProvision:
+    """선택한 stage 원장 행이 정해지기 전까지 두는 자리."""
+    return WorktreeProvision(
+        status="deferred-final-verification",
+        note=(
+            "final-verification single-stage uses the selected implementation "
+            "stage worktree from the registry"
+        ),
+    )
+
+
+def verification_target_request(
+    *,
+    project_root: str,
+    project_id: str,
+    task_group: str,
+    task_id: str,
+    work_category: str,
+    approved_plan_path: str,
+    stage: str,
+    stage_map: list[dict],
+) -> FinalVerificationTargetRequest:
+    """``stage`` 가 ``auto`` 이면 대상 선택을 비운다. 호출부가 기본값을 고르지 않는다."""
+    selected = int(stage) if stage and stage != "auto" else None
+    return FinalVerificationTargetRequest(
+        project_root=Path(project_root),
+        project_id=project_id,
+        task_group=task_group,
+        task_id=task_id,
+        work_category=work_category,
+        approved_plan_path=Path(approved_plan_path),
+        stage=selected,
+        stage_map=tuple(stage_map),
+    )
+
+
+def apply_verification_target(
+    ctx: dict,
+    acquisition: FinalVerificationTargetAcquisition,
+    diff_stat: str,
+) -> None:
+    """획득한 검증 대상을 렌더 문맥에 적는다. diff 요약은 호출부가 계산한다."""
+    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()
+    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 write_verification_target_snapshot(
+    instruction_set: Path,
+    target_markdown: str,
+) -> tuple[Path, str]:
+    """정규화한 검증 대상 스냅샷을 쓰고 그 다이제스트를 돌려준다."""
+    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 _format_verification_target(
+    target: 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 _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 warning in integ.warnings:
+        lines.append("- **경고:** " + warning)
+    return "\n".join(lines)

package/runtime/{prompts/profiles/final-verification.md → python/okstra_ctl/phases/final_verification/profile.md}

@@ -13,7 +13,7 @@
 - Primary focus areas (each maps to a deliverable section below):
   - Acceptance-gating — a failure here pushes the verdict toward `blocked` / `conditional-accept`:
     - requirement & acceptance coverage — every must-pass point in the brief's `## Expected Behavior` / `## Preserved Behavior` / `## Expected Outcome` (and the approved plan's requirements) is covered with a cited artifact or raised as an Acceptance Blocker; no silent omissions
-    - over-delivery — every surface the merged diff **adds** is traced back to a requirement. Enumerate them: each identifier, module, and configuration entry the diff introduces, searched for its callers across the whole repository (a declaration, its own test, or a commented-out line is not a caller). Record one `addedSurfaceAudit` row per surface with its disposition. `traced` names the brief requirement it serves. `exempt` names one of the legitimate exits and cites it — the approved plan reserves it for a named later stage, or something outside project code calls it (framework entrypoint, implemented interface method, migration hook, published-package API). `over-delivery` is everything else, and it is graded by callers: **no caller anywhere** is an Acceptance Blocker (delete it, or fold an added parameter back into its single call site), while **called but serving no requirement** is a Conditional Acceptance Condition with `blocksReleaseHandoff: false` — the judgement there rests on reading intent, so it travels to the PR body instead of stopping the release. The baseline is the brief, not the approved plan: a surface the plan authorised but no requirement asked for is still over-delivery, and this is the last gate that can see it. **Enforced:** `validators/validate-run.py` `_validate_added_surface_audit` refuses a `traced` row naming no requirement, and an `over-delivery` row whose note does not cite the `AB-NNN` / `CA-NNN` row it became.
+    - over-delivery — every surface the merged diff **adds** is traced back to a requirement. Enumerate them: each identifier, module, and configuration entry the diff introduces, searched for its callers across the whole repository (a declaration, its own test, or a commented-out line is not a caller). Record one `addedSurfaceAudit` row per surface with its disposition. `traced` names the brief requirement it serves. `exempt` names one of the legitimate exits and cites it — the approved plan reserves it for a named later stage, or something outside project code calls it (framework entrypoint, implemented interface method, migration hook, published-package API). `over-delivery` is everything else, and it is graded by callers: **no caller anywhere** is an Acceptance Blocker (delete it, or fold an added parameter back into its single call site), while **called but serving no requirement** is a Conditional Acceptance Condition with `blocksReleaseHandoff: false` — the judgement there rests on reading intent, so it travels to the PR body instead of stopping the release. The baseline is the brief, not the approved plan: a surface the plan authorised but no requirement asked for is still over-delivery, and this is the last gate that can see it. **Enforced:** `scripts/okstra_ctl/phases/final_verification/validation.py` `_validate_added_surface_audit` refuses a `traced` row naming no requirement, and an `over-delivery` row whose note does not cite the `AB-NNN` / `CA-NNN` row it became.
     - delivered artifacts match recorded expected values in `reference-expectations` (config files, deployment manifests, other recorded expected states); when reference-expectations are absent, record it as missing information rather than assuming a match
     - test & validation suite pass status — independently re-run the read-only two-tier command set (Tier 1 = brief/approved-plan `validation`, Tier 2 = `project.json` `qaCommands`) and confirm each passes on the verified head, citing exact command + exit code
     - test correctness — delivered tests actually assert the intended behaviour: no gutted/weakened assertions, no tautological or always-passing tests, no tests exercising only mocks; new behaviour has matching coverage. For an `external-interface` / `transformation-mapping` surface specifically, treat a test whose only oracle is a self-authored synthetic fixture (no captured-real-sample provenance) as NOT establishing external correctness — it shows only that the parser agrees with its author's assumed shape, never that the shape matches reality; record that surface's external correctness as a user-owned external advisory gap (a Residual Risk carrying the exact "capture a real sample and confirm" next step, per the Coverage check in the self-review pass below), never as covered — the same non-blocking treatment the External QA advisory policy gives a live external check
@@ -34,9 +34,9 @@
   - **single-stage scope** (`--stage N`): prep verified stage N is `status:done` and its isolated stage worktree exists and is clean. Other stages' state is irrelevant. A single-stage run is a partial verification of one stage, and that is exactly the unit release-handoff ships: an `accepted` verdict here makes the stage PR-eligible, so `release-handoff` is the routing target. It says nothing about any other stage.
   - the lead still captures `git status --short` from the injected worktree to confirm the analysis ran against the delivered work-tree state; an unexpected divergence (dirty tree outside `.okstra/`, missing worktree) is a `tool-failure`, not a silent proceed.
 - Worker verification procedure:
-  - **Target confirmation:** analyse the injected target and nothing else. Read `verification-target.md` for the stage/report mapping and the complete diff stat. Prepare fixed that target and `validators/validate-run.py` `_validate_verification_target_match` re-checks the report against its digest, so the procedure to follow here is simply: if the worktree you can see does not match the injected target, record a `tool-failure` — never reselect a target.
+  - **Target confirmation:** analyse the injected target and nothing else. Read `verification-target.md` for the stage/report mapping and the complete diff stat. Prepare fixed that target and `phases/final_verification/validation.py` `validate_verification_target_match` (called by `validators/validate-run.py`) re-checks the report against its digest, so the procedure to follow here is simply: if the worktree you can see does not match the injected target, record a `tool-failure` — never reselect a target.
   - **Evidence:** attach file:line, exact command + exit code, log excerpt, or MCP SELECT evidence to every finding. Mark a requirement as covered only when the cited artifact demonstrates it.
-  - **Tier 1 and Tier 2 read-only validation:** Tier 1 is the originating brief/approved plan `validation` set. Tier 2 is the `Project QA Commands` section from `okstra model-io project-context --project-root <PROJECT_ROOT> --task-ref <task-ref>`. Do not auto-detect commands from package manifests. A missing tier is `qa-command not configured: <category>`. Before execution, reject commands containing source/lockfile mutation tokens such as `--fix`, `--write`, ` -w`, ` -u`, `--snapshot-update`, `INSTA_UPDATE=<not-no>`, `cargo update`, or `npm install` without `ci`; record the exact denied token. Tier 2 is already screened by prepare, so this check catches a Tier 1 command the brief or plan named.
+  - **Tier 1 and Tier 2 read-only validation:** Tier 1 is the originating brief/approved plan `validation` set. Tier 2 is the `Project QA Commands` section from `okstra model-io project-context --project-root <PROJECT_ROOT> --task-ref <TASK_KEY>` (the full `Task key` your dispatch prompt names). Do not auto-detect commands from package manifests. A missing tier is `qa-command not configured: <category>`. Before execution, reject commands containing source/lockfile mutation tokens such as `--fix`, `--write`, ` -w`, ` -u`, `--snapshot-update`, `INSTA_UPDATE=<not-no>`, `cargo update`, or `npm install` without `ci`; record the exact denied token. Tier 2 is already screened by prepare, so this check catches a Tier 1 command the brief or plan named.
   - **External QA outcome policy:** continue to attempt every in-scope Tier 3
     command. For an entry requiring `db`, `http`, or `external`, record non-PASS
     as a Tier 3 `advisory` command, add a user-owned Residual Risk and exact
@@ -57,7 +57,7 @@
   - **Could-not-verify honesty:** use `not-configured`, `env-unavailable`, `rejected`, `gap`, or `blocked` as appropriate. Never convert unavailable evidence into an executed/pass claim.
   - **Source-mutation prohibition:** verification may write only assigned okstra run artifacts. Do not edit source, schema, deployment, lockfile, or configuration files; route detected defects to a later phase.
 - Required deliverable shape (final report, in addition to the standard sections):
-  - **Source Implementation Report(s)** (**Enforced:** `validators/validate-run.py` `_validate_verification_target_match` compares `verificationScope`, `worktreePath`, `implementationBaseRef`, `capturedHeadSha`, and the `stageReports` stage set against the digest-verified `instruction-set/verification-target.md`; a snapshot whose digest no longer checks out is ignored rather than trusted. `verificationScope` in particular gates both stage-group eligibility and release-handoff routing, so it is not the report's to restate): the `VERIFICATION_TARGET` snapshot verbatim — verification scope, worktree path, base/head refs, the list of stages under verification, and one row per stage citing its originating implementation final-report (`report_path` from `consumers.jsonl`; render `(report_path unrecorded)` when absent). Every analyser prompt carries the same compact target identity (`**Verification scope:** / **Worktree:** / **Verification base ref:** / **Verification head ref:** / **Verification target path:** / **Verification target digest:**`) and reads the sidecar on demand for the complete diff stat. A worker that cannot confirm its analysis ran against that worktree's delivered diff MUST record a `tool-failure`.
+  - **Source Implementation Report(s)** (**Enforced:** `phases/final_verification/validation.py` `validate_verification_target_match` (called by `validators/validate-run.py`) compares `verificationScope`, `worktreePath`, `implementationBaseRef`, `capturedHeadSha`, and the `stageReports` stage set against the digest-verified `instruction-set/verification-target.md`; a snapshot whose digest no longer checks out is ignored rather than trusted. `verificationScope` in particular gates both stage-group eligibility and release-handoff routing, so it is not the report's to restate): the `VERIFICATION_TARGET` snapshot verbatim — verification scope, worktree path, base/head refs, the list of stages under verification, and one row per stage citing its originating implementation final-report (`report_path` from `consumers.jsonl`; render `(report_path unrecorded)` when absent). Every analyser prompt carries the same compact target identity (`**Verification scope:** / **Worktree:** / **Verification base ref:** / **Verification head ref:** / **Verification target path:** / **Verification target digest:**`) and reads the sidecar on demand for the complete diff stat. A worker that cannot confirm its analysis ran against that worktree's delivered diff MUST record a `tool-failure`.
   - **Verdict vocabulary**: Section 7 (`Final Verdict`) MUST include a `Verdict Token` field whose value is exactly one of `accepted`, `conditional-accept`, or `blocked`. `conditional-accept` requires an explicit, exhaustive list of conditions; ambiguous verdicts ("looks good", "mostly ready") are not allowed. Each condition MUST be recorded as a row in the **Conditional Acceptance Conditions** deliverable (`id` `CA-NNN`, `condition`, `evidenceRequired`, `blocksReleaseHandoff`). `blocksReleaseHandoff` is a gate, not a note: `false` means this condition alone would not stop the release, and a `conditional-accept` whose conditions are all `false` may route to `release-handoff` (the conditions travel into the PR body as unresolved items). Declare `true` for anything that must be settled before release. The validator enforces verdict↔deliverable consistency: `accepted` ⇒ zero acceptance blockers, `blocked` ⇒ at least one, `conditional-accept` ⇒ at least one condition, and a `release-handoff` routing recommendation is allowed only when the verdict is release-ready by `okstra_ctl.release_gate.release_handoff_allowed`. **Any Acceptance Blocker therefore forces the verdict off `accepted` (to `conditional-accept` or `blocked`); the gates below cite this rule instead of restating the arithmetic.**
   - **Added-surface audit** (`finalVerification.addedSurfaceAudit`): the reverse of requirement coverage — one row per surface the merged diff added (`id` `AS-NNN`, `surface` as `path:line` + the added name, `callers`, `requirement`, `disposition`, `note`). Requirement coverage proves every requirement reached the diff; this table proves every addition answers a requirement. An empty array is a claim that the diff added no identifier, module, or configuration entry, not permission to skip the enumeration. Single-stage scope audits its own stage's diff; whole-task audits the merged diff, which is the only place a surface added by one stage and orphaned by another is visible.
   - **Acceptance Blockers block** (under section 4): one row per blocker with `id`, `severity` (`critical` / `major`), evidence (file path, log excerpt, or test output), and the recommended follow-up phase: `error-analysis` for a cause problem, `implementation-option-selection` for a direction problem, or `implementation-planning` for a detailed-plan problem. Empty block is acceptable and preferred — render the single line `- No acceptance blockers found.`
@@ -65,7 +65,7 @@
   - **Validation Evidence**: for every requirement in the originating plan or task brief, cite the artifact (commit SHA, test output, log line, MCP SELECT result) that demonstrates coverage. Paraphrased "verified" claims without an artifact are rejected.
   - **Read-only command log**: any pre-existing test/validation command touched during this run MUST be listed with its exact command line and one honest status — `executed` (ran; carries its exit code) / `advisory` (external Tier 3 did not PASS; carries observed/expected results and remains user-owned) / `env-unavailable` (should run but cannot in this environment — missing replica DB, container, or service; carries the reason, never a faked pass) / `not-configured` (no such qa-command tier) / `rejected` (a mutating/denied token — skipped, carries the denied token). A check that could not run locally is recorded as `env-unavailable` or `advisory` according to the external QA policy — never silently dropped and never reported as `executed` with an invented exit code. Mutating-command prohibition is the shared read-only boundary (see Non-goals); it is not restated per row.
   - **Could-not-verify roll-up (§5.8.9)**: the template mechanically aggregates every not-confirmed check into one scannable list — `gap` requirement-coverage rows, `advisory` / `not-configured` / `env-unavailable` / `rejected` command rows, and `blocked` manual tests. You do not hand-author it, but you MUST give those rows their honest status so nothing unverified hides across sections: a check silently recorded as `executed`/`covered` will not surface in the roll-up. This is okstra's answer to "say what could not be verified this run."
-  - **Routing recommendation**: `finalVerification.routingRecommendation` is an **object** with exactly two fields — `target`, one value of the enum below, and `rationale`, the sentence tying that choice to the verdict and the blocker list. Free routing prose is not the field; a target named only in the prose does not route the task, because Phase 7 projects `workflow.nextRecommendedPhase` from `target` alone. The eight allowed targets are `release-handoff`, `release-handoff(stage-group)`, `final-verification`, `error-analysis`, `implementation-option-selection`, `implementation-planning`, `implementation`, and `done`. `final-verification` re-runs this phase on the same head and is for exactly one situation: every remaining blocker is an environment or configuration fault whose cause this report already names — a `qaCommands` entry pointing at a path that no longer exists, a missing credential, a stale fixture — so nothing in the code, the plan, or the selected direction is being re-decided. Name the repair in the `rationale`. When any blocker needs a code, plan, or direction change, route to the phase that owns that change instead; routing a defect you have not diagnosed back into this phase re-runs the verification that already failed. Both `release-handoff` forms are allowed ONLY when the verdict is release-ready — `accepted`, or `conditional-accept` with every condition declaring `blocksReleaseHandoff: false`. Either verification scope may route there: release-handoff opens one PR per stage, so a release-ready `single-stage` run is the evidence for that stage's PR, and `release-handoff(stage-group)` is only a scope qualifier that projects onto the same phase. `done` ends the lifecycle here. Enforcement: `schemas/final-report-v2.0.schema.json` rejects a `target` outside the enum, a missing `rationale`, and a string in place of the object; `validators/validate-run.py` rejects a missing `target` and a verdict that is not release-ready routed to either `release-handoff` form (naming the condition ids that block it).
+  - **Routing recommendation**: this phase records the verdict, the blockers, the conditions, and the repair each blocker needs. The lead chooses the next phase from the `## final-verification` section of `prompts/lead/phase-routing.md`, which lists the allowed targets and the shape of `finalVerification.routingRecommendation`. Read that section before writing the field.
   - **Verified-row recording** (both scopes): when the verdict is release-ready, the lead MUST run `okstra handoff record-verified --plan-run-root <plan-run-root> --stage <N> --report-path <final-report data.json path> --data-json <final-report data.json path>` and quote the command + exit code in the report. Pass the record path to both: the Markdown reading copy is rendered on request and does not exist in a finished run (ADR-0014), and the helper normalizes either path to the record anyway. A `whole-task` report clears every stage in its own `stageReports`, so run it **once per those stages** — each run writes that stage's row from this one report. Without those rows the stage is never offered a pull request, and release-handoff opens one PR per stage. The helper checks the latest verification manifest, task/stage identity, report pointer, prepared target, and recorded implementation commit. It records the captured commit and original verdict, including conditional acceptance conditions. A missing target or mismatched commit requires re-verification. Recording happens before final validation; eligibility is granted only after that verification passes validation. **Enforced:** `okstra_ctl.handoff_verification` validates the evidence, and `validators/validate-run.py` `_validate_verified_row_recorded` requires a `verified` row matching this report, captured commit, and verdict.
 - Clarification request policy (phase-specific addendum — shared policy is in `_common-contract.md`):
   - populate `## 1. Clarification Items` only when a blocker hinges on information only the user can supply (deployment intent, intended target environment, business-rule interpretation); use `Blocks=next-phase` for items that gate continuing to release-handoff

package/runtime/python/okstra_ctl/{report_html/view_models/final_verification.py → phases/final_verification/report.py}

@@ -1,9 +1,12 @@
 """Human-first final-verification view model."""
 from __future__ import annotations
 
-from ...release_gate import release_handoff_allowed
-from ..common import evidence_index
-from ..models import HumanReportView
+from pathlib import Path
+
+from okstra_ctl.release_gate import release_handoff_allowed
+from okstra_ctl.report_html.common import evidence_index
+from okstra_ctl.report_html.models import HumanReportView
+from okstra_ctl.verification_target import read_verification_target
 
 # Record fields this template anchors as `id-<row id>` (see
 # `HumanReportView.anchored_fields`); ids elsewhere land in the ledger.
@@ -16,6 +19,12 @@ ANCHORED_FIELDS = (
 )
 
 
+def verification_scope(project_root: Path, relative: str) -> str:
+    """준비된 검증 대상에서 범위를 읽는다. 파서는 공통 계약이 소유한다."""
+    target = read_verification_target(project_root, relative)
+    return str((target or {}).get("scope") or "").strip()
+
+
 def build_final_verification_view(data: dict) -> HumanReportView:
     final = data["finalVerification"]
     verdict_token = data["finalVerdict"]["verdictToken"]

package/runtime/{templates/reports → python/okstra_ctl/phases/final_verification/report_assets}/final-verification-input.template.md

@@ -85,7 +85,7 @@ taskType: "{{FM_TASK_TYPE}}"
 
 > Verifiers MUST NOT extend acceptance checks, regression scans, or sign-off recommendations into items listed here. If a verifier believes an excluded item must pass before release, it is reported as a recommended follow-up verification task in the final report — never silently included in the pass/fail decision of this run. If this section is left empty, verifiers treat any check beyond what `Acceptance Criteria` enumerates as out of scope by default.
 
-**Enforced (delivery only):** `tests/contract/test_scope_boundary_delivery.py` pins that a filled section reaches every analysis worker through `okstra_ctl.analysis_packet` — drop it from `CANONICAL_BRIEF_SECTIONS` and every run's exclusions vanish silently. The exclusions themselves are prose and are **not** machine-checked: only the codebase-scan `out-of-scope` frontmatter is a path list, and `validators/validate_improvement_report.py` checks that one.
+**Enforced (delivery only):** `tests/contract/test_scope_boundary_delivery.py` pins that a filled section reaches every analysis worker through `okstra_ctl.analysis_packet` — drop it from `CANONICAL_BRIEF_SECTIONS` and every run's exclusions vanish silently. The exclusions themselves are prose and are **not** machine-checked: only the codebase-scan `out-of-scope` frontmatter is a path list, and `scripts/okstra_ctl/phases/improvement_discovery/validation.py` checks that one.
 
 ## Config and Deployment Verification Targets
 

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`)
+- `scripts/okstra_ctl/phases/final_verification/report_assets/final-verification-input.template.md`
+- `validators/validate-run.py`
+- `scripts/okstra_ctl/release_gate.py`