phase-loop-runtime 0.2.0__py3-none-any.whl

phase_loop_runtime/git_topology.py

@@ -0,0 +1,252 @@
+from __future__ import annotations
+
+import os
+import subprocess
+from dataclasses import replace
+from pathlib import Path
+from typing import Any
+
+from .models import LoopEvent, StateSnapshot
+
+
+def attach_git_topology(repo: Path, value: LoopEvent | StateSnapshot) -> LoopEvent | StateSnapshot:
+    if value.git_topology:
+        return value
+    return replace(value, git_topology=collect_git_topology(repo))
+
+
+def collect_git_topology(repo: Path) -> dict[str, Any]:
+    if not _git_available(repo):
+        return {"available": False, "reason": "not a git worktree"}
+
+    topology: dict[str, Any] = {
+        "available": True,
+        "branch": _branch(repo),
+        "head": _git(repo, "rev-parse", "HEAD"),
+        "status_short_branch": _git(repo, "status", "--short", "--branch"),
+    }
+    topology["clean"] = not bool(_git(repo, "status", "--short"))
+
+    upstream = _git(repo, "rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}")
+    if upstream:
+        topology["upstream_ref"] = upstream
+        topology["upstream_head"] = _git(repo, "rev-parse", upstream)
+        behind, ahead = _ahead_behind(repo, upstream)
+        if ahead is not None:
+            topology["ahead_of_upstream"] = ahead
+        if behind is not None:
+            topology["behind_upstream"] = behind
+
+    default_remote = _git(repo, "symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD")
+    if default_remote:
+        topology["default_remote_ref"] = default_remote
+
+    base_ref = os.environ.get("PHASE_LOOP_BASE_REF") or upstream or default_remote or _existing_ref(repo, "origin/main")
+    if base_ref:
+        topology["base_ref"] = base_ref
+        topology["base_head"] = _git(repo, "rev-parse", base_ref)
+        behind, ahead = _ahead_behind(repo, base_ref)
+        if ahead is not None:
+            topology["ahead_of_base"] = ahead
+        if behind is not None:
+            topology["behind_base"] = behind
+
+    target_push_ref = os.environ.get("PHASE_LOOP_TARGET_PUSH_REF")
+    if target_push_ref:
+        topology["target_push_ref"] = target_push_ref
+    pr_head_ref = os.environ.get("PHASE_LOOP_PR_HEAD_REF") or os.environ.get("GITHUB_HEAD_REF")
+    if pr_head_ref:
+        topology["pr_head_ref"] = pr_head_ref
+    pr_base_ref = os.environ.get("PHASE_LOOP_PR_BASE_REF") or os.environ.get("GITHUB_BASE_REF")
+    if pr_base_ref:
+        topology["pr_base_ref"] = pr_base_ref
+    pr_url = os.environ.get("PHASE_LOOP_PR_URL")
+    if pr_url:
+        topology["pr_url"] = pr_url
+    elif "pr_url" not in topology:
+        topology.update(_matching_pr_metadata(repo, topology.get("head"), default_remote))
+
+    return {key: value for key, value in topology.items() if value not in (None, "")}
+
+
+def resolve_closeout_push_target(repo: Path, topology: dict[str, Any] | None = None) -> dict[str, Any]:
+    topology = dict(topology or collect_git_topology(repo))
+    if not topology.get("available"):
+        return {"allowed": False, "refusal_reason": "not_a_git_worktree"}
+
+    explicit_target = topology.get("target_push_ref")
+    upstream = topology.get("upstream_ref")
+    remote = _remote_from_upstream(upstream)
+    if explicit_target:
+        push_ref = str(explicit_target)
+        if remote is None:
+            remote = _default_push_remote(repo, topology)
+        if remote is None:
+            return {"allowed": False, "refusal_reason": "missing_push_remote"}
+    elif upstream:
+        remote, branch_ref = _split_upstream_ref(str(upstream))
+        if remote is None or branch_ref is None:
+            return {"allowed": False, "refusal_reason": "ambiguous_upstream_ref"}
+        push_ref = branch_ref
+    else:
+        return {"allowed": False, "refusal_reason": "missing_push_target"}
+
+    if not topology.get("clean", False):
+        return {"allowed": False, "remote": remote, "push_ref": push_ref, "refusal_reason": "post_commit_dirty_worktree"}
+    if int(topology.get("behind_upstream", 0) or 0) > 0:
+        return {"allowed": False, "remote": remote, "push_ref": push_ref, "refusal_reason": "behind_upstream"}
+
+    return {"allowed": True, "remote": remote, "push_ref": push_ref}
+
+
+def _git_available(repo: Path) -> bool:
+    return _git(repo, "rev-parse", "--is-inside-work-tree") == "true"
+
+
+def _branch(repo: Path) -> str:
+    branch = _git(repo, "branch", "--show-current")
+    if branch:
+        return branch
+    head = _git(repo, "rev-parse", "--short", "HEAD")
+    return f"detached@{head}" if head else "unknown"
+
+
+def _existing_ref(repo: Path, ref: str) -> str | None:
+    return ref if _git(repo, "rev-parse", "--verify", "--quiet", ref) else None
+
+
+def _ahead_behind(repo: Path, base_ref: str) -> tuple[int | None, int | None]:
+    counts = _git(repo, "rev-list", "--left-right", "--count", f"{base_ref}...HEAD")
+    if not counts:
+        return None, None
+    parts = counts.split()
+    if len(parts) != 2:
+        return None, None
+    try:
+        behind = int(parts[0])
+        ahead = int(parts[1])
+    except ValueError:
+        return None, None
+    return behind, ahead
+
+
+def _remote_from_upstream(upstream_ref: Any) -> str | None:
+    if not isinstance(upstream_ref, str) or "/" not in upstream_ref:
+        return None
+    return upstream_ref.split("/", 1)[0] or None
+
+
+def _split_upstream_ref(upstream_ref: str) -> tuple[str | None, str | None]:
+    if "/" not in upstream_ref:
+        return None, None
+    remote, branch = upstream_ref.split("/", 1)
+    if not remote or not branch:
+        return None, None
+    return remote, f"refs/heads/{branch}"
+
+
+def _default_push_remote(repo: Path, topology: dict[str, Any]) -> str | None:
+    upstream_remote = _remote_from_upstream(topology.get("upstream_ref"))
+    if upstream_remote:
+        return upstream_remote
+    default_remote = topology.get("default_remote_ref")
+    if isinstance(default_remote, str) and "/" in default_remote:
+        return default_remote.split("/", 1)[0]
+    remotes = _git(repo, "remote")
+    if not remotes:
+        return None
+    names = [line.strip() for line in remotes.splitlines() if line.strip()]
+    if len(names) == 1:
+        return names[0]
+    if "origin" in names:
+        return "origin"
+    return None
+
+
+def _matching_pr_metadata(repo: Path, head: Any, default_remote: str | None) -> dict[str, Any]:
+    if not isinstance(head, str) or not head:
+        return {}
+    default_branch = default_remote.removeprefix("origin/") if default_remote else "main"
+    for ref in _remote_refs_at_head(repo, head):
+        if ref == f"origin/{default_branch}":
+            continue
+        if not ref.startswith("origin/"):
+            continue
+        metadata = _gh_pr_metadata(repo, ref.removeprefix("origin/"))
+        if metadata:
+            metadata["matching_remote_ref"] = ref
+            return metadata
+    return {}
+
+
+def _remote_refs_at_head(repo: Path, head: str) -> list[str]:
+    refs = _git(repo, "for-each-ref", "--format=%(refname:short) %(objectname)", "refs/remotes/origin")
+    if not refs:
+        return []
+    matches: list[str] = []
+    for line in refs.splitlines():
+        parts = line.split()
+        if len(parts) == 2 and parts[1] == head:
+            matches.append(parts[0])
+    return matches
+
+
+def _gh_pr_metadata(repo: Path, branch: str) -> dict[str, Any]:
+    payload = _gh(repo, "pr", "list", "--head", branch, "--state", "open", "--limit", "1", "--json", "number,url,headRefName,baseRefName,reviewDecision,mergeable,isDraft")
+    if not payload:
+        return {}
+    try:
+        import json
+
+        prs = json.loads(payload)
+    except Exception:
+        return {}
+    if not isinstance(prs, list) or not prs:
+        return {}
+    pr = prs[0]
+    if not isinstance(pr, dict):
+        return {}
+    return {
+        "pr_number": pr.get("number"),
+        "pr_url": pr.get("url"),
+        "pr_head_ref": pr.get("headRefName"),
+        "pr_base_ref": pr.get("baseRefName"),
+        "pr_review_decision": pr.get("reviewDecision"),
+        "pr_mergeable": pr.get("mergeable"),
+        "pr_is_draft": pr.get("isDraft"),
+    }
+
+
+def _git(repo: Path, *args: str) -> str | None:
+    try:
+        completed = subprocess.run(
+            ["git", "-C", str(repo), *args],
+            check=False,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            text=True,
+            timeout=5,
+        )
+    except Exception:
+        return None
+    if completed.returncode != 0:
+        return None
+    return completed.stdout.strip() or None
+
+
+def _gh(repo: Path, *args: str) -> str | None:
+    try:
+        completed = subprocess.run(
+            ["gh", *args],
+            cwd=repo,
+            check=False,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            text=True,
+            timeout=5,
+        )
+    except Exception:
+        return None
+    if completed.returncode != 0:
+        return None
+    return completed.stdout.strip() or None

phase_loop_runtime/governed_bundle.py

@@ -0,0 +1,137 @@
+"""Governed pre-merge review bundle (model-routing-v2 P1, IF-0-P1-1).
+
+The artifact the panel reviews at the pre-merge gate is a *review bundle*, not a
+bare diff: the EXACT staged diff the closeout is about to commit, plus the plan's
+``## Acceptance Criteria``, the verification-command results, and a one-paragraph
+closeout summary. The panel needs the change *and* the spec to judge it against.
+
+The gate fires INSIDE ``_perform_phase_closeout`` — after ``git add`` stages the
+owned paths and before the commit is finalized — and passes the staged-index diff
+(``git diff --cached``) in here. So "what the panel reviews" == "what gets
+committed" by construction: no separately-discovered path set to diverge from
+closeout, no untracked-file synthesis, and the renderer never writes a file into
+the repo (advisor-panel reconciliation — the prior independent path discovery and
+in-repo staging were the divergence + worktree-dirtying defects).
+"""
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+
+def staged_index_diff(repo: Path, paths: Sequence[str]) -> str:
+    """The EXACT diff about to be committed: ``git diff --cached -- <paths>``.
+
+    After ``git add``, newly-added files appear natively in the cached diff (no
+    ``--no-index`` synthesis, no untracked probe). This is the staged index, so it
+    cannot diverge from what the commit records.
+    """
+    if not paths:
+        return "(no staged paths)"
+    try:
+        out = subprocess.run(
+            ["git", "-C", str(repo), "diff", "--cached", "--", *paths],
+            capture_output=True, text=True, timeout=30,
+        )
+    except Exception:
+        return "(staged diff unavailable)"
+    return out.stdout.rstrip() or "(empty staged diff)"
+
+
+def _acceptance_criteria(plan_path: str | Path | None) -> str:
+    if not plan_path:
+        return "(no plan path)"
+    try:
+        text = Path(plan_path).read_text(encoding="utf-8")
+    except OSError:
+        return "(plan unreadable)"
+    lines = text.splitlines()
+    out: list[str] = []
+    capture = False
+    for line in lines:
+        if line.lstrip().lower().startswith("## acceptance"):
+            capture = True
+            continue
+        if capture and line.startswith("## "):
+            break
+        if capture:
+            out.append(line)
+    body = "\n".join(out).strip()
+    return body or "(no acceptance-criteria section found)"
+
+
+def _verification_results(terminal: Mapping[str, Any]) -> str:
+    # The terminal summary records per-command verification under
+    # `verification_commands` (list[dict]); `build_terminal_summary` never emits
+    # `verification`/`verification_results`, so the old keys always missed and the
+    # panel saw "no results recorded" even when commands ran (code-review finding,
+    # verified). Accept the real key first; keep the legacy keys as a tolerant
+    # fallback for hand-built terminals in tests.
+    rows = terminal.get("verification_commands") or ()
+    if not rows:
+        results = terminal.get("verification") if isinstance(terminal.get("verification"), Mapping) else None
+        if isinstance(results, Mapping):
+            rows = results.get("results") or results.get("commands") or ()
+        else:
+            rows = terminal.get("verification_results") or ()
+    if not rows:
+        unit = terminal.get("latest_verification_unit")
+        status = (
+            (unit.get("status") if isinstance(unit, Mapping) else None)
+            or terminal.get("verification_status")
+            or "unknown"
+        )
+        return f"verification_status: {status} (no per-command results recorded)"
+    lines = []
+    for r in rows:
+        if isinstance(r, Mapping):
+            lines.append(f"- {r.get('code') or r.get('command') or r}: {r.get('status') or r.get('ok')}")
+        else:
+            lines.append(f"- {r}")
+    return "\n".join(lines)
+
+
+def _summary(terminal: Mapping[str, Any]) -> str:
+    return str(
+        terminal.get("next_action")
+        or terminal.get("terminal_status")
+        or "(no summary)"
+    )
+
+
+def render_governed_bundle(
+    *,
+    phase_alias: str,
+    terminal: Mapping[str, Any],
+    plan_path: str | Path | None,
+    diff_text: str,
+) -> str:
+    """Render the review bundle text from a PRECOMPUTED staged-index diff.
+
+    The caller (the in-closeout gate) computes ``diff_text`` via
+    ``staged_index_diff`` over the exact paths it is committing, so the bundle
+    cannot diverge from the commit. The renderer never touches git or the
+    filesystem; ``panel_invoker`` stages the bundle as material in a temp dir
+    OUTSIDE the repo, so the gate never dirties the worktree under review.
+    """
+    return "\n".join(
+        [
+            f"# Governed pre-merge review — phase {phase_alias}",
+            "",
+            "## Change (staged diff — exactly what will be committed)",
+            "```diff",
+            diff_text,  # producer (staged_index_diff) owns the empty/unavailable sentinel
+            "```",
+            "",
+            "## Acceptance Criteria (the spec to judge against)",
+            _acceptance_criteria(plan_path),
+            "",
+            "## Verification results",
+            _verification_results(terminal),
+            "",
+            "## Summary",
+            _summary(terminal),
+            "",
+        ]
+    )

phase_loop_runtime/governed_premerge.py

@@ -0,0 +1,219 @@
+"""Implementation escalation ladder + governed pre-merge review loop
+(model-routing-v1 P3).
+
+Two behaviors, both **mode-branched** and **non-human terminal**:
+
+1. ``next_escalation`` — the failure ladder. On repeated failure the model_class
+   escalates ``implementer → planner``; a still-failing planner then forks by
+   run_mode: ``governed`` invokes the panel, ``autonomous`` terminates as a
+   **repairable non-human blocker** (``repeated_verification_failure``, never
+   ``human_required``).
+
+2. ``run_governed_premerge_loop`` — the bounded pre-merge gate. In ``governed``
+   mode it runs panel review → fix → re-review, capped at ``max_rounds`` (default
+   3). Zero ``block`` findings ⇒ mergeable (``nit`` findings recorded, non-gating).
+   Non-convergence — or losing the panel while still failing — terminates as a
+   non-human ``review_gate_block`` + halt, surfaced in the run-end summary. In
+   ``autonomous`` mode the loop does NOT run and never spawns a panel.
+
+These are pure, runner-importable functions with a mockable panel seam; nothing
+here adds ``human_required`` and the autonomous path is a literal no-op.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Sequence
+
+from .closeout_validators import ReviewFinding
+from .governed_review import GateResult, governed_planning_gate
+from .panel_invoker import invoke_panel
+
+#: A class is escalated once it has failed this many times (tests or patch retries).
+ESCALATION_FAIL_THRESHOLD = 2
+#: Default cap on governed pre-merge review→fix rounds (bounded; never infinite).
+DEFAULT_MAX_REVIEW_ROUNDS = 3
+
+# implementer → planner is the only model_class escalation; planner is terminal.
+_NEXT_CLASS = {"implementer": "planner", "worker": "implementer"}
+
+
+def _non_human_blocker(blocker_class: str, summary: str) -> dict:
+    """Every terminal in this module is a repairable, non-human blocker."""
+    return {
+        "human_required": False,
+        "blocker_class": blocker_class,
+        "blocker_summary": summary,
+        "required_human_inputs": (),
+    }
+
+
+@dataclass(frozen=True)
+class EscalationDecision:
+    action: str          # "retry" | "escalate_class" | "invoke_panel" | "terminal_blocker"
+    model_class: str     # the class to use for the next attempt
+    run_mode: str
+    reason: str
+    blocker: dict | None = None   # set iff action == "terminal_blocker" (non-human)
+
+
+def next_escalation(
+    *,
+    model_class: str,
+    failed_tests: int = 0,
+    patch_retries: int = 0,
+    run_mode: str = "autonomous",
+) -> EscalationDecision:
+    """The mode-branched failure ladder.
+
+    Below threshold → ``retry`` (same class). At/over threshold:
+    ``implementer → planner`` (escalate_class); a failing ``planner`` forks by
+    run_mode — ``governed`` ⇒ ``invoke_panel``, ``autonomous`` ⇒ non-human
+    ``terminal_blocker``.
+    """
+    failing = failed_tests >= ESCALATION_FAIL_THRESHOLD or patch_retries >= ESCALATION_FAIL_THRESHOLD
+    if not failing:
+        return EscalationDecision(
+            action="retry", model_class=model_class, run_mode=run_mode,
+            reason="below escalation threshold",
+        )
+    nxt = _NEXT_CLASS.get(model_class)
+    if nxt is not None:
+        return EscalationDecision(
+            action="escalate_class", model_class=nxt, run_mode=run_mode,
+            reason=f"{model_class} failed threshold → escalate to {nxt}",
+        )
+    # planner (terminal class) still failing → branch by mode.
+    if run_mode == "governed":
+        return EscalationDecision(
+            action="invoke_panel", model_class=model_class, run_mode=run_mode,
+            reason="planner tier failing in governed mode → invoke advisor panel",
+        )
+    return EscalationDecision(
+        action="terminal_blocker", model_class=model_class, run_mode=run_mode,
+        reason="planner tier failing in autonomous mode → non-human terminal",
+        blocker=_non_human_blocker(
+            "repeated_verification_failure",
+            "implementer→planner escalation exhausted; autonomous run halts as a "
+            "repairable non-human blocker (no panel, no human_required)",
+        ),
+    )
+
+
+@dataclass(frozen=True)
+class LoopResult:
+    mergeable: bool
+    ran: bool
+    rounds: int = 0
+    findings: tuple[ReviewFinding, ...] = ()
+    degraded: bool = False
+    terminal_blocker: dict | None = None
+    reason: str | None = None
+
+
+def run_governed_premerge_loop(
+    *,
+    artifact: str,
+    author_executor: str,
+    run_mode: str,
+    author_vendors: Sequence[str] | None = None,
+    apply_fix: Callable[[int, str, tuple[ReviewFinding, ...]], str] | None = None,
+    available_legs: Sequence[str] | None = None,
+    invoke: Callable[..., GateResult] = governed_planning_gate,
+    spawn=None,
+    repo_dir=None,
+    max_rounds: int = DEFAULT_MAX_REVIEW_ROUNDS,
+    max_concurrency: int | None = None,
+) -> LoopResult:
+    """Bounded governed pre-merge review loop.
+
+    Autonomous mode is a no-op (mergeable, no panel). Governed mode reviews up to
+    ``max_rounds`` times, applying ``apply_fix`` between rounds while ``block``
+    findings remain. Terminals are always non-human. ``author_vendors`` (the set
+    of vendors that authored the phase) takes precedence over ``author_executor``
+    for reviewer≠author exclusion when provided.
+    """
+    if run_mode != "governed":
+        return LoopResult(mergeable=True, ran=False, reason="autonomous")
+
+    # Reasons that mean "the gate could not run a real review" (no disjoint
+    # reviewer / unknown author / no usable verdict) — surfaced verbatim in the
+    # terminal so the operator sees the ACCURATE cause, not a generic
+    # "non_convergence" (CR finding).
+    _STRUCTURAL_HOLD = frozenset({
+        "unknown_author", "no_disjoint_reviewer", "author_vendor_only",
+        "no_reviewers", "no_usable_review",
+    })
+    seen_block = False
+    current = artifact
+    collected: list[ReviewFinding] = []
+    rnd = 0
+    last_reason: str | None = None
+    for rnd in range(1, max_rounds + 1):
+        invoke_kwargs = {
+            "artifact": current,
+            "author_executor": author_executor,
+            "author_vendors": author_vendors,
+            "run_mode": "governed",
+            "available_legs": available_legs,
+            "spawn": spawn,
+        }
+        if repo_dir is not None:
+            invoke_kwargs["repo_dir"] = repo_dir
+        # Parallel by default; threaded only when a caller requests a cap/sequential
+        # (byte-neutral for the default path + a strict-signature custom ``invoke``).
+        if max_concurrency is not None:
+            invoke_kwargs["max_concurrency"] = max_concurrency
+        gate = invoke(**invoke_kwargs)
+        collected.extend(gate.findings)
+        last_reason = gate.reason
+
+        if gate.degraded:
+            # FAIL-CLOSED (advisor-panel reconciliation): in governed mode, "no
+            # usable disjoint reviewer" is NOT an advisory pass — the prior
+            # advisory-pass-before-any-block was a fail-open (a codex-empty phase
+            # whose only disjoint reviewer was offline both rendered an empty diff
+            # AND advisory-passed). The gate now blocks on no-usable-review
+            # directly (promoted=False), so reaching here means a degraded result
+            # we treat as a non-human halt regardless of `seen_block`.
+            return LoopResult(
+                mergeable=False, ran=True, rounds=rnd, findings=tuple(collected),
+                terminal_blocker=_non_human_blocker(
+                    "review_gate_block",
+                    f"governed pre-merge review could not obtain a usable disjoint "
+                    f"reviewer after {rnd} round(s); halting (non-human)",
+                ),
+                reason=gate.reason or "panel_unavailable",
+            )
+
+        if gate.promoted:  # zero block findings; any nits already in `collected`
+            return LoopResult(
+                mergeable=True, ran=True, rounds=rnd, findings=tuple(collected),
+            )
+
+        # Unresolved block findings this round.
+        seen_block = True
+        if apply_fix is None or rnd == max_rounds:
+            break
+        current = apply_fix(rnd, current, gate.findings)
+
+    # Fell out of the loop while held. Distinguish a fail-closed STRUCTURAL hold
+    # (no disjoint reviewer / unknown author / no usable verdict — the review never
+    # really ran) from genuine NON-CONVERGENCE (real block findings unresolved), so
+    # the terminal carries the accurate cause instead of always "non_convergence".
+    if last_reason in _STRUCTURAL_HOLD:
+        summary = (
+            f"governed pre-merge review held ({last_reason}) — no real review could "
+            f"run after {rnd} round(s); halting (non-human, surfaced in run-end summary)"
+        )
+        reason = last_reason
+    else:
+        summary = (
+            f"governed pre-merge review did not converge to zero block findings "
+            f"after {rnd} round(s); halting (non-human, surfaced in run-end summary)"
+        )
+        reason = "non_convergence"
+    return LoopResult(
+        mergeable=False, ran=True, rounds=rnd, findings=tuple(collected),
+        terminal_blocker=_non_human_blocker("review_gate_block", summary),
+        reason=reason,
+    )