@miller-tech/uap 1.106.0 → 1.107.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miller-tech/uap",
-  "version": "1.106.0",
+  "version": "1.107.0",
   "description": "Autonomous AI agent memory system with CLAUDE.md protocol enforcement",
   "type": "module",
   "main": "dist/index.js",
@@ -29,7 +29,7 @@
     "install:web": "bash scripts/setup/install-web.sh",
     "install:desktop": "bash scripts/setup/install-desktop.sh",
     "install:cloakbrowser": "tsx scripts/setup/install-cloakbrowser.ts",
-    "postinstall": "echo '\n✨ Run: npx @miller-tech/uap init --interactive'",
+    "postinstall": "echo '\n\u2728 Run: npx @miller-tech/uap init --interactive'",
     "version:patch": "bash scripts/version-bump.sh patch",
     "version:minor": "bash scripts/version-bump.sh minor",
     "version:major": "bash scripts/version-bump.sh major",

package/src/policies/enforcers/adr_guard.py

@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+"""adr-guard enforcer — generic ADR-driven tool-call gate.
+
+Reads machine-readable rule blocks from every ADR under `docs/adr/` and
+enforces them on Write/Edit tool calls. This lets us express architectural
+and security invariants once — in the ADR itself — and have them enforced
+automatically by UAP agents.
+
+Rule block format (embedded inside an ADR as an HTML comment):
+
+    <!-- uap-rules
+    - id: ADR-0007-FE-NO-BEARER
+      scope:
+        include: ["apps/web/", "apps/cms/", "apps/marketing/"]
+        exclude: ["/tests/", ".test.", ".spec.", "/node_modules/"]
+        ext: [".js", ".ts", ".jsx", ".tsx"]
+      forbid: 'Authorization.*Bearer'
+      message: "FE must not set Authorization: Bearer. See ADR-0007."
+    - id: ADR-0006-PIPELINE-ONLY
+      scope:
+        include: ["infra/"]
+        exclude: ["infra/archive/"]
+      require: '^#\\s*managed-by:\\s*terraform'
+      message: "Infra files must declare terraform ownership. See ADR-0006."
+    -->
+
+Fields:
+    id        — unique rule ID (prefix with ADR number)
+    scope.*   — path filters (include prefixes, exclude substrings, ext list)
+    forbid    — regex that MUST NOT match the written content
+    require   — regex that MUST match (at least one hit) when writing into scope
+    message   — explanation shown when blocked
+    on_tools  — optional list of tool names (default: Write, Edit, MultiEdit)
+
+The parser caches rules by ADR-file mtime so rebuilds are cheap.
+"""
+from __future__ import annotations
+
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).parent))
+from _common import emit, parse_cli, repo_root  # noqa: E402
+
+try:
+    import yaml  # type: ignore
+except ImportError:  # pragma: no cover
+    yaml = None
+
+
+RULE_BLOCK_RE = re.compile(
+    r"<!--\s*uap-rules\s*\n(.*?)\n\s*-->", re.DOTALL | re.IGNORECASE
+)
+
+
+def _parse_adr_rules(adr_dir: Path) -> list[dict[str, Any]]:
+    """Extract all uap-rules blocks from ADR files."""
+    if not adr_dir.is_dir() or yaml is None:
+        return []
+    rules: list[dict[str, Any]] = []
+    for f in sorted(adr_dir.glob("*.md")):
+        try:
+            text = f.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            continue
+        for m in RULE_BLOCK_RE.finditer(text):
+            body = m.group(1)
+            try:
+                parsed = yaml.safe_load(body)
+            except yaml.YAMLError:
+                continue
+            if not isinstance(parsed, list):
+                continue
+            for r in parsed:
+                if not isinstance(r, dict):
+                    continue
+                r["_adr"] = f.name
+                rules.append(r)
+    return rules
+
+
+def _extract_write_target(op: str, args: dict[str, Any]) -> tuple[str, str] | None:
+    tool = op.lower()
+    if tool == "write":
+        return args.get("file_path") or "", args.get("content") or ""
+    if tool == "edit":
+        return args.get("file_path") or "", args.get("new_string") or ""
+    if tool == "multiedit":
+        fp = args.get("file_path") or ""
+        edits = args.get("edits") or []
+        content = "\n".join(
+            e.get("new_string", "") for e in edits if isinstance(e, dict)
+        )
+        return fp, content
+    if tool == "notebookedit":
+        return args.get("notebook_path") or "", args.get("new_source") or ""
+    return None
+
+
+def _path_matches_scope(path: str, scope: dict[str, Any] | None) -> bool:
+    if not scope:
+        return True
+    includes = scope.get("include") or [""]
+    excludes = scope.get("exclude") or []
+    exts = scope.get("ext")
+    if not any(inc == "" or inc in path for inc in includes):
+        return False
+    for exc in excludes:
+        if exc and exc in path:
+            return False
+    if exts:
+        if not any(path.endswith(e) for e in exts):
+            return False
+    return True
+
+
+def _normalize_path(file_path: str) -> str:
+    norm = file_path.replace("\\", "/")
+    for top in (
+        "apps/", "infra/", "services/", "docs/", "scripts/", ".github/",
+        ".semgrep/", ".policy-tools/", ".claude/", "observability/",
+    ):
+        idx = norm.find(top)
+        if idx >= 0:
+            return norm[idx:]
+    return norm
+
+
+def main() -> None:
+    op, args = parse_cli()
+    target = _extract_write_target(op, args)
+    if target is None:
+        emit(True, "not a write/edit operation")
+    file_path, content = target
+    if not file_path:
+        emit(True, "no file path in args")
+
+    root = repo_root()
+    rules = _parse_adr_rules(root / "docs" / "adr")
+    if not rules:
+        emit(True, "no ADR rules active")
+
+    norm = _normalize_path(file_path)
+    tool = op if op else ""
+
+    violations: list[str] = []
+    for rule in rules:
+        on_tools = rule.get("on_tools") or ["Write", "Edit", "MultiEdit"]
+        if tool and tool not in on_tools:
+            continue
+        if not _path_matches_scope(norm, rule.get("scope")):
+            continue
+
+        forbid = rule.get("forbid")
+        if forbid:
+            try:
+                if re.search(forbid, content):
+                    msg = rule.get("message") or f"ADR rule {rule.get('id','?')}"
+                    violations.append(
+                        f"[{rule.get('id','adr-rule')} from {rule.get('_adr')}] {msg}"
+                    )
+            except re.error:
+                continue
+
+        require = rule.get("require")
+        if require:
+            try:
+                if not re.search(require, content):
+                    msg = rule.get("message") or f"ADR rule {rule.get('id','?')}"
+                    violations.append(
+                        f"[{rule.get('id','adr-rule')} from {rule.get('_adr')}] (required pattern missing) {msg}"
+                    )
+            except re.error:
+                continue
+
+    if violations:
+        emit(
+            False,
+            "adr-guard: " + " | ".join(violations),
+            violations=violations,
+        )
+    emit(True, "no ADR rule violations in write")
+
+
+if __name__ == "__main__":
+    main()

package/src/policies/enforcers/bearer_lockdown.py

@@ -0,0 +1,298 @@
+#!/usr/bin/env python3
+"""bearer-lockdown enforcer — UAP gate for ADR-0007 cookie-only frontend.
+
+Blocks Write/Edit tool calls that would reintroduce any of the seven
+ADR-0007 invariants. Mirrors scripts/bearer-lockdown-scan.sh but runs at
+tool-call time so agents are prevented from writing the regression in
+the first place, not merely caught at CI time.
+
+Invariants enforced (details in docs/adr/ADR-0007-cookie-only-frontend.md):
+    FE-NO-BEARER           Frontend code must not set Authorization: Bearer.
+    FE-NO-STORAGE          No token keys in localStorage / sessionStorage.
+    PROXY-NO-BYPASS        No --skip-jwt-bearer-tokens=true on oauth2-proxy.
+    BACKEND-NO-CLIENT-AUTH Backend must not read client Authorization header.
+    AUTH-ME-OPAQUE         /auth/me must emit user_ref, not raw user_id.
+    NO-COMMITTED-JWT       No RS256 JWT (>100 chars) anywhere.
+
+The ISTIO-DENY-ALIVE invariant is runtime-only (Kyverno + alerts) since
+tool-level detection would require reasoning about the whole cluster state.
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).parent))
+from _common import emit, parse_cli  # noqa: E402
+
+# --------------------------------------------------------------------------
+# Rule definitions. Each rule has:
+#   - id: short code (matches scanner/semgrep IDs)
+#   - path_include: list of glob prefixes the file must match
+#   - path_exclude: list of glob substrings that veto the rule
+#   - pattern: compiled regex matched against the written content
+#   - message: explanation shown to the agent when blocked
+# --------------------------------------------------------------------------
+RULES: list[dict[str, Any]] = [
+    {
+        "id": "BL-001",
+        "invariant": "FE-NO-BEARER",
+        "path_include": ("apps/web/", "apps/cms/", "apps/marketing/"),
+        "path_exclude": (
+            "/tests/",
+            "/test/",
+            ".test.",
+            ".spec.",
+            "/node_modules/",
+            "/dist/",
+        ),
+        "ext": (".js", ".ts", ".jsx", ".tsx", ".mjs", ".cjs"),
+        # Match Authorization followed by Bearer on the same line, with
+        # optional quoting/colon/equals between them. False positives on
+        # JS comments in scoped paths are rare and easy to rephrase — the
+        # scanner + semgrep catch the same, so redundancy is fine.
+        "pattern": re.compile(
+            r"Authorization[\"']?\s*[:=]\s*[\"'`]?Bearer\b",
+        ),
+        "message": (
+            "ADR-0007 FE-NO-BEARER: frontend code must not set "
+            "`Authorization: Bearer`. Auth rides on the httpOnly "
+            "`_oauth2_proxy` cookie only. See "
+            "docs/adr/ADR-0007-cookie-only-frontend.md."
+        ),
+    },
+    {
+        "id": "BL-002",
+        "invariant": "FE-NO-STORAGE",
+        "path_include": ("apps/web/", "apps/cms/", "apps/marketing/"),
+        "path_exclude": (
+            "/tests/",
+            "/test/",
+            ".test.",
+            ".spec.",
+            "/node_modules/",
+        ),
+        "ext": (".js", ".ts", ".jsx", ".tsx", ".mjs", ".cjs"),
+        "pattern": re.compile(
+            r"(local|session)Storage\.setItem\s*\(\s*[\"'](access_token|refresh_token|id_token|auth_token|authToken|bearer_token)[\"']",
+        ),
+        "message": (
+            "ADR-0007 FE-NO-STORAGE: token-like keys must not be written to "
+            "localStorage/sessionStorage (XSS-reachable). Auth is cookie-only. "
+            "See docs/adr/ADR-0007-cookie-only-frontend.md."
+        ),
+    },
+    {
+        "id": "BL-003",
+        "invariant": "PROXY-NO-BYPASS",
+        "path_include": ("infra/",),
+        "path_exclude": (
+            "infra/archive/",
+            "infra/k8s/archive/",
+            # Policy files that reference the forbidden flag to enforce it.
+            "infra/policies/rego/bearer_lockdown.rego",
+            "infra/k8s/kyverno/",
+            "infra/k8s/istio/authz-policy-deny-client-bearer.yaml",
+        ),
+        "ext": None,  # any extension
+        "pattern": re.compile(r"--skip-jwt-bearer-tokens=true"),
+        "message": (
+            "ADR-0007 PROXY-NO-BYPASS: oauth2-proxy must not carry "
+            "`--skip-jwt-bearer-tokens=true`. It lets a client-held Bearer "
+            "substitute for the session cookie. See "
+            "docs/adr/ADR-0007-cookie-only-frontend.md."
+        ),
+    },
+    {
+        "id": "BL-006",
+        "invariant": "BACKEND-NO-CLIENT-AUTH",
+        "path_include": ("apps/api/",),
+        "path_exclude": ("apps/api/tests/",),
+        "ext": (".hpp", ".cpp", ".h"),
+        "pattern": re.compile(
+            r'get_header_value\s*\(\s*"authorization"\s*\)',
+        ),
+        "message": (
+            "ADR-0007 BACKEND-NO-CLIENT-AUTH: the backend must not read the "
+            "client `Authorization` header. JWT is resolved from proxy-set "
+            "headers (`X-Forwarded-Access-Token` or "
+            "`x-auth-request-access-token`) only. See "
+            "docs/adr/ADR-0007-cookie-only-frontend.md."
+        ),
+    },
+    {
+        "id": "BL-007",
+        "invariant": "AUTH-ME-OPAQUE",
+        "path_include": ("apps/api/src/handlers/auth_handler.cpp",),
+        "path_exclude": (),
+        "ext": None,
+        "pattern": re.compile(r'response\s*\[\s*"user_id"\s*\]\s*='),
+        "message": (
+            "ADR-0007 AUTH-ME-OPAQUE: /auth/me must return `user_ref` "
+            "(opaque HMAC of user_id), not the raw Zitadel `user_id`. See "
+            "apps/api/include/pay2u/utils/token.hpp::deriveUserRef and "
+            "docs/adr/ADR-0007-cookie-only-frontend.md."
+        ),
+    },
+    {
+        "id": "BL-004",
+        "invariant": "NO-COMMITTED-JWT",
+        "path_include": ("",),  # any path
+        "path_exclude": (
+            "scripts/bearer-lockdown-scan.sh",
+            ".gitleaks.toml",
+            ".semgrep/",
+            "docs/adr/",
+            ".policy-tools/bearer_lockdown.py",
+        ),
+        "ext": None,
+        # Require >=100 chars after header to skip truncated doc examples.
+        "pattern": re.compile(r"eyJhbGciOiJSUzI1NiI[A-Za-z0-9_-]{100,}"),
+        "message": (
+            "ADR-0007 NO-COMMITTED-JWT: RS256 JWT detected in content. "
+            "Tokens must never be committed to the repository — they are "
+            "real credentials with long TTLs. See "
+            "docs/adr/ADR-0007-cookie-only-frontend.md."
+        ),
+    },
+    {
+        # Frontend must not READ the upstream-bound auth headers from any
+        # Response. They are stripped at the gateway egress, but blocking
+        # the read at write-time prevents code that would silently break
+        # once the strip lands (or worse, ship before it lands).
+        "id": "BL-008",
+        "invariant": "XAUTH-FE-NO-READ",
+        "path_include": ("apps/web/", "apps/cms/", "apps/marketing/"),
+        "path_exclude": (
+            "/tests/",
+            "/test/",
+            ".test.",
+            ".spec.",
+            "/node_modules/",
+            "/dist/",
+        ),
+        "ext": (".js", ".ts", ".jsx", ".tsx", ".mjs", ".cjs"),
+        # Match any reference to one of the forbidden header names in
+        # string-literal form. Case-insensitive — HTTP header names are.
+        "pattern": re.compile(
+            r"""['"](?i:x-auth-request-(?:email|preferred-username|user|access-token|groups|jti)|x-forwarded-access-token)['"]""",
+        ),
+        "message": (
+            "ADR-0007 XAUTH-FE-NO-READ: frontend code must not reference "
+            "upstream-bound auth headers (`x-auth-request-*`, "
+            "`x-forwarded-access-token`). They are stripped at the "
+            "gateway egress and exist only between oauth2-proxy and the "
+            "backend API. See "
+            "infra/k8s/istio/envoyfilter-strip-auth-egress-headers.yaml "
+            "and docs/adr/ADR-0007-cookie-only-frontend.md."
+        ),
+    },
+    {
+        # Backend must not EMIT (set as response header) any of the
+        # forbidden auth-bound names. Defence-in-depth against a future
+        # handler accidentally echoing an upstream header back to the caller.
+        "id": "BL-009",
+        "invariant": "XAUTH-BE-NO-EMIT",
+        "path_include": ("apps/api/",),
+        "path_exclude": ("apps/api/tests/",),
+        "ext": (".hpp", ".cpp", ".h"),
+        # Match `set_header("authorization", ...)`,
+        # `set_header("x-auth-request-...", ...)`, etc. Case-insensitive.
+        "pattern": re.compile(
+            r"""set_header\s*\(\s*['"](?i:authorization|x-auth-request-(?:email|preferred-username|user|access-token|groups|jti)|x-forwarded-access-token|x-access-token|x-id-token)['"]""",
+        ),
+        "message": (
+            "ADR-0007 XAUTH-BE-NO-EMIT: backend handlers must not write "
+            "auth-bound headers (`Authorization`, `x-auth-request-*`, "
+            "`x-forwarded-access-token`, `x-access-token`, `x-id-token`) "
+            "into responses. The gateway strips them as a safety net but "
+            "this rule prevents the source from ever being introduced. "
+            "See docs/adr/ADR-0007-cookie-only-frontend.md."
+        ),
+    },
+]
+
+
+def _extract_write_target(op: str, args: dict[str, Any]) -> tuple[str, str] | None:
+    """Return (file_path, content) if this call writes/edits a file, else None."""
+    tool = op.lower()
+    if tool == "write":
+        fp = args.get("file_path") or ""
+        content = args.get("content") or ""
+        return fp, content
+    if tool == "edit":
+        fp = args.get("file_path") or ""
+        # For Edit, only the new_string is the newly-introduced content.
+        new = args.get("new_string") or ""
+        return fp, new
+    if tool == "multiedit":
+        fp = args.get("file_path") or ""
+        edits = args.get("edits") or []
+        content = "\n".join(e.get("new_string", "") for e in edits if isinstance(e, dict))
+        return fp, content
+    if tool == "notebookedit":
+        fp = args.get("notebook_path") or ""
+        content = args.get("new_source") or ""
+        return fp, content
+    return None
+
+
+def _path_matches(path: str, includes: tuple[str, ...], excludes: tuple[str, ...]) -> bool:
+    """True if path is under any include prefix and not under any exclude."""
+    # "" in includes means match any path.
+    if not any(inc == "" or inc in path for inc in includes):
+        return False
+    for exc in excludes:
+        if exc and exc in path:
+            return False
+    return True
+
+
+def _ext_ok(path: str, exts: tuple[str, ...] | None) -> bool:
+    if exts is None:
+        return True
+    return any(path.endswith(e) for e in exts)
+
+
+def main() -> None:
+    op, args = parse_cli()
+    target = _extract_write_target(op, args)
+    if target is None:
+        emit(True, "not a write/edit operation")
+    file_path, content = target
+    if not file_path:
+        emit(True, "no file path in args")
+
+    # Normalize: strip leading ./ or absolute prefix to repo-relative form.
+    norm = file_path.replace("\\", "/")
+    # Drop a leading absolute path portion up to the first known top-level dir.
+    for top in ("apps/", "infra/", "services/", "docs/", "scripts/", ".github/",
+                ".semgrep/", ".policy-tools/", ".claude/", "observability/"):
+        idx = norm.find(top)
+        if idx >= 0:
+            norm = norm[idx:]
+            break
+
+    violations: list[str] = []
+    for rule in RULES:
+        if not _path_matches(norm, rule["path_include"], rule["path_exclude"]):
+            continue
+        if not _ext_ok(norm, rule["ext"]):
+            continue
+        if rule["pattern"].search(content):
+            violations.append(f"[{rule['id']}] {rule['message']}")
+
+    if violations:
+        emit(
+            False,
+            "bearer-lockdown: " + " | ".join(violations),
+            violations=[v for v in violations],
+            adr="docs/adr/ADR-0007-cookie-only-frontend.md",
+        )
+    emit(True, "no bearer-lockdown violations in write")
+
+
+if __name__ == "__main__":
+    main()

package/src/policies/enforcers/local_build_before_push.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""local-build-before-push enforcer.
+
+Blocks `git push` / `gh pr create` / `gh pr merge` when the local branch
+contains C++ API source changes that have not been verified by a local
+Docker `--target builder` compile. The policy exists because the project's
+"compilation check via Docker" CI workflow takes ~50 min from scratch and
+~10-20 min cached, while running the same Dockerfile locally takes ~2-5 min
+cached. The pentest-remediation saga (2026-05-20) burned several CI cycles
+on a jwt-cpp v0.7.0 API mismatch and a sequence of wrong-audience IaC pins
+that local builds would have caught immediately.
+
+The pass marker is `.uap/local-build-pass.txt`, written by
+`scripts/uap-local-build.sh` after a successful Docker builder-stage build.
+The marker contains the verified HEAD SHA; this enforcer allows the push
+only when the current HEAD matches.
+
+Bypass: set `UAP_SKIP_LOCAL_BUILD=1` (the override should be justified in
+the commit message — there are legitimate cases like remote-only secrets).
+"""
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from _common import emit, parse_cli, repo_root, run  # noqa: E402
+
+MARKER = ".uap/local-build-pass.txt"
+
+# A push that only touches files outside these prefixes does not need the
+# local C++ compile gate. Adjust if more code paths gain expensive builds.
+BUILDABLE_PREFIXES = (
+    "apps/api/src/",
+    "apps/api/include/",
+    "apps/api/CMakeLists.txt",
+    "apps/api/Dockerfile",
+    "apps/api/Dockerfile.optimized",
+    "apps/api/Dockerfile.test",
+    "apps/api/Dockerfile.ubuntu",
+)
+
+# Bash command substrings that trigger the gate. Kept narrow to avoid
+# false-positives on unrelated git commands.
+PUSH_TRIGGERS = (
+    "git push",
+    "gh pr create",
+    "gh pr merge",
+)
+
+
+def _wants_gate(cmd_lower: str) -> bool:
+    return any(trigger in cmd_lower for trigger in PUSH_TRIGGERS)
+
+
+def _changed_files(root: Path) -> list[str]:
+    """Files changed on the current branch vs origin/main."""
+    # Make sure we have an origin/main ref to compare against; if not,
+    # fall back to comparing against HEAD~10 or HEAD itself.
+    rc, _, _ = run(["git", "show-ref", "--verify", "--quiet",
+                    "refs/remotes/origin/main"], cwd=root)
+    base = "origin/main" if rc == 0 else "HEAD~10"
+    rc, out, _ = run(["git", "diff", "--name-only", f"{base}..HEAD"], cwd=root)
+    if rc != 0:
+        return []
+    return [line for line in out.splitlines() if line]
+
+
+def main() -> None:
+    op, args = parse_cli()
+    cmd = (args.get("command") or args.get("cmd") or "").strip()
+    if not cmd or op.lower() != "bash":
+        emit(True, "not a Bash command")
+
+    cmd_lower = cmd.lower()
+    if not _wants_gate(cmd_lower):
+        emit(True, "not a push/PR-create/PR-merge command")
+
+    if os.environ.get("UAP_SKIP_LOCAL_BUILD") == "1":
+        emit(True, "UAP_SKIP_LOCAL_BUILD=1 override (justify in commit msg)")
+
+    root = repo_root()
+
+    changed = _changed_files(root)
+    needs_build = any(
+        f.startswith(p) for f in changed for p in BUILDABLE_PREFIXES
+    )
+    if not needs_build:
+        emit(True, "no buildable C++ API source changes — gate not required")
+
+    rc, head_sha, _ = run(["git", "rev-parse", "HEAD"], cwd=root)
+    head_sha = head_sha.strip()
+    if not head_sha:
+        emit(True, "could not resolve HEAD (allowing)")
+
+    marker_path = root / MARKER
+    if marker_path.exists():
+        try:
+            marker_text = marker_path.read_text()
+        except OSError:
+            marker_text = ""
+        if head_sha in marker_text:
+            emit(True, f"local-build-pass marker matches HEAD={head_sha[:10]}")
+
+    short_changed = ", ".join(sorted({
+        next((p for p in BUILDABLE_PREFIXES if f.startswith(p)), f)
+        for f in changed
+    }))[:200]
+
+    emit(
+        False,
+        "local-build-before-push: apps/api/ source changed "
+        f"({short_changed}) but no local-build-pass marker found for "
+        f"HEAD={head_sha[:10]}. Run the same Docker compile gate that CI "
+        "uses locally:\n"
+        "  bash scripts/uap-local-build.sh\n"
+        "Cached build takes ~2-5 min; CI takes ~10-50 min. If local build "
+        "is genuinely not feasible (e.g. cluster-only secret), set "
+        "UAP_SKIP_LOCAL_BUILD=1 and justify in the commit message.",
+    )
+
+
+if __name__ == "__main__":
+    main()

package/src/policies/enforcers/ship_loop_gate.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""ship-loop-gate enforcer.
+
+A task may not be marked `completed` until evidence exists for all four
+ship-loop phases. Enforcement point: `TaskUpdate` operations that set
+`status` to `completed` (and `TaskCreate` calls that try to land in
+`completed` directly).
+
+Required evidence keys (under `metadata.shipped`):
+  - merged    : PR URL or merge commit SHA. The change is on `main`.
+  - deployed  : deploy run URL / artifact ID. The change is in production.
+  - monitored : log/metric query window + result. The change isn't
+                producing new errors / regressions.
+  - verified  : behavioural assertion against the deployed change
+                (URL probed, golden-path replayed, etc.). The change
+                produces the intended user-visible outcome.
+
+Anything else (string content) is fine — the gate just checks each key
+has a non-empty value, putting the burden on the engineer to write it
+down. The values land in task metadata and become the audit trail.
+
+Why this gate exists
+--------------------
+Multiple incidents in the last quarter where work was reported as
+"done" once a PR merged, but the deploy regressed silently or the
+behaviour was never verified. The mere act of having to write down
+*proof of deploy + monitor + verify* eliminates the most common
+class of "done" lies.
+
+Bypass
+------
+Set the `metadata.shipped.bypass_reason` to a non-empty justification
+when a task legitimately cannot be verified end-to-end (docs-only PR,
+research spike, internal refactor with no deployable surface). The
+bypass still persists into task metadata so the audit trail captures
+*why* the gate was waived. Do not use bypass to dodge real verification
+on changes with a deployable surface.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+from _common import emit, parse_cli  # noqa: E402
+
+REQUIRED_EVIDENCE_KEYS = ("merged", "deployed", "monitored", "verified")
+
+
+def _example_payload() -> str:
+    return (
+        "  metadata = {\n"
+        '    "shipped": {\n'
+        '      "merged":    "PR #1234 merged at SHA abc1234",\n'
+        '      "deployed":  "cd-frontend-multicloud run 25281634698 success",\n'
+        '      "monitored": "OO logs 14:00-14:15 UTC: 0 new errors on app.pay2u.com.au",\n'
+        '      "verified":  "curl https://app.pay2u.com.au/feature returned 200 with expected payload"\n'
+        "    }\n"
+        "  }"
+    )
+
+
+def main() -> None:
+    op, args = parse_cli()
+
+    # Only fire on attempts to mark a task `completed`.
+    if op not in {"TaskUpdate", "TaskCreate"}:
+        emit(True, "ship-loop-gate: not a task-status operation")
+
+    status = (args.get("status") or "").lower()
+    if status != "completed":
+        emit(True, "ship-loop-gate: not a completion update")
+
+    metadata = args.get("metadata") or {}
+    if not isinstance(metadata, dict):
+        emit(False, "ship-loop-gate: metadata must be an object containing `shipped` evidence")
+
+    shipped = metadata.get("shipped")
+    if not isinstance(shipped, dict):
+        emit(
+            False,
+            (
+                "ship-loop-gate: cannot mark task completed — no `metadata.shipped` "
+                "evidence block. Add proof of merge + deploy + monitor + verify before "
+                "claiming Done. Example:\n"
+                f"{_example_payload()}"
+            ),
+        )
+
+    bypass = (shipped.get("bypass_reason") or "").strip()
+    if bypass:
+        emit(True, f"ship-loop-gate: bypassed with reason: {bypass}")
+
+    missing = [k for k in REQUIRED_EVIDENCE_KEYS if not str(shipped.get(k) or "").strip()]
+    if missing:
+        emit(
+            False,
+            (
+                "ship-loop-gate: cannot mark task completed — missing evidence for: "
+                f"{', '.join(missing)}. Each key under metadata.shipped must be a "
+                "non-empty string describing what happened in that phase. Use "
+                "`metadata.shipped.bypass_reason` only when the task has no "
+                "deployable surface (docs / research / pure refactor). Example:\n"
+                f"{_example_payload()}"
+            ),
+        )
+
+    emit(True, "ship-loop-gate: all four phases (merged, deployed, monitored, verified) attested")
+
+
+if __name__ == "__main__":
+    main()

package/src/policies/enforcers/workdir_scope.py

@@ -13,7 +13,8 @@ Allowed targets:
   * anything under the current working tree (UAP_WORKTREE_ROOT) or the main
     checkout (UAP_REPO_ROOT) — worktrees included;
   * relative paths (they resolve under the project root);
-  * a scratch allow-list: /tmp, $TMPDIR, ~/.cache/uap, ~/.config/uap, plus any
+  * a scratch allow-list: /tmp, $TMPDIR, ~/.cache/uap, ~/.config/uap,
+    ~/.claude/projects (Claude Code auto-memory/session storage), plus any
     colon-separated prefixes in UAP_WORKDIR_ALLOW.
 
 Escape hatch: UAP_WORKDIR_SCOPE_OFF=1 allows everything (operator override).
@@ -58,7 +59,17 @@ def _allowed_roots() -> list[Path]:
 
     add(worktree_root())
     add(repo_root())
-    for p in ("/tmp", os.environ.get("TMPDIR", "/tmp"), "~/.cache/uap", "~/.config/uap"):
+    # ~/.claude/projects is the Claude Code harness's own storage (auto-memory
+    # topic files, MEMORY.md index, session/transcript data). The harness
+    # instructs agents to persist memories there; blocking it silently breaks
+    # memory recording (observed on pay2u 2026-07-05).
+    for p in (
+        "/tmp",
+        os.environ.get("TMPDIR", "/tmp"),
+        "~/.cache/uap",
+        "~/.config/uap",
+        "~/.claude/projects",
+    ):
         add(_expand(p))
     for p in os.environ.get("UAP_WORKDIR_ALLOW", "").split(":"):
         if p.strip():

package/src/policies/schemas/policies/adr-guard.md

@@ -0,0 +1,35 @@
+# adr-guard
+
+**Category**: architecture
+**Level**: RECOMMENDED
+**Enforcement Stage**: pre-exec
+**Tags**: adr, architecture, invariants, write-gate
+
+## Rule
+
+Write/Edit tool calls MUST satisfy every machine-readable rule block declared
+in the project's ADRs. An ADR under `docs/adr/` may embed a `<!-- uap-rules
+... -->` HTML comment declaring `forbid` / `require` regexes scoped by path
+prefix, exclusion substring, and extension. A write whose content violates a
+matching rule is **blocked** with the ADR's own message.
+
+## Why
+
+Architectural and security invariants decided in an ADR decay unless they are
+enforced where the regression would be written. Declaring the rule inside the
+ADR itself keeps a single source of truth: accept the decision, and the gate
+comes with it. The policy is inert in projects whose ADRs declare no rule
+blocks.
+
+## Enforcement
+
+Python enforcer `adr_guard.py` parses `uap-rules` blocks from every ADR under
+`docs/adr/` (cached per mtime) and evaluates each Write/Edit target/content
+against the matching rules. Rule fields: `id`, `scope.include/exclude/ext`,
+`forbid` (regex must NOT match), `require` (regex MUST match), `message`.
+
+```rules
+- title: "Writes must satisfy the machine-readable rule blocks embedded in ADRs"
+  keywords: [write, edit, adr, invariant, forbid, require]
+  antiPatterns: []
+```

package/src/policies/schemas/policies/bearer-lockdown.md

@@ -0,0 +1,38 @@
+# bearer-lockdown
+
+**Category**: security
+**Level**: REQUIRED
+**Enforcement Stage**: pre-exec
+**Tags**: auth, cookie-only, bearer, security, write-gate
+
+## Rule
+
+Write/Edit tool calls MUST NOT reintroduce any cookie-only-frontend
+(ADR-0007-style) invariant violation: frontend code setting
+`Authorization: Bearer`, token keys in `localStorage`/`sessionStorage`,
+`--skip-jwt-bearer-tokens=true` on oauth2-proxy, backend reading the client
+`Authorization` header, `/auth/me` emitting a raw user id instead of an opaque
+ref, or a committed RS256 JWT. Violating writes are **blocked** at tool-call
+time.
+
+## Why
+
+A cookie-only auth architecture is one careless write away from regression,
+and CI-time scanning catches it only after the agent has already built on top
+of the mistake. Gating at write time prevents the regression from ever
+entering the tree. Mirrors the originating project's bearer-lockdown CI scan.
+
+## Enforcement
+
+Python enforcer `bearer_lockdown.py` applies per-invariant regex checks scoped
+by path (frontend trees, infra, backend). Path prefixes default to the
+originating project's layout (`apps/web/`, `apps/cms/`, `apps/marketing/`,
+`apps/api/`, `infra/`) — adjust the `path_include`/`path_exclude` tuples when
+installing into a differently-shaped repo. Runtime-only invariants (e.g.
+"Istio DENY policy alive") stay with cluster tooling, not this gate.
+
+```rules
+- title: "No write may reintroduce a bearer-token/cookie-only-frontend regression"
+  keywords: [write, edit, authorization, bearer, localStorage, jwt, oauth2-proxy]
+  antiPatterns: ["Authorization: Bearer in frontend code", "token in localStorage"]
+```

package/src/policies/schemas/policies/local-build-before-push.md

@@ -0,0 +1,38 @@
+# local-build-before-push
+
+**Category**: quality
+**Level**: RECOMMENDED
+**Enforcement Stage**: pre-exec
+**Tags**: build, push, ci, docker, compile-gate
+
+## Rule
+
+`git push` / `gh pr create` / `gh pr merge` are **blocked** while the local
+branch contains compiled-source changes (default scope: the project's C++ API
+tree) that have not passed a local Docker builder-stage compile. The pass
+marker (`.uap/local-build-pass.txt`, written by the project's local-build
+script) must record the current HEAD SHA.
+
+## Why
+
+The CI compile gate can take 10-50 minutes; the identical local Docker build
+takes 2-5 minutes cached. Pushing unverified compiled-source changes burns CI
+cycles on errors a local build catches immediately. The marker-ties-to-HEAD
+design means "built something earlier" never satisfies the gate — only the
+exact tree being pushed.
+
+## Enforcement
+
+Python enforcer `local_build_before_push.py` intercepts push/PR Bash commands,
+diffs the branch against the base, and blocks when watched paths (default
+`apps/api/` sources/CMake/Dockerfiles — adjust per project) changed without a
+matching pass marker. Bypass: `UAP_SKIP_LOCAL_BUILD=1` (session env — justify
+in the commit message). NOTE: the enforcer diffs against the LOCAL base ref;
+keep local main fast-forwarded or already-merged changes read as phantom
+diffs.
+
+```rules
+- title: "Compiled-source changes must pass a local Docker build before push/PR"
+  keywords: [git push, gh pr create, gh pr merge, docker, build, compile]
+  antiPatterns: ["push without local build verification"]
+```

package/src/policies/schemas/policies/ship-loop-gate.md

@@ -0,0 +1,35 @@
+# ship-loop-gate
+
+**Category**: process
+**Level**: REQUIRED
+**Enforcement Stage**: pre-exec
+**Tags**: ship-loop, task, completion, evidence, merge-deploy-monitor-verify
+
+## Rule
+
+A task MUST NOT be marked `completed` without evidence for all four ship-loop
+phases under `metadata.shipped`: `merged` (PR URL / merge SHA on main),
+`deployed` (deploy run URL), `monitored` (log/metric window + result), and
+`verified` (behavioural assertion against the deployed change). `TaskUpdate`
+setting `status=completed` — or `TaskCreate` landing directly in `completed` —
+without all four non-empty keys is **blocked**.
+
+## Why
+
+"Merged" is not "done": deploys regress silently and features ship dark.
+Requiring written evidence per phase turns the merge -> deploy -> monitor ->
+verify loop from a convention into a contract, and the recorded values become
+the audit trail. Companion to the `merge-deploy-monitor-verify` policy — this
+is its enforcement point at task-completion time.
+
+## Enforcement
+
+Python enforcer `ship_loop_gate.py` inspects TaskUpdate/TaskCreate arguments
+and rejects completion without the four evidence keys, echoing an example of
+the expected `metadata.shipped` shape in the denial message.
+
+```rules
+- title: "Task completion requires merged/deployed/monitored/verified evidence"
+  keywords: [taskupdate, taskcreate, completed, shipped, evidence]
+  antiPatterns: ["marking a task completed with no ship evidence"]
+```

package/src/policies/schemas/policies/workdir-scope.md

@@ -13,8 +13,11 @@ command whose create/move destination (`mkdir`, `touch`, `cp`, `mv`, `install`,
 `tee`, output redirection) — resolves OUTSIDE the working tree is **blocked**.
 
 In scope (allowed): the current working tree and main checkout (worktrees
-included), relative paths, and a scratch allow-list (`/tmp`, `$TMPDIR`,
-`~/.cache/uap`, `~/.config/uap`, plus `UAP_WORKDIR_ALLOW` prefixes).
+included), relative paths, `/dev/*` device sinks (`2>/dev/null` is not a
+write), and a scratch allow-list (`/tmp`, `$TMPDIR`, `~/.cache/uap`,
+`~/.config/uap`, `~/.claude/projects` — the Claude Code harness's own
+auto-memory/session storage, which agents are instructed to write to — plus
+`UAP_WORKDIR_ALLOW` prefixes).
 
 ## Why
 

package/tools/agents/tests/test_workdir_scope_enforcer.py

@@ -76,6 +76,16 @@ class TestWorkdirScopeEnforcer(unittest.TestCase):
         out, c = run("Write", {"file_path": "/tmp/uap-scratch/x"}, self.root)
         self._allow(out, c, "/tmp scratch")
 
+    def test_claude_memory_dir_allowed(self):
+        # ~/.claude/projects is the Claude Code harness's auto-memory/session
+        # storage; the harness instructs agents to write memories there.
+        out, c = run(
+            "Write",
+            {"file_path": str(Path.home() / ".claude/projects/-x-proj/memory/note.md")},
+            self.root,
+        )
+        self._allow(out, c, "claude memory dir")
+
     def test_worktree_path_allowed(self):
         out, c = run("Write", {"file_path": str(self.root / ".worktrees/001-x/f.ts")}, self.root)
         self._allow(out, c, "worktree path")