okstra 0.205.0 → 0.206.0

package/runtime/python/okstra_ctl/implementation_direction.py

@@ -30,7 +30,10 @@ from .json_boundary import (
     load_owned_object_snapshot,
     write_owned_object_atomic,
 )
-from .report_views import normalize_direction_selection_identity
+from .report_views import (
+    direction_candidate_ineligibility,
+    normalize_direction_selection_identity,
+)
 from .qa_commands import find_denied_tokens
 from .scope_provenance import brief_end_state_id_sequence
 from .user_response import UserResponseError, parse_direction_selection
@@ -309,15 +312,13 @@ def _selected_option(
         raise DirectionSelectionError(str(exc)) from exc
     if report_option_id != option_id:
         raise DirectionSelectionError("selected candidate id does not match report")
-    coverage = option.get("coverageSummary")
-    if not isinstance(coverage, Mapping) or coverage.get("coverageVerdict") != "exact":
-        raise DirectionSelectionError("selected candidate must have exact coverage")
+    ineligibility = direction_candidate_ineligibility(option)
+    if ineligibility:
+        raise DirectionSelectionError(ineligibility)
     return option, report_option_name
 
 
-def _validate_no_blockers(data: Mapping[str, Any], option: Mapping[str, Any]) -> None:
-    if option.get("safetyBlockers") or option.get("unresolvedFeasibilityFacts"):
-        raise DirectionSelectionError("selected candidate has a safety blocker")
+def _validate_no_blockers(data: Mapping[str, Any]) -> None:
     blockers = progress_blocking_ids(
         data.get("clarificationItems"), USER_INPUT_BLOCKS
     )
@@ -389,7 +390,7 @@ def resolve_selected_direction(
     else:
         raise DirectionSelectionError(f"unsupported selection mode: {mode}")
     option, normalized_option_name = _selected_option(selection, option_id)
-    _validate_no_blockers(data, option)
+    _validate_no_blockers(data)
     return SelectedDirection(
         mode=mode,
         task_key=expected_task_key,

package/runtime/python/okstra_ctl/incremental_carry.py

@@ -387,7 +387,16 @@ def _carry_unchanged_checklists(
 def _recompute_dispatch_queue(
     narrative: Mapping[str, Any],
     state_items: dict[str, dict],
+    stage_ledger: Mapping[str, Any] | None = None,
 ) -> list[str]:
+    """이월 뒤 남은 디스패치 큐.
+
+    stage 상태는 디스크 원장이 답한다. 그것 없이 서사의 depends-on 만으로 다시
+    세면 이미 구현된 stage 가 `ready` 로 읽혀 큐에 들어가고, 정작 이번 run 이
+    추가한 stage 는 의존이 안 풀린 것으로 보여 빠진다 — 큐가 정확히 뒤집힌다
+    (2026-09-24, jobs implementation-planning 003: stage 1~8 done + stage 9
+    추가인 carry-all run 에서 큐 33 → 60, 내용은 done stage 의 항목뿐).
+    """
     try:
         extracted = extract_plan_items(_planning(dict(narrative)))
     except (CarryError, PlanItemContractError, KeyError, TypeError):
@@ -404,7 +413,13 @@ def _recompute_dispatch_queue(
     }
     if not previous_hashes:
         return []
-    ledger = planning_stage_ledger(_planning(dict(narrative)))
+    ledger = planning_stage_ledger(
+        _planning(dict(narrative)),
+        {
+            str(stage): str(status)
+            for stage, status in (stage_ledger or {}).items()
+        },
+    )
     return reverify_item_ids(extracted, previous_hashes, ledger)
 
 
@@ -479,7 +494,9 @@ def merge_v3_plan_state(
     pbv["planItems"] = [
         state_items[item_id] for item_id in sorted(state_items)
     ]
-    queue = _recompute_dispatch_queue(narrative, state_items)
+    queue = _recompute_dispatch_queue(
+        narrative, state_items, pbv.get("stageLedger"),
+    )
     if queue:
         pbv["dispatchQueue"] = queue
     return state

package/runtime/python/okstra_ctl/next_phase.py

@@ -283,8 +283,8 @@ def _direction_selection_reason(selection: Mapping[str, Any]) -> str:
     # (`implementation_direction.py` `_comparison_selection`). 종전 문장은
     # "위저드에 후보가 선택지로 나온다" 고 해서 사이드카 없이 계획을 열게 했다.
     return (
-        f"{head} 고르는 자리는 이 리포트의 HTML 열람본입니다 — 방향 선택 칸에서 "
-        "후보를 고르고 Export 한 파일을 "
+        f"{head} `/okstra-user-response` 에서 이 리포트를 골라 채팅으로 고르거나, "
+        "이 리포트의 HTML 열람본 방향 선택 칸에서 고르고 Export 한 파일을 "
         "`runs/implementation-option-selection/user-responses/"
         "user-response-implementation-option-selection-<이 리포트 번호>.md` 로 "
         "저장하세요. 그다음 `/okstra-run` 으로 `implementation-planning` 을 "

package/runtime/python/okstra_ctl/paths.py

@@ -88,7 +88,21 @@ def find_asset_root(
         root = Path(override)
         if is_present(root.joinpath(*relative)):
             return root
+    return walk_to_asset_root(relative, start=start, is_present=is_present)
 
+
+def walk_to_asset_root(
+    relative: Sequence[str],
+    *,
+    start: Optional[Path] = None,
+    is_present: Callable[[Path], bool] = Path.is_file,
+) -> Optional[Path]:
+    """The nearest ancestor of ``start`` that carries ``relative``, or None.
+
+    This is the layout walk of `find_asset_root` without the `OKSTRA_HOME`
+    override. A caller that must stay inside the tree it started from (a phase
+    profile resolving its includes) calls this directly.
+    """
     here = Path(start or __file__).resolve()
     for parent in [here, *here.parents]:
         if is_present(parent.joinpath(*relative)):

package/runtime/python/okstra_ctl/phases/__init__.py

@@ -0,0 +1,4 @@
+"""단계 패키지.
+
+등록표는 ``catalog`` 다. 이 패키지를 import 해도 단계 실행 모듈은 적재되지 않는다.
+"""

package/runtime/python/okstra_ctl/phases/catalog.py

@@ -0,0 +1,216 @@
+"""12개 작업 유형과 단계 디렉터리의 고정 대응.
+
+이 모듈을 import 해도 단계 실행 모듈은 적재되지 않는다. 경로는 문자열로만
+계산한다. 외부 설정에서 모듈 경로를 받아 실행하지 않는다.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..paths import walk_to_asset_root
+
+
+class PhaseAssetError(ValueError):
+    """단계 자산을 요청한 실행 루트에서 해석할 수 없다."""
+
+
+class UnknownTaskType(PhaseAssetError):
+    """등록표에 없는 작업 유형이다."""
+
+
+@dataclass(frozen=True)
+class PhaseRecord:
+    """외부 작업 유형 하나와 그 코드 위치."""
+
+    task_type: str
+    package_name: str
+    migrated: bool
+    view_module: str
+    view_function: str
+
+
+def _view(package_name: str, function: str, *, phase_package: bool) -> tuple[str, str]:
+    if phase_package:
+        return f"okstra_ctl.phases.{package_name}.report", function
+    return f"okstra_ctl.report_html.view_models.{package_name}", function
+
+
+def _record(
+    task_type: str,
+    package_name: str,
+    migrated: bool,
+    view_function: str,
+) -> PhaseRecord:
+    module, function = _view(package_name, view_function, phase_package=migrated)
+    return PhaseRecord(task_type, package_name, migrated, module, function)
+
+
+# 이전되지 않은 단계는 기존 ``prompts/profiles`` 위치를 명시적으로 쓴다.
+# 이전된 단계는 okstra_ctl 패키지를 품은 루트에서 단계 디렉터리만 본다. 그
+# 루트의 단계 파일이 없어도 prompts/profiles 사본으로 넘어가지 않는다. 패키지를
+# 품지 않은 루트는 그 루트의 prompts/profiles 사본이 자료다 (``profile_markdown``).
+PHASES: tuple[PhaseRecord, ...] = (
+    _record("requirements-discovery", "requirements_discovery", False, "build_requirements_discovery_view"),
+    _record("improvement-discovery", "improvement_discovery", False, "build_improvement_discovery_view"),
+    _record("project-analysis", "project_analysis", False, "build_project_analysis_view"),
+    _record("feature-analysis", "feature_analysis", False, "build_feature_analysis_view"),
+    _record("change-impact-analysis", "change_impact_analysis", False, "build_change_impact_analysis_view"),
+    _record("error-analysis", "error_analysis", False, "build_error_analysis_view"),
+    _record("technical-verification", "technical_verification", False, "build_technical_verification_view"),
+    _record(
+        "implementation-option-selection",
+        "implementation_option_selection",
+        False,
+        "build_implementation_option_selection_view",
+    ),
+    _record("implementation-planning", "implementation_planning", False, "build_implementation_planning_view"),
+    _record("implementation", "implementation", False, "build_implementation_view"),
+    _record("final-verification", "final_verification", True, "build_final_verification_view"),
+    _record("release-handoff", "release_handoff", False, "build_release_handoff_view"),
+)
+
+_BY_TASK_TYPE = {row.task_type: row for row in PHASES}
+
+# 같은 자산 루트 안에서만 고른다. 다른 설치본으로 넘어가는 순서가 아니다.
+_PACKAGE_RELATIVES = (
+    ("scripts", "okstra_ctl"),
+    ("python", "okstra_ctl"),
+    ("lib", "python", "okstra_ctl"),
+)
+
+
+def phase_record(task_type: str) -> PhaseRecord:
+    try:
+        return _BY_TASK_TYPE[task_type]
+    except KeyError as exc:
+        raise UnknownTaskType(f"unknown task type: {task_type}") from exc
+
+
+def task_types() -> tuple[str, ...]:
+    return tuple(row.task_type for row in PHASES)
+
+
+def is_migrated(task_type: str) -> bool:
+    """단계 패키지로 옮겨진 작업 유형인지. 등록표에 없는 이름은 False."""
+    record = _BY_TASK_TYPE.get(task_type)
+    return record is not None and record.migrated
+
+
+def logical_profile_markdown(task_type: str) -> str:
+    """실행 자료에 기록되는 프로필 계약 경로. 물리 파일 이름과 다를 수 있다."""
+    phase_record(task_type)
+    return f"prompts/profiles/{task_type}.md"
+
+
+def package_root(asset_root: Path) -> Path | None:
+    """``asset_root`` 안의 okstra_ctl 패키지. 없으면 None, 둘 이상이면 오류."""
+    found = [
+        asset_root.joinpath(*parts)
+        for parts in _PACKAGE_RELATIVES
+        if (asset_root.joinpath(*parts) / "__init__.py").is_file()
+    ]
+    if not found:
+        return None
+    if len(found) > 1:
+        joined = ", ".join(str(path) for path in found)
+        raise PhaseAssetError(f"ambiguous okstra_ctl package under {asset_root}: {joined}")
+    return found[0]
+
+
+def profile_markdown(asset_root: Path, task_type: str) -> Path:
+    """요청한 실행 루트에서 프로필 Markdown 의 물리 경로."""
+    record = phase_record(task_type)
+    legacy = asset_root / "prompts" / "profiles" / f"{task_type}.md"
+    if not record.migrated:
+        return legacy
+    root = package_root(asset_root)
+    # 요청한 루트가 런타임 패키지를 품지 않으면 그 루트에 있는 프로필이 그 실행의
+    # 자료다. 패키지를 품은 루트에서 단계 파일이 없을 때는 아래 경로를 그대로
+    # 돌려, 같은 루트의 prompts/profiles 사본으로 넘어가지 않는다.
+    if root is None:
+        return legacy
+    return root / "phases" / record.package_name / "profile.md"
+
+
+def profile_contract(asset_root: Path, task_type: str) -> Path:
+    return profile_markdown(asset_root, task_type).with_suffix(".json")
+
+
+def view_builder_import(task_type: str) -> tuple[str, str]:
+    """표시 함수의 모듈과 이름. import 는 호출자가 선택 시점에 한다."""
+    record = phase_record(task_type)
+    return record.view_module, record.view_function
+
+
+def migrated_report_template(asset_root: Path, logical_name: str) -> Path | None:
+    """이전된 보고서 본문의 물리 경로.
+
+    이 논리 이름이 단계 소유가 아니면 None 이다. ``asset_root`` 가 okstra_ctl
+    패키지를 품지 않을 때도 None 이며, 호출자는 그 루트의 ``templates/reports``
+    사본을 읽는다 (``profile_markdown`` 과 같은 규칙).
+    """
+    for record in PHASES:
+        if not record.migrated:
+            continue
+        filename = _report_template_filename(record.task_type, logical_name)
+        if filename is None:
+            continue
+        root = package_root(asset_root)
+        if root is None:
+            return None
+        return root / "phases" / record.package_name / "report_assets" / filename
+    return None
+
+
+def resolve_include(profile_path: Path, target_name: str) -> Path:
+    """포함 대상을 찾는다.
+
+    이전되지 않은 프로필은 자기 부모 디렉터리 기준을 유지한다. 이전된
+    ``profile.md`` 는 그 파일을 품은 자산 루트의 논리 경로로 찾고, 다른
+    설치본의 ``OKSTRA_HOME`` 으로 넘어가지 않는다. 공유 조각과 같은 이름의
+    단계 전용 파일이 함께 있으면 어느 쪽인지 정할 수 없으므로 오류다.
+    """
+    name = target_name.strip()
+    if not name or name.startswith("/") or ".." in Path(name).parts:
+        raise PhaseAssetError(f"invalid profile include target: {target_name!r}")
+    if not _is_migrated_profile(profile_path):
+        return profile_path.parent / name
+    asset_root = _asset_root_containing(profile_path)
+    if name.startswith("prompts/"):
+        return asset_root / name
+    shared = asset_root / "prompts" / "profiles" / Path(name).name
+    local = profile_path.parent / name
+    if shared.is_file() and local.is_file():
+        raise PhaseAssetError(
+            f"profile include {name!r} exists both as a shared fragment ({shared}) "
+            f"and beside the phase profile ({local})"
+        )
+    if local.is_file():
+        return local
+    return shared
+
+
+def _is_migrated_profile(profile_path: Path) -> bool:
+    if profile_path.name != "profile.md" or profile_path.parent.parent.name != "phases":
+        return False
+    package_name = profile_path.parent.name
+    return any(row.migrated and row.package_name == package_name for row in PHASES)
+
+
+def _asset_root_containing(start: Path) -> Path:
+    root = walk_to_asset_root(("prompts", "profiles"), start=start, is_present=Path.is_dir)
+    if root is None:
+        raise PhaseAssetError(
+            f"could not locate prompts/profiles while resolving an include from {start}"
+        )
+    return root
+
+
+def _report_template_filename(task_type: str, logical_name: str) -> str | None:
+    if logical_name == f"html/tasks/{task_type}.template.html":
+        return f"{task_type}.template.html"
+    if logical_name == f"md/tasks/{task_type}.template.md":
+        return f"{task_type}.template.md"
+    return None
+

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

@@ -0,0 +1,4 @@
+"""final-verification 단계 패키지.
+
+공통 실행 조립부와 다른 단계 패키지를 여기서 가져오지 않는다.
+"""

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,7 +34,7 @@
   - **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.
   - **External QA outcome policy:** continue to attempt every in-scope Tier 3
@@ -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"]