@miller-tech/uap 2.1.6 → 2.11.0

package/src/policies/enforcers/evidence_bound_ship.py

@@ -0,0 +1,257 @@
+#!/usr/bin/env python3
+"""evidence-bound-ship enforcer: gate evidence must be bound to the shipped SHA.
+
+Blocks ship actions (same detection as expert-review-required: git commit /
+push / merge, gh pr create / merge / ready, pr-ready / signoff) unless
+`.uap/evidence/<head-sha>.json` exists AND proves the mission's gates passed
+for EXACTLY the commit being shipped:
+
+  - missing artifact          -> BLOCK
+  - malformed JSON            -> BLOCK
+  - version != 1              -> BLOCK
+  - candidateSha != HEAD      -> BLOCK (evidence for a different commit proves
+                                nothing about this one — the forgery/staleness
+                                case this gate exists to refuse)
+  - recordedAt before the commit's own committer time, or older than the
+    staleness window (default 24h) -> BLOCK
+  - no gate with exitCode 0 + command + timestamp -> BLOCK (empty/forged)
+
+The artifact is written by the deliver CLI (src/delivery/gate-evidence.ts) at
+mission completion. `.uap/evidence/` is a self-protect PROTECTED_TARGET with no
+agent carve-out, so the enforcer's trust root is "only the tooling could have
+written this", same as the review artifacts' waiver dirs.
+
+Fail-CLOSED on anything ambiguous — that is the difference between this gate
+and expert-review: review evidence fail-opens on detached/unresolvable HEAD
+because a review is a human act; gate evidence is machine-written at deliver
+time, so a ship with unverifiable evidence is simply refused. The ONLY
+fail-open is when git itself is absent or cwd is not a repo (non-UAP trees are
+unaffected).
+
+Local git + fs only: no network, no gh — the enforcer runs in the live policy
+chain and must be fast. `gh pr merge <N>` binds to the LOCAL worktree HEAD (the
+PR head is not resolvable without gh); ship from the branch you deliver on.
+
+Escape hatch: UAP_EVIDENCE_GATE_OFF=1 in the LAUNCH environment (operator-only;
+enforcement-self-protect refuses the inline form, same as UAP_NO_REVIEW).
+Staleness window override: UAP_EVIDENCE_MAX_AGE_HOURS (default 24).
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from _common import emit, parse_cli, worktree_root, run  # noqa: E402
+# Ship-action detection is SHARED with expert-review-required: one definition,
+# so a verb one gate sees can never slip past the other.
+from expert_review_required import is_ship_action  # noqa: E402
+
+EVIDENCE_DIR = ".uap/evidence"
+DEFAULT_MAX_AGE_HOURS = 24
+# A deliver-written artifact is a few KB of gate outcomes. Anything near half a
+# megabyte is not evidence, it's a payload — cap the read BEFORE parsing so a
+# hostile or corrupt file cannot make the gate parse unbounded input.
+MAX_ARTIFACT_BYTES = 512 * 1024
+# Clock-skew allowance for the future-dating check: recordedAt may lead the
+# gate host's clock by a little on a machine with sloppy NTP; 5 minutes is
+# generosity, not a loophole (staleness is measured in hours).
+FUTURE_SKEW_SEC = 300
+
+
+def _max_age_sec() -> int:
+    """Staleness window in seconds; a malformed env override falls back to the
+    default rather than disabling the check (0) or crashing the gate."""
+    try:
+        hours = float(os.environ.get("UAP_EVIDENCE_MAX_AGE_HOURS", "") or DEFAULT_MAX_AGE_HOURS)
+        return max(0, int(hours * 3600))
+    except ValueError:
+        return DEFAULT_MAX_AGE_HOURS * 3600
+
+
+def _parse_iso(value: object) -> float | None:
+    """ISO-8601 -> epoch seconds, or None when unparseable. Tolerates a
+    trailing 'Z' (the writer emits it; fromisoformat only learned 'Z' in 3.11).
+    """
+    if not isinstance(value, str) or not value.strip():
+        return None
+    try:
+        dt = datetime.fromisoformat(value.strip().replace("Z", "+00:00"))
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return dt.timestamp()
+    except ValueError:
+        return None
+
+
+def _head_sha(root: Path) -> str | None:
+    rc, out, _ = run(["git", "rev-parse", "--verify", "HEAD^{commit}"], cwd=root)
+    sha = out.strip()
+    return sha if rc == 0 and sha else None
+
+
+def _commit_time(root: Path, sha: str) -> float | None:
+    rc, out, _ = run(["git", "show", "-s", "--format=%ct", sha], cwd=root)
+    try:
+        return float(out.strip()) if rc == 0 else None
+    except ValueError:
+        return None
+
+
+def _block(reason: str, fix: str) -> None:
+    emit(
+        False,
+        f"evidence-bound-ship: {reason} {fix} "
+        "Operator override: UAP_EVIDENCE_GATE_OFF=1 in the launch environment.",
+    )
+
+
+def main() -> None:
+    op, args = parse_cli()
+
+    if os.environ.get("UAP_EVIDENCE_GATE_OFF") == "1":
+        emit(True, "UAP_EVIDENCE_GATE_OFF override set")
+
+    if op.lower() != "bash":
+        emit(True, "not a ship operation")
+
+    cmd = args.get("command") or args.get("cmd") or ""
+    if not is_ship_action(cmd, worktree_root()):
+        emit(True, "not a ship action")
+
+    root = worktree_root()
+
+    # Fail-open ONLY when git cannot answer at all (git missing, or cwd is not
+    # a repository) — non-UAP trees must be unaffected. Everything else fails
+    # closed below.
+    rc, out, _ = run(["git", "rev-parse", "--is-inside-work-tree"], cwd=root)
+    if rc != 0 or out.strip() != "true":
+        emit(True, "not a git repo (or git unavailable) — fail-open")
+
+    sha = _head_sha(root)
+    if sha is None:
+        _block(
+            "HEAD is not resolvable to a commit (unborn branch or corrupt repo),"
+            " so no candidate-bound evidence can exist.",
+            "Fix: deliver the mission with `uap deliver` on a branch with a real HEAD.",
+        )
+
+    artifact = root / EVIDENCE_DIR / f"{sha}.json"
+    if not artifact.exists():
+        _block(
+            f"no gate-evidence artifact at {EVIDENCE_DIR}/{sha[:12]}….json for the current HEAD.",
+            "Fix: run `uap deliver` so the mission's gates are recorded against this commit,"
+            " then ship.",
+        )
+
+    try:
+        size = artifact.stat().st_size
+    except OSError:
+        size = None  # raced away between exists() and stat() — fail closed
+    if size is None or size > MAX_ARTIFACT_BYTES:
+        _block(
+            f"the evidence artifact {EVIDENCE_DIR}/{sha[:12]}….json is oversized or unreadable"
+            f" ({size if size is not None else 'stat failed'}; cap {MAX_ARTIFACT_BYTES} bytes)"
+            " — a deliver-written artifact is a few KB.",
+            "Fix: delete it and re-run `uap deliver` so a well-formed artifact is recorded.",
+        )
+
+    try:
+        data = json.loads(artifact.read_text())
+    except Exception:  # noqa: BLE001
+        _block(
+            f"the evidence artifact {EVIDENCE_DIR}/{sha[:12]}….json is malformed (not JSON).",
+            "Fix: delete it and re-run `uap deliver` so a well-formed artifact is recorded.",
+        )
+
+    if not isinstance(data, dict) or data.get("version") != 1:
+        _block(
+            f"the evidence artifact for {sha[:12]}… has an unsupported schema version.",
+            "Fix: re-run `uap deliver` with the current CLI to re-record it (version 1).",
+        )
+
+    recorded_sha = data.get("candidateSha")
+    if recorded_sha != sha:
+        _block(
+            f"the evidence artifact covers {str(recorded_sha)[:12]}… but HEAD is {sha[:12]}…"
+            " — evidence for a different commit proves nothing about this one.",
+            "Fix: re-run `uap deliver` so the gates are recorded against the commit you are shipping.",
+        )
+
+    recorded_at = _parse_iso(data.get("recordedAt"))
+    if recorded_at is None:
+        _block(
+            "the evidence artifact has no parseable recordedAt timestamp.",
+            "Fix: re-run `uap deliver` to re-record it.",
+        )
+
+    # Backdating guard: evidence claiming to predate the commit it binds to is
+    # forged — the commit did not exist to be gated yet. The commit time being
+    # UNRESOLVABLE is anomalous (the sha resolved but git show failed): fail
+    # closed rather than skip the one check that anchors recordedAt to reality.
+    committed_at = _commit_time(root, sha)
+    if committed_at is None:
+        _block(
+            f"the commit time of HEAD ({sha[:12]}…) could not be resolved — the sha"
+            " resolved but `git show` failed, which is anomalous.",
+            "Fix: investigate the repo (corrupt object?), then re-run `uap deliver`.",
+        )
+    if recorded_at < committed_at:
+        _block(
+            "the evidence predates the commit it claims to prove"
+            f" (recordedAt {data.get('recordedAt')}, commit time {int(committed_at)}).",
+            "Fix: re-run `uap deliver` after the candidate commit exists.",
+        )
+
+    now = datetime.now(timezone.utc).timestamp()
+    if recorded_at > now + FUTURE_SKEW_SEC:
+        _block(
+            f"the evidence is FUTURE-dated (recordedAt {data.get('recordedAt')}"
+            f" is more than {FUTURE_SKEW_SEC}s ahead of now) — forged or a"
+            " badly skewed clock.",
+            "Fix: fix the clock and re-run `uap deliver`.",
+        )
+
+    age = now - recorded_at
+    window = _max_age_sec()
+    if age > window:
+        _block(
+            f"the gate evidence is stale ({int(age // 3600)}h old; window"
+            f" {window // 3600}h) — the tree may have drifted since the gates ran.",
+            "Fix: re-run `uap deliver` to refresh the evidence for this HEAD.",
+        )
+
+    gates = data.get("gates")
+    passing = [
+        g
+        for g in (gates if isinstance(gates, list) else [])
+        if isinstance(g, dict)
+        and g.get("exitCode") == 0
+        and isinstance(g.get("command"), str)
+        and g["command"].strip()
+        and _parse_iso(g.get("at")) is not None
+    ]
+    if not passing:
+        _block(
+            "the evidence artifact records no passing gate with a command and"
+            " timestamp — an empty or forged artifact is not evidence.",
+            "Fix: re-run `uap deliver` so the real gate outcomes are recorded.",
+        )
+
+    emit(
+        True,
+        f"evidence-bound-ship satisfied ({EVIDENCE_DIR}/{sha[:12]}….json,"
+        f" {len(passing)} passing gate(s), recorded {data.get('recordedAt')})",
+    )
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except SystemExit:
+        raise
+    except Exception as e:  # noqa: BLE001 — the live policy chain must never see a traceback
+        _block(f"enforcer error ({type(e).__name__}: {e}); failing closed.", "Fix: report this.")

package/src/policies/enforcers/expert_review_required.py

@@ -23,6 +23,7 @@ import os
 import re
 import shlex
 import sys
+from datetime import datetime
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).parent))
@@ -275,6 +276,114 @@ def _is_low_risk(f: str) -> bool:
     return Path(f).suffix.lower() in LOW_RISK_EXT
 
 
+# --- Visual-captures gate (uplift 0.3) --------------------------------------
+# A diff touching UI files is not done until before/after captures are bound
+# to the review — code review cannot see what the user sees. The captures live
+# in a SIBLING artifact (<slug>.captures.json), never in <slug>.json itself:
+# this enforcer treats that file's existence as "a review happened", so an
+# advisory recording must not create it. The surface definition mirrors
+# UI_EXT/UI_DIR_PREFIXES in visual_verification.py and
+# src/review/visual-captures.ts — keep all three in sync.
+UI_EXT = {".css", ".scss", ".sass", ".less", ".tsx", ".jsx", ".vue", ".svelte", ".html", ".astro"}
+UI_DIR_PREFIXES = ("web/", "src/dashboard/", "public/")
+CAPTURES_STALENESS_GRACE_S = 1.0  # same grace the commit-time visual enforcer uses
+
+
+def _is_ui(f: str) -> bool:
+    # Case-insensitive like the TS mirror (isUiFile in visual-captures.ts):
+    # `Web/` or `Component.TSX` must not slip between two definitions.
+    lower = f.lower()
+    return Path(lower).suffix in UI_EXT or lower.startswith(UI_DIR_PREFIXES)
+
+
+def _safe_capture_path(p: object) -> str | None:
+    """A capture path the gate may existence-check, or None when it escapes
+    the project. The recorder refuses these, but the enforcer is the gate and
+    must not trust the artifact: Path(root) / "/etc/passwd" collapses to the
+    absolute path, and "root / '../../x'" resolves outside the project."""
+    s = str(p)
+    if os.path.isabs(s) or s == ".." or s.startswith("../") or "/../" in s:
+        return None
+    return s
+
+
+def _check_visual_captures(root: Path, slug: str, ui_files: list[str]) -> None:
+    """emit(False, ...) unless fresh before/after captures cover the UI diff."""
+    # Operator escape hatch, environment-only (set by whoever launched the
+    # session) — never parsed out of the command string; an inline override
+    # would be self-grantable, the exact hole removed from UAP_NO_REVIEW.
+    if os.environ.get("UAP_VISUAL_GATE_OFF") == "1":
+        return
+
+    artifact = root / REVIEW_ARTIFACT_DIR / f"{slug}.captures.json"
+    guidance = (
+        "capture before/after evidence with a capture tool (agent-browser for "
+        "web surfaces, tuistory/pty-capture for terminal surfaces), review the "
+        "pair, and register it: uap review captures add --before <img> --after "
+        "<img> --tool <name>. Verify with `uap review captures check`."
+    )
+    if not artifact.exists():
+        emit(
+            False,
+            f"visual-captures: the diff touches {len(ui_files)} UI file(s) "
+            f"({', '.join(sorted(ui_files)[:6])}{' …' if len(ui_files) > 6 else ''}) "
+            f"but no captures artifact exists at .uap/reviews/{slug}.captures.json. "
+            "A UI change is not reviewable from code alone — completion gate 7 "
+            f"(self-review) requires the rendered evidence. {guidance} "
+            "Operator override: UAP_VISUAL_GATE_OFF=1 in the launch environment.",
+        )
+    try:
+        data = json.loads(artifact.read_text())
+    except Exception:  # noqa: BLE001
+        data = {}
+    captures = data.get("captures") if isinstance(data, dict) else None
+    pairs = [c for c in (captures or []) if isinstance(c, dict) and c.get("before") and c.get("after")]
+    if not pairs:
+        emit(
+            False,
+            f"visual-captures: .uap/reviews/{slug}.captures.json has no complete "
+            f"before/after pair. {guidance}",
+        )
+    paths = [p for c in pairs for p in (c.get("before"), c.get("after"))]
+    if any(_safe_capture_path(p) is None for p in paths):
+        emit(
+            False,
+            f"visual-captures: .uap/reviews/{slug}.captures.json references a path "
+            "outside the project (absolute or .. escape). Re-register captures with "
+            "`uap review captures add` — project-relative paths only.",
+        )
+    missing = [str(p) for p in paths if not (root / str(p)).exists()]
+    if missing:
+        emit(
+            False,
+            f"visual-captures: capture file(s) referenced by the artifact are missing: "
+            f"{', '.join(sorted(set(missing))[:6])}. Re-capture and re-register.",
+        )
+
+    # Freshness: captures predating the newest UI edit say nothing about the
+    # current look. The artifact's `at` must postdate every UI file's mtime.
+    try:
+        captured_at = datetime.fromisoformat(str(data.get("at", "")).replace("Z", "+00:00")).timestamp()
+    except Exception:  # noqa: BLE001
+        captured_at = 0.0
+    stale = []
+    for f in ui_files:
+        p = root / f
+        try:
+            if p.exists() and p.stat().st_mtime > captured_at + CAPTURES_STALENESS_GRACE_S:
+                stale.append(f)
+        except OSError:
+            continue
+    if stale:
+        emit(
+            False,
+            f"visual-captures: UI file(s) changed AFTER the captures were taken — the "
+            f"current look is unverified: {', '.join(sorted(stale)[:6])}"
+            f"{' …' if len(stale) > 6 else ''}. Re-capture and re-register with "
+            "`uap review captures add`.",
+        )
+
+
 def _active_waiver(root: Path) -> bool:
     """A committable, env-free bypass: an active waiver file. Works in harnesses
     that strip env vars (where UAP_NO_REVIEW=1 cannot be set)."""
@@ -438,6 +547,17 @@ def main() -> None:
     # `gh pr merge` from the main checkout is not the PR's contents at all —
     # it would grade the wrong change as low-risk.
     changed = None if pr_branch else _changed_files(root)
+
+    # Visual-captures gate BEFORE the low-risk early-allow: UI-only diffs are
+    # exactly what this gate exists for, and the low-risk path would otherwise
+    # wave them through unobserved. Fail-open when the base is unresolvable
+    # (same posture as the risk-scope check) and skipped for PR ships, where
+    # the local diff is not the PR's contents.
+    if changed is not None:
+        ui_files = [f for f in changed if _is_ui(f)]
+        if ui_files:
+            _check_visual_captures(root, slug, ui_files)
+
     if changed and all(_is_low_risk(f) for f in changed):
         emit(
             True,

package/src/policies/schemas/policies/evidence-bound-ship.md

@@ -0,0 +1,106 @@
+# evidence-bound-ship
+
+**Category**: quality
+**Level**: REQUIRED
+**Enforcement Stage**: review
+**Tags**: uap, delivery, evidence, gates, enforcement, ship
+
+## Rule
+
+A ship action MUST present machine-recorded gate evidence bound to the exact
+commit being shipped. When no valid evidence artifact exists for the current
+HEAD, the enforcer blocks the ship actions:
+
+- `git commit`, `git push`, `git merge`
+- `gh pr create`, `gh pr merge`, `gh pr ready`
+- merge / pr-ready / signoff / ready-for-review operations
+
+Evidence artifact: `.uap/evidence/<candidate-sha>.json`, written by the
+**deliver CLI** (`src/delivery/gate-evidence.ts`) when a mission completes with
+its gates green. Recognised shape (version 1):
+
+```json
+{
+  "version": 1,
+  "candidateSha": "<full HEAD sha the gates prove>",
+  "recordedAt": "<ISO-8601>",
+  "runId": "<deliver run id, optional>",
+  "hatches": ["<gate-affecting env vars set at deliver time, audit only>"],
+  "gates": [
+    { "name": "test", "command": "npm test", "exitCode": 0,
+      "outputTail": "<last ≤2000 chars>", "at": "<ISO-8601>" }
+  ]
+}
+```
+
+The writer **refuses to record against a dirty working tree** (`git status
+--porcelain` must be empty): evidence claims the gates passed for `<sha>`, and
+with uncommitted changes they provably ran against HEAD-plus-delta. The
+supported flow is therefore commit → `uap deliver` (a green tree short-circuits
+as `alreadyDelivered`, and the baseline ladder's rung results become the
+evidence) → ship.
+
+Per-gate `at` is **reconstructed**, not measured: rungs carry durations but no
+wall-clock finish time, so a gate's stamp is the recording time minus the
+durations of the gates that ran after it. Honest ordering, approximate clock.
+
+`hatches` lists which known gate-affecting env vars (the
+enforcement-self-protect BYPASS_PATTERNS set plus `UAP_VISUAL_GATE_OFF` /
+`UAP_DESIGN_GATE_OFF`) were set when the evidence was recorded. Audit value
+only; the enforcer does not act on it.
+
+The enforcer rejects (BLOCKS) an artifact that is:
+
+- **missing** — no `.uap/evidence/<head>.json` for the current HEAD;
+- **oversized** — larger than 512KB (read capped before parsing);
+- **malformed** — not parseable JSON;
+- **wrong version** — anything but `version: 1`;
+- **SHA-mismatched** — `candidateSha` differs from HEAD (evidence for a
+  different commit proves nothing about this one; this is also the forgery
+  case, since `.uap/evidence/` is agent-write-protected by
+  enforcement-self-protect, including interpreter-mediated writes);
+- **backdated** — `recordedAt` earlier than the commit's own committer time
+  (and an UNRESOLVABLE commit time blocks too: the sha resolving while
+  `git show` fails is anomalous, not a skip);
+- **future-dated** — `recordedAt` more than 5 minutes ahead of now;
+- **stale** — `recordedAt` older than the staleness window (default **24h**,
+  operator-tunable via `UAP_EVIDENCE_MAX_AGE_HOURS` in the launch environment;
+  the agent cannot set it — enforcement-self-protect refuses any assignment);
+- **empty** — no gate entry with `exitCode: 0`, a non-empty `command`, and a
+  parseable `at` timestamp.
+
+## Why
+
+Deliver missions claim "all gates pass", but until this policy nothing bound
+that claim to the commit a ship action actually publishes. An agent could run
+the gates on one tree, amend or swap the commit, and ship code the gates never
+saw — the ship gates trusted the run, not the artifact. Evidence binding makes
+the merge candidate carry its proof: the ship enforcer reads the artifact for
+`HEAD` and fails closed on anything missing, stale, or mismatched.
+
+This is the machine-recorded analogue of `expert-review-required`: review
+evidence is a human verdict (fail-open on unresolvable HEAD); gate evidence is
+written by the CLI at deliver time, so the posture is fail-closed — the only
+fail-open is a tree that is not a git repo at all.
+
+## Enforcement
+
+Python enforcer `evidence_bound_ship.py` resolves the candidate HEAD via local
+git (`git rev-parse --verify HEAD^{commit}` — no network, no `gh`), then checks
+`.uap/evidence/<sha>.json` as above. Ship-action detection is **shared** with
+`expert-review-required` (imported `is_ship_action`), so the two gates can
+never disagree on what a ship action is.
+
+Fail-closed on every ambiguity; fail-open only when git itself is absent or
+the working tree is not a repository (non-UAP trees unaffected).
+
+Bypass (operator-only, environment-only — the inline form is refused by
+enforcement-self-protect because the agent composes its own command strings):
+
+- `UAP_EVIDENCE_GATE_OFF=1` — set in the launch environment.
+
+```rules
+- title: "A ship action must present gate evidence bound to the shipped commit"
+  keywords: [git commit, git push, gh pr create, merge, pr-ready, signoff, gate evidence]
+  antiPatterns: [no-evidence, stale-evidence, forged-evidence, evidence-sha-mismatch]
+```

package/src/policies/schemas/policies/visual-verification.md

@@ -44,6 +44,14 @@ an agent that can see the output can improve it.
 - Fail-open ONLY when no headless browser is available (vm-DOM cannot
   render pixels); the skip is stated explicitly in the report.
 
+## Review binding (uplift 0.3)
+
+Distinct from this runtime render gate: when a diff touches UI files, the
+review must also carry before/after **captures** (agent-browser / tuistory /
+pty-capture) registered via `uap review captures add` and validated by the
+ship-time enforcer — see `docs/reference/visual-captures.md`. The render gate
+proves the UI runs; captures prove a reviewer looked at the change.
+
 ## Agent obligations
 
 After any delivery with a rendered artifact: run `uap verify --dir <project>`,