okstra 0.186.7 → 0.188.0

package/runtime/python/okstra_ctl/convergence_store.py

@@ -1,6 +1,7 @@
 """Validated JSON loading and atomic persistence for convergence artifacts."""
 from __future__ import annotations
 
+import hashlib
 from pathlib import Path
 from typing import Any, Mapping
 
@@ -13,8 +14,6 @@ from .execution_manifest import (
 )
 from .final_report_schema import load_named_schema
 from .json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
-from .worker_request import verifier_extra_dirs
-from .write_policy import build_invocation_write_contract
 
 
 DYNAMIC_VERIFIER_SOURCE_ROLES = frozenset({
@@ -107,19 +106,13 @@ def reserve_dynamic_verifier(
     *,
     input_digest: str,
     invocation_ref: str | None = None,
-    artifact_paths: tuple[Path, ...],
-    worktree: Path | None = None,
 ) -> tuple[RoleExecution, Invocation]:
     """Reserve one provider-neutral verifier identity for a logical round.
 
-    `worktree` 는 이 런의 워커가 실제로 서는 루트다. 디스패치가 정책을 다시
-    계산할 때 쓰는 값(`dispatch_core._canonical_write_contract` 이 job 의
-    worktree 를 넘긴다)과 같아야 한다. 여기서 None 으로 고정하면 예약된 정책의
-    `sourcePolicy.allowedRoot` 는 프로젝트 루트, 디스패치가 계산한 정책은 스테이지
-    워크트리가 되어 writePolicyDigest 가 갈리고, 같은 invocationRef 가
-    `invocationRef drift` 로 거부된다 — 워크트리를 쓰는 런(implementation stage)
-    에서만 나타나고 워크트리가 없는 런(implementation-planning)에서는 안 나타나
-    버전 문제로 보이기 쉽다.
+    예약은 정체성만 잡는다. 쓰기 계약은 디스패치가 attempt 를 열 때 한 번만
+    계산해 그 attempt 행에 적는다 — 예약이 같은 값을 두 번째로 계산하던 동안,
+    두 계산의 입력(worktree)이 갈리면 같은 invocationRef 가 `invocationRef
+    drift` 로 거부됐다.
     """
     if round_number < 1:
         raise ExecutionManifestError("dynamic verifier round must be positive")
@@ -156,20 +149,6 @@ def reserve_dynamic_verifier(
             raise ExecutionManifestError(
                 "dynamic verifier has no runner write capability"
             )
-        try:
-            policy, enforcement = build_invocation_write_contract(
-                role="verifier",
-                project_root=project_root,
-                worktree=worktree,
-                artifact_paths=artifact_paths,
-                maximum_precision=capability.max_boundary_precision,
-                auxiliary_roots=verifier_extra_dirs("verifier"),
-                validated_auxiliary_roots=verifier_extra_dirs("verifier"),
-            )
-        except (OSError, ValueError) as exc:
-            raise ExecutionManifestError(
-                f"dynamic verifier write policy is invalid: {exc}"
-            ) from exc
         return Invocation(
             invocation_ref=selected_ref,
             participant_ref=verifier.participant_ref,
@@ -180,9 +159,6 @@ def reserve_dynamic_verifier(
             dispatch_kind=f"reverify-r{round_number}",
             round=round_number,
             input_digest=input_digest,
-            write_policy=policy.to_payload(),
-            write_policy_digest=policy.digest,
-            write_enforcement=enforcement.to_payload(),
         )
 
     return reserve_derived_role_invocation(

package/runtime/python/okstra_ctl/design_prep.py

@@ -53,6 +53,9 @@ _PLANNING_DATA_RE = re.compile(
 )
 _REQUEST_STATUSES = {"provisional", "blocked"}
 _INPUT_DECISIONS = {"accept-draft", "modify-draft", "reject-draft", "defer"}
+_RECORDED_REQUEST_RE = re.compile(
+    r"^design-prep-requests/design-prep-request-(?P<token>[0-9]+)-(?P<item>.+)\.md$"
+)
 _INPUT_FILENAME_RE = re.compile(
     r"^design-prep-input-(?P<seq>\d+)-(?P<item>PREP-\d{3})-"
     r"r(?P<revision>\d{3,})-(?P<input_id>[0-9a-f-]{36})\.md$"
@@ -322,12 +325,34 @@ def _request_target(
         "design-prep-requests/"
         f"design-prep-request-{planning_seq}-{item_id}.md"
     )
-    if item.get("requestPath") != expected_relative:
+    request_dir = data_path.parent.parent / "design-prep-requests"
+    recorded = item.get("requestPath")
+    if recorded == expected_relative:
+        target = (data_path.parent.parent / expected_relative).resolve()
+    elif isinstance(recorded, str) and recorded.startswith("design-prep-requests/"):
+        target = (data_path.parent.parent / recorded).resolve()
+        match = _RECORDED_REQUEST_RE.fullmatch(recorded)
+        same_item = bool(match and match.group("item") == item_id)
+        stages = {
+            stage for stage in (item.get("stageRefs") or []) if isinstance(stage, int)
+        }
+        token_ok = bool(match) and int(match.group("token")) in stages
+        if target.is_file() and same_item:
+            pass
+        elif same_item and token_ok:
+            # 스냅샷은 stage 번호를 파일명에 쓴다. 파일이 아직 없어도 그 경로가
+            # 정본이다.
+            pass
+        else:
+            raise DesignPrepError(
+                f"item {item_id} must use canonical requestPath {expected_relative}"
+            )
+    else:
         raise DesignPrepError(
             f"item {item_id} must use canonical requestPath {expected_relative}"
         )
-    request_dir = data_path.parent.parent / "design-prep-requests"
-    target = (data_path.parent.parent / expected_relative).resolve()
+    # resolve 하지 않은 request_dir 과 비교한다. 디렉터리가 바깥을 가리키는
+    # 심링크면 target.parent 가 바깥이 되어 탈출을 잡는다.
     if target.parent != request_dir:
         raise DesignPrepError(f"requestPath escapes design-prep-requests: {target}")
     return target
@@ -358,13 +383,54 @@ def _render_request(
     return target, _complete_request(body, assessment, request_content).encode("utf-8")
 
 
-def _require_matching_request(target: Path, expected: bytes, conflict: str) -> None:
+# 요청의 내용이 아니라 "어느 리포트가 이 요청을 실었는가" 에 딸린 프론트매터 줄.
+# `request-content-fingerprint` 가 여기 드는 이유는 그 해시의 입력
+# (`_render_request_body_without_fingerprints`) 이 `source-report` 줄을 포함하기
+# 때문이다 — 리포트가 바뀌면 지문도 같이 흔들린다.
+_REPORT_BOUND_REQUEST_FIELDS = ("source-report:", "request-content-fingerprint:")
+
+
+def _request_identity(raw: bytes) -> bytes:
+    """발행 리포트에 딸린 줄을 뺀 요청 신원.
+
+    Stage Ledger 규칙은 `done` stage 의 본문을 다음 계획 run 으로 그대로
+    이월하도록 요구하고, 그러면 같은 PREP 항목이 매 run 마다 다시 탐지된다.
+    렌더된 요청은 `source-report` 한 줄만 달라지므로, 발행 리포트까지 신원에
+    넣으면 한 태스크의 **두 번째 계획 run 부터 조립이 항상 막힌다** — 요청
+    파일은 태스크 단위 디렉터리에 누적되고 이월은 선택이 아니기 때문이다.
+
+    내용의 동일성은 남는 것들이 그대로 덮는다: `assessment-fingerprint` 는
+    항목의 의미 필드만 해시하고(`assessment_fingerprint`), 본문 10개 절은 통째로
+    비교된다. 즉 요청이 실제로 달라지면 여기서 여전히 걸린다.
+    """
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeError:
+        # 신원을 계산할 수 없는 파일이다. 원본 바이트로 비교하게 두어 다르다고
+        # 판정되게 한다 — 읽을 수 없는 파일을 같다고 볼 근거가 없다.
+        return raw
+    return "\n".join(
+        line
+        for line in text.splitlines()
+        if not line.startswith(_REPORT_BOUND_REQUEST_FIELDS)
+    ).encode("utf-8")
+
+
+def _request_conflicts(target: Path, expected: bytes, conflict: str) -> str | None:
+    """Return a one-line conflict description, or ``None`` when the file matches."""
     try:
         existing = target.read_bytes()
     except OSError as exc:
         raise DesignPrepError(f"cannot read existing request {target}: {exc}") from exc
-    if existing != expected:
-        raise DesignPrepError(f"refuses to overwrite {conflict}: {target}")
+    if _request_identity(existing) != _request_identity(expected):
+        return f"refuses to overwrite {conflict}: {target}"
+    return None
+
+
+def _require_matching_request(target: Path, expected: bytes, conflict: str) -> None:
+    reason = _request_conflicts(target, expected, conflict)
+    if reason is not None:
+        raise DesignPrepError(reason)
 
 
 def _write_request_no_clobber(target: Path, encoded: bytes) -> None:
@@ -397,16 +463,32 @@ def materialize_design_prep_requests(plan_data_path: Path) -> list[Path]:
     planning_seq = _planning_seq(data_path)
     report_language = _report_language(data)
     items = _design_preparation_items(data)
-    written: list[Path] = []
-    for item in items:
-        if item.get("status") not in _REQUEST_STATUSES:
-            continue
-        target, encoded = _render_request(
+    # 충돌은 한 항목씩 알리지 않는다. 요청 12개가 모두 옛 리포트의 파일과 부딪히면
+    # 첫 건에서 멈추는 구현은 사용자에게 12회 왕복을 시키고, 그때마다 이미 쓴
+    # 앞쪽 파일이 남아 상태가 절반만 진행된다. 전부 렌더해 전부 검사한 뒤 쓴다.
+    rendered = [
+        _render_request(
             data_path=data_path,
             planning_seq=planning_seq,
             report_language=report_language,
             item=item,
         )
+        for item in items
+        if item.get("status") in _REQUEST_STATUSES
+    ]
+    conflicts = [
+        reason
+        for target, encoded in rendered
+        if target.exists()
+        and (reason := _request_conflicts(target, encoded, "different request"))
+    ]
+    if conflicts:
+        raise DesignPrepError(
+            f"{len(conflicts)} design-prep request(s) conflict with existing files: "
+            + "; ".join(conflicts)
+        )
+    written: list[Path] = []
+    for target, encoded in rendered:
         _write_request_no_clobber(target, encoded)
         written.append(target)
     return written
@@ -1367,8 +1449,22 @@ def _discover_planning_reports(project_root: Path) -> list[Path]:
     return sorted(project_root.glob(pattern))
 
 
+_CLI_EPILOG = r"""Usage:
+  okstra design-prep list [--project-root <path>] [--report <path>]
+  okstra design-prep show --report <path> [--item PREP-001]
+  okstra design-prep write --report <path> --item PREP-001 \
+    --decision <accept-draft|modify-draft|reject-draft|defer> \
+    [--overrides <json-object>] [--notes <text>] --confirmed
+"""
+_CLI_DESCRIPTION = "Review AI-prepared implementation design inputs."
+
+
 def _build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(prog="design-prep")
+    parser = argparse.ArgumentParser(
+        description=_CLI_DESCRIPTION,
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        prog="okstra design-prep")
     subparsers = parser.add_subparsers(dest="command", required=True)
     list_parser = subparsers.add_parser("list")
     list_parser.add_argument("--project-root", default="")

package/runtime/python/okstra_ctl/design_snapshot.py

@@ -114,8 +114,18 @@ def write_snapshot(narrative_path: Path, output_path: Path) -> dict[str, Any]:
     return snapshot
 
 
+_CLI_EPILOG = r"""Usage:
+  okstra design-snapshot --narrative <report-narrative.md> --output <design-preparation.json>
+"""
+_CLI_DESCRIPTION = "Write the detector-owned planning snapshot."
+
+
 def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(prog="okstra design-snapshot")
+    parser = argparse.ArgumentParser(
+        description=_CLI_DESCRIPTION,
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        prog="okstra design-snapshot")
     parser.add_argument("--narrative", type=Path, required=True)
     parser.add_argument("--output", type=Path, required=True)
     args = parser.parse_args(argv)

package/runtime/python/okstra_ctl/design_surfaces.py

@@ -110,6 +110,34 @@ def _phrase_matches(text: str, phrase: str) -> bool:
     return re.search(rf"(?<![\w-]){re.escape(phrase)}(?![\w-])", text) is not None
 
 
+SELECTED_DIRECTION_CONTRACT = "selected-direction"
+
+
+def _planned_file_structure(planning: Mapping[str, Any]) -> list[Any]:
+    """설계 표면 탐지가 읽는 "이 계획이 건드리는 파일" 목록.
+
+    계획서에는 계약이 둘 있고 그 목록의 자리가 다르다. 선택 방향 계약은
+    `directionRealization.fileStructure`, 레거시 후보비교 계약은 추천 후보의
+    `optionCandidates[].fileStructure` 다.
+
+    분기가 이 함수 안이 아니라 호출부 한 곳(`plan_items._extract_prep_items`)에만
+    있던 동안, 같은 탐지기를 부르는 나머지 세 호출부(`design_snapshot`,
+    `report_projections`, `validate-run`)는 선택 방향 계획을 레거시 모양으로 읽고
+    "recommended option '' is missing or ambiguous" 로 실패했다. 계획은 멀쩡한데
+    최종 검증만 막혔다.
+    """
+    if planning.get("planningContract") == SELECTED_DIRECTION_CONTRACT:
+        realization = planning.get("directionRealization")
+        if not isinstance(realization, Mapping):
+            raise DesignSurfaceError(
+                "selected-direction plan has no directionRealization object"
+            )
+        rows = realization.get("fileStructure")
+        return list(rows) if isinstance(rows, list) else []
+    rows = _selected_candidate(planning).get("fileStructure")
+    return list(rows) if isinstance(rows, list) else []
+
+
 def _selected_candidate(planning: Mapping[str, Any]) -> Mapping[str, Any]:
     recommended = _normalise((planning.get("recommendedOption") or {}).get("name"))
     candidates = [
@@ -321,8 +349,7 @@ def detect_design_surfaces(
                     value=step.get(field),
                 ):
                     grouped.setdefault((stage_number, kind), []).append(evidence)
-    selected = _selected_candidate(planning)
-    for row in selected.get("fileStructure") or []:
+    for row in _planned_file_structure(planning):
         if not isinstance(row, Mapping):
             continue
         path = str(row.get("path") or "")