prizmkit 1.1.123 → 1.1.124

package/bundled/skills/prizmkit-code-review/scripts/check_loop.py

@@ -1,186 +1,380 @@
 #!/usr/bin/env python3
-"""
-Loop Exit Gatekeeper for prizmkit-code-review skill.
-
-Stateless design: all loop state is passed via stdin and returned via stdout.
-The caller (AI model) tracks `findings_history` and `max_rounds` between calls.
-No runtime files are created — the script is a pure function over JSON.
-
-The model supplies the current round in each call — the script does not auto-increment
-rounds, because the gate is called twice per loop iteration (after Reviewer returns
-and after Main Agent filters), and only the model knows when a full cycle completes.
-
-Usage:
-    echo '{"reviewer_result":"NEEDS_FIXES","accepted_count":2,"findings_count":5,"round":1,"findings_history":[],"max_rounds":3,"filtering_done":true}' | python3 check_loop.py
-
-Input JSON schema:
-    {
-        "reviewer_result": "PASS" | "NEEDS_FIXES",
-        "accepted_count": int,
-        "findings_count": int,
-        "round": int,
-        "findings_history": [int, ...],
-        "max_rounds": int,
-        "filtering_done": bool
-    }
-
-Output JSON schema:
-    {
-        "endLoop": bool,
-        "reason": str,
-        "verdict": "PASS" | "NEEDS_FIXES" | null,
-        "round": int,
-        "maxRounds": int,
-        "divergenceWarning": bool,
-        "findings_history": [int, ...]
-    }
-
-Exit conditions (checked in order):
-    1. Reviewer returned PASS          → endLoop=true, verdict=PASS
-    2. NEEDS_FIXES before filtering    → endLoop=false, wait for filtering
-    3. Filtered findings all rejected  → endLoop=true, verdict=PASS
-    4. Max rounds reached after filtering → endLoop=true, verdict=NEEDS_FIXES
-    5. Otherwise                       → endLoop=false
+"""Strict execution and convergence gate for prizmkit-code-review protocol v2."""
 
-Divergence detection:
-    If findings_count strictly increases for 3 consecutive rounds, set divergenceWarning=true.
-    This is a warning only — it does not force loop exit.
-"""
+from __future__ import annotations
 
 import json
 import sys
+from typing import Any
+
+PROTOCOL_VERSION = 2
+REVIEW_SAFETY_LIMIT = 10
+
+CAPABILITY_FIELDS = {
+    "mutation_capability",
+    "delegation_equivalent_capability",
+    "downstream_execution_creation",
+    "orchestration_reentry_capability",
+    "review_execution",
+    "status",
+}
+PREFLIGHT_FIELDS = {
+    "protocol_version",
+    "gate_stage",
+    "round",
+    "reviewers_started_this_round",
+    "reviewers_started_total",
+    "fresh_reviewer",
+    "workspace_snapshot_ready",
+    "capability_attestation",
+}
+RESULT_BASE_FIELDS = {
+    "protocol_version",
+    "gate_stage",
+    "filtering_done",
+    "round",
+    "reviewers_started_this_round",
+    "reviewers_started_total",
+    "fresh_reviewer",
+    "descendant_execution_units_observed",
+    "delegation_depth_observed",
+    "capability_attestation",
+    "orchestration_status",
+    "workspace_status",
+    "review_complete",
+    "reviewer_result",
+    "findings_count",
+}
+RESULT_FILTER_FIELDS = {"accepted_count", "rejected_count"}
+
+
+class ProtocolError(ValueError):
+    """Raised when a payload violates the strict protocol schema."""
 
-DEFAULT_MAX_ROUNDS = 3
 
+def _is_int(value: Any) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool)
 
-def check_divergence(findings_history):
-    """Return True if the last 3 entries in findings_history are strictly increasing."""
-    if len(findings_history) < 3:
-        return False
-    last_three = findings_history[-3:]
-    return last_three[0] < last_three[1] < last_three[2]
 
+def _require_exact_fields(data: dict[str, Any], required: set[str]) -> None:
+    missing = sorted(required - data.keys())
+    unknown = sorted(data.keys() - required)
+    if missing:
+        raise ProtocolError(f"missing required fields: {', '.join(missing)}")
+    if unknown:
+        raise ProtocolError(f"unknown fields: {', '.join(unknown)}")
+
+
+def _require_bool(data: dict[str, Any], name: str) -> bool:
+    value = data[name]
+    if not isinstance(value, bool):
+        raise ProtocolError(f"{name} must be a boolean")
+    return value
+
+
+def _require_count(data: dict[str, Any], name: str) -> int:
+    value = data[name]
+    if not _is_int(value) or value < 0:
+        raise ProtocolError(f"{name} must be a non-negative integer")
+    return value
+
+
+def _require_round(data: dict[str, Any]) -> int:
+    current_round = _require_count(data, "round")
+    if not 1 <= current_round <= REVIEW_SAFETY_LIMIT:
+        raise ProtocolError(
+            f"round must be between 1 and {REVIEW_SAFETY_LIMIT}"
+        )
+    return current_round
 
-def record_findings_count(findings_history, current_round, findings_count):
-    """Record findings_count once per round index, updating duplicate calls for the same round."""
-    if current_round <= 0:
-        return findings_history
 
-    target_index = current_round - 1
-    while len(findings_history) < target_index:
-        findings_history.append(0)
+def _require_enum(data: dict[str, Any], name: str, allowed: set[str]) -> str:
+    value = data[name]
+    if value not in allowed:
+        choices = ", ".join(sorted(allowed))
+        raise ProtocolError(f"{name} must be one of: {choices}")
+    return value
 
-    if len(findings_history) == target_index:
-        findings_history.append(findings_count)
-    else:
-        findings_history[target_index] = findings_count
 
-    return findings_history
+def _validate_protocol_header(data: dict[str, Any], stage: str) -> None:
+    if data["protocol_version"] != PROTOCOL_VERSION:
+        raise ProtocolError(
+            f"protocol_version must be {PROTOCOL_VERSION}"
+        )
+    if data["gate_stage"] != stage:
+        raise ProtocolError(f"gate_stage must be {stage}")
 
 
-def check_exit_condition(data):
-    """Determine whether the loop should exit. Pure function — no side effects.
+def _validate_attestation(value: Any) -> bool:
+    if not isinstance(value, dict):
+        raise ProtocolError("capability_attestation must be an object")
+    _require_exact_fields(value, CAPABILITY_FIELDS)
 
-    Round is model-supplied — the script does not auto-increment it because
-    the gate is called twice per loop iteration (after Step 2 and Step 3).
-    """
-    reviewer_result = data.get("reviewer_result")
-    accepted_count = data.get("accepted_count", 0)
-    findings_count = data.get("findings_count", 0)
-    current_round = data.get("round", 0)
-    findings_history = list(data.get("findings_history", []))
-    max_rounds = data.get("max_rounds", DEFAULT_MAX_ROUNDS)
-    filtering_done = data.get("filtering_done", reviewer_result == "PASS")
+    unavailable_fields = (
+        "mutation_capability",
+        "delegation_equivalent_capability",
+        "downstream_execution_creation",
+        "orchestration_reentry_capability",
+    )
+    for name in unavailable_fields:
+        _require_enum(value, name, {"available", "unavailable"})
+    _require_enum(
+        value,
+        "review_execution",
+        {"foreground-single-authority", "unsupported"},
+    )
+    _require_enum(value, "status", {"FAILED", "VERIFIED"})
 
-    findings_history = record_findings_count(
-        findings_history, current_round, findings_count
+    return (
+        value["status"] == "VERIFIED"
+        and value["review_execution"] == "foreground-single-authority"
+        and all(value[name] == "unavailable" for name in unavailable_fields)
     )
-    divergence_warning = check_divergence(findings_history)
-
-    # Condition 1: Reviewer returned PASS
-    if reviewer_result == "PASS":
-        return {
-            "endLoop": True,
-            "reason": f"Round {current_round}: Reviewer returned PASS",
-            "verdict": "PASS",
-            "round": current_round,
-            "maxRounds": max_rounds,
-            "divergenceWarning": False,
-            "findings_history": findings_history,
-        }
-
-    # Condition 2: Reviewer returned findings, but filtering has not happened yet
-    if reviewer_result == "NEEDS_FIXES" and not filtering_done:
-        return {
-            "endLoop": False,
-            "reason": f"Round {current_round}: reviewer returned findings; filter before applying exit conditions",
-            "verdict": None,
-            "round": current_round,
-            "maxRounds": max_rounds,
-            "divergenceWarning": divergence_warning,
-            "findings_history": findings_history,
-        }
-
-    # Condition 3: All findings rejected after filtering
-    if reviewer_result == "NEEDS_FIXES" and accepted_count == 0:
-        return {
-            "endLoop": True,
-            "reason": f"Round {current_round}: all findings rejected by main agent",
-            "verdict": "PASS",
-            "round": current_round,
-            "maxRounds": max_rounds,
-            "divergenceWarning": False,
-            "findings_history": findings_history,
-        }
-
-    # Condition 4: Max rounds reached
-    if current_round >= max_rounds:
-        return {
-            "endLoop": True,
-            "reason": f"Hard limit: max {max_rounds} rounds reached",
-            "verdict": "NEEDS_FIXES",
-            "round": current_round,
-            "maxRounds": max_rounds,
-            "divergenceWarning": divergence_warning,
-            "findings_history": findings_history,
-        }
-
-    # Condition 5: Continue loop
-    next_round = current_round + 1
+
+
+def _response(
+    *,
+    action: str,
+    verdict: str | None,
+    blocker_code: str | None = None,
+    launch_authorized: bool = False,
+    result_usable: bool = False,
+    end_loop: bool = False,
+    reason: str,
+) -> dict[str, Any]:
     return {
-        "endLoop": False,
-        "reason": f"Round {current_round}: {accepted_count} findings accepted, continuing to round {next_round}",
-        "verdict": None,
-        "round": current_round,
-        "maxRounds": max_rounds,
-        "divergenceWarning": divergence_warning,
-        "findings_history": findings_history,
+        "action": action,
+        "launchAuthorized": launch_authorized,
+        "resultUsable": result_usable,
+        "endLoop": end_loop,
+        "verdict": verdict,
+        "blockerCode": blocker_code,
+        "reason": reason,
     }
 
 
-def main():
-    # Read input from stdin
+def check_preflight(data: dict[str, Any]) -> dict[str, Any]:
+    """Authorize one safe Reviewer launch or return a fail-closed blocker."""
+    _require_exact_fields(data, PREFLIGHT_FIELDS)
+    _validate_protocol_header(data, "preflight")
+    current_round = _require_round(data)
+    started_this_round = _require_count(data, "reviewers_started_this_round")
+    started_total = _require_count(data, "reviewers_started_total")
+    fresh_reviewer = _require_bool(data, "fresh_reviewer")
+    snapshot_ready = _require_bool(data, "workspace_snapshot_ready")
+    attested = _validate_attestation(data["capability_attestation"])
+
+    if started_this_round != 0:
+        raise ProtocolError(
+            "preflight requires reviewers_started_this_round to equal 0"
+        )
+    if started_total != current_round - 1:
+        raise ProtocolError(
+            "preflight reviewers_started_total must equal round - 1"
+        )
+    if not fresh_reviewer:
+        return _response(
+            action="STOP",
+            verdict="NEEDS_FIXES",
+            blocker_code="REVIEW_INFRASTRUCTURE_BLOCKED",
+            end_loop=True,
+            reason="Reviewer execution is not fresh",
+        )
+    if not snapshot_ready:
+        return _response(
+            action="STOP",
+            verdict="NEEDS_FIXES",
+            blocker_code="REVIEW_INFRASTRUCTURE_BLOCKED",
+            end_loop=True,
+            reason="Workspace snapshot is not ready",
+        )
+    if not attested:
+        return _response(
+            action="STOP",
+            verdict="NEEDS_FIXES",
+            blocker_code="REVIEW_INFRASTRUCTURE_BLOCKED",
+            end_loop=True,
+            reason="Mandatory Reviewer capability boundary is not verified",
+        )
+
+    return _response(
+        action="AUTHORIZE_LAUNCH",
+        verdict=None,
+        launch_authorized=True,
+        reason=f"Round {current_round} may launch one fresh Reviewer",
+    )
+
+
+def _validate_result_structure(data: dict[str, Any]) -> tuple[int, int, bool]:
+    filtering_done = _require_bool(data, "filtering_done")
+    required_fields = RESULT_BASE_FIELDS | (
+        RESULT_FILTER_FIELDS if filtering_done else set()
+    )
+    _require_exact_fields(data, required_fields)
+    _validate_protocol_header(data, "result")
+
+    current_round = _require_round(data)
+    started_this_round = _require_count(data, "reviewers_started_this_round")
+    started_total = _require_count(data, "reviewers_started_total")
+    fresh_reviewer = _require_bool(data, "fresh_reviewer")
+    _require_count(data, "descendant_execution_units_observed")
+    _require_count(data, "delegation_depth_observed")
+    _require_bool(data, "review_complete")
+    findings_count = _require_count(data, "findings_count")
+    reviewer_result = _require_enum(
+        data, "reviewer_result", {"NEEDS_FIXES", "PASS"}
+    )
+    _require_enum(
+        data,
+        "orchestration_status",
+        {"COMPLIANT", "UNVERIFIABLE", "VIOLATION"},
+    )
+    _require_enum(data, "workspace_status", {"MATCHED", "MISMATCH"})
+    _validate_attestation(data["capability_attestation"])
+
+    if started_this_round != 1:
+        raise ProtocolError(
+            "result requires exactly one Reviewer started in the round"
+        )
+    if started_total != current_round:
+        raise ProtocolError("result reviewers_started_total must equal round")
+    if not fresh_reviewer:
+        raise ProtocolError("result requires a fresh Reviewer execution")
+    if reviewer_result == "PASS" and findings_count != 0:
+        raise ProtocolError("PASS requires findings_count to equal 0")
+    if reviewer_result == "NEEDS_FIXES" and findings_count == 0:
+        raise ProtocolError("NEEDS_FIXES requires at least one finding")
+
+    if filtering_done:
+        accepted_count = _require_count(data, "accepted_count")
+        rejected_count = _require_count(data, "rejected_count")
+        if accepted_count + rejected_count != findings_count:
+            raise ProtocolError(
+                "accepted_count + rejected_count must equal findings_count"
+            )
+        if reviewer_result == "PASS" and (accepted_count or rejected_count):
+            raise ProtocolError("PASS cannot contain finding classifications")
+
+    return current_round, findings_count, filtering_done
+
+
+def check_result(data: dict[str, Any]) -> dict[str, Any]:
+    """Validate topology and workspace before filtering, then decide convergence."""
+    current_round, _, filtering_done = _validate_result_structure(data)
+    attested = _validate_attestation(data["capability_attestation"])
+
+    if (
+        not attested
+        or data["descendant_execution_units_observed"] != 0
+        or data["delegation_depth_observed"] != 0
+        or data["orchestration_status"] != "COMPLIANT"
+    ):
+        return _response(
+            action="STOP",
+            verdict="NEEDS_FIXES",
+            blocker_code="REVIEW_ORCHESTRATION_VIOLATION",
+            end_loop=True,
+            reason="Reviewer execution topology is non-compliant or unverifiable",
+        )
+
+    if data["workspace_status"] != "MATCHED":
+        return _response(
+            action="STOP",
+            verdict="NEEDS_FIXES",
+            blocker_code="WORKSPACE_MISMATCH",
+            end_loop=True,
+            reason="Reviewer workspace does not match the authorized snapshot",
+        )
+
+    if not data["review_complete"]:
+        return _response(
+            action="STOP",
+            verdict="NEEDS_FIXES",
+            blocker_code="INVALID_REVIEW_RESULT",
+            end_loop=True,
+            reason="Reviewer output is incomplete",
+        )
+
+    if not filtering_done:
+        if data["reviewer_result"] == "PASS":
+            return _response(
+                action="PASS",
+                verdict="PASS",
+                result_usable=True,
+                end_loop=True,
+                reason=f"Round {current_round} completed with no findings",
+            )
+        return _response(
+            action="AUTHORIZE_FILTERING",
+            verdict=None,
+            result_usable=True,
+            reason=f"Round {current_round} findings are authorized for filtering",
+        )
+
+    if data["accepted_count"] == 0:
+        return _response(
+            action="PASS",
+            verdict="PASS",
+            result_usable=True,
+            end_loop=True,
+            reason=f"Round {current_round} converged with zero accepted findings",
+        )
+
+    if current_round == REVIEW_SAFETY_LIMIT:
+        return _response(
+            action="STOP",
+            verdict="NEEDS_FIXES",
+            blocker_code="REVIEW_SAFETY_LIMIT_REACHED",
+            result_usable=True,
+            end_loop=True,
+            reason="Accepted findings remain at the internal safety limit",
+        )
+
+    return _response(
+        action="CONTINUE",
+        verdict=None,
+        result_usable=True,
+        reason=(
+            f"Round {current_round} has {data['accepted_count']} accepted "
+            "findings; repair and start a fresh complete review"
+        ),
+    )
+
+
+def check_gate(data: Any) -> dict[str, Any]:
+    """Validate a strict v2 payload and dispatch to the requested stage."""
+    if not isinstance(data, dict):
+        raise ProtocolError("input must be a JSON object")
+    stage = data.get("gate_stage")
+    if stage == "preflight":
+        return check_preflight(data)
+    if stage == "result":
+        return check_result(data)
+    raise ProtocolError("gate_stage must be preflight or result")
+
+
+def main() -> int:
     try:
         data = json.load(sys.stdin)
-    except json.JSONDecodeError as e:
+        result = check_gate(data)
+    except (json.JSONDecodeError, ProtocolError) as error:
         print(
             json.dumps(
-                {
-                    "endLoop": False,
-                    "reason": f"Invalid JSON input: {e}",
-                    "verdict": None,
-                    "round": 0,
-                    "maxRounds": DEFAULT_MAX_ROUNDS,
-                    "divergenceWarning": False,
-                    "findings_history": [],
-                }
+                _response(
+                    action="STOP",
+                    verdict="NEEDS_FIXES",
+                    blocker_code="INVALID_REVIEW_RESULT",
+                    end_loop=True,
+                    reason=f"Invalid protocol payload: {error}",
+                ),
+                sort_keys=True,
             )
         )
-        sys.exit(1)
+        return 1
 
-    result = check_exit_condition(data)
-    print(json.dumps(result))
+    print(json.dumps(result, sort_keys=True))
+    return 0
 
 
 if __name__ == "__main__":
-    main()
+    sys.exit(main())