@miller-tech/uap 1.179.0 → 1.179.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miller-tech/uap",
-  "version": "1.179.0",
+  "version": "1.179.2",
   "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": "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",
+    "test:enforcers": "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",
     "test:coverage": "vitest --coverage",
     "bench": "vitest --config vitest.bench.config.ts",
     "lint": "eslint src --ext .ts",
@@ -31,7 +31,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\u2728 Run: npx @miller-tech/uap init --interactive'",
+    "postinstall": "echo '\n✨ 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/validate_plan_on_change.py

@@ -119,6 +119,49 @@ def _is_plan_file(target: str) -> bool:
     return bool(PLAN_STEM_RE.search(name[:-3]))
 
 
+def _inside_project(target: str) -> bool:
+    """True when `target` resolves to the project root or below it.
+
+    `uap plan validate` refuses any file outside the project directory, so
+    recording one creates a pending entry NOTHING can clear: every build in the
+    repo blocks, and the remedy the refusal names declines the file. Observed
+    live with a memory note under ~/.claude/, matched only because its filename
+    contained "plan".
+
+    Fails CLOSED on error (treat as inside, i.e. record it). Failing open here
+    would let a transient getcwd() error silently un-gate a plan write.
+    """
+    try:
+        root = os.path.realpath(os.getcwd())
+        abs_target = os.path.realpath(os.path.join(root, target))
+        return abs_target == root or abs_target.startswith(root + os.sep)
+    except Exception:  # noqa: BLE001
+        return True
+
+
+def _prune_unvalidatable(pending: dict) -> tuple[dict, list]:
+    """Split pending into (kept, dropped) — OUTSIDE-PROJECT entries only.
+
+    Those can never be cleared: `uap plan validate` refuses them by design, so
+    they block every build with a remedy that declines the file. This only
+    matters for state recorded before the tracking fix above.
+
+    A MISSING file is deliberately NOT pruned here. `mv PLAN.md PLAN2.md` is not
+    an edit op, so no new entry is recorded; auto-forgiving the old key on the
+    build path would make a rename a silent, unattended gate bypass with the
+    plan content fully intact. A deleted plan is dropped only by an operator
+    running `uap plan clear`, which records what it dropped and why.
+    """
+    kept: dict = {}
+    dropped: list = []
+    for key, seen in pending.items():
+        if not _inside_project(key):
+            dropped.append(key)
+        else:
+            kept[key] = seen
+    return kept, dropped
+
+
 def _key(target: str) -> str:
     """Repo-relative, forward-slashed — the shape `uap plan validate` records."""
     posix = target.replace(os.sep, "/")
@@ -148,6 +191,8 @@ def _refuse(paths: list[str], why: str) -> None:
         "risks, and whether it still matches the request.\n"
         f"  2. Record it: `uap plan validate {sorted(paths)[0]}`.\n"
         "  3. Retry this command.\n"
+        "(If validation refuses the file — outside the project, or deleted — it can "
+        "never clear: `uap plan status` names it and `uap plan clear` drops it.)\n"
         "(Escape hatch, justify in the plan/PR: UAP_PLAN_VALIDATE_OFF=1.)",
         inject_prompt="validate the plan",
     )
@@ -164,6 +209,9 @@ def main() -> None:
         target = _target(args)
         if not _is_plan_file(target):
             emit(True, "not a plan artifact")
+        # Only track what `uap plan validate` can actually validate.
+        if not _inside_project(target):
+            emit(True, "plan artifact outside the project — not tracked")
         state = _load_state()
         pending = state.get("pending") or {}
         pending[_key(target)] = int(time.time())
@@ -181,7 +229,20 @@ def main() -> None:
         emit(True, "not a build/execute/deploy command")
 
     state = _load_state()
-    pending = list((state.get("pending") or {}).keys())
+    # Drop legacy entries `uap plan validate` can never clear, recording what was
+    # dropped so a shrinking blocking set is auditable.
+    pending_map = state.get("pending") or {}
+    kept, dropped = _prune_unvalidatable(pending_map)
+    if dropped:
+        state["pending"] = kept
+        cleared = list(state.get("cleared") or [])
+        cleared.extend(
+            {"key": k, "reason": "outside the project directory", "at": int(time.time())}
+            for k in dropped
+        )
+        state["cleared"] = cleared[-50:]
+        _save_state(state)
+    pending = list(kept.keys())
     if pending:
         _refuse(pending, "these plans were created or modified and never validated")
 

package/src/policies/schemas/policies/validate-plan-on-change.md

@@ -59,10 +59,14 @@ State in `.uap/plan_state.json` (honours `UAP_STATE_DIR`), shared with
 ```json
 {
   "pending":   { "<repo-relative path>": "<epoch seen>" },
-  "validated": { "<repo-relative path>": "<sha256 of the reviewed bytes>" }
+  "validated": { "<repo-relative path>": "<sha256 of the reviewed bytes>" },
+  "cleared":   [ { "key": "<path>", "reason": "<why unreachable>", "at": "<epoch>" } ]
 }
 ```
 
+`cleared` is the audit trail of pending entries dropped as UNREACHABLE. The
+blocking set only shrinks through validation or through a recorded drop.
+
 Gated commands: `uap deliver`, `npm run build`, `npm start`, `yarn`/`pnpm build`,
 `make`, `cargo build|run`, `go build|run`, `mvn package|install`,
 `gradle build`, `docker build`, `docker compose up`, `terraform apply`,
@@ -75,4 +79,12 @@ Everything not listed is allowed; there is no second allowlist to keep in sync.
 Escape hatch, justify in the plan/PR: `UAP_PLAN_VALIDATE_OFF=1`.
 
 `uap plan status` reports exactly what the gate is waiting on (pending plans and
-plans that have drifted since validation).
+plans that have drifted since validation), listing separately any entry that is
+UNREACHABLE — one validation can never clear, because the file is outside the
+project, deleted, or unreadable.
+
+`uap plan clear` drops those unreachable entries and records them under
+`cleared`. It REFUSES a plan that is present and reviewable, pointing back at
+`uap plan validate`: it is a recovery hatch for a wedged gate, not a way to skip
+review. Without it the only exit from a wedge was editing the state file by
+hand.

package/tools/agents/scripts/anthropic_proxy.py

@@ -393,12 +393,55 @@ def _error_signature(text: str) -> str:
         return ""
     if _NEGATED_FAILURE_RE.search(line):
         return ""
+    return _normalize_error_line(line)
+
+
+def _normalize_error_line(line: str) -> str:
+    """Edit-invariant form of one error line: paths, hex and digits collapsed."""
     line = re.sub(r"(/[^\s:]+)+", "<path>", line)          # unix paths
     line = re.sub(r"\b[0-9a-fA-F]{6,}\b", "<hex>", line)    # hashes/addresses
     line = re.sub(r"\d+", "#", line)                        # line numbers, counts
     line = re.sub(r"\s+", " ", line).strip().lower()
     return line[:200]
 
+
+def _error_signature_for_result(text: str, result_error: bool | None = None) -> str:
+    """Signature for a tool_result, honouring the protocol's own `is_error`.
+
+    Keyword sniffing cannot tell a program REPORTING a failure from a file that
+    merely CONTAINS the word. Observed live (2026-07-31): the model read a Python
+    source file, `_ERROR_LINE_RE` matched the line
+
+        except Exception:  # noqa: BLE001 - unreadable state must not break ...
+
+    and three reads of the same file produced three identical "failures" — so
+    ERROR-LOOP fired and told the model to re-read the file it had just read.
+    Reading a file is the single most common thing an agent does; any file whose
+    text contains `Exception`, `error`, or `not found` could manufacture a streak.
+
+    The transcript already carries the answer. A tool_result has an `is_error`
+    flag, and the DOUBLING-DOWN guard has always preferred it over the keyword
+    heuristics; ERROR-LOOP computed its signature from the text and threw the
+    flag away. Now:
+
+      is_error False -> a clean result. No signature, whatever the bytes say.
+      is_error True  -> a real failure. Signature from the text, and if none of
+                        the keywords match, from its first meaningful line, so
+                        an unfamiliar error shape still forms a streak.
+      absent         -> fall back to the keyword heuristics as before.
+    """
+    if result_error is False:
+        return ""
+    sig = _error_signature(text)
+    if sig or result_error is not True:
+        return sig
+    # Declared an error, but shaped like nothing we recognise. Anchor the streak
+    # on the first meaningful line rather than losing the failure entirely.
+    for raw in (text or "").splitlines():
+        if raw.strip():
+            return _normalize_error_line(raw)
+    return ""
+
 # ---------------------------------------------------------------------------
 # DEFERRAL-BREAK guardrail (Fix A): a model can end a turn with plain prose that
 # DEFERS the work instead of doing it -- "I need more exploration cycles to
@@ -1786,15 +1829,23 @@ class SessionMonitor:
                     by_tool = self.tool_target_history.setdefault(name, {})
                     by_tool[target] = by_tool.get(target, 0) + 1
 
-    def note_tool_result_error(self, latest_result_text: str) -> None:
+    def note_tool_result_error(
+        self, latest_result_text: str, result_error: bool | None = None
+    ) -> None:
         """Track a repeated tool_result error signature (ERROR-LOOP guardrail).
 
         Same normalized error as last turn -> increment the streak; a new error
         or a clean (error-free) result -> reset. Only a SUSTAINED same-failure
-        streak (despite the model's varied edits) trips the nudge."""
+        streak (despite the model's varied edits) trips the nudge.
+
+        result_error is the tool_result `is_error` flag when the client sent one.
+        It beats the keyword heuristics in both directions — see
+        _error_signature_for_result. The caller has always computed this flag;
+        it just was not passed here, so reading a file containing the word
+        `Exception` three times looked exactly like failing three times."""
         if not PROXY_ERROR_LOOP:
             return
-        sig = _error_signature(latest_result_text or "")
+        sig = _error_signature_for_result(latest_result_text or "", result_error)
         if sig and sig == self.last_error_signature:
             self.error_signature_streak += 1
         elif sig:
@@ -6773,7 +6824,7 @@ def _record_last_assistant_tool_calls(
                 if _flags:
                     _latest_err = any(_flags)
                 break
-    monitor.note_tool_result_error(_latest_tr)
+    monitor.note_tool_result_error(_latest_tr, _latest_err)
     tool_fingerprints = []
     tool_targets: dict[str, str] = {}
     assistant_had_text = False  # Fix B: did the last assistant turn emit prose?

package/tools/agents/tests/test_error_loop_ignores_correctives.py

@@ -52,10 +52,12 @@ def _load_signature():
     start = src.index("_ERROR_LINE_RE = re.compile(")
     end = src.index("\n# ---", src.index("def _error_signature"))
     exec(src[start:end], ns)  # noqa: S102 - reading our own source, not input
-    return ns["_error_signature"]
+    return ns
 
 
-_error_signature = _load_signature()
+_NS = _load_signature()
+_error_signature = _NS["_error_signature"]
+_error_signature_for_result = _NS["_error_signature_for_result"]
 
 
 class TestHarnessCorrectivesAreNotFailures(unittest.TestCase):
@@ -164,3 +166,90 @@ class TestDeniedFailuresInPlainProse(unittest.TestCase):
             "2 tests failed",
         ):
             assert _error_signature(line) != "", line
+
+
+# The source file the model was reading when ERROR-LOOP fired on 2026-07-31.
+# Nothing failed; this is a file's CONTENTS, delivered as a successful Read.
+SOURCE_FILE_READ = '''def _load_state() -> dict:
+    try:
+        data = json.loads(_state_path().read_text())
+        return data if isinstance(data, dict) else {}
+    except Exception:  # noqa: BLE001 - unreadable state must not break the tool call
+        return {}
+'''
+
+
+class TestIsErrorFlagBeatsKeywords(unittest.TestCase):
+    """A file that CONTAINS "Exception" is not a failure.
+
+    Keyword sniffing cannot tell a program reporting a failure from a file that
+    merely mentions one. Reading a file is the most common thing an agent does,
+    so any source containing `Exception`, `error` or `not found` could
+    manufacture a streak — and did: three reads of one file produced three
+    identical signatures, and ERROR-LOOP told the model to re-read the file it
+    had just read.
+    """
+
+    def test_a_successful_read_never_produces_a_signature(self):
+        self.assertEqual(_error_signature_for_result(SOURCE_FILE_READ, False), "")
+
+    def test_three_successful_reads_cannot_arm_the_guard(self):
+        # Three was the threshold, and re-reading a file is not a failure streak.
+        sigs = {_error_signature_for_result(SOURCE_FILE_READ, False) for _ in range(3)}
+        self.assertEqual(sigs, {""})
+
+    def test_is_error_false_wins_over_a_real_looking_traceback(self):
+        # `cat` of a log file full of tracebacks is still a successful read.
+        text = "Traceback (most recent call last):\nTypeError: x is not a function"
+        self.assertEqual(_error_signature_for_result(text, False), "")
+
+    def test_is_error_true_still_produces_a_signature(self):
+        text = "ERROR: TypeError: x is not a function at /a/b.js:12"
+        self.assertNotEqual(_error_signature_for_result(text, True), "")
+
+    def test_is_error_true_with_an_unfamiliar_shape_still_forms_a_streak(self):
+        # The client declared a failure; losing it because no keyword matched
+        # would be the opposite mistake — a real repeated failure going untracked.
+        text = "the frobnicator declined\nmore detail here"
+        sig = _error_signature_for_result(text, True)
+        self.assertNotEqual(sig, "")
+        self.assertEqual(sig, _error_signature_for_result(text, True))  # stable
+
+    def test_without_the_flag_the_old_heuristics_still_apply(self):
+        # Clients that never send is_error must keep working exactly as before.
+        self.assertNotEqual(_error_signature_for_result("ERROR: SyntaxError: bad", None), "")
+        self.assertEqual(_error_signature_for_result("all tests passed", None), "")
+        self.assertEqual(
+            _error_signature_for_result(SOURCE_FILE_READ, None), _error_signature(SOURCE_FILE_READ)
+        )
+
+    def test_an_empty_declared_error_does_not_crash(self):
+        self.assertEqual(_error_signature_for_result("", True), "")
+        self.assertEqual(_error_signature_for_result("   \n\n ", True), "")
+
+
+class TestTheFlagIsActuallyWiredThrough(unittest.TestCase):
+    """The logic above is worthless if the caller never passes the flag.
+
+    That was the whole bug: the request handler computed `_latest_err` from the
+    tool_result blocks and then called `note_tool_result_error(_latest_tr)`,
+    dropping it. Every unit test passed. Reverting the call site to the one-arg
+    form — i.e. restoring the live bug exactly — still passes the entire suite,
+    which is why this asserts on the source.
+    """
+
+    def test_the_request_handler_passes_the_is_error_flag(self):
+        src = PROXY.read_text()
+        assert "_latest_err" in src, "the handler no longer computes the is_error flag"
+        assert re.search(r"note_tool_result_error\(\s*_latest_tr\s*,\s*_latest_err\s*\)", src), (
+            "note_tool_result_error is called without the is_error flag — reading a file that "
+            "contains the word 'Exception' will manufacture a failure streak again"
+        )
+
+    def test_the_signature_helper_is_the_one_being_used(self):
+        # A refactor that quietly points the monitor back at _error_signature
+        # would reinstate the keyword-only behaviour.
+        src = PROXY.read_text()
+        assert re.search(
+            r"sig = _error_signature_for_result\(latest_result_text or \"\", result_error\)", src
+        ), "note_tool_result_error no longer routes through _error_signature_for_result"

package/tools/agents/tests/test_validate_plan_inside_project.py

@@ -0,0 +1,106 @@
+"""validate-plan-on-change: only track what `uap plan validate` can validate.
+
+The enforcer recorded ANY plan-named file it saw written, including paths
+outside the project. `uap plan validate` refuses those ("explicit plan file must
+live under the project directory"), so the entry could never be cleared: every
+build in the repo blocked, and the remedy the refusal named declined the file.
+Observed live with a memory note at
+~/.claude/projects/<slug>/memory/plan_gate_before_build.md — not a plan at all,
+matched only because its filename contains "plan".
+
+The rename case is the one to guard hardest. `mv PLAN.md PLAN2.md` is not an
+edit op, so no new pending entry is recorded; auto-forgiving the old key on the
+build path would make a rename a silent, unattended gate bypass with the plan
+content fully intact. An earlier draft of this change did exactly that.
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+ENFORCER = Path(__file__).resolve().parents[3] / "src" / "policies" / "enforcers" / "validate_plan_on_change.py"
+
+
+def run(cwd: str, op: str, args: dict) -> str:
+    proc = subprocess.run(
+        [sys.executable, str(ENFORCER), "--operation", op, "--args", json.dumps(args)],
+        capture_output=True,
+        text=True,
+        cwd=cwd,
+    )
+    return proc.stdout + proc.stderr
+
+
+def state(cwd: str) -> dict:
+    path = Path(cwd) / ".uap" / "plan_state.json"
+    return json.loads(path.read_text()) if path.exists() else {}
+
+
+class TestPlanGateTracksOnlyProjectFiles(unittest.TestCase):
+    def setUp(self) -> None:
+        self._tmp = tempfile.TemporaryDirectory()
+        self.cwd = self._tmp.name
+        os.makedirs(os.path.join(self.cwd, "docs", "plans"), exist_ok=True)
+
+    def tearDown(self) -> None:
+        self._tmp.cleanup()
+
+    def test_outside_project_plan_is_not_tracked(self) -> None:
+        out = run(self.cwd, "Write", {"file_path": "/tmp/elsewhere/stray-plan.md"})
+        self.assertIn("outside the project", out)
+        self.assertEqual(state(self.cwd).get("pending", {}), {})
+
+    def test_in_project_plan_is_still_tracked(self) -> None:
+        Path(self.cwd, "docs", "plans", "real-plan.md").write_text("# real")
+        run(self.cwd, "Write", {"file_path": "docs/plans/real-plan.md"})
+        self.assertIn("docs/plans/real-plan.md", state(self.cwd).get("pending", {}))
+
+    def test_build_is_blocked_and_names_the_recovery_command(self) -> None:
+        Path(self.cwd, "docs", "plans", "real-plan.md").write_text("# real")
+        run(self.cwd, "Write", {"file_path": "docs/plans/real-plan.md"})
+        out = run(self.cwd, "Bash", {"command": "npm run build"})
+        self.assertIn("never validated", out)
+        # A wedged agent must not be sent to the one command that declines the file.
+        self.assertIn("uap plan clear", out)
+
+    def test_renaming_a_pending_plan_does_not_forgive_it(self) -> None:
+        plan = Path(self.cwd, "docs", "plans", "real-plan.md")
+        plan.write_text("# real")
+        run(self.cwd, "Write", {"file_path": "docs/plans/real-plan.md"})
+        plan.rename(Path(self.cwd, "docs", "plans", "real-plan-v2.md"))
+
+        out = run(self.cwd, "Bash", {"command": "npm run build"})
+        self.assertIn("never validated", out)
+        self.assertIn("docs/plans/real-plan.md", state(self.cwd).get("pending", {}))
+
+    def test_legacy_outside_entry_is_pruned_and_audited(self) -> None:
+        Path(self.cwd, "docs", "plans", "real-plan.md").write_text("# real")
+        run(self.cwd, "Write", {"file_path": "docs/plans/real-plan.md"})
+        st = state(self.cwd)
+        st.setdefault("pending", {})["/home/somewhere/legacy-plan.md"] = 1
+        Path(self.cwd, ".uap", "plan_state.json").write_text(json.dumps(st))
+
+        run(self.cwd, "Bash", {"command": "npm run build"})
+        st = state(self.cwd)
+        self.assertNotIn("/home/somewhere/legacy-plan.md", st.get("pending", {}))
+        # The in-project plan still gates the build.
+        self.assertIn("docs/plans/real-plan.md", st.get("pending", {}))
+        # A shrinking blocking set must leave a trail.
+        cleared = st.get("cleared", [])
+        self.assertEqual(len(cleared), 1)
+        self.assertEqual(cleared[0]["key"], "/home/somewhere/legacy-plan.md")
+        self.assertIn("outside the project", cleared[0]["reason"])
+
+    def test_non_plan_writes_are_untouched(self) -> None:
+        out = run(self.cwd, "Write", {"file_path": "src/index.ts"})
+        self.assertIn("not a plan artifact", out)
+        self.assertEqual(state(self.cwd).get("pending", {}), {})
+
+
+if __name__ == "__main__":
+    unittest.main()

package/docs/patches/validate-plan-on-change-inside-project.patch

@@ -1,154 +0,0 @@
-# validate-plan-on-change: stop the gate wedging on paths it cannot validate
-#
-# The enforcer records ANY plan-named file it sees written, including paths
-# OUTSIDE the project. `uap plan validate` refuses those ('explicit plan file
-# must live under the project directory'), so such an entry can never be
-# cleared: every build in the repo blocks, and the remedy the refusal names
-# declines the file. Observed live: a memory note at
-# ~/.claude/projects/<slug>/memory/plan_gate_before_build.md — not a plan at
-# all, matched only because its filename contains 'plan' — blocked the repo
-# until .uap/plan_state.json was edited by hand.
-#
-# This patch:
-#   1. stop TRACKING plan files outside the project (the root cause);
-#   2. prune legacy outside-project entries, with an audit record;
-#   3. point the refusal at `uap plan clear` when validation cannot help.
-#
-# It deliberately does NOT auto-prune entries whose file is merely MISSING.
-# `mv PLAN.md PLAN2.md` is not an edit op, so no new entry is recorded — and
-# forgiving the old key on the build path would turn a rename into a silent,
-# unattended gate bypass with the plan content fully intact. A deleted plan is
-# dropped only by an operator running `uap plan clear`, which records it.
-#
-# `src/policies/enforcers/**` is protected by Enforcement Self-Protect, so an
-# agent cannot apply this. Operator, from the repo root:
-#
-#     git apply docs/patches/validate-plan-on-change-inside-project.patch
-#
-# `uap plan clear` (shipped in this PR) recovers an ALREADY-wedged gate without
-# this patch; the patch is what stops the wedge recurring.
-
---- a/src/policies/enforcers/validate_plan_on_change.py
-+++ b/src/policies/enforcers/validate_plan_on_change.py
-@@ -119,6 +119,49 @@
-     return bool(PLAN_STEM_RE.search(name[:-3]))
- 
- 
-+def _inside_project(target: str) -> bool:
-+    """True when `target` resolves to the project root or below it.
-+
-+    `uap plan validate` refuses any file outside the project directory, so
-+    recording one creates a pending entry NOTHING can clear: every build in the
-+    repo blocks, and the remedy the refusal names declines the file. Observed
-+    live with a memory note under ~/.claude/, matched only because its filename
-+    contained "plan".
-+
-+    Fails CLOSED on error (treat as inside, i.e. record it). Failing open here
-+    would let a transient getcwd() error silently un-gate a plan write.
-+    """
-+    try:
-+        root = os.path.realpath(os.getcwd())
-+        abs_target = os.path.realpath(os.path.join(root, target))
-+        return abs_target == root or abs_target.startswith(root + os.sep)
-+    except Exception:  # noqa: BLE001
-+        return True
-+
-+
-+def _prune_unvalidatable(pending: dict) -> tuple[dict, list]:
-+    """Split pending into (kept, dropped) — OUTSIDE-PROJECT entries only.
-+
-+    Those can never be cleared: `uap plan validate` refuses them by design, so
-+    they block every build with a remedy that declines the file. This only
-+    matters for state recorded before the tracking fix above.
-+
-+    A MISSING file is deliberately NOT pruned here. `mv PLAN.md PLAN2.md` is not
-+    an edit op, so no new entry is recorded; auto-forgiving the old key on the
-+    build path would make a rename a silent, unattended gate bypass with the
-+    plan content fully intact. A deleted plan is dropped only by an operator
-+    running `uap plan clear`, which records what it dropped and why.
-+    """
-+    kept: dict = {}
-+    dropped: list = []
-+    for key, seen in pending.items():
-+        if not _inside_project(key):
-+            dropped.append(key)
-+        else:
-+            kept[key] = seen
-+    return kept, dropped
-+
-+
- def _key(target: str) -> str:
-     """Repo-relative, forward-slashed — the shape `uap plan validate` records."""
-     posix = target.replace(os.sep, "/")
-@@ -148,6 +191,8 @@
-         "risks, and whether it still matches the request.\n"
-         f"  2. Record it: `uap plan validate {sorted(paths)[0]}`.\n"
-         "  3. Retry this command.\n"
-+        "(If validation refuses the file — outside the project, or deleted — it can "
-+        "never clear: `uap plan status` names it and `uap plan clear` drops it.)\n"
-         "(Escape hatch, justify in the plan/PR: UAP_PLAN_VALIDATE_OFF=1.)",
-         inject_prompt="validate the plan",
-     )
-@@ -164,6 +209,9 @@
-         target = _target(args)
-         if not _is_plan_file(target):
-             emit(True, "not a plan artifact")
-+        # Only track what `uap plan validate` can actually validate.
-+        if not _inside_project(target):
-+            emit(True, "plan artifact outside the project — not tracked")
-         state = _load_state()
-         pending = state.get("pending") or {}
-         pending[_key(target)] = int(time.time())
-@@ -181,7 +229,20 @@
-         emit(True, "not a build/execute/deploy command")
- 
-     state = _load_state()
--    pending = list((state.get("pending") or {}).keys())
-+    # Drop legacy entries `uap plan validate` can never clear, recording what was
-+    # dropped so a shrinking blocking set is auditable.
-+    pending_map = state.get("pending") or {}
-+    kept, dropped = _prune_unvalidatable(pending_map)
-+    if dropped:
-+        state["pending"] = kept
-+        cleared = list(state.get("cleared") or [])
-+        cleared.extend(
-+            {"key": k, "reason": "outside the project directory", "at": int(time.time())}
-+            for k in dropped
-+        )
-+        state["cleared"] = cleared[-50:]
-+        _save_state(state)
-+    pending = list(kept.keys())
-     if pending:
-         _refuse(pending, "these plans were created or modified and never validated")
- 
---- a/src/policies/schemas/policies/validate-plan-on-change.md
-+++ b/src/policies/schemas/policies/validate-plan-on-change.md
-@@ -59,9 +59,13 @@
- ```json
- {
-   "pending":   { "<repo-relative path>": "<epoch seen>" },
--  "validated": { "<repo-relative path>": "<sha256 of the reviewed bytes>" }
-+  "validated": { "<repo-relative path>": "<sha256 of the reviewed bytes>" },
-+  "cleared":   [ { "key": "<path>", "reason": "<why unreachable>", "at": "<epoch>" } ]
- }
- ```
-+
-+`cleared` is the audit trail of pending entries dropped as UNREACHABLE. The
-+blocking set only shrinks through validation or through a recorded drop.
- 
- Gated commands: `uap deliver`, `npm run build`, `npm start`, `yarn`/`pnpm build`,
- `make`, `cargo build|run`, `go build|run`, `mvn package|install`,
-@@ -75,4 +79,12 @@
- Escape hatch, justify in the plan/PR: `UAP_PLAN_VALIDATE_OFF=1`.
- 
- `uap plan status` reports exactly what the gate is waiting on (pending plans and
--plans that have drifted since validation).
-+plans that have drifted since validation), listing separately any entry that is
-+UNREACHABLE — one validation can never clear, because the file is outside the
-+project, deleted, or unreadable.
-+
-+`uap plan clear` drops those unreachable entries and records them under
-+`cleared`. It REFUSES a plan that is present and reviewable, pointing back at
-+`uap plan validate`: it is a recovery hatch for a wedged gate, not a way to skip
-+review. Without it the only exit from a wedge was editing the state file by
-+hand.