@miller-tech/uap 1.105.0 → 1.107.0

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/templates/hooks/session-start.sh

@@ -241,6 +241,15 @@ if [ -f "$TASK_DB" ] && [ "$TASK_BLOCKED" -gt 0 ]; then
   fi
 fi
 
+# Hands-free auto-resume: surface an in-progress build's remaining work so the
+# session picks it back up without being asked. Silent when nothing is pending.
+if command -v uap >/dev/null 2>&1; then
+  resume_banner="$( ( cd "$PROJECT_DIR" 2>/dev/null && uap handsfree resume-banner 2>/dev/null ) || true )"
+  if [ -n "$resume_banner" ]; then
+    output+=$'\n'"$resume_banner"$'\n'
+  fi
+fi
+
 if [ -n "$output" ]; then
   echo "$output"
 fi

package/templates/hooks/uap-todo-ledger.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# UAP Hands-free auto-seed — PostToolUse(TodoWrite)
+# Mirror the model's plan (TodoWrite todo list) into the completion ledger so an
+# interactive multi-step build auto-seeds a ledger with zero manual `init`.
+# Silent, fail-open: never blocks or perturbs the session.
+set -uo pipefail
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-${FACTORY_PROJECT_DIR:-${CURSOR_PROJECT_DIR:-.}}}"
+INPUT="$(timeout 2 cat 2>/dev/null || true)"
+if command -v uap >/dev/null 2>&1; then
+  ( cd "$PROJECT_DIR" && printf '%s' "$INPUT" | uap handsfree sync-todos >/dev/null 2>&1 ) || true
+fi
+exit 0

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")