okstra 0.183.2 → 0.185.0

package/runtime/python/okstra_ctl/incremental_scope.py

@@ -28,6 +28,11 @@ CUTOFF_RATIO = 0.5
 # either a structural judgement or a mapping the lead never made.
 DECLARED_FULL_PREFIX = "declared structural change:"
 
+# CLI-to-lead signal only: an answered id traced to no stage and the user has
+# not named `--impacted` stages. Never recorded as incrementalDecision (schema
+# enum is incremental|full). The lead asks for stage numbers and calls again.
+UNRESOLVED_MODE = "unresolved"
+
 # `P-Step-<stage>.<step>` and `P-Prep-S<stage>-<kind>` carry their stage in the
 # id itself. Every other prefix (`P-Opt`, `P-Dep`, `P-Val`, `P-Rb`, `P-Req`) is
 # numbered by position in its own array, so its stage is only recoverable from
@@ -37,7 +42,7 @@ _STRUCTURAL_STAGE_IN_ID_RE = re.compile(r"^P-(?:Step-(\d+)\.\d+|Prep-S(\d+)-)")
 
 @dataclass
 class IncrementalDecision:
-    mode: str  # "incremental" | "full"
+    mode: str  # "incremental" | "full" | "unresolved"
     reverify_stages: list[int]
     carry_stages: list[int]
     reason: str
@@ -167,6 +172,25 @@ def _stages_blocked_on(coverage: object, clarification_id: str) -> set[int]:
     return stages
 
 
+def partition_clarification_stages(
+    data: dict, clarification_ids: set[str]
+) -> tuple[set[int], list[str]]:
+    """연결된 stage 번호와, 아무 stage 에도 안 닿는 id.
+
+    preview 와 판정 경로가 같은 분할을 쓴다. unlinked 는 full 강등이 아니라
+    `--impacted` 를 받거나 `--full-reason` 을 받는 분기이다.
+    """
+    impacted: set[int] = set()
+    unlinked: list[str] = []
+    for clarification_id in sorted(clarification_ids):
+        stages = stages_for_clarification(data, clarification_id)
+        if stages:
+            impacted |= stages
+        else:
+            unlinked.append(clarification_id)
+    return impacted, unlinked
+
+
 def clarification_impacted_stages(
     data: dict, clarification_ids: set[str]
 ) -> set[int]:
@@ -179,16 +203,15 @@ def clarification_impacted_stages(
 
     Raises when any id resolves to no stage — a partially-resolved set would
     narrow the re-run past an answer whose blast radius nobody established.
+    The CLI decision path does not use this raise as a full fallback; it asks
+    for `--impacted` instead.
     """
-    impacted: set[int] = set()
-    for clarification_id in sorted(clarification_ids):
-        stages = stages_for_clarification(data, clarification_id)
-        if not stages:
-            raise ValueError(
-                f"answered clarification {clarification_id} traces to no stage "
-                "(no plan item or coverage row cites one)"
-            )
-        impacted |= stages
+    impacted, unlinked = partition_clarification_stages(data, clarification_ids)
+    if unlinked:
+        raise ValueError(
+            f"answered clarification {unlinked[0]} traces to no stage "
+            "(no plan item or coverage row cites one)"
+        )
     return impacted
 
 
@@ -227,20 +250,19 @@ def preview_link_availability(data: dict, clarification_ids: set[str]) -> dict:
     be shown while the run is still reshapeable.
 
     `wouldForceFull: false` is therefore not a promise of `incremental` — it
-    says only that this half found nothing forcing full.
+    says only that this half found nothing forcing full. An unlinked id is
+    not such a thing: it cannot auto-narrow, and it does not force full.
     """
-    unlinked = sorted(
-        clarification_id
-        for clarification_id in clarification_ids
-        if not stages_for_clarification(data, clarification_id)
-    )
+    _, unlinked = partition_clarification_stages(data, clarification_ids)
     if unlinked:
         return {
-            "wouldForceFull": True,
+            "wouldForceFull": False,
             "unlinkedIds": unlinked,
             "reason": (
                 f"{', '.join(unlinked)} trace(s) to no stage in the prior report — "
-                "an answer whose blast radius was never recorded cannot narrow anything"
+                "name those stages via --impacted, or declare a structural change "
+                "with --full-reason; an unlinked id does not force the whole re-run "
+                "to full"
             ),
         }
     if not clarification_ids:
@@ -350,6 +372,47 @@ def _preview_result(args) -> dict:
         }
 
 
+def _decision_for_run(args) -> IncrementalDecision:
+    """SHA·폐포·컷오프 판정. unlinked 는 full 로 강등하지 않는다."""
+    data = load_owned_object(
+        Path(args.prev_data), artifact="incremental scope report"
+    )
+    stages = parse_stage_graph(data)
+    impacted = {
+        int(token.strip()) for token in args.impacted.split(",") if token.strip()
+    }
+    prep_ids = {
+        token.strip() for token in args.prep_items.split(",") if token.strip()
+    }
+    impacted.update(design_prep_impacted_stages(data, prep_ids))
+    answered = {
+        token.strip()
+        for token in args.answered_clarifications.split(",")
+        if token.strip()
+    }
+    linked, unlinked = partition_clarification_stages(data, answered)
+    if unlinked and not impacted:
+        return IncrementalDecision(
+            UNRESOLVED_MODE,
+            [],
+            [],
+            f"{', '.join(unlinked)} trace(s) to no stage in the prior report — "
+            "pass --impacted with the stage numbers those answers affect, or "
+            "--full-reason for a structural change",
+        )
+    impacted.update(linked)
+    unknown_stages = impacted - {stage for stage, _ in stages}
+    if unknown_stages:
+        unknown = ", ".join(str(stage) for stage in sorted(unknown_stages))
+        raise ValueError(f"impacted stage(s) absent from Stage Map: {unknown}")
+    return decide_scope(
+        stages=stages,
+        impacted_stages=impacted,
+        prev_base_sha=args.prev_base_sha,
+        cur_base_sha=args.cur_base_sha,
+    )
+
+
 def main(argv: list[str]) -> int:
     ap = argparse.ArgumentParser(prog="okstra incremental-scope")
     ap.add_argument("--prev-data", required=True, help="prior run final-report data.json")
@@ -395,31 +458,13 @@ def main(argv: list[str]) -> int:
         return 0
 
     try:
-        data = load_owned_object(
-            Path(args.prev_data), artifact="incremental scope report"
-        )
-        stages = parse_stage_graph(data)
-        impacted = {int(t.strip()) for t in args.impacted.split(",") if t.strip()}
-        prep_ids = {t.strip() for t in args.prep_items.split(",") if t.strip()}
-        impacted.update(design_prep_impacted_stages(data, prep_ids))
-        answered = {
-            t.strip() for t in args.answered_clarifications.split(",") if t.strip()
-        }
-        if answered:
-            impacted.update(clarification_impacted_stages(data, answered))
-        unknown_stages = impacted - {stage for stage, _ in stages}
-        if unknown_stages:
-            unknown = ", ".join(str(stage) for stage in sorted(unknown_stages))
-            raise ValueError(f"impacted stage(s) absent from Stage Map: {unknown}")
-        decision = decide_scope(
-            stages=stages, impacted_stages=impacted,
-            prev_base_sha=args.prev_base_sha, cur_base_sha=args.cur_base_sha,
-        )
+        decision = _decision_for_run(args)
     # Every bad input degrades to a full re-verification rather than raising:
     # `full` is always the safe answer, and the caller reads the decision off
     # stdout, so a traceback would leave it with no decision at all. OSError
     # covers an unreadable --prev-data, KeyError/TypeError a stageMap row that
-    # is missing `stage` or is not a mapping.
+    # is missing `stage` or is not a mapping. Unlinked ids are not this case
+    # — `_decision_for_run` returns `unresolved` instead of raising.
     except (OSError, ValueError, KeyError, TypeError) as exc:
         decision = IncrementalDecision(
             "full", [], [], f"invalid incremental-scope input: {exc}",

package/runtime/python/okstra_ctl/next_phase.py

@@ -9,6 +9,8 @@ from __future__ import annotations
 
 from typing import Any, Mapping
 
+from okstra_ctl.clarification_items import APPROVAL_BLOCKS, UNRESOLVED_STATUSES
+
 STATUS_READY = "ready"
 STATUS_PENDING = "pending"
 STATUS_BLOCKED = "blocked"
@@ -69,6 +71,12 @@ _OPTION_SELECTION_NON_PHASE = {
     "blocked": STATUS_BLOCKED,
 }
 
+# run.py BLOCKING_PLAN_BODY_GATES 와 같아야 한다. next_phase 는 run 을
+# 가져오지 않는다 — wizard 가 둘 다 import 해서 순환이 생긴다.
+_BLOCKING_PLAN_GATES = frozenset(
+    {"blocked-by-disagreement", "aborted-non-result"}
+)
+
 # final-verification 의 routing enum 중 phase 이름이 아니라 phase 에 붙은 범위
 # 한정자인 값 → 실제로 실행할 phase. `release-handoff(stage-group)` 은 넘길 stage
 # 묶음을 좁힌다는 뜻이지 다른 phase 가 아니다. 범위는 위저드의 handoff_stage_pick
@@ -210,13 +218,68 @@ def _from_option_selection(report_data: Mapping[str, Any]) -> dict[str, str]:
     return make(phase=routing, status=STATUS_READY)
 
 
+def _unresolved_approval_ids(report_data: Mapping[str, Any]) -> list[str]:
+    rows = report_data.get("clarificationItems")
+    if not isinstance(rows, list):
+        return []
+    ids: list[str] = []
+    for row in rows:
+        if not isinstance(row, Mapping):
+            continue
+        blocks = str(row.get("blocks") or "").strip().lower()
+        status = str(row.get("status") or "").strip().lower()
+        row_id = row.get("id")
+        if (
+            blocks in APPROVAL_BLOCKS
+            and status in UNRESOLVED_STATUSES
+            and isinstance(row_id, str)
+            and row_id
+        ):
+            ids.append(row_id)
+    return ids
+
+
+def _planning_approval_block_reason(
+    report_data: Mapping[str, Any], planning: Mapping[str, Any]
+) -> str:
+    """plan-ready 인데 승인할 수 없으면 근거, 아니면 빈 문자열.
+
+    자문 게이트(`passed-with-dissent`)와 재현 실패 `has-dissent` 는 여기 안
+    들어온다. 차단은 `blocked-by-disagreement` / `aborted-non-result` 와
+    `Status` 가 open/answered 인 `Blocks=approval` 행뿐이다.
+    """
+    ids = _unresolved_approval_ids(report_data)
+    if ids:
+        listed = ", ".join(ids)
+        return (
+            f"{listed} 가 Blocks=approval 로 열려 승인할 수 없습니다. "
+            "okstra-user-response 로 답한 뒤 그 답을 가지고 계획 단계를 "
+            "재개하세요. 구현을 시작하거나, 답을 쓰기 전에 계획 단계를 "
+            "다시 돌리지 마세요."
+        )
+    verification = planning.get("planBodyVerification")
+    gate = ""
+    if isinstance(verification, Mapping):
+        gate = str(verification.get("gateResult") or "").strip().lower()
+    if gate in _BLOCKING_PLAN_GATES:
+        return (
+            f"계획 본문 게이트가 `{gate}` 이라 승인할 수 없습니다. "
+            "구현을 시작하거나 계획 단계를 바로 다시 돌리지 마세요."
+        )
+    return ""
+
+
 def _from_planning(report_data: Mapping[str, Any]) -> dict[str, str]:
-    outcome = str(_block(report_data, "implementationPlanning").get("outcome") or "")
-    if outcome == "plan-ready":
-        return make(phase="implementation", status=STATUS_READY)
+    planning = _block(report_data, "implementationPlanning")
+    outcome = str(planning.get("outcome") or "")
     if outcome == "direction-invalidated":
         return make(phase="implementation-option-selection", status=STATUS_READY)
-    return make(status=STATUS_PENDING)
+    if outcome != "plan-ready":
+        return make(status=STATUS_PENDING)
+    blocked_reason = _planning_approval_block_reason(report_data, planning)
+    if blocked_reason:
+        return make(status=STATUS_BLOCKED, rationale=blocked_reason)
+    return make(phase="implementation", status=STATUS_READY)
 
 
 def _from_target(report_data: Mapping[str, Any], key: str) -> dict[str, str]: