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

phase_loop_runtime/closeout_classifier.py

@@ -0,0 +1,120 @@
+"""GATE (roadmap v40) — sensitivity classifier for beyond-ownership dirty paths.
+
+`classify_unowned_path(repo_relpath)` maps a repo-relative path to a
+``SensitivityVerdict`` whose ``sensitivity_class`` is a member of
+``models.SENSITIVITY_CLASSES``. The graduated closeout gate auto-commits a
+verified beyond-ownership path only when its verdict is ``safe``; everything else
+blocks (deny-by-default).
+
+Precedence is load-bearing and deny-by-default:
+  1. UNSAFE-specific patterns first — secrets, lockfiles, CI config. These must win
+     over any broad SAFE rule (e.g. a ``.github/workflows/*.yml`` is CI, not docs).
+  2. tests → ``source`` (UNSAFE). Test paths only ever earn owned status via
+     structural sibling matching upstream; a test reaching this classifier failed
+     that and must not auto-commit.
+  3. narrow SAFE rules — plans, handoffs, docs, and a *tight* config_nonsource
+     allowlist (never a ``.toml``/``.yaml``/``.json`` suffix rule).
+  4. fall through → ``source`` (UNSAFE). Unmatched is never SAFE.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+
+from .models import SAFE_SENSITIVITY_CLASSES
+
+
+@dataclass(frozen=True)
+class SensitivityVerdict:
+    sensitivity_class: str
+    safe: bool
+
+
+# Tight allowlists — membership, not broad suffix rules.
+_CONFIG_NONSOURCE_NAMES = frozenset(
+    {".gitignore", ".gitattributes", ".editorconfig", ".dockerignore", ".npmrc", ".prettierrc"}
+)
+_CONFIG_NONSOURCE_SUFFIXES = frozenset({".cfg", ".ini"})
+
+_SECRET_SUFFIXES = frozenset({".pem", ".key", ".p12", ".pfx", ".crt", ".keystore", ".jks"})
+_LOCKFILE_NAMES = frozenset(
+    {
+        "package-lock.json",
+        "pnpm-lock.yaml",
+        "yarn.lock",
+        "uv.lock",
+        "poetry.lock",
+        "cargo.lock",
+        "go.sum",
+        "gemfile.lock",
+        "composer.lock",
+        "requirements.txt",
+    }
+)
+# Bare suffix → docs only for unambiguous documentation formats. A `.txt` is NOT
+# auto-docs (e.g. src/foo.txt is source-adjacent); it is docs only under docs/.
+_DOC_SUFFIXES = frozenset({".md", ".rst"})
+
+
+def _verdict(sensitivity_class: str) -> SensitivityVerdict:
+    return SensitivityVerdict(
+        sensitivity_class=sensitivity_class,
+        safe=sensitivity_class in SAFE_SENSITIVITY_CLASSES,
+    )
+
+
+def classify_unowned_path(repo_relpath: str) -> SensitivityVerdict:
+    raw = (repo_relpath or "").strip()
+    # Normalize: strip leading "./", lowercase for matching.
+    norm = raw[2:] if raw.startswith("./") else raw
+    lower = norm.lower()
+    posix = PurePosixPath(lower)
+    name = posix.name
+    suffix = posix.suffix
+    parts = posix.parts
+    slashed = "/" + lower  # so "/tests/" infix matches a leading "tests/" too
+
+    # --- 1. UNSAFE-specific patterns first (precedence) ---
+    # secrets
+    if (
+        name == ".env"
+        or name.startswith(".env.")
+        or suffix in _SECRET_SUFFIXES
+        or "secrets" in parts
+    ):
+        return _verdict("secrets")
+    # lockfiles
+    if name in _LOCKFILE_NAMES or name.endswith(".lock") or name.endswith("-lock.json"):
+        return _verdict("lockfile")
+    # CI config
+    if (
+        any(part in {".github", ".gitlab", ".circleci", ".gitea"} for part in parts)
+        or lower.startswith("ci/")
+        or "/workflows/" in slashed
+    ):
+        return _verdict("ci")
+    # tests → source (UNSAFE) — GATE decision (see plan/IF-0-GATE-1)
+    if (
+        "/tests/" in slashed
+        or "__tests__" in parts
+        or "__fixtures__" in parts
+        or name.startswith("test_")
+        or name.endswith("_test.py")
+        or ".test." in name
+        or ".spec." in name
+    ):
+        return _verdict("source")
+
+    # --- 2. narrow SAFE rules ---
+    if lower.startswith("plans/"):
+        return _verdict("plans")
+    if ".dev-skills/handoffs/" in slashed:
+        return _verdict("handoffs")
+    if "/docs/" in slashed or name == "readme.md" or suffix in _DOC_SUFFIXES:
+        return _verdict("docs")
+    if name in _CONFIG_NONSOURCE_NAMES or suffix in _CONFIG_NONSOURCE_SUFFIXES:
+        return _verdict("config_nonsource")
+
+    # --- 3. deny-by-default: everything else (incl. .py/.toml/.yaml/.json/.sh) ---
+    return _verdict("source")

phase_loop_runtime/closeout_evidence_audit.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import re
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+
+
+AUDIT_STATUSES = ("passed", "drift_detected", "skipped")
+MAX_CLAIMS = 32
+MAX_DIFF_PATHS = 64
+
+CLAIM_RE = re.compile(r"\b(?:Added|Created|Wrote|Updated)\s+`([^`]+)`", re.IGNORECASE)
+BULLET_CLAIM_RE = re.compile(r"^\s*[-*]\s+[A-Za-z][A-Za-z0-9_-]*\s+`([^`]+)`", re.MULTILINE)
+IDENTIFIER_RE = re.compile(r"\b[A-Za-z_][A-Za-z0-9_]*\b")
+
+
+@dataclass(frozen=True)
+class AuditResult:
+    matched_claims: list[str]
+    unmatched_claims: list[str]
+    audit_status: str
+
+
+def audit_closeout_evidence(commit_sha: str, phase_alias: str, repo_root: Path) -> AuditResult:
+    commit_body = _git_output(repo_root, "log", "-1", "--format=%B", commit_sha)
+    claims = _parse_claims(commit_body)
+    if not claims:
+        return AuditResult(matched_claims=[], unmatched_claims=[], audit_status="skipped")
+
+    diff_paths = _diff_paths(repo_root, commit_sha)
+    diff_body = _git_output(repo_root, "show", "--format=", "--unified=0", commit_sha)
+    matched: list[str] = []
+    unmatched: list[str] = []
+    for claim in claims:
+        if _claim_matches_evidence(claim, diff_paths, diff_body):
+            matched.append(claim)
+        else:
+            unmatched.append(claim)
+
+    return AuditResult(
+        matched_claims=matched,
+        unmatched_claims=unmatched,
+        audit_status="drift_detected" if unmatched else "passed",
+    )
+
+
+def _parse_claims(text: str) -> list[str]:
+    claims: list[str] = []
+    for pattern in (CLAIM_RE, BULLET_CLAIM_RE):
+        for match in pattern.finditer(text):
+            claim = match.group(1).strip()
+            if claim and claim not in claims:
+                claims.append(claim)
+            if len(claims) >= MAX_CLAIMS:
+                return claims
+    return claims
+
+
+def _diff_paths(repo_root: Path, commit_sha: str) -> list[str]:
+    names = _git_output(repo_root, "show", "--format=", "--name-only", commit_sha)
+    paths: list[str] = []
+    for line in names.splitlines():
+        path = line.strip()
+        if not path or path in paths:
+            continue
+        paths.append(path)
+        if len(paths) >= MAX_DIFF_PATHS:
+            break
+    return paths
+
+
+def _claim_matches_evidence(claim: str, diff_paths: list[str], diff_body: str) -> bool:
+    normalized = claim.strip().lstrip("/")
+    if not normalized:
+        return False
+    normalized_posix = normalized.replace("\\", "/")
+    claim_path = PurePosixPath(normalized_posix)
+    claim_basename = claim_path.name
+    claim_stem = claim_path.stem
+    for path in diff_paths:
+        path_posix = path.replace("\\", "/")
+        path_path = PurePosixPath(path_posix)
+        if path_posix.endswith(normalized_posix) or path_posix.endswith(f"/{normalized_posix}"):
+            return True
+        if claim_basename and claim_basename == path_path.name:
+            return True
+        if claim_stem and claim_stem == path_path.stem:
+            return True
+    return any(identifier in diff_body for identifier in _identifier_candidates(claim))
+
+
+def _identifier_candidates(claim: str) -> list[str]:
+    candidates: list[str] = []
+    for token in IDENTIFIER_RE.findall(claim):
+        if len(token) < 4:
+            continue
+        if not any(char.isupper() for char in token) and "_" not in token:
+            continue
+        if token not in candidates:
+            candidates.append(token)
+    return candidates
+
+
+def _git_output(repo_root: Path, *args: str) -> str:
+    result = subprocess.run(
+        ["git", "-C", str(repo_root), *args],
+        text=True,
+        capture_output=True,
+        check=True,
+    )
+    return result.stdout

phase_loop_runtime/closeout_validation.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping
+
+
+IF_GATE_RE = re.compile(r"\bIF-\d+-[A-Z0-9_-]+-\d+\b")
+
+
+@dataclass(frozen=True)
+class ValidationResult:
+    ok: bool
+    warning: str | None = None
+    blocker_class: str | None = None
+    blocker_summary: str | None = None
+    expected_gates: tuple[str, ...] = ()
+    produced_gates: tuple[str, ...] = ()
+    missing_gates: tuple[str, ...] = ()
+    unexpected_gates: tuple[str, ...] = ()
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "ok": self.ok,
+            "warning": self.warning,
+            "blocker_class": self.blocker_class,
+            "blocker_summary": self.blocker_summary,
+            "expected_gates": list(self.expected_gates),
+            "produced_gates": list(self.produced_gates),
+            "missing_gates": list(self.missing_gates),
+            "unexpected_gates": list(self.unexpected_gates),
+        }
+
+
+def extract_plan_produces(plan_path: Path) -> tuple[str, ...]:
+    try:
+        text = plan_path.read_text(encoding="utf-8")
+    except OSError:
+        return ()
+
+    gates: list[str] = []
+    for line in text.splitlines():
+        stripped = line.strip()
+        if not (
+            stripped.startswith("**Produces**:")
+            or stripped.startswith("Produces:")
+            or "**Interfaces provided**:" in stripped
+        ):
+            continue
+        for match in IF_GATE_RE.finditer(line):
+            gate = match.group(0)
+            if gate not in gates:
+                gates.append(gate)
+    return tuple(gates)
+
+
+def validate_produced_gates(plan_path: Path, closeout_payload: dict[str, Any]) -> ValidationResult:
+    terminal_status = str(
+        closeout_payload.get("terminal_status")
+        or closeout_payload.get("automation_status")
+        or ""
+    )
+    expected = extract_plan_produces(plan_path)
+    if "produced_if_gates" not in closeout_payload:
+        if terminal_status == "complete":
+            return ValidationResult(
+                ok=True,
+                warning="produced_if_gates missing during NATIVE compatibility window",
+                expected_gates=expected,
+            )
+        return ValidationResult(ok=True, expected_gates=expected)
+
+    produced_raw = _normalize_gates(closeout_payload.get("produced_if_gates"))
+    # Filter to canonical IF-gate tokens. Executors sometimes emit free-text
+    # description sentences in produced_if_gates (e.g. when the plan declares
+    # no IF gate, codex has been observed outputting
+    # ["...verified...; active plan declares no interface-freeze gate"]).
+    # Treat non-IF-token entries as commentary, not as produced gates.
+    produced = tuple(g for g in produced_raw if IF_GATE_RE.fullmatch(g))
+    non_gate_chatter = tuple(g for g in produced_raw if not IF_GATE_RE.fullmatch(g))
+    missing = tuple(gate for gate in expected if gate not in produced)
+    unexpected = tuple(gate for gate in produced if gate not in expected)
+
+    # If the plan declares no IF gates, the phase is internal/tooling and
+    # cannot fail the contract check. Allow with a warning if the executor
+    # emitted any chatter.
+    if not expected:
+        warning = None
+        if non_gate_chatter:
+            warning = (
+                "executor produced non-IF-gate strings in produced_if_gates "
+                "for a plan that declares no IF gates; treated as commentary"
+            )
+        return ValidationResult(
+            ok=True,
+            warning=warning,
+            expected_gates=expected,
+            produced_gates=produced,
+            missing_gates=missing,
+            unexpected_gates=unexpected,
+        )
+
+    if terminal_status == "complete" and (not produced or missing or unexpected):
+        summary = "completed closeout produced_if_gates did not match the active phase plan"
+        if not produced:
+            summary = "completed closeout reported zero produced_if_gates"
+        return ValidationResult(
+            ok=False,
+            blocker_class="contract_bug",
+            blocker_summary=summary,
+            expected_gates=expected,
+            produced_gates=produced,
+            missing_gates=missing,
+            unexpected_gates=unexpected,
+        )
+
+    return ValidationResult(
+        ok=True,
+        expected_gates=expected,
+        produced_gates=produced,
+        missing_gates=missing,
+        unexpected_gates=unexpected,
+    )
+
+
+def verification_enforcement_mode(env: Mapping[str, str] | None = None) -> str:
+    value = str((env or {}).get("PHASE_LOOP_VERIFY_ENFORCE") or "").strip().lower()
+    return "warn" if value == "warn" else "hard"
+
+
+def _normalize_gates(value: Any) -> tuple[str, ...]:
+    if isinstance(value, str):
+        raw_items = re.split(r"[,\s]+", value)
+    elif isinstance(value, (list, tuple, set)):
+        raw_items = [str(item) for item in value]
+    else:
+        raw_items = []
+    gates: list[str] = []
+    for item in raw_items:
+        gate = item.strip().strip("'\"")
+        if gate and gate not in gates:
+            gates.append(gate)
+    return tuple(gates)

phase_loop_runtime/closeout_validators.py

@@ -0,0 +1,203 @@
+"""Pluggable closeout-validator hook (rigor-v1 P1).
+
+The single seam through which review gates (doc-delta, verification-evidence,
+visual-evidence, …) plug into the closeout pass/fail decision **without** each
+gate editing ``closeout.py``'s status logic. ``build_phase_loop_closeout`` runs
+the registered validators once and applies their findings.
+
+Autonomy-first severity model (see ``specs/phase-plans-v1.md`` and the
+``[[phase-loop-autonomy-first-guardrails]]`` constraint):
+
+* Each finding carries a severity of ``warn`` or ``block``.
+* The global ``PHASE_LOOP_REVIEW`` control (``off`` | ``warn`` | ``block``,
+  **default ``warn``**) sets the effective behavior:
+    - ``off``   — validators do not run; no findings.
+    - ``warn``  — validators run; every finding is forced to ``warn`` (recorded
+      to the closeout for later human spot-check, the loop **continues**).
+    - ``block`` — validators run; a ``block`` finding refuses ``complete``.
+* **No validator may set ``human_required``.** A blocking finding produces a
+  non-human, agent-recoverable blocker — never a stall waiting on a person.
+
+Back-compat: with zero validators registered (the state shipped by P1), the
+runner returns no findings and closeout behavior is byte-for-byte unchanged.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field, replace
+from typing import Any, Callable, Iterable, Mapping
+
+ReviewSeverity = str  # "warn" | "block"
+REVIEW_SEVERITIES: tuple[str, ...] = ("warn", "block")
+REVIEW_MODES: tuple[str, ...] = ("off", "warn", "block")
+DEFAULT_REVIEW_MODE = "warn"
+REVIEW_MODE_ENV = "PHASE_LOOP_REVIEW"
+
+
+@dataclass(frozen=True)
+class ReviewFinding:
+    """A single review-gate observation about a closeout."""
+
+    code: str
+    reason: str
+    severity: ReviewSeverity = "warn"
+    blocker_class: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.severity not in REVIEW_SEVERITIES:
+            raise ValueError(f"invalid review severity: {self.severity!r}")
+
+    def to_json(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "kind": "review_finding",
+            "code": self.code,
+            "reason": self.reason,
+            "severity": self.severity,
+        }
+        if self.blocker_class is not None:
+            payload["blocker_class"] = self.blocker_class
+        return payload
+
+
+@dataclass(frozen=True)
+class CloseoutContext:
+    """Read-only view of the closeout a validator inspects."""
+
+    phase_alias: str
+    plan_path: str
+    terminal: Mapping[str, Any] = field(default_factory=dict)
+    automation: Mapping[str, Any] = field(default_factory=dict)
+    blocker: Mapping[str, Any] = field(default_factory=dict)
+    changed_paths: tuple[str, ...] = ()
+    # model-routing-v1 P2: the run_mode axis (autonomous default | governed).
+    # Carried so a validator can tell which mode it is in; governed-only review
+    # machinery lives in `governed_review`, never in this closeout registry.
+    run_mode: str = "autonomous"
+    # issue #18 F5: the runner-side docs-freshness pre-scan result (or None when
+    # unwired). Threaded read-only so a validator can CORROBORATE a self-attested
+    # decision (e.g. `no_doc_delta`) against the path-keyed scan evidence without
+    # doing repo IO itself (validators stay pure). None => no corroboration
+    # available => the validator must not newly-fail on its absence.
+    docs_freshness: Mapping[str, Any] | None = None
+
+
+# A validator receives the context and returns zero or more findings.
+CloseoutValidator = Callable[[CloseoutContext], Iterable[ReviewFinding]]
+
+_VALIDATORS: list[CloseoutValidator] = []
+
+
+def register_closeout_validator(fn: CloseoutValidator) -> CloseoutValidator:
+    """Register a closeout validator. Returns ``fn`` so it can be used as a decorator."""
+    if fn not in _VALIDATORS:
+        _VALIDATORS.append(fn)
+    return fn
+
+
+def clear_closeout_validators() -> None:
+    """Drop all registered validators (test hook)."""
+    _VALIDATORS.clear()
+
+
+def registered_closeout_validators() -> tuple[CloseoutValidator, ...]:
+    return tuple(_VALIDATORS)
+
+
+def resolve_review_mode(env: Mapping[str, str] | None = None) -> str:
+    env = os.environ if env is None else env
+    value = str(env.get(REVIEW_MODE_ENV) or "").strip().lower()
+    return value if value in REVIEW_MODES else DEFAULT_REVIEW_MODE
+
+
+def run_closeout_validators(
+    ctx: CloseoutContext,
+    env: Mapping[str, str] | None = None,
+) -> list[ReviewFinding]:
+    """Run every registered validator and return findings at their effective severity.
+
+    A validator that raises is skipped — a review gate must never break closeout.
+    """
+    mode = resolve_review_mode(env)
+    if mode == "off":
+        return []
+    findings: list[ReviewFinding] = []
+    for fn in tuple(_VALIDATORS):
+        try:
+            produced = fn(ctx) or ()
+        except Exception:
+            continue
+        for finding in produced:
+            effective = "warn" if mode == "warn" else finding.severity
+            findings.append(replace(finding, severity=effective))
+    return findings
+
+
+def apply_review_findings(
+    *,
+    findings: list[ReviewFinding],
+    terminal: dict[str, Any],
+    automation: dict[str, Any],
+    blocker: dict[str, Any],
+) -> dict[str, Any]:
+    """Fold findings into the closeout dicts.
+
+    ``warn`` findings are recorded as results (audit trail) and do not change
+    the outcome. The first ``block`` finding turns the closeout into a
+    non-human ``blocked`` outcome, mirroring the verification-evidence gate.
+    """
+    updated_terminal = dict(terminal)
+    updated_automation = dict(automation)
+    updated_blocker = dict(blocker)
+    results = [f.to_json() for f in findings]
+
+    blocking = next((f for f in findings if f.severity == "block"), None)
+    if blocking is not None:
+        blocker_class = blocking.blocker_class or "review_gate_block"
+        summary = f"Review gate blocked closeout: {blocking.code} — {blocking.reason}"
+        updated_terminal["terminal_status"] = "blocked"
+        updated_terminal["verification_status"] = "blocked"
+        updated_automation["status"] = "blocked"
+        updated_automation["verification_status"] = "blocked"
+        updated_automation["blocker_class"] = blocker_class
+        updated_automation["blocker_summary"] = summary
+        updated_automation["human_required"] = False
+        updated_blocker.update(
+            {
+                "human_required": False,
+                "blocker_class": blocker_class,
+                "blocker_summary": summary,
+                "required_human_inputs": (),
+            }
+        )
+    return {
+        "terminal": updated_terminal,
+        "automation": updated_automation,
+        "blocker": updated_blocker,
+        "results": results,
+    }
+
+
+def load_builtin_closeout_validators() -> None:
+    """Import the built-in validator modules so they self-register.
+
+    Extension point: each downstream rigor phase adds its validator module
+    (e.g. ``doc_delta_validator``) and one guarded import line here. Imports are
+    guarded so an incremental checkout missing a module never breaks closeout.
+    P1 ships no built-in validators — the registry is empty by default.
+    """
+    try:
+        from . import doc_delta_validator  # noqa: F401  (P2)
+    except Exception:
+        pass
+    try:
+        from . import verification_evidence_validator  # noqa: F401  (P5)
+    except Exception:
+        pass
+    try:
+        from . import visual_evidence_validator  # noqa: F401  (P6)
+    except Exception:
+        pass
+    return None
+
+
+load_builtin_closeout_validators()