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

phase_loop_runtime/dispatch_lock.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from .runtime_paths import ensure_phase_loop_excluded, phase_loop_dir
+from .runtime_paths import _path_slug
+
+# Platform-conditional locking primitives (issue #16).
+# POSIX uses fcntl.flock; Windows uses msvcrt.locking on a 1-byte region at
+# the file's current seek position. Both surface non-blocking exclusive lock
+# acquisition + release through the same _acquire_exclusive / _release_exclusive
+# helpers so the rest of this module stays platform-agnostic.
+if sys.platform == "win32":
+    import msvcrt
+
+    _LOCK_REGION_BYTES = 1
+
+    def _acquire_exclusive(handle) -> None:
+        # msvcrt.locking locks a region of length _LOCK_REGION_BYTES starting
+        # at the file's current seek position. Seek to start so concurrent
+        # holders contend on the same byte. LK_NBLCK = non-blocking exclusive.
+        # Raises OSError (subclass of BlockingIOError on Py3.10+? actually
+        # raises OSError with errno EACCES) when contended; normalize to
+        # BlockingIOError to match POSIX flock semantics.
+        handle.seek(0)
+        try:
+            msvcrt.locking(handle.fileno(), msvcrt.LK_NBLCK, _LOCK_REGION_BYTES)
+        except OSError as exc:
+            raise BlockingIOError(str(exc)) from exc
+
+    def _release_exclusive(handle) -> None:
+        handle.seek(0)
+        try:
+            msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, _LOCK_REGION_BYTES)
+        except OSError:
+            # Already released or process is exiting — let cleanup proceed.
+            pass
+
+else:
+    import fcntl
+
+    def _acquire_exclusive(handle) -> None:
+        fcntl.flock(handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+
+    def _release_exclusive(handle) -> None:
+        fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+
+
+@dataclass(frozen=True)
+class DispatchLockContention(RuntimeError):
+    lock_path: Path
+    holder_pid: int | None
+    holder_started_at: float | None
+    roadmap: str | None
+
+    @property
+    def elapsed_seconds(self) -> int | None:
+        if self.holder_started_at is None:
+            return None
+        return max(0, int(time.time() - self.holder_started_at))
+
+    def blocker_summary(self, roadmap: Path) -> str:
+        pid = self.holder_pid if self.holder_pid is not None else "unknown"
+        elapsed = self.elapsed_seconds
+        elapsed_text = f"{elapsed}s" if elapsed is not None else "unknown seconds"
+        holder_roadmap = self.roadmap or str(roadmap)
+        return (
+            "Concurrent dispatch refused: roadmap "
+            f"{holder_roadmap} is locked by PID {pid} for {elapsed_text} "
+            f"(lock: {self.lock_path})."
+        )
+
+
+class DispatchLock:
+    def __init__(self, repo: Path, roadmap: Path) -> None:
+        self.repo = repo
+        self.roadmap = roadmap
+        self.path = dispatch_lock_path(repo, roadmap)
+        self._handle = None
+
+    def acquire(self) -> "DispatchLock":
+        ensure_phase_loop_excluded(self.repo)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        handle = self.path.open("a+", encoding="utf-8")
+        try:
+            _acquire_exclusive(handle)
+        except BlockingIOError as exc:
+            holder = _read_holder_metadata(handle)
+            handle.close()
+            raise DispatchLockContention(
+                lock_path=self.path,
+                holder_pid=_int_or_none(holder.get("pid")),
+                holder_started_at=_float_or_none(holder.get("started_at")),
+                roadmap=str(holder.get("roadmap") or "") or None,
+            ) from exc
+
+        handle.seek(0)
+        handle.truncate()
+        json.dump(
+            {
+                "pid": os.getpid(),
+                "started_at": time.time(),
+                "repo": str(self.repo),
+                "roadmap": str(self.roadmap),
+            },
+            handle,
+            sort_keys=True,
+        )
+        handle.write("\n")
+        handle.flush()
+        os.fsync(handle.fileno())
+        self._handle = handle
+        return self
+
+    def release(self) -> None:
+        if self._handle is None:
+            return
+        try:
+            _release_exclusive(self._handle)
+        finally:
+            self._handle.close()
+            self._handle = None
+
+    def __enter__(self) -> "DispatchLock":
+        if self._handle is not None:
+            return self
+        return self.acquire()
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.release()
+
+
+def dispatch_lock_path(repo: Path, roadmap: Path) -> Path:
+    try:
+        roadmap_key = str(roadmap.resolve().relative_to(repo.resolve()))
+    except ValueError:
+        roadmap_key = str(roadmap.resolve())
+    return phase_loop_dir(repo) / _path_slug(roadmap_key) / "dispatch.lock"
+
+
+def _read_holder_metadata(handle) -> dict[str, object]:
+    try:
+        handle.seek(0)
+        raw = handle.read().strip()
+        payload = json.loads(raw) if raw else {}
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return payload if isinstance(payload, dict) else {}
+
+
+def _int_or_none(value: object) -> int | None:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _float_or_none(value: object) -> float | None:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None

phase_loop_runtime/doc_delta_validator.py

@@ -0,0 +1,98 @@
+"""Doc-delta closeout validator (rigor-v1 P2).
+
+When a phase's diff touches a user-visible public surface but the closeout
+records no doc-delta decision, raise a finding. Autonomy-first: the finding is
+``block``-severity, so under the default ``PHASE_LOOP_REVIEW=warn`` it is merely
+recorded (the loop continues) and only blocks when an operator opts in. The
+agent self-satisfies it by updating docs or recording a ``no_doc_delta``
+decision in the terminal summary — no human required.
+
+The executor records its decision as ``doc_delta_decision: <literal>`` in the
+terminal summary (one of ``models.DOC_DELTA_DECISIONS``).
+
+issue #18 F5 — evidence-backed corroboration. A bare ``no_doc_delta`` is a
+*self-attested literal*: the executor claims "the public surface is already
+current, no docs change needed". On a **release/explicit-release** phase that
+claim is exactly the one the docs-freshness incident proved unreliable. When a
+runner-side freshness scan was threaded in (``ctx.docs_freshness``), we
+corroborate the ``no_doc_delta`` against its enumerated-surface evidence: an
+un-corroborated ``no_doc_delta`` on a release phase is downgraded to a recorded
+**warn** finding (never a block — autonomy-first), surfacing the scan result
+alongside. Ordinary phases, and any phase with no scan threaded in, are
+unaffected (the literal still satisfies, as before).
+"""
+from __future__ import annotations
+
+from .closeout_validators import CloseoutContext, ReviewFinding, register_closeout_validator
+from .docs_freshness import docs_freshness_evidence_backed
+from .models import DOC_DELTA_DECISIONS, public_surface_touched
+
+
+@register_closeout_validator
+def doc_delta_validator(ctx: CloseoutContext) -> list[ReviewFinding]:
+    if not public_surface_touched(ctx.changed_paths):
+        return []
+    decision = str(ctx.terminal.get("doc_delta_decision") or "").strip()
+    if decision in DOC_DELTA_DECISIONS:
+        return _corroborate_no_doc_delta(ctx, decision)  # may be [] or a warn
+    return [
+        ReviewFinding(
+            code="doc_delta_undecided",
+            reason=(
+                "changed a public surface (CLI/schema/contract docs/README/CHANGELOG) "
+                "but recorded no doc_delta decision; update the doc surface or record "
+                "doc_delta_decision=no_doc_delta with a justification"
+            ),
+            severity="block",
+            blocker_class="review_gate_block",
+        )
+    ]
+
+
+def _corroborate_no_doc_delta(ctx: CloseoutContext, decision: str) -> list[ReviewFinding]:
+    """F5: corroborate a self-attested ``no_doc_delta`` on a release phase.
+
+    Default-safe by construction:
+
+    * Only ``no_doc_delta`` is corroborated — ``docs_updated`` /
+      ``docs_follow_up_filed`` already evidence a real change and pass through.
+    * No scan threaded in (``ctx.docs_freshness is None``) → no corroboration is
+      available → satisfied (return ``[]``). We never newly-fail because the
+      runner didn't wire the scan.
+    * Non-release phases are untouched: an ordinary phase legitimately records
+      ``no_doc_delta`` for an internal change, and the freshness scan reports
+      ``skipped`` there anyway.
+    * Freshness gate ``off`` (``PHASE_LOOP_DOCS_FRESHNESS=off``) means "assert
+      nothing about docs": no corroboration is performed (return ``[]``), so
+      disabling the gate never *adds* a finding.
+    * The downgrade is **warn**, never block — the existing block path is the
+      *undecided* case, which this branch never reaches.
+    """
+    if decision != "no_doc_delta":
+        return []
+    detail = ctx.docs_freshness
+    if not detail:
+        return []  # unwired scan — no corroboration available, satisfied
+    detail = dict(detail)
+    if str(detail.get("mode") or "") == "off":
+        return []  # gate disabled — assert nothing, never add a finding
+    if not detail.get("is_release_phase"):
+        return []  # ordinary phase — self-attested no_doc_delta is fine
+    if docs_freshness_evidence_backed(detail):
+        return []  # the path-keyed scan corroborates the claim — satisfied
+    status = str(detail.get("status") or "skipped")
+    surfaces = list(detail.get("surfaces_scanned") or ())
+    return [
+        ReviewFinding(
+            code="doc_delta_uncorroborated",
+            reason=(
+                "release phase recorded `no_doc_delta` but the path-keyed "
+                "docs-freshness scan does not corroborate it "
+                f"(docs_freshness={status}, surfaces_scanned={len(surfaces)}); "
+                "treat the no-doc-change claim as unverified until the freshness "
+                "scan enumerates the public-doc surfaces and reports `passed`."
+            ),
+            severity="warn",
+            blocker_class="review_gate_warn",
+        )
+    ]

phase_loop_runtime/docs_audit.py

@@ -0,0 +1,285 @@
+"""Pipeline-independent docs-freshness audit (docs-freshness v4 P1, Layer A).
+
+`phase-loop docs-audit --base <ref>` runs on a git diff ALONE — no `.phase-loop/`
+state — so it is immune to the three #18 evasion paths (under-scoped docs lane,
+direct-`Agent()` pipeline bypass, absent runtime helper). It classifies the changed
+paths against the canonical `docs_surfaces` taxonomy and enforces the per-surface,
+relevance-bound decision contract, emitting a `docs_freshness: passed|skipped|blocked`
+report and a non-zero exit when a public surface changed without a satisfying decision.
+
+This is the only *non-bypassable* control; the in-pipeline `docs_freshness` closeout
+gate (shipped in v0.1.6) is the advisory early-feedback / content-token layer. This
+backstop adds the piece that gate structurally cannot catch: the *silent-absence* case
+— a release surface changed in the diff but its required doc was never updated.
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from . import docs_surfaces as ds
+
+#: git's well-known empty-tree object — the diff base for a first push / first tag,
+#: where the whole tree is "new" and there is no prior ref to diff against.
+_EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904"
+
+
+class DiffUnavailable(RuntimeError):
+    """A git diff could not be computed — the audit fails CLOSED, never a silent pass."""
+
+#: Decisions an operator/executor can record per surface. Release-class is held to
+#: the relevance binding regardless (a token never substitutes for the real doc).
+DECISION_TOKENS = ("docs_updated", "no_doc_delta", "docs_follow_up_filed")
+#: Repo-visible decision artifact, recoverable WITHOUT `.phase-loop/` state.
+DEFAULT_DECISIONS_PATH = ".doc-decisions.json"
+DOC_DECISIONS_SCHEMA_VERSION = 1
+
+
+def _git(repo: Path, *args: str) -> str:
+    try:
+        return subprocess.check_output(
+            ["git", "-C", str(repo), *args], text=True, stderr=subprocess.DEVNULL
+        ).strip()
+    except Exception:
+        return ""
+
+
+def _rev_ok(repo: Path, ref: str) -> bool:
+    return bool(_git(repo, "rev-parse", "--verify", f"{ref}^{{commit}}"))
+
+
+def _first_push_base(repo: Path) -> str:
+    """Base for a first push / first tag — HEAD~1 if it exists, else the empty tree."""
+    return "HEAD~1" if _rev_ok(repo, "HEAD~1") else _EMPTY_TREE
+
+
+def resolve_base(repo: Path, base: str | None) -> tuple[str | None, str]:
+    """Resolve the diff base across the CI contexts. Returns (base, context).
+
+    Explicit `--base` wins. Otherwise: a PR (`GITHUB_BASE_REF`) → `origin/<base>`; a tag
+    push (`GITHUB_REF=refs/tags/...`) → the prior tag (first tag → fallback base); a
+    branch push → the push **before** SHA (`DOCS_AUDIT_PUSH_BEFORE`, set to
+    `github.event.before`) so the WHOLE batch is diffed, never just the tip. An all-zeros
+    `before` (first push to the ref) → fallback base.
+    """
+    if base:
+        return base, "explicit"
+    pr_base = os.environ.get("GITHUB_BASE_REF")
+    if pr_base:
+        return f"origin/{pr_base}", "pull_request"
+    ref = os.environ.get("GITHUB_REF", "")
+    if ref.startswith("refs/tags/"):
+        prior = _git(repo, "describe", "--tags", "--abbrev=0", "HEAD^")
+        if prior:
+            return prior, "push_tag"
+        return _first_push_base(repo), "push_tag_first"
+    before = os.environ.get("DOCS_AUDIT_PUSH_BEFORE", "").strip()
+    if before:
+        if set(before) <= {"0"}:  # all-zeros sentinel → first push to this ref
+            return _first_push_base(repo), "push_first"
+        return before, "push"
+    return "HEAD~1", "push"  # local / no-CI-env fallback
+
+
+def _base_usable(repo: Path, base: str) -> bool:
+    return base == _EMPTY_TREE or _rev_ok(repo, base)
+
+
+def _diff_op(context: str) -> str:
+    # PR / explicit: three-dot (changes vs the merge-base). push / tag: two-dot
+    # (exactly the pushed commits — the correct semantics for a batched push range).
+    return "..." if context in {"pull_request", "explicit"} else ".."
+
+
+def changed_paths(repo: Path, base: str, op: str = "...", head: str = "HEAD") -> list[str]:
+    """`git diff --name-only base<op>head`. Raises `DiffUnavailable` on a git error so
+    the caller fails CLOSED — an empty result means "no changes", never "couldn't tell"."""
+    try:
+        completed = subprocess.run(
+            ["git", "-C", str(repo), "diff", "--name-only", f"{base}{op}{head}"],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            text=True,
+            check=False,
+        )
+    except OSError as exc:
+        raise DiffUnavailable(str(exc)) from exc
+    if completed.returncode not in {0, 1}:
+        raise DiffUnavailable(f"git diff exited {completed.returncode} for {base}{op}{head}")
+    return [p for p in completed.stdout.splitlines() if p.strip()]
+
+
+def load_decisions(repo: Path, path: str | None = None) -> dict[str, dict[str, Any]]:
+    """Read the repo-visible decision artifact. Missing file → no decisions.
+
+    Returns a mapping `surface-key -> {decision, reason, evidence}`. The key may be a
+    glob/path matching changed surfaces, or a class name (`general`/`release`/`*`).
+    """
+    decisions_path = repo / (path or DEFAULT_DECISIONS_PATH)
+    if not decisions_path.is_file():
+        return {}
+    try:
+        data = json.loads(decisions_path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+    out: dict[str, dict[str, Any]] = {}
+    for entry in data.get("decisions", []) or []:
+        surface = str(entry.get("surface") or "").strip()
+        decision = str(entry.get("decision") or "").strip()
+        if surface and decision in DECISION_TOKENS:
+            out[surface] = {
+                "decision": decision,
+                "reason": str(entry.get("reason") or ""),
+                "evidence": tuple(entry.get("evidence") or ()),
+            }
+    return out
+
+
+def _decision_for(path: str, klass: str, decisions: dict[str, dict[str, Any]]) -> dict[str, Any] | None:
+    for key in (path, klass, "*"):
+        if key in decisions:
+            return decisions[key]
+    for key, value in decisions.items():
+        if any(ch in key for ch in "*?[") and ds._match(path, key):
+            return value
+    return None
+
+
+@dataclass
+class AuditReport:
+    docs_freshness: str  # "passed" | "skipped" | "blocked"
+    findings: list[dict[str, Any]] = field(default_factory=list)
+    surfaces: dict[str, list[str]] = field(default_factory=dict)
+    evidence: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def exit_code(self) -> int:
+        return 0 if self.docs_freshness in {"passed", "skipped"} else 1
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "docs_freshness": self.docs_freshness,
+            "findings": self.findings,
+            "surfaces": self.surfaces,
+            "evidence": self.evidence,
+        }
+
+
+def evaluate(changed: list[str], decisions: dict[str, dict[str, Any]]) -> AuditReport:
+    """Apply the per-surface, relevance-bound decision contract to a changed-path set."""
+    changed_docs = [p for p in changed if ds.is_doc_surface(p)]
+    release_surfaces = [p for p in changed if ds.classify_surface(p) == "release" and not ds.is_doc_surface(p)]
+    general_surfaces = [p for p in changed if ds.classify_surface(p) == "general" and not ds.is_doc_surface(p)]
+
+    findings: list[dict[str, Any]] = []
+
+    for surface in release_surfaces:
+        required = ds.required_docs_for(surface)
+        if required:
+            relevant_changed = any(ds._match(d, pat) for d in changed_docs for pat in required)
+        else:
+            relevant_changed = bool(changed_docs)
+        if not relevant_changed:
+            findings.append({
+                "surface": surface,
+                "klass": "release",
+                "code": "release_docs_unsatisfied",
+                "reason": (
+                    f"release-class surface `{surface}` changed but its required doc "
+                    f"surface(s) {list(required) or ['any doc']} did not — a token or an "
+                    f"unrelated doc edit does not satisfy a release surface"
+                ),
+            })
+
+    for surface in general_surfaces:
+        decision = _decision_for(surface, "general", decisions)
+        if not (changed_docs or decision):
+            findings.append({
+                "surface": surface,
+                "klass": "general",
+                "code": "general_decision_missing",
+                "reason": (
+                    f"public surface `{surface}` changed with no doc change and no recorded "
+                    f"doc decision; update a doc or record a doc decision (no_doc_delta + reason)"
+                ),
+            })
+
+    surfaces = {
+        "release": release_surfaces,
+        "general": general_surfaces,
+        "docs": changed_docs,
+    }
+    if not release_surfaces and not general_surfaces:
+        return AuditReport("skipped", findings, surfaces, {"reason": "no public surfaces changed"})
+    if findings:
+        return AuditReport("blocked", findings, surfaces)
+    return AuditReport("passed", findings, surfaces)
+
+
+def run_audit(repo: Path, base: str | None = None, decisions_path: str | None = None) -> AuditReport:
+    """Orchestrate the diff-driven audit. Un-evaluable input → `blocked` (never silent pass)."""
+    resolved, context = resolve_base(repo, base)
+    if not resolved or not _base_usable(repo, resolved):
+        return AuditReport(
+            "blocked",
+            [{
+                "surface": None,
+                "klass": "audit",
+                "code": "base_unresolved",
+                "reason": (
+                    f"could not resolve the diff base (`{base or '<auto>'}`, context={context}); "
+                    f"the audit cannot evaluate freshness — failing closed (never a silent pass)"
+                ),
+            }],
+            evidence={"base": resolved, "context": context},
+        )
+    try:
+        changed = changed_paths(repo, resolved, _diff_op(context))
+    except DiffUnavailable as exc:
+        return AuditReport(
+            "blocked",
+            [{
+                "surface": None,
+                "klass": "audit",
+                "code": "diff_unavailable",
+                "reason": (
+                    f"git diff failed (base=`{resolved}`, context={context}): {exc} — the audit "
+                    f"cannot evaluate freshness, failing closed (never a silent pass)"
+                ),
+            }],
+            evidence={"base": resolved, "context": context},
+        )
+    report = evaluate(changed, load_decisions(repo, decisions_path))
+    report.evidence = {"base": resolved, "context": context, "changed_count": len(changed)}
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+
+    parser = argparse.ArgumentParser(prog="phase-loop docs-audit")
+    parser.add_argument("--base", help="Diff base ref (auto-resolved from CI env if omitted).")
+    parser.add_argument("--repo", default=".", help="Repository root (default: cwd).")
+    parser.add_argument("--decisions", help=f"Decision artifact path (default: {DEFAULT_DECISIONS_PATH}).")
+    parser.add_argument("--json", action="store_true", help="Emit the report as JSON.")
+    # tolerate the leading 'docs-audit' token when dispatched from the main CLI
+    args = parser.parse_args([a for a in (argv or []) if a != "docs-audit"])
+
+    report = run_audit(Path(args.repo), args.base, args.decisions)
+    if args.json:
+        print(json.dumps(report.to_json(), indent=2))
+    else:
+        print(f"docs_freshness: {report.docs_freshness}")
+        for f in report.findings:
+            print(f"  [{f['klass']}] {f.get('surface') or '-'}: {f['reason']}")
+        if report.docs_freshness == "blocked":
+            print(
+                "\nRemediation: update the required doc surface(s), or record a doc decision in "
+                f"{args.decisions or DEFAULT_DECISIONS_PATH} (release-class needs a real, relevant "
+                "doc change — a token does not satisfy it)."
+            )
+    return report.exit_code