okstra 0.175.1 → 0.176.0

package/runtime/validators/validate-run.py

@@ -73,8 +73,8 @@ from okstra_ctl.incremental_scope import (  # noqa: E402
     coverage_row_blocked_on,
     stages_for_clarification,
 )
+from okstra_ctl import next_phase  # noqa: E402
 from okstra_ctl.workflow import (  # noqa: E402
-    DEFAULT_NEXT_PHASE,
     ERROR_ANALYSIS_ROUTING_DIRECTIONS,
     PHASE_SEQUENCE,
     REQUIREMENTS_DISCOVERY_ROUTING_TARGETS,
@@ -627,68 +627,6 @@ def write_json(path: Path, payload: dict) -> None:
     path.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n")
 
 
-def default_next_phase(task_type: str) -> str:
-    return DEFAULT_NEXT_PHASE.get(task_type, "unknown")
-
-
-def advance_next_phase(
-    current_phase: str,
-    phase_sequence: list,
-) -> str:
-    """Compute the next recommended phase after `current_phase` completes.
-
-    Walk `phase_sequence` and return the entry following `current_phase`.
-    Falls back to the static `default_next_phase` mapping when the current
-    phase is the terminal entry or is absent from the sequence (e.g. custom
-    task types that aren't part of the standard 5-phase lifecycle).
-    """
-    if isinstance(phase_sequence, list) and current_phase in phase_sequence:
-        idx = phase_sequence.index(current_phase)
-        if idx + 1 < len(phase_sequence):
-            return phase_sequence[idx + 1]
-        return "done-or-follow-up"
-    return default_next_phase(current_phase)
-
-
-def _error_analysis_next_phase(data: Mapping[str, Any]) -> str | None:
-    if not isinstance(data, Mapping):
-        return None
-    header = data.get("header")
-    if not isinstance(header, Mapping) or header.get("taskType") != "error-analysis":
-        return None
-    error_analysis = data.get("errorAnalysis")
-    if not isinstance(error_analysis, Mapping):
-        return None
-    routing = error_analysis.get("routing")
-    if not isinstance(routing, Mapping):
-        return None
-    target = routing.get("nextTaskType")
-    if target in ERROR_ANALYSIS_ROUTING_DIRECTIONS:
-        return str(target)
-    return None
-
-
-def _requirements_discovery_next_phase(data: Mapping[str, Any]) -> str | None:
-    if not isinstance(data, Mapping):
-        return None
-    header = data.get("header")
-    if (
-        not isinstance(header, Mapping)
-        or header.get("taskType") != "requirements-discovery"
-    ):
-        return None
-    requirements = data.get("requirementsDiscovery")
-    if not isinstance(requirements, Mapping):
-        return None
-    routing = requirements.get("routing")
-    if not isinstance(routing, Mapping):
-        return None
-    target = routing.get("nextTaskType")
-    if target in REQUIREMENTS_DISCOVERY_ROUTING_TARGETS:
-        return str(target)
-    return None
-
-
 def update_workflow_metadata(
     run_manifest: dict,
     task_manifest: dict,
@@ -715,36 +653,49 @@ def update_workflow_metadata(
     for phase in phase_sequence:
         phase_states.setdefault(phase, "not-started")
 
+    # 포인터는 리드가 리포트에 저작하고, 이 검증기는 그것을 계산하지 않는다.
+    # 여기서 하는 일은 리포트의 Phase 라우팅 투영과 대조하는 것뿐이다.
+    authored = next_phase.promote(workflow.get("nextRecommendedPhase"))
+    workflow.pop("nextRecommendedPhaseCorrection", None)
+
     if validation_status == "passed":
         current_phase_state = "completed"
         if current_phase:
             phase_states[current_phase] = current_phase_state
         last_completed_phase = current_phase or workflow.get("lastCompletedPhase", "")
-        # Validation just passed → actively advance to the next phase in
-        # the sequence rather than preserving a stale value that may equal
-        # current_phase (which would cause the lifecycle pointer to stall).
-        if current_phase == "requirements-discovery":
-            report_next_phase = _requirements_discovery_next_phase(report_data or {})
-        elif current_phase == "error-analysis":
-            report_next_phase = _error_analysis_next_phase(report_data or {})
+        # 어긋나면 투영값으로 정정하되 실행은 죽이지 않는다 — 분석이 통과한 run 을
+        # 장부 필드 하나 때문에 버리지 않는다 (ADR-0004).
+        projected = next_phase.project(report_data or {})
+        if (
+            authored["phase"] == projected["phase"]
+            and authored["status"] == projected["status"]
+        ):
+            next_recommended_phase = authored
         else:
-            report_next_phase = None
-        next_recommended_phase = report_next_phase or advance_next_phase(
-            current_phase, phase_sequence
-        )
+            # 리드의 근거는 리드가 고른 phase 를 설명하는 문장이다. phase 를 정정한
+            # 뒤에도 들고 오면 포인터가 자기 목적지를 설명하지 않는 문장을 달게 된다.
+            # 원문은 아래 correction["authored"] 에 그대로 보존된다.
+            next_recommended_phase = next_phase.make(
+                phase=projected["phase"],
+                status=projected["status"],
+                rationale=(
+                    "리포트 라우팅에서 투영됨. 리드가 쓴 값과 근거는 "
+                    "nextRecommendedPhaseCorrection.authored 에 있다."
+                ),
+            )
+            # applied 는 사본이다. 살아 있는 포인터와 같은 dict 를 가리키면
+            # 나중에 포인터를 제자리 변형하는 호출부가 감사 기록까지 바꾼다.
+            workflow["nextRecommendedPhaseCorrection"] = {
+                "authored": authored,
+                "applied": dict(next_recommended_phase),
+            }
     else:
         current_phase_state = "blocked"
         if current_phase:
             phase_states[current_phase] = current_phase_state
         last_completed_phase = workflow.get("lastCompletedPhase", "")
-        next_recommended_phase = current_phase or workflow.get(
-            "nextRecommendedPhase", ""
-        )
-
-    routing_status = workflow.get("routingStatus")
-    if not isinstance(routing_status, str) or not routing_status.strip():
-        routing_status = (
-            "pending" if current_phase == "requirements-discovery" else "not-applicable"
+        next_recommended_phase = next_phase.make(
+            status=next_phase.STATUS_BLOCKED, rationale=authored["rationale"]
         )
 
     awaiting_approval = workflow.get("awaitingApproval")
@@ -792,6 +743,9 @@ def update_workflow_metadata(
         }
     )
 
+    # routingStatus 는 포인터 status 로 흡수됐다. update() 는 키를 더할 뿐이라
+    # 이전 run 이 남긴 값은 명시적으로 지워야 사라진다.
+    workflow.pop("routingStatus", None)
     workflow.update(
         {
             "phaseSequence": phase_sequence,
@@ -801,7 +755,6 @@ def update_workflow_metadata(
             "lastCompletedPhase": last_completed_phase,
             "nextRecommendedPhase": next_recommended_phase,
             "awaitingApproval": awaiting_approval,
-            "routingStatus": routing_status,
             "lastSafeCheckpoint": last_safe_checkpoint,
         }
     )
@@ -810,6 +763,10 @@ def update_workflow_metadata(
     workflow_snapshot = run_manifest.get("workflowSnapshot", {})
     if not isinstance(workflow_snapshot, dict):
         workflow_snapshot = {}
+    # task manifest 의 workflow 는 다음 run 이 덮어쓰므로 정정 기록이 남지 않는다.
+    # run 단위 감사 기록은 이 스냅샷이 유일한 보관처다.
+    workflow_snapshot.pop("routingStatus", None)
+    workflow_snapshot.pop("nextRecommendedPhaseCorrection", None)
     workflow_snapshot.update(
         {
             "phaseSequence": workflow["phaseSequence"],
@@ -817,12 +774,20 @@ def update_workflow_metadata(
             "currentPhaseState": workflow["currentPhaseState"],
             "phaseStates": workflow["phaseStates"],
             "lastCompletedPhase": workflow["lastCompletedPhase"],
-            "nextRecommendedPhase": workflow["nextRecommendedPhase"],
+            # 포인터는 이제 문자열이 아니라 dict 다. 두 매니페스트가 같은 객체를
+            # 공유하면 한쪽을 제자리 변형할 때 다른 쪽이 조용히 따라 바뀐다.
+            "nextRecommendedPhase": dict(workflow["nextRecommendedPhase"]),
             "awaitingApproval": workflow["awaitingApproval"],
-            "routingStatus": workflow["routingStatus"],
             "lastSafeCheckpoint": workflow["lastSafeCheckpoint"],
         }
     )
+    if "nextRecommendedPhaseCorrection" in workflow:
+        # 두 매니페스트는 별개 파일로 나간다 — dict 를 공유시키지 않는다.
+        # 겉 dict 만 복사하면 authored·applied 는 여전히 같은 객체다.
+        workflow_snapshot["nextRecommendedPhaseCorrection"] = {
+            key: dict(value)
+            for key, value in workflow["nextRecommendedPhaseCorrection"].items()
+        }
     run_manifest["workflowSnapshot"] = workflow_snapshot
 
 
@@ -7949,13 +7914,6 @@ def _validate_stage_has_requirement(data: dict, failures: list[str]) -> None:
         )
 
 
-_FINAL_VERIFICATION_ROUTING_TOKEN_RE = re.compile(
-    r"(?<![A-Za-z-])(?:release-handoff\(stage-group\)|release-handoff|done|"
-    r"implementation|error-analysis|implementation-option-selection|"
-    r"implementation-planning)(?![A-Za-z-])"
-)
-
-
 def _validate_final_verification_consistency(data: dict, failures: list[str]) -> None:
     """Enforce verdict ↔ blocker/condition/routing consistency on the
     final-verification data.json (SSOT). The schema guarantees field SHAPE;
@@ -7971,15 +7929,15 @@ def _validate_final_verification_consistency(data: dict, failures: list[str]) ->
     blockers = fv.get("acceptanceBlockers") or []
     conditions = verdict.get("conditionalAcceptanceConditions") or []
     routing_value = fv.get("routingRecommendation")
-    routing = routing_value if isinstance(routing_value, str) else ""
-    routing_tokens = _FINAL_VERIFICATION_ROUTING_TOKEN_RE.findall(routing)
-    routing_token = routing_tokens[0] if len(routing_tokens) == 1 else None
-
-    if routing_token is None:
+    routing_token = ""
+    if isinstance(routing_value, dict):
+        routing_token = str(routing_value.get("target") or "")
+    if not routing_token:
         failures.append(
-            "final-verification: routingRecommendation must contain exactly one "
-            "supported routing token."
+            "final-verification: routingRecommendation.target must name exactly one "
+            "supported routing target."
         )
+        routing_token = None
 
     if token == "accepted" and blockers:
         failures.append(