@miller-tech/uap 1.183.3 → 1.184.1

package/docs/reference/CONFIGURATION_REFERENCE.md

@@ -26,6 +26,7 @@ uap config wizard               # interactive expert configurator (also: uap set
 - [Orchestrator & hands-free](#orchestration) — Long-task autonomy: decompose, resume, and loop-to-100%.
 - [Reactor (auto-apply)](#reactor) — Per-prompt injection of the matching experts, skills, and patterns.
 - [Design system](#design) — DESIGN.md interrogation and the hard token gate for UI work.
+- [Engineering principles](#principles) — How code should be written, and the backward-compatibility stance.
 - [Worktree workflow](#worktree) — Branch-per-feature isolation and auto-cleanup.
 - [Inference proxy tuning](#proxy) — Guardrails and context limits for a local model behind the proxy.
 - [Dashboard](#dashboard) — The live analytics server and its mutation token.
@@ -60,6 +61,18 @@ How local-model sessions are routed through delivery. `deliver` runs builds thro
 
 **Recommendation:** `deliver` when a local model does the writing (routes it through the verified loop); `advisory` for exploratory work.
 
+### `deliver.escalateModel`
+
+| | |
+|---|---|
+| **Where** | `.uap.json` |
+| **Type** | string |
+| **Default** | `null` |
+
+Stronger model id for deliver escalation ladders: repair passes, the phase-5 escalation tier, and the evaluator fallback. Same role as $UAP_ESCALATE_MODEL but persisted in .uap.json (reproducible).
+
+**Recommendation:** Point at your strongest available preset/model (e.g. an Opus cloud id) when the executor is a local model — stuck epics then escalate instead of re-splitting into the same wall.
+
 ### `UAP_ENFORCE_DELIVERY`
 
 | | |
@@ -100,6 +113,30 @@ Installs the runtime-verify Stop-hook: at end of turn it actually runs the chang
 
 **Recommendation:** Enable for any project with a runnable artifact — it catches "declared done but never ran". Safe on empty projects (it skips when nothing is runnable).
 
+### `delivery.userValidation`
+
+| | |
+|---|---|
+| **Where** | `.uap.json` |
+| **Type** | string |
+| **Default** | `block` |
+
+User-path validation gate: deliver runs the .uap/user-paths.json critical journeys through the real client (headless browser / HTTP / built CLI) as the terminal gate rung. block = DELIVERED requires them green; advisory = report only; off = disabled.
+
+**Recommendation:** Leave on block — it is the only gate that proves the artifact works for a real user, not just that tests pass.
+
+### `UAP_USER_VALIDATION`
+
+| | |
+|---|---|
+| **Where** | shell env |
+| **Type** | boolean |
+| **Default** | `true` |
+
+Runtime downgrade for the user-validation gate: `0` demotes block to advisory for this run only. Persisting `0` is blocked by the self-protect enforcer.
+
+**Recommendation:** Leave unset. Use inline `UAP_USER_VALIDATION=0 uap deliver ...` only to unblock a run where the gate itself misfires.
+
 ### `UAP_VERIFY_ON_STOP`
 
 | | |
@@ -112,6 +149,78 @@ Master switch for the runtime execution gate in the Stop hook. `0` bypasses it.
 
 **Recommendation:** Leave on (default). Set `0` only to unblock a session where the runtime gate misfires.
 
+### `fidelity.mode`
+
+| | |
+|---|---|
+| **Where** | `.uap.json` |
+| **Type** | enum (standard \| max) |
+| **Default** | `standard` |
+
+Maximum-fidelity mode. `max` flips every verification default to its strongest: raised verifier floor (runtime+integration), acceptance judge required, blocking vision review, and a fail-CLOSED visual gate — a delivery is accepted only when it builds, runs, looks right, and matches the spec. (`UAP_FIDELITY` overrides at runtime.)
+
+**Recommendation:** `max` when correctness matters more than speed (UI work, releases, hands-free autonomy). `standard` for fast exploratory iteration.
+
+### `UAP_FIDELITY`
+
+| | |
+|---|---|
+| **Where** | shell env |
+| **Type** | enum (standard \| max) |
+| **Default** | `standard` |
+
+Runtime override of `fidelity.mode`, read from the shell env by verify/deliver and the Python enforcers. Takes precedence over the config value.
+
+**Recommendation:** Set inline (`UAP_FIDELITY=max <cmd>`) to force max fidelity for one command without editing config.
+
+### `fidelity.visionMinScore`
+
+| | |
+|---|---|
+| **Where** | `.uap.json` |
+| **Type** | number |
+| **Default** | `6` |
+
+Minimum aesthetic score (0–10) the vision judge must give a rendered UI before it passes under `max` fidelity.
+
+**Recommendation:** 6 is a reasonable "looks like a real, polished app" bar. Raise toward 8 for design-critical surfaces; lower to 4 to only catch broken/blank UIs.
+
+### `fidelity.visualBaselines`
+
+| | |
+|---|---|
+| **Where** | `.uap.json` |
+| **Type** | boolean |
+| **Default** | `true` |
+
+Keep approved UI screenshots as regression baselines under `.uap/visual/baseline/` and block on visual drift beyond threshold on later runs.
+
+**Recommendation:** Leave on so accepted UIs are pinned against regressions. Disable for throwaway prototypes where every render legitimately differs.
+
+### `UAP_VISION_ENDPOINT`
+
+| | |
+|---|---|
+| **Where** | `.uap/proxy.env` |
+| **Type** | string |
+| **Default** | `` |
+
+Base URL of an OpenAI-compatible, image_url-capable endpoint used for aesthetic screenshot review (e.g. http://127.0.0.1:8080/v1). Defaults to the local model when set by setup.
+
+**Recommendation:** Point at your local vision-capable model so aesthetic review runs offline with no per-image cost.
+
+### `UAP_VISION_MODEL`
+
+| | |
+|---|---|
+| **Where** | `.uap/proxy.env` |
+| **Type** | string |
+| **Default** | `` |
+
+Model id sent to the vision endpoint for aesthetic review (e.g. qwen36-35b-a3b-iq4xs).
+
+**Recommendation:** Set by `uap setup` to your local vision model. Required for blocking vision review under `max` fidelity.
+
 ## Model routing
 
 <a id="routing"></a>Which model handles planning, execution, and review.
@@ -482,6 +591,58 @@ Hard-blocks UI edits that hardcode off-token colors or off-scale spacing.
 
 **Recommendation:** Enable once your DESIGN.md tokens are stable — it keeps the UI on-system automatically.
 
+## Engineering principles
+
+<a id="principles"></a>How code should be written, and the backward-compatibility stance.
+
+### `principles.enabled`
+
+| | |
+|---|---|
+| **Where** | `.uap.json` |
+| **Type** | boolean |
+| **Default** | `true` |
+
+Applies the engineering principles (simplest sufficient implementation, reuse over reinvention, no stopgaps, prior art first) to generated code.
+
+**Recommendation:** Leave on. Turn it off only if your project has its own conflicting house style.
+
+### `principles.compat`
+
+| | |
+|---|---|
+| **Where** | `.uap.json` |
+| **Type** | enum (ask \| preserve \| remove) |
+| **Default** | `ask` |
+
+Backward-compatibility stance. `remove` deletes obsolete paths outright; `preserve` keeps them working and migrates callers; `ask` (default) prompts once per session instead of guessing.
+
+**Recommendation:** Leave on `ask` unless the project's answer is settled. `remove` is for side projects — on anything published it tells the agent to delete migration paths.
+
+### `principles.maturity`
+
+| | |
+|---|---|
+| **Where** | `.uap.json` |
+| **Type** | enum (ask \| greenfield \| production) |
+| **Default** | `ask` |
+
+What breaking a caller costs. `production` adds caveats about existing callers and dependency cost; `greenfield` states the rules absolutely.
+
+**Recommendation:** Set `production` for anything with real users; `greenfield` for a fresh side project.
+
+### `principles.injectDeliver`
+
+| | |
+|---|---|
+| **Where** | `.uap.json` |
+| **Type** | boolean |
+| **Default** | `true` |
+
+Injects the compact principles block into deliver prompts, so generated code follows them rather than only the agent preamble.
+
+**Recommendation:** Leave on. Disable only if you are tight on prompt budget with a small-context model.
+
 ## Worktree workflow
 
 <a id="worktree"></a>Branch-per-feature isolation and auto-cleanup.
@@ -651,6 +812,66 @@ Dashboard data refresh interval in milliseconds (floor 250).
 
 **Recommendation:** 2000 is fine; lower for a more live feel at higher CPU cost.
 
+### `proxy.dashboard`
+
+| | |
+|---|---|
+| **Where** | `.uap.json` |
+| **Type** | boolean |
+| **Default** | `true` |
+
+Ride-along dashboard: `uap proxy ensure|start` also starts (or adopts) `uap dashboard serve`, and release/stop tears it down under the same ownership rules — so a session gets monitoring without running a second command. Only takes effect where the proxy itself runs (hooks gate on proxy.autostart).
+
+**Recommendation:** Leave on. Turn off if you prefer to run `uap dash serve` yourself, or the port is spoken for.
+
+### `UAP_PROXY_DASHBOARD`
+
+| | |
+|---|---|
+| **Where** | shell env |
+| **Type** | boolean |
+| **Default** | `true` |
+
+Force the ride-along dashboard on (1/on/true) or off (0/off/false). Wins over .uap.json proxy.dashboard.
+
+**Recommendation:** Use for one-off overrides; prefer `uap proxy dashboard on|off` for a durable project setting.
+
+### `UAP_DASH_PORT`
+
+| | |
+|---|---|
+| **Where** | shell env |
+| **Type** | number |
+| **Default** | `3847` |
+
+Port the ride-along dashboard binds and is probed on (1-65535). Does not change `uap dash serve --port`.
+
+**Recommendation:** Change only on a port clash; keep it consistent across sessions so adoption works.
+
+### `UAP_DASH_HOST`
+
+| | |
+|---|---|
+| **Where** | shell env |
+| **Type** | string |
+| **Default** | `localhost` |
+
+Interface the ride-along dashboard binds. `0.0.0.0` exposes it beyond this machine.
+
+**Recommendation:** Keep localhost. Bind wider only behind a trusted network, and set UAP_DASHBOARD_TOKEN when you do.
+
+### `UAP_DASH_HEALTH_WAIT_MS`
+
+| | |
+|---|---|
+| **Where** | shell env |
+| **Type** | number |
+| **Default** | `10000` |
+
+How long `uap proxy ensure` waits for the ride-along dashboard to serve before giving up.
+
+**Recommendation:** Lower it if session start feels slow on a cold dashboard; the proxy is unaffected either way.
+
 ## Token & time optimization
 
 <a id="optimization"></a>Context budgets, caching, batching, and parallelism.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miller-tech/uap",
-  "version": "1.183.3",
+  "version": "1.184.1",
   "description": "Autonomous AI agent memory system with CLAUDE.md protocol enforcement",
   "type": "module",
   "main": "dist/index.js",
@@ -21,7 +21,7 @@
     "start": "node dist/bin/cli.js",
     "test": "vitest",
     "test:ci": "vitest run",
-    "test:enforcers": "UAP_PROXY_ENV_AUTOLOAD=0 python3 -m unittest tools.agents.tests.test_enforcement_self_protect tools.agents.tests.test_schema_diff_gate tools.agents.tests.test_stream_telemetry tools.agents.tests.test_project_telemetry_events tools.agents.tests.test_workdir_scope_enforcer tools.agents.tests.test_path_containment tools.agents.tests.test_path_normalizer_hardened tools.agents.tests.test_sandbox_tool_strip tools.agents.tests.test_proxy_env_loader tools.agents.tests.test_stream_required_tool tools.agents.tests.test_tool_call_wrapper_profiles tools.agents.tests.test_tool_convert_cache tools.agents.tests.test_doubling_break tools.agents.tests.test_error_loop_ignores_correctives tools.agents.tests.test_attractor_detection tools.agents.tests.test_client_disconnect tools.agents.tests.test_confidence_escalation tools.agents.tests.test_coordination_ban tools.agents.tests.test_coordination_early_ban tools.agents.tests.test_cycle_break_exploration tools.agents.tests.test_deferral_break tools.agents.tests.test_deliver_autoroute tools.agents.tests.test_delivery_enforcement_all_langs tools.agents.tests.test_delivery_enforcement_exemptions tools.agents.tests.test_delivery_enforcement_filepath tools.agents.tests.test_delivery_enforcement_web_and_bash tools.agents.tests.test_disconnect_watcher tools.agents.tests.test_empty_maxtokens_recovery tools.agents.tests.test_empty_tool_loop_break tools.agents.tests.test_enforcer_escape_hatches tools.agents.tests.test_error_loop_break tools.agents.tests.test_finalize_suppression tools.agents.tests.test_malformed_unclosed_think tools.agents.tests.test_mandate_beats_recon tools.agents.tests.test_mandate_deliver tools.agents.tests.test_overflow_truncate_count_tokens tools.agents.tests.test_passthrough_oauth tools.agents.tests.test_project_telemetry tools.agents.tests.test_proxy_auth_headers tools.agents.tests.test_prune_preserve_force_write tools.agents.tests.test_recon_deliver_gate tools.agents.tests.test_session_admission tools.agents.tests.test_stream_heartbeat tools.agents.tests.test_stuck_break_reattach tools.agents.tests.test_turn_count_breaker_periodic tools.agents.tests.test_upstream_chokepoint tools.agents.tests.test_vision_passthrough tools.agents.tests.test_worktree_required tools.agents.tests.test_enforcer_suite_coverage tools.agents.tests.test_validate_plan_gate tools.agents.tests.test_validate_plan_inside_project tools.agents.tests.test_anthropic_proxy_streaming tools.agents.tests.test_delivery_enforcement_worktree tools.agents.tests.test_output_token_ceilings tools.agents.tests.test_tool_narrowing_core",
+    "test:enforcers": "UAP_PROXY_ENV_AUTOLOAD=0 python3 -m unittest tools.agents.tests.test_enforcement_self_protect tools.agents.tests.test_schema_diff_gate tools.agents.tests.test_stream_telemetry tools.agents.tests.test_project_telemetry_events tools.agents.tests.test_workdir_scope_enforcer tools.agents.tests.test_expert_review_pr_scope tools.agents.tests.test_path_containment tools.agents.tests.test_path_normalizer_hardened tools.agents.tests.test_sandbox_tool_strip tools.agents.tests.test_proxy_env_loader tools.agents.tests.test_stream_required_tool tools.agents.tests.test_tool_call_wrapper_profiles tools.agents.tests.test_tool_convert_cache tools.agents.tests.test_doubling_break tools.agents.tests.test_error_loop_ignores_correctives tools.agents.tests.test_attractor_detection tools.agents.tests.test_client_disconnect tools.agents.tests.test_confidence_escalation tools.agents.tests.test_coordination_ban tools.agents.tests.test_coordination_early_ban tools.agents.tests.test_cycle_break_exploration tools.agents.tests.test_deferral_break tools.agents.tests.test_deliver_autoroute tools.agents.tests.test_delivery_enforcement_all_langs tools.agents.tests.test_delivery_enforcement_exemptions tools.agents.tests.test_delivery_enforcement_filepath tools.agents.tests.test_delivery_enforcement_web_and_bash tools.agents.tests.test_disconnect_watcher tools.agents.tests.test_empty_maxtokens_recovery tools.agents.tests.test_empty_tool_loop_break tools.agents.tests.test_enforcer_escape_hatches tools.agents.tests.test_error_loop_break tools.agents.tests.test_finalize_suppression tools.agents.tests.test_malformed_unclosed_think tools.agents.tests.test_mandate_beats_recon tools.agents.tests.test_mandate_deliver tools.agents.tests.test_overflow_truncate_count_tokens tools.agents.tests.test_passthrough_oauth tools.agents.tests.test_project_telemetry tools.agents.tests.test_proxy_auth_headers tools.agents.tests.test_prune_preserve_force_write tools.agents.tests.test_recon_deliver_gate tools.agents.tests.test_session_admission tools.agents.tests.test_stream_heartbeat tools.agents.tests.test_stuck_break_reattach tools.agents.tests.test_turn_count_breaker_periodic tools.agents.tests.test_upstream_chokepoint tools.agents.tests.test_vision_passthrough tools.agents.tests.test_worktree_required tools.agents.tests.test_enforcer_suite_coverage tools.agents.tests.test_validate_plan_gate tools.agents.tests.test_validate_plan_inside_project tools.agents.tests.test_anthropic_proxy_streaming tools.agents.tests.test_delivery_enforcement_worktree tools.agents.tests.test_output_token_ceilings tools.agents.tests.test_tool_narrowing_core",
     "test:coverage": "vitest --coverage",
     "bench": "vitest --config vitest.bench.config.ts",
     "lint": "eslint src --ext .ts",

package/src/policies/enforcers/codebase_read_before_plan.py

@@ -8,12 +8,41 @@ import time
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).parent))
-from _common import arg_str, emit, parse_cli  # noqa: E402
+from _common import arg_str, emit, parse_cli, repo_root  # noqa: E402
 
 PLAN_OPS = {"ExitPlanMode", "Plan", "TodoWrite"}
 PLAN_WORD_RE = re.compile(r"(?<![-\w/])(plan the|design the|architect the|propose a plan|spec the)", re.I)
 READ_LOG = Path(os.environ.get("UAP_STATE_DIR", ".uap")) / "read_log.state"
 RECENT_SEC = 1800
+# The PostToolUse hook that writes READ_LOG. This gate accepts evidence that
+# ONLY that hook produces, so without it the evidence can never appear.
+#
+# Checked per platform, not just under .claude/: copyHookScripts() drops the
+# script into EVERY platform's hook dir, but each platform needs its own
+# PostToolUse wiring. A hardcoded .claude/ probe would report "writer present"
+# for a Factory or Cursor session whose settings never invoke it — enforcing
+# strictly against evidence that platform cannot produce, which is the same
+# permanent block this fail-open exists to prevent.
+WRITER_HOOK_DIRS = (".claude", ".factory", ".cursor", ".codex", ".forge", ".opencode")
+WRITER_HOOK_NAME = "post-tool-use-read.sh"
+
+
+def writer_installed() -> bool:
+    """True when the hook that populates READ_LOG is installed for this platform.
+
+    Load-bearing. For a long time nothing wrote read_log.state at all: the
+    matcher was never added to settings.json, the last entries aged past
+    RECENT_SEC, and this gate then refused every ExitPlanMode with a remedy
+    ("read the codebase first") that no amount of reading could clear. A gate
+    whose writer is missing silently escalates from advisory to a wall, so when
+    the writer is absent we degrade to advisory instead of bricking planning.
+    """
+    roots = (repo_root(), Path.cwd())
+    for root in roots:
+        for hook_dir in WRITER_HOOK_DIRS:
+            if (root / hook_dir / "hooks" / WRITER_HOOK_NAME).exists():
+                return True
+    return False
 
 
 def recent_reads() -> set[str]:
@@ -41,6 +70,9 @@ def main() -> None:
     if reads:
         emit(True, f"{len(reads)} recent codebase reads on record")
 
+    if not writer_installed():
+        emit(True, "read-log writer hook not installed — gate advisory (run `uap hooks install`)")
+
     emit(
         False,
         "codebase-read-before-plan: no Read/Grep/Glob within the last 30 min. "

package/src/policies/enforcers/expert_review_required.py

@@ -2,8 +2,9 @@
 """expert-review-required enforcer: a parallel expert review must precede ship.
 
 Blocks ship actions (git commit / git push / gh pr create / merge / pr-ready /
-signoff) unless a review artifact exists for the current branch AND covers the
-current HEAD. This makes the `parallel-expert-review` skill's "REQUIRED by
+signoff) unless a review artifact exists for the branch being shipped AND covers
+its HEAD. For `gh pr merge <N>` the branch being shipped is the PR's head
+branch, resolved via gh — not whatever branch the invoking shell is on. This makes the `parallel-expert-review` skill's "REQUIRED by
 policy" claim real rather than advisory.
 
 Review artifact: .uap/reviews/<branch-slug>.json, written by the
@@ -20,6 +21,7 @@ from __future__ import annotations
 import json
 import os
 import re
+import shlex
 import sys
 from pathlib import Path
 
@@ -37,6 +39,19 @@ SHIP_PATTERNS = (
     re.compile(r"\b(pr[-_ ]?ready|sign[-_ ]?off|ready[-_ ]for[-_ ]review)\b", re.I),
 )
 
+# A ship action that NAMES a pull request. The review that matters is the one
+# for that PR's head branch, which is usually not the branch the shell is on.
+PR_SHIP_VERBS = ("merge", "ready")
+
+# Flags on those verbs that consume the NEXT token as their value. Without this,
+# `gh pr merge -b 1 900` reads "1" as the PR — so the review for PR 1 authorises
+# shipping PR 900. `gh pr merge --body Merging 123` misfires the same way by
+# accident, which is the more likely path to it happening.
+PR_VALUE_FLAGS = frozenset({
+    "-b", "--body", "-F", "--body-file", "-t", "--subject",
+    "-R", "--repo", "--match-head-commit", "-c", "--comment",
+})
+
 # Risk-scope: a parallel expert review is required only for *substantive* diffs.
 # A diff that touches ONLY low-risk surfaces (frontend/styles, docs, config,
 # tests, assets) ships freely — trivial/frontend PRs aren't gated. High-risk
@@ -115,6 +130,64 @@ def slug_for(branch: str) -> str:
     return branch.replace("%", "%25").replace("/", "%2F")
 
 
+def pr_reference(cmd: str) -> str | None:
+    """The pull request a `gh pr merge|ready` command names, or None.
+
+    Tokenized rather than pattern-matched on "digits right after the verb":
+    flags may come first (`gh pr merge --squash 645`), and gh accepts a number,
+    a URL, or a branch name interchangeably. The narrow form missed all of
+    those and fell back to the local branch — silently reinstating the very bug
+    this resolution exists to fix.
+
+    A bare `gh pr merge` (the current branch's PR) returns None, which is
+    correct: the local branch IS the right thing to check then.
+    """
+    try:
+        tokens = shlex.split(cmd, comments=True)
+    except ValueError:
+        return None
+    for i in range(len(tokens) - 2):
+        if (
+            os.path.basename(tokens[i]) == "gh"
+            and tokens[i + 1] == "pr"
+            and tokens[i + 2] in PR_SHIP_VERBS
+        ):
+            skip_value = False
+            for tok in tokens[i + 3:]:
+                if skip_value:
+                    skip_value = False
+                    continue
+                if tok.startswith("-"):
+                    # `--body=x` carries its value inline; `--body x` does not,
+                    # and that value can look exactly like a PR reference.
+                    if tok in PR_VALUE_FLAGS:
+                        skip_value = True
+                    continue
+                return tok
+            return None
+    return None
+
+
+def pr_target(root: Path, ref: str) -> tuple[str | None, str | None]:
+    """(head branch, head sha) of the PR being shipped, resolved via `gh`.
+
+    Returns (None, None) on any failure — no gh, no network, no auth, unknown
+    PR — so the caller falls back to the local branch and this stays fail-open.
+    `run` already bounds the call at 5s, and PR_SHIP_RE only matches an explicit
+    `gh pr merge/ready <N>`, so the cost is paid on ship actions, not per Bash.
+    """
+    rc, out, _ = run(
+        ["gh", "pr", "view", ref, "--json", "headRefName,headRefOid"], cwd=root
+    )
+    if rc != 0 or not out.strip():
+        return None, None
+    try:
+        data = json.loads(out)
+    except Exception:  # noqa: BLE001
+        return None, None
+    return (data.get("headRefName") or None), (data.get("headRefOid") or None)
+
+
 def head_sha(root: Path) -> str | None:
     rc, out, _ = run(["git", "rev-parse", "HEAD"], cwd=root)
     return out.strip() if rc == 0 and out.strip() else None
@@ -158,7 +231,16 @@ def main() -> None:
     # to MAIN_ROOT by the gate, so it always read the main checkout's branch and
     # demanded a review for the wrong branch on every worktree commit/push.
     root = worktree_root()
-    branch = current_branch(root)
+
+    # `gh pr merge 645` ships PR 645's branch. Reading the LOCAL branch here
+    # meant a merge run from the main checkout looked for .uap/reviews/master
+    # .json — an artifact for a branch that is not being shipped — and refused
+    # a PR whose own branch was reviewed and approved. Resolve the PR's head
+    # instead; fall back to the local branch when gh cannot answer.
+    pr_ref = pr_reference(cmd)
+    pr_branch, pr_sha = pr_target(root, pr_ref) if pr_ref else (None, None)
+
+    branch = pr_branch or current_branch(root)
     if branch is None:
         emit(True, "branch not resolvable (detached/non-git) — fail-open")
     slug = slug_for(branch)
@@ -172,7 +254,10 @@ def main() -> None:
     # migrations, or policy code — the change ships without a parallel review.
     # When the base diff is not resolvable (None) we do NOT skip: we can't prove
     # the change is low-risk, so the review requirement below still applies.
-    changed = _changed_files(root)
+    # Skipped for a PR ship: this diffs the LOCAL working tree, which on a
+    # `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)
     if changed and all(_is_low_risk(f) for f in changed):
         emit(
             True,
@@ -191,7 +276,7 @@ def main() -> None:
             "(no longer honoured inline), or a waiver file.",
         )
 
-    head = head_sha(root)
+    head = pr_sha or head_sha(root)
     try:
         data = json.loads(review.read_text())
     except Exception:  # noqa: BLE001

package/src/policies/enforcers/memory_before_plan.py

@@ -8,16 +8,34 @@ import time
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).parent))
-from _common import arg_str, emit, parse_cli, repo_root  # noqa: E402
+from _common import arg_str, emit, parse_cli, repo_root, worktree_root  # noqa: E402
 
 PLAN_OPS = {"ExitPlanMode", "Plan", "TodoWrite", "plan", "design"}
 # Only match standalone words, not compounds like 'validate-plan-on-change'
 PLAN_WORD_RE = re.compile(r"(?<![-\w/])(plan the|design the|architect the|propose a plan|roadmap for)", re.I)
 RECENT_SEC = 300
+DB_REL = Path("agents") / "data" / "memory" / "short_term.db"
 
 
-def recent_memory_query(root: Path) -> bool:
-    db = root / "agents" / "data" / "memory" / "short_term.db"
+def candidate_dbs() -> list[Path]:
+    """Every short-term DB that could hold the evidence, worktree first.
+
+    `uap memory query` writes to the DB under the CWD, which inside a worktree
+    is the WORKTREE's DB — but this gate used to read only repo_root()'s. An
+    agent doing the required query while working in a worktree (which the
+    worktree policy mandates) therefore produced evidence the gate never saw,
+    and the remedy could not clear it. Same repo_root()-vs-worktree_root() bug
+    already fixed in expert-review-required and local-build-before-push.
+    """
+    seen: list[Path] = []
+    for root in (worktree_root(), repo_root()):
+        db = root / DB_REL
+        if db not in seen:
+            seen.append(db)
+    return seen
+
+
+def recent_memory_query(db: Path) -> bool:
     if not db.exists():
         return False
     try:
@@ -48,8 +66,9 @@ def main() -> None:
     if op not in PLAN_OPS and not PLAN_WORD_RE.search(blob):
         emit(True, "not a plan operation")
 
-    if recent_memory_query(repo_root()):
-        emit(True, "recent uap memory query on record")
+    for db in candidate_dbs():
+        if recent_memory_query(db):
+            emit(True, "recent uap memory query on record")
 
     emit(
         False,