okstra 0.205.1 → 0.206.1

package/runtime/python/okstra_ctl/stage_map.py

@@ -641,3 +641,16 @@ def _resolve_plan_path(task_root: Path, value: str) -> Path:
 # 예전에는 okstra_project.state 가 이 어댑터를 들고 okstra_ctl 을 함수 본문에서
 # 지연 import 했다. 하위 계층이 상위를 되짚는 배치였다. 읽는 대상이 okstra_ctl 의
 # Stage Map 과 consumer 상태이므로 소유자를 여기로 옮긴다.
+
+
+def parse_stage_map_for_prepare(plan_path: str) -> list:
+    """Parse the approved plan into context records for execution consumers."""
+    from .prepare_error import PrepareError
+
+    try:
+        return stage_map_records(parse_stage_map_file(Path(plan_path)))
+    except StageMapError as exc:
+        raise PrepareError(
+            "approved-plan 의 Stage Map 을 신뢰할 수 없어 거부합니다 "
+            f"({plan_path}): {exc.reason}. plan 의 Stage Map 을 점검하세요."
+        ) from exc

package/runtime/python/okstra_ctl/stage_targets.py

@@ -1,7 +1,11 @@
 """Stage readiness and verification target rules.
 
-This module owns the policy that decides which Stage Map stage can run, which
-commit it branches from, and what final-verification should inspect. It keeps
+This module owns the policy that decides which Stage Map stage can run and which
+commit it branches from, plus the Git and ledger facts final-verification builds
+its target from (whole-task integration, the stage that contains every other
+done stage, teardown after the verdict). Which of those facts a
+final-verification run uses is decided in
+``phases/final_verification/target.py``. It keeps
 the stage lifecycle rules behind one interface instead of leaking raw
 ``consumers.jsonl`` rows and git ancestry checks into prepare callers.
 """
@@ -10,13 +14,11 @@ from __future__ import annotations
 import heapq
 import subprocess
 import sys
-from dataclasses import dataclass, replace
+from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
-from .plan_run_root import plan_run_root_from_approved_plan
 from .prepare_error import PrepareError  # noqa: F401 — 재노출(단일 참조점)
-from .stage_integrate import IntegrateResult
 from okstra_project.slug import slugify
 
 
@@ -37,32 +39,6 @@ class FinalVerificationTarget:
     reports: list[str]
 
 
-@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], ...] = ()
-
-
 @dataclass(frozen=True)
 class StageLifecycle:
     stage: int
@@ -809,117 +785,6 @@ def resolve_and_integrate_whole_task(
         )
 
 
-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."""
-    from .consumers import latest_done_by_stage
-
-    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]]:
-    from .consumers import backfill_done_from_carry, read_stage_consumer_state
-    from .stage_reconcile import auto_reconcile_best_effort
-
-    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:
-    from . import worktree_registry
-    from .worktree import _git, is_dirty_excluding_okstra
-
-    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 single_containing_head(project_root: Path,
                            heads: dict[int, str]) -> int | None:
     """주어진 stage 들의 commit 을 혼자서 모두 담고 있는 stage. 없으면 None.
@@ -952,117 +817,12 @@ def containing_stage(project_root: Path,
     return single_containing_head(project_root, heads)
 
 
-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 브랜치 통합 경로로 넘긴다."""
-    from . import worktree_registry
-    from .consumers import latest_done_by_stage
-    from .worktree import _git, is_dirty_excluding_okstra
-
-    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:
-    from . import worktree_registry
-
-    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 integrate_and_teardown_whole_task(
     *, project_root: Path, task_group: str, task_id: str,
 ) -> dict[str, Any]:
     """판정이 끝난 whole-task 검증의 stage worktree 와 registry 키를 회수한다.
 
-    진입은 통합만 하고 정리를 남겨 두므로(`_resolve_whole_task_acquisition`), 정리는
+    진입은 통합만 하고 정리를 남겨 두므로(`phases/final_verification/target.py`), 정리는
     판정 뒤인 Phase 7 에서 여기로 들어온다. 통합은 이미 끝나 있어 Phase A 는 전부
     `already_merged` 로 지나가고 Phase B 만 실제 일을 한다. 두 번 불려도 결과는 같다 —
     사라진 worktree 는 건너뛰고, 미커밋 변경이 남은 stage 트리는 보존한다.
@@ -1117,7 +877,7 @@ def integrate_and_teardown_whole_task(
             done_rows=done_rows,
             teardown=True,
             # 한 stage 브랜치가 이미 전체를 담고 있으면 검증은 거기서 돌았다
-            # (`_acquire_tip_stage_target`). 그 경우 task 브랜치로의 머지는 아무도
+            # (`phases/final_verification/target.py`). 그 경우 task 브랜치로의 머지는 아무도
             # 읽지 않는 산출물이므로 정리만 한다.
             merge=tip is None,
             verified_head=(done_by_stage.get(tip) or {}).get("head_commit", ""),
@@ -1130,40 +890,3 @@ def integrate_and_teardown_whole_task(
         ],
         "warnings": result.warnings,
     }
-
-
-def acquire_final_verification_target(
-    request: FinalVerificationTargetRequest,
-) -> FinalVerificationTargetAcquisition:
-    """Acquire a stable final-verification target behind one task-key lock."""
-    from okstra_project.dirs import okstra_home
-
-    from .locks import worktree_provision_mutex
-
-    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/technical_verification_facts.py

@@ -0,0 +1,52 @@
+"""방향 비교와 기술 검증이 함께 읽는 미확정 사실 계약."""
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, TypedDict
+
+from .clarification_items import USER_INPUT_BLOCKS, progress_blocking_ids
+
+
+class VerificationFact(TypedDict):
+    id: str
+    candidateId: str
+    factIndex: int
+    fact: str
+    whyItMatters: str
+    evidence: list[str]
+
+
+class TechnicalVerificationError(ValueError):
+    """시험 입력 또는 관측 결과가 원본 사실과 일치하지 않는다."""
+
+
+def technical_verification_facts(data: Mapping[str, Any]) -> list[VerificationFact]:
+    """안전 차단이 없는 후보의 명시적인 기술 검증 사실만 추출한다."""
+    blockers = progress_blocking_ids(
+        data.get("clarificationItems"), USER_INPUT_BLOCKS, report_data=data
+    )
+    if blockers:
+        raise TechnicalVerificationError(
+            "unresolved user decisions: " + ", ".join(blockers)
+        )
+    selection = data.get("implementationOptionSelection") or {}
+    facts: list[VerificationFact] = []
+    for candidate in selection.get("candidateAudit") or []:
+        if candidate.get("safetyBlockers"):
+            continue
+        for index, fact in enumerate(candidate.get("unresolvedFeasibilityFacts") or []):
+            if fact.get("resolutionKind") != "technical-verification":
+                continue
+            facts.append(
+                {
+                    "id": f"TV-{len(facts) + 1:03d}",
+                    "candidateId": candidate["id"],
+                    "factIndex": index,
+                    "fact": fact["fact"],
+                    "whyItMatters": fact["whyItMatters"],
+                    "evidence": fact["evidence"],
+                }
+            )
+    if not facts:
+        raise TechnicalVerificationError("no eligible technical-verification facts")
+    return facts