okstra 0.183.2 → 0.185.0

package/runtime/python/okstra_ctl/plan_items.py

@@ -1,11 +1,16 @@
 """Deterministic extraction of implementation-planning verification items."""
 from __future__ import annotations
 
+import hashlib
+import json
 import re
-from collections.abc import Mapping
+from collections.abc import Mapping, Sequence
 from copy import deepcopy
+from dataclasses import dataclass
 from typing import Any
 
+from .build_tools import command_invokes_build_tool
+from .design_snapshot import build_design_snapshot
 from .design_surfaces import (
     DesignSurfaceError,
     detect_design_surfaces,
@@ -398,3 +403,407 @@ def extract_plan_items(implementation_planning: Mapping[str, Any]) -> list[dict[
 def expected_plan_item_ids(implementation_planning: Mapping[str, Any]) -> list[str]:
     """Return the exact ordered IDs produced by extract_plan_items()."""
     return [item["id"] for item in extract_plan_items(implementation_planning)]
+
+
+_STARTABLE_STATUSES = frozenset({"ready", "active"})
+
+
+def content_hash(item: Mapping[str, Any]) -> str:
+    """이 항목 본문의 지문. 문구가 같으면 라운드가 달라도 같은 판정이다.
+
+    라운드 번호만 보면 고치지 않은 항목까지 재검증해야 한다. subject·payload·
+    block·stageScope 가 같으면 그 항목이 가리키는 텍스트는 재작성 전과 같다.
+    """
+    payload = {
+        "block": item.get("block"),
+        "payload": item.get("payload"),
+        "stageScope": item.get("stageScope"),
+        "subject": item.get("subject"),
+    }
+    encoded = json.dumps(payload, ensure_ascii=False, sort_keys=True, default=str)
+    return hashlib.sha256(encoded.encode("utf-8")).hexdigest()
+
+
+def stage_scope_bucket(
+    item: Mapping[str, Any],
+    ledger: Mapping[str, str] | None,
+) -> str:
+    """게이트·디스패치가 공유하는 범위. ``in-scope`` / ``observed`` / ``deferred``.
+
+    원장이 없거나 항목에 스테이지가 없으면 계획 전체로 읽는다. 검증기
+    ``_stage_scope_bucket`` 과 같은 판정이어야 한다 — 디스패치와 게이트가
+    다른 통을 쓰면 워커가 본 항목과 승인을 막는 항목이 갈라진다.
+    """
+    if not isinstance(ledger, Mapping) or not ledger:
+        return "in-scope"
+    scope = item.get("stageScope")
+    stages = [
+        value for value in scope
+        if isinstance(value, int) and not isinstance(value, bool)
+    ] if isinstance(scope, list) else []
+    if not stages:
+        return "in-scope"
+    statuses = {str(ledger.get(str(stage)) or "") for stage in stages}
+    if statuses & _STARTABLE_STATUSES:
+        return "in-scope"
+    return "observed" if "done" in statuses else "deferred"
+
+
+def _depends_on(value: object) -> tuple[int, ...]:
+    if value in (None, "", "(none)", []):
+        return ()
+    if isinstance(value, list):
+        return tuple(
+            entry for entry in value
+            if isinstance(entry, int) and not isinstance(entry, bool) and entry >= 1
+        )
+    if isinstance(value, str):
+        stripped = value.strip()
+        if stripped in {"", "(none)"}:
+            return ()
+        numbers: list[int] = []
+        for token in stripped.split(","):
+            piece = token.strip()
+            if piece.isdigit() and int(piece) >= 1:
+                numbers.append(int(piece))
+        return tuple(numbers)
+    return ()
+
+
+def _planning_stage_rows(planning: Mapping[str, Any]) -> list[tuple[int, tuple[int, ...]]]:
+    stage_map = planning.get("stageMap")
+    if isinstance(stage_map, list) and stage_map:
+        rows: list[tuple[int, tuple[int, ...]]] = []
+        for row in stage_map:
+            if not isinstance(row, Mapping):
+                continue
+            number = row.get("stage")
+            if not isinstance(number, int) or isinstance(number, bool) or number < 1:
+                continue
+            rows.append((number, _depends_on(row.get("dependsOn"))))
+        return rows
+    stages = planning.get("stages")
+    if not isinstance(stages, list):
+        return []
+    rows = []
+    for row in stages:
+        if not isinstance(row, Mapping):
+            continue
+        number = row.get("stage")
+        if not isinstance(number, int) or isinstance(number, bool) or number < 1:
+            continue
+        rows.append((number, _depends_on(row.get("dependsOn"))))
+    return rows
+
+
+def planning_stage_ledger(
+    planning: Mapping[str, Any],
+    disk_status: Mapping[str, str] | None = None,
+) -> dict[str, str]:
+    """지금 계획의 스테이지를 ``done`` / ``active`` / ``ready`` / ``blocked`` 로.
+
+    디스크 원장은 이미 구현된 것만 안다. 첫 계획 run 에는 원장이 없어서
+    게이트가 전 항목을 in-scope 로 읽었다. 이 함수는 현재 계획의 depends-on 으로
+    그 빈칸을 채운다. 디스크에 ``done`` / ``active`` 가 있으면 그쪽이 이긴다.
+    """
+    recorded = {
+        key: value
+        for key, value in (disk_status or {}).items()
+        if value in {"done", "active", "ready", "blocked"}
+    }
+    done = {key for key, value in recorded.items() if value == "done"}
+    ledger: dict[str, str] = {}
+    for number, depends in _planning_stage_rows(planning):
+        key = str(number)
+        status = recorded.get(key)
+        if status in {"done", "active"}:
+            ledger[key] = status
+            continue
+        ready = all(str(dep) in done for dep in depends)
+        ledger[key] = "ready" if ready else "blocked"
+    return ledger
+
+
+def dispatch_item_ids(
+    items: Sequence[Mapping[str, Any]],
+    ledger: Mapping[str, str] | None,
+) -> list[str]:
+    """워커에게 보낼 항목. 게이트가 묻는 범위와 같다."""
+    ids: list[str] = []
+    for item in items:
+        item_id = item.get("id")
+        if not isinstance(item_id, str) or not item_id:
+            continue
+        if stage_scope_bucket(item, ledger) == "in-scope":
+            ids.append(item_id)
+    return ids
+
+
+def reverify_item_ids(
+    items: Sequence[Mapping[str, Any]],
+    previous_hashes: Mapping[str, str],
+    ledger: Mapping[str, str] | None,
+) -> list[str]:
+    """self-fix 뒤 다시 볼 항목. 해시가 바뀐 것과 같은 스테이지, 계획 전체.
+
+    이전이 없으면 첫 라운드라 디스패치 큐 전부다. 해시가 같은 다른 스테이지
+    항목은 보내지 않는다 — 그게 96개 일소 배치를 만들던 규칙이다.
+    """
+    dispatched = dispatch_item_ids(items, ledger)
+    by_id = {
+        item["id"]: item
+        for item in items
+        if isinstance(item.get("id"), str)
+    }
+    if not previous_hashes:
+        return dispatched
+    changed = [
+        item_id for item_id in dispatched
+        if previous_hashes.get(item_id) != content_hash(by_id[item_id])
+    ]
+    changed_stages: set[int] = set()
+    for item_id in changed:
+        scope = by_id[item_id].get("stageScope")
+        if isinstance(scope, list):
+            changed_stages.update(
+                value for value in scope
+                if isinstance(value, int) and not isinstance(value, bool)
+            )
+    queue: list[str] = []
+    for item_id in dispatched:
+        item = by_id[item_id]
+        scope = item.get("stageScope")
+        stages = [
+            value for value in scope
+            if isinstance(value, int) and not isinstance(value, bool)
+        ] if isinstance(scope, list) else []
+        if not stages:
+            if changed:
+                queue.append(item_id)
+            continue
+        if item_id in changed or changed_stages.intersection(stages):
+            queue.append(item_id)
+    return queue
+
+
+def advisory_plan_body_gating(
+    planning: Mapping[str, Any],
+    extracted: Sequence[Mapping[str, Any]] | None = None,
+) -> bool:
+    """검출 표면 0 + 스테이지 1이면 본문 검증은 자문만 한다.
+
+    준비 시점에는 계획이 없어 ``gating`` 을 false 로 둘 수 없다. 작성
+    초안과 탐지기 스냅샷이 생긴 뒤에만 이 판정을 쓴다. 다단계이거나
+    PREP 항목이 있으면 지금 게이트 계약 그대로다.
+    """
+    if len(_planning_stage_rows(planning)) != 1:
+        return False
+    if extracted is not None and any(
+        str(item.get("id") or "").startswith("P-Prep-") for item in extracted
+    ):
+        return False
+    preparation = planning.get("designPreparation")
+    if not isinstance(preparation, Mapping):
+        preparation = build_design_snapshot(planning).get("designPreparation")
+    if not isinstance(preparation, Mapping):
+        return False
+    items = preparation.get("items")
+    if preparation.get("mode") != "no-design-inputs":
+        return False
+    return not (isinstance(items, list) and items)
+
+
+def tie_vote_item_ids(
+    items: Sequence[Mapping[str, Any]],
+    ledger: Mapping[str, str] | None,
+    tied_ids: Sequence[str],
+) -> list[str]:
+    """needs-reverify 동수 항목만 세 번째 표에 보낸다.
+
+    첫 라운드 큐나 self-fix 재검증 큐와 섞지 않는다. 동수가 없으면 빈 목록이고
+    세 번째 워커는 뜨지 않는다.
+    """
+    allowed = set(dispatch_item_ids(items, ledger))
+    queue: list[str] = []
+    seen: set[str] = set()
+    for item_id in tied_ids:
+        if item_id in allowed and item_id not in seen:
+            queue.append(item_id)
+            seen.add(item_id)
+    return queue
+
+
+_ERROR_VERDICTS = frozenset({
+    "verification-error", "UNVERIFIABLE", "VERIFICATION-ERROR",
+})
+_COMMAND_KEYS = ("command", "commandOrObservation")
+
+ENVIRONMENT_CORRECTION_PREAMBLE = (
+    "Planning-time environment gap: this worktree has no build/test "
+    "dependencies installed. A command that is declared in package.json / "
+    "Makefile / the task runner but fails here on a missing module, binary, "
+    "exit 127, or command-not-found is UNVERIFIABLE, not DISAGREE(b). A "
+    "referenced path that does not exist is still DISAGREE(b). Whether a "
+    "path exists, whether a command is declared, and whether the plan is "
+    "internally consistent are all checkable without installing dependencies. "
+    "A blanket \"capability constraints prevent workspace resolution\" is not "
+    "a valid answer to any of them.\n"
+)
+
+
+def item_cites_build_command(item: Mapping[str, Any]) -> bool:
+    """이 항목이 계획 워크트리에서 실행 불가한 빌드/테스트 명령을 인용하는가."""
+    payload = item.get("payload") if isinstance(item.get("payload"), Mapping) else item
+    if not isinstance(payload, Mapping):
+        return False
+    for key in _COMMAND_KEYS:
+        value = payload.get(key)
+        if isinstance(value, str) and command_invokes_build_tool(value):
+            return True
+    return False
+
+
+def _error_verdict(token: str) -> bool:
+    stripped = token.strip()
+    return stripped in _ERROR_VERDICTS or stripped.upper() == "UNVERIFIABLE"
+
+
+def _item_votes(item: Mapping[str, Any]) -> list[tuple[str, str]]:
+    rows: list[tuple[str, str]] = []
+    for row in item.get("verdicts") or []:
+        if not isinstance(row, Mapping):
+            continue
+        worker = str(row.get("worker") or "").strip()
+        token = str(row.get("verdict") or "").strip()
+        if worker and token:
+            rows.append((worker, token))
+    return rows
+
+
+def _worker_vote_map(
+    items: Sequence[Mapping[str, Any]],
+) -> dict[str, list[tuple[str, str]]]:
+    votes: dict[str, list[tuple[str, str]]] = {}
+    for item in items:
+        item_id = str(item.get("id") or "")
+        if not item_id:
+            continue
+        for worker, token in _item_votes(item):
+            votes.setdefault(worker, []).append((item_id, token))
+    return votes
+
+
+def _with_payload(
+    item: Mapping[str, Any],
+    payloads: Mapping[str, Mapping[str, Any]] | None,
+) -> Mapping[str, Any]:
+    extra = payloads.get(str(item.get("id") or "")) if payloads else None
+    if extra is None or "payload" not in extra:
+        return item
+    merged = dict(item)
+    merged["payload"] = extra["payload"]
+    return merged
+
+
+def _worker_is_blanket(
+    votes: Sequence[tuple[str, str]],
+    items_by_id: Mapping[str, Mapping[str, Any]],
+    payloads: Mapping[str, Mapping[str, Any]] | None,
+) -> bool:
+    """전 표가 오류이고, 빌드 명령이 아닌 확인 가능 항목이 하나라도 있다."""
+    if not votes or any(not _error_verdict(token) for _item_id, token in votes):
+        return False
+    return any(
+        not item_cites_build_command(_with_payload(items_by_id[item_id], payloads))
+        for item_id, _token in votes
+        if item_id in items_by_id
+    )
+
+
+def blanket_unverifiable_workers(
+    items: Sequence[Mapping[str, Any]],
+    payloads: Mapping[str, Mapping[str, Any]] | None = None,
+) -> list[str]:
+    """전 배정 표가 UNVERIFIABLE/verification-error 인 워커. 경로 확인은 예외가 아니다."""
+    by_id = {
+        str(item["id"]): item
+        for item in items
+        if isinstance(item.get("id"), str) and item["id"]
+    }
+    return sorted(
+        worker
+        for worker, votes in _worker_vote_map(items).items()
+        if _worker_is_blanket(votes, by_id, payloads)
+    )
+
+
+def _is_tie(item: Mapping[str, Any]) -> bool:
+    tokens = [
+        token for _worker, token in _item_votes(item) if not _error_verdict(token)
+    ]
+    if len(tokens) < 2:
+        return False
+    disagree = sum(1 for token in tokens if token.upper().startswith("DISAGREE"))
+    agree = sum(1 for token in tokens if token.upper() in {"AGREE", "SUPPLEMENT"})
+    return disagree == agree and disagree > 0
+
+
+@dataclass(frozen=True)
+class NextDispatch:
+    """다음 워커 배치. ``none`` 은 배치를 열지 않는다."""
+
+    kind: str
+    workers: tuple[str, ...]
+    item_ids: tuple[str, ...]
+    reason: str
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "kind": self.kind,
+            "workers": list(self.workers),
+            "itemIds": list(self.item_ids),
+            "reason": self.reason,
+        }
+
+
+def next_dispatch(
+    items: Sequence[Mapping[str, Any]],
+    payloads: Mapping[str, Mapping[str, Any]] | None = None,
+) -> NextDispatch:
+    """환경 전용 UNVERIFIABLE 은 전체 라운드를 만들지 않는다. 일괄 오류만 그 워커."""
+    assigned = tuple(
+        str(item["id"]) for item in items
+        if isinstance(item.get("id"), str) and item["id"]
+    )
+    blanket = tuple(blanket_unverifiable_workers(items, payloads))
+    if blanket:
+        return NextDispatch(
+            kind="worker-correction",
+            workers=blanket,
+            item_ids=assigned,
+            reason=(
+                "blanket UNVERIFIABLE/verification-error; "
+                "correct those workers only"
+            ),
+        )
+    ties = tuple(
+        str(item["id"]) for item in items
+        if isinstance(item.get("id"), str) and _is_tie(item)
+    )
+    if ties:
+        return NextDispatch(
+            kind="queue-reverify",
+            workers=tuple(sorted(_worker_vote_map(items))),
+            item_ids=ties,
+            reason="unsettled tie on a blocking kind",
+        )
+    return NextDispatch(
+        kind="none", workers=(), item_ids=(),
+        reason="no worker batch",
+    )
+
+
+def correction_prompt_text(queue_markdown: str) -> str:
+    """시정 프롬프트. 환경 예외 단락이 큐보다 앞이다."""
+    return f"{ENVIRONMENT_CORRECTION_PREAMBLE.rstrip()}\n\n{queue_markdown.lstrip()}"
+