okstra 0.184.0 → 0.185.0

package/runtime/validators/validate-run.py

@@ -642,6 +642,35 @@ def write_json(path: Path, payload: dict) -> None:
     path.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n")
 
 
+def _report_already_approved(report_data: Mapping[str, Any] | None) -> bool:
+    if not isinstance(report_data, Mapping):
+        return False
+    frontmatter = report_data.get("frontmatter")
+    return isinstance(frontmatter, Mapping) and frontmatter.get("approved") is True
+
+
+def _derive_awaiting_approval(
+    *,
+    existing: bool,
+    validation_status: str,
+    current_phase: str,
+    pointer: Mapping[str, str],
+    report_data: Mapping[str, Any] | None,
+) -> bool:
+    """planning 이 승인 가능한 plan-ready 를 남기면 올리고, implementation
+    이 그 승인을 소비하면 내린다. 차단 게이트나 열린 Blocks=approval 은
+    포인터가 blocked 라 올리지 않는다."""
+    if validation_status == "passed" and current_phase == "implementation":
+        return False
+    if validation_status == "passed" and current_phase == "implementation-planning":
+        return (
+            pointer.get("phase") == "implementation"
+            and pointer.get("status") == next_phase.STATUS_READY
+            and not _report_already_approved(report_data)
+        )
+    return existing
+
+
 def update_workflow_metadata(
     run_manifest: dict,
     task_manifest: dict,
@@ -693,7 +722,8 @@ def update_workflow_metadata(
             next_recommended_phase = next_phase.make(
                 phase=projected["phase"],
                 status=projected["status"],
-                rationale=(
+                rationale=projected["rationale"]
+                or (
                     "리포트 라우팅에서 투영됨. 리드가 쓴 값과 근거는 "
                     "nextRecommendedPhaseCorrection.authored 에 있다."
                 ),
@@ -713,16 +743,16 @@ def update_workflow_metadata(
             status=next_phase.STATUS_BLOCKED, rationale=authored["rationale"]
         )
 
-    awaiting_approval = workflow.get("awaitingApproval")
-    if not isinstance(awaiting_approval, bool):
-        awaiting_approval = False
-    # 승인 게이트(`frontmatter approved`)는 implementation 진입 직전에 한 번만 의미를 가진다.
-    # implementation run 이 검증을 통과했다는 것은 `_validate_approved_plan` 이 이미 사용자
-    # 승인 플래그(frontmatter `approved: true`)를 소비했다는 뜻이므로, 이 시점에
-    # awaitingApproval 플래그를 명시적으로 내려 다음 phase 의 status 뷰에서 stale 상태로
-    # 남지 않게 한다.
-    if validation_status == "passed" and current_phase == "implementation":
-        awaiting_approval = False
+    awaiting_existing = workflow.get("awaitingApproval")
+    if not isinstance(awaiting_existing, bool):
+        awaiting_existing = False
+    awaiting_approval = _derive_awaiting_approval(
+        existing=awaiting_existing,
+        validation_status=validation_status,
+        current_phase=current_phase,
+        pointer=next_recommended_phase,
+        report_data=report_data,
+    )
 
     last_safe_checkpoint = workflow.get("lastSafeCheckpoint", {})
     if not isinstance(last_safe_checkpoint, dict):
@@ -3562,6 +3592,7 @@ def validate_final_report_data(
         _validate_clarification_evidence_note(data, failures)
         _validate_approval_clarification_backtrace(data, failures)
         _validate_rerun_guidance(data, failures)
+        _validate_approval_guidance(data, failures)
         _validate_variation_point_analysis(
             (data.get("implementationPlanning") or {}).get("variationPointAnalysis"),
             resolve_architecture(_project_root_from_report(report_path)),
@@ -6140,6 +6171,7 @@ def _validate_approval_clarification_backtrace(
 
 
 _RERUN_FLAG = "--answered-clarifications"
+_APPROVE_HINT = re.compile(r"--approve|\bapprov", re.IGNORECASE)
 
 
 def _next_step_texts(steps: object) -> list[str]:
@@ -6156,6 +6188,24 @@ def _next_step_texts(steps: object) -> list[str]:
     return texts
 
 
+def _has_blocks_approval_row(data: dict) -> bool:
+    return any(
+        isinstance(row, dict) and row.get("blocks") == "approval"
+        for row in data.get("clarificationItems") or []
+    )
+
+
+def _planning_gate_blocks_approval(data: dict) -> bool:
+    planning = data.get("implementationPlanning")
+    if not isinstance(planning, dict):
+        return False
+    verification = planning.get("planBodyVerification")
+    if not isinstance(verification, dict):
+        return False
+    gate = str(verification.get("gateResult") or "").strip().lower()
+    return gate in {"blocked-by-disagreement", "aborted-non-result"}
+
+
 def _validate_rerun_guidance(data: dict, failures: list[str]) -> None:
     """A report that withholds approval must say how to come back from it.
 
@@ -6168,10 +6218,7 @@ def _validate_rerun_guidance(data: dict, failures: list[str]) -> None:
     """
     if (data.get("header") or {}).get("taskType") != "implementation-planning":
         return
-    has_blocker = any(
-        isinstance(row, dict) and row.get("blocks") == "approval"
-        for row in data.get("clarificationItems") or []
-    )
+    has_blocker = _has_blocks_approval_row(data)
     if not has_blocker:
         return
     if any(_RERUN_FLAG in text for text in _next_step_texts(
@@ -6187,6 +6234,34 @@ def _validate_rerun_guidance(data: dict, failures: list[str]) -> None:
     )
 
 
+def _validate_approval_guidance(data: dict, failures: list[str]) -> None:
+    """승인 가능한 plan-ready 는 사용자에게 승인하라고 말해야 한다.
+
+    포인터가 implementation/ready 여도 승인은 사용자만 뒤집는다. 다음 단계
+    안내가 계획 재실행이면 승인 칸을 건너뛰고 같은 단계를 다시 돈다.
+    """
+    if (data.get("header") or {}).get("taskType") != "implementation-planning":
+        return
+    planning = data.get("implementationPlanning")
+    if not isinstance(planning, dict) or planning.get("outcome") != "plan-ready":
+        return
+    if _has_blocks_approval_row(data) or _planning_gate_blocks_approval(data):
+        return
+    if _report_already_approved(data):
+        return
+    if any(_APPROVE_HINT.search(text) for text in _next_step_texts(
+        data.get("recommendedNextSteps")
+    )):
+        return
+    failures.append(
+        "final-report data.json: this plan is ready for the user to approve, "
+        "but no `recommendedNextSteps` entry tells the reader to approve — "
+        "name `--approve` or the in-session wizard in a step's `text` or "
+        "one of its `commands`. Do not recommend another "
+        "implementation-planning run."
+    )
+
+
 def _validate_self_fix_grouping(data: dict, failures: list[str]) -> None:
     """A self-fix round must be instructed by cause, not as a flat item list.