@miller-tech/uap 1.184.1 → 1.184.3

package/docs/guides/POLICIES.md

@@ -194,43 +194,52 @@ the next tool call.
 
 ## Changing an enforcer's code
 
-Two things trip people up here, and both fail *silently* — the source looks
-fixed while the gate keeps enforcing the old behaviour.
+Three things trip people up here, and all of them fail *silently* — the source
+looks fixed, `uap policy install` prints success, and the gate goes on
+enforcing the old behaviour.
 
 **1. The gate does not run `src/policies/enforcers/*.py`.** It runs
 `.policy-tools/<policyId>_<toolName>.py`, a separate materialized copy (plus a
 snapshot in the `code` column of `policies.db`). Editing the source changes
-nothing on its own — re-run `uap policy install <slug>` to refresh the
-executable copy:
+nothing on its own — the executable copy has to be refreshed by
+`uap policy install <slug>`.
+
+**2. `uap policy install` reads the enforcer from the RUNNING PACKAGE, not from
+your repo.** `resolvePolicyDir()` resolves `src/policies/enforcers/` relative to
+the installed package first, and only falls back to `process.cwd()` — deliberately,
+so that `uap` works in projects that are not this repo. When `uap` is the global
+install, editing this repo's enforcer and running `uap policy install` copies the
+**global package's** version, and the message still says
+"attached enforcer … from src/policies/enforcers/…".
+
+So an enforcer change reaches the running gate only after the package the `uap`
+binary comes from contains it:
 
 ```bash
+which uap                       # /usr/local/bin/uap -> the global install?
+uap --version                   # does it match this repo's package.json?
+
+npm i -g .                      # from the repo, after the fix is merged
 uap policy install workdir-scope
 grep -l _my_new_function .policy-tools/*workdir_scope.py   # verify it took
 ```
 
-**2. Run that install from the MAIN checkout, not a worktree.** The policy gate
-anchors runtime state — `policies.db` and `.policy-tools/` — to `MAIN_ROOT`, so
-that every worktree enforces the same policies. `uap policy install` run from
-inside a worktree gets this wrong in *both* directions, while still printing
-success:
-
-- it **reads** the enforcer source from the main checkout (not the worktree's
-  edited copy), and
-- it **writes** the materialized copy into a worktree-local `.policy-tools/`
-  that the gate never reads.
+That last `grep` is the only real confirmation. A byte-size comparison against
+the enforcer source works too: a mismatch means the copy came from somewhere else.
 
-So the install is a no-op for enforcement, and it is silent about it: the
-edited enforcer is verified by the test suite (which reads the worktree source)
-while the running gate still executes the old code. Verified 2026-08-03 by
-comparing the materialized copy against both sources — it matched the main
-checkout byte for byte.
+**3. Run the install from the MAIN checkout, not a worktree.** The gate anchors
+runtime state — `policies.db` and `.policy-tools/` — to `MAIN_ROOT`, so every
+worktree enforces the same policies. Run from inside a worktree, the install
+writes a worktree-local `.policy-tools/` that the gate never reads.
 
-So an enforcer fix is two separate steps in two different directories:
+Put together, an enforcer fix is three steps in two directories:
 
 - edit the enforcer **in your worktree**, so the change ships in the PR;
-- after it merges, run `uap policy install <slug>` **from the main checkout** to
-  refresh the runtime copy.
+- after it merges, update the package the `uap` binary resolves to
+  (`npm i -g .` from the main checkout, or install the published version);
+- run `uap policy install <slug>` **from the main checkout**, and verify the
+  materialized copy actually changed.
 
 Note that `enforcement-self-protect` blocks agent writes to `src/policies/**`
-outright, with no model-reachable bypass. An agent cannot make either change —
-enforcer edits are an operator action by design.
+outright, with no model-reachable bypass. An agent cannot make any of these
+changes — enforcer edits are an operator action by design.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miller-tech/uap",
-  "version": "1.184.1",
+  "version": "1.184.3",
   "description": "Autonomous AI agent memory system with CLAUDE.md protocol enforcement",
   "type": "module",
   "main": "dist/index.js",

package/src/policies/enforcers/expert_review_required.py

@@ -27,7 +27,8 @@ from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).parent))
 from _common import (  # noqa: E402
-    emit, parse_cli, worktree_root, run, REVIEW_ARTIFACT_DIR, REVIEW_WAIVER_DIR,
+    emit, parse_cli, worktree_root, run, strip_heredoc_bodies,
+    REVIEW_ARTIFACT_DIR, REVIEW_WAIVER_DIR,
 )
 
 # Ship verbs are anchored to their tool prefix so that the bare tokens "merge"
@@ -39,6 +40,133 @@ SHIP_PATTERNS = (
     re.compile(r"\b(pr[-_ ]?ready|sign[-_ ]?off|ready[-_ ]for[-_ ]review)\b", re.I),
 )
 
+# Additional, command-position detection: `git -C <path> push` is a real ship
+# action that the patterns above never matched (they require git and the
+# subcommand to be adjacent). Unioned with them, so it only ever ADDS coverage.
+GIT_SHIP_SUBCOMMANDS = frozenset({"commit", "push", "merge"})
+GIT_VALUE_OPTIONS = frozenset({"-C", "-c", "--git-dir", "--work-tree", "--namespace"})
+WRAPPER_VERBS = frozenset({
+    "rtk", "env", "nohup", "sudo", "time", "command", "timeout", "stdbuf",
+})
+_SEGMENT_SPLIT = re.compile(r"(?:\|\||&&|[;\n|&])")
+_ENV_ASSIGN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*=\S*$")
+
+
+# Verbs that PRINT or SEARCH their arguments rather than executing them.
+# Quoted text is treated as prose only for these.
+#
+# An allowlist, deliberately. The inverse — masking by default and listing
+# the executors to exempt — cannot be completed: bash -c, python -c, perl -e,
+# su -c, script -qc, fish -c, parallel, expect ... every review round found
+# another, and `script -qc 'git push' /dev/null` really does ship. An
+# unrecognised verb here simply scans the raw text, which is the behaviour
+# this enforcer always had, so being wrong about one costs nothing.
+INERT_VERBS = frozenset({
+    "echo", "printf", "cat", "head", "tail", "less", "more",
+    "grep", "egrep", "fgrep", "rg", "ag", "ack",
+    "wc", "sort", "uniq", "comm", "diff", "cut", "column",
+    "ls", "basename", "dirname", "date", "jq", "true", "false",
+})
+
+
+def _mask_prose(text: str) -> str:
+    """`text` with the CONTENT of quoted spans blanked.
+
+    Quoted text is where prose lives: a commit message, an echoed string, a
+    grep pattern. Blanking it stops a mere MENTION of a ship verb from being
+    read as one.
+
+    Returns the text UNCHANGED when the quoting is not simple enough to model
+    (an unterminated quote). For this gate the safe direction is to
+    over-detect: a review demanded unnecessarily is a nuisance, a ship that
+    slips past ungated is the failure this enforcer exists to prevent.
+    """
+    out = list(text)
+    quote = None
+    i = 0
+    while i < len(text):
+        ch = text[i]
+        if quote is None:
+            if ch == "\\":
+                i += 2                      # escaped char cannot open a quote
+                continue
+            if ch in ("'", '"'):
+                quote = ch
+        elif ch == quote:
+            quote = None
+        else:
+            out[i] = " "
+        i += 1
+    return text if quote is not None else "".join(out)
+
+
+def _ships_at_command_position(text: str) -> bool:
+    """True when a segment's VERB is git with a ship subcommand.
+
+    Only used to add `git -C <path> push`; the patterns carry the rest.
+    """
+    for segment in _SEGMENT_SPLIT.split(text):
+        try:
+            tokens = shlex.split(segment.strip(), comments=True)
+        except ValueError:
+            tokens = segment.split()
+        while tokens and (_ENV_ASSIGN.match(tokens[0])
+                          or os.path.basename(tokens[0]).lower() in WRAPPER_VERBS):
+            tokens = tokens[1:]
+        if not tokens or os.path.basename(tokens[0]).lower() != "git":
+            continue
+        rest, i = tokens[1:], 0
+        while i < len(rest) and rest[i].startswith("-"):
+            i += 2 if rest[i] in GIT_VALUE_OPTIONS else 1
+        if i < len(rest) and rest[i].lower() in GIT_SHIP_SUBCOMMANDS:
+            return True
+    return False
+
+
+def _only_inert_verbs(text: str) -> bool:
+    """True when every segment's verb merely prints or searches its arguments.
+
+    Only then is quoted text safely prose. `hands_text_to_shell` still decides
+    the heredoc question upstream; this decides the quoting one.
+    """
+    saw = False
+    for segment in _SEGMENT_SPLIT.split(text):
+        try:
+            tokens = shlex.split(segment.strip(), comments=True)
+        except ValueError:
+            return False                     # unlexable: do not mask
+        while tokens and (_ENV_ASSIGN.match(tokens[0])
+                          or os.path.basename(tokens[0]).lower() in WRAPPER_VERBS):
+            tokens = tokens[1:]
+        if not tokens:
+            continue
+        if os.path.basename(tokens[0]).lower() not in INERT_VERBS:
+            return False
+        saw = True
+    return saw
+
+
+def is_ship_action(command: str) -> bool:
+    """True when the command line PERFORMS a ship action.
+
+    The patterns used to run against the raw string, so any text that merely
+    NAMED a ship verb tripped the gate — a quoted string, a grep pattern, a
+    heredoc body. It self-deadlocked too: writing this gate's own review
+    artifact was refused because the notes described the bug being fixed.
+
+    So the prose is removed before matching, rather than the matching being
+    replaced. `git commit -m 'mentions gh pr merge'` is still a ship action —
+    the commit is outside the quotes.
+    """
+    text = strip_heredoc_bodies(command or "")
+    # Quoted text counts as prose only under a verb that prints or searches it
+    # (`echo 'git push'`). Under anything else — a shell, an interpreter, or
+    # something nobody listed — the raw text is scanned, as it always was.
+    scan = _mask_prose(text) if _only_inert_verbs(text) else text
+    if any(p.search(scan) for p in SHIP_PATTERNS):
+        return True
+    return _ships_at_command_position(text)
+
 # 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")
@@ -223,7 +351,7 @@ def main() -> None:
     # enforcement-self-protect also lists this flag among the bypasses the agent
     # may not set, so an inline attempt is refused with an explicit message
     # instead of appearing to work.
-    if not any(p.search(cmd) for p in SHIP_PATTERNS):
+    if not is_ship_action(cmd):
         emit(True, "not a ship action")
 
     # Resolve against the WORKING TREE the operation runs in (the worktree when a

package/tools/agents/tests/test_expert_review_pr_scope.py

@@ -26,6 +26,7 @@ ENFORCER = (
 
 PR_NUMBER = "645"
 VERB = "merge"
+DQ, SQ = chr(34), chr(39)
 PR_BRANCH = "feature/160-plan-gate-writers"
 PR_SHA = "dd5ce346281d720dff357d4a649d7389e65bfd61"
 STALE_SHA = "2f1b660f" + "0" * 32
@@ -197,5 +198,190 @@ class TestExpertReviewPrScope(unittest.TestCase):
         self.assertIn("master", out.get("reason", ""))
 
 
+class TestShipDetectionIsCommandPosition(unittest.TestCase):
+    """A ship verb in PROSE is not a ship action.
+
+    The patterns used to be searched over the whole command string, so any text
+    that merely named a ship verb tripped the gate — a quoted string, a grep
+    pattern, a heredoc body. It self-deadlocked too: writing this gate's own
+    review artifact was refused because the notes described the bug being fixed.
+
+    The risk in the fix is UNDER-detection, so the ship cases below matter more
+    than the prose ones. `rtk git push` especially: this repo requires git to be
+    invoked through rtk, so a verb check that stopped at the wrapper would miss
+    every real ship command in the codebase.
+    """
+
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        base = Path(self._tmp.name)
+        self.root = base / "repo"
+        self.bin = base / "bin"
+        self.root.mkdir()
+        self.bin.mkdir()
+        self._write_stub_gh()
+        self._init_repo()
+        # Deliberately NO review artifact: a ship action must be refused, and a
+        # non-ship command must sail past with "not a ship action".
+
+    def tearDown(self):
+        self._tmp.cleanup()
+
+    _write_stub_gh = TestExpertReviewPrScope._write_stub_gh
+    _init_repo = TestExpertReviewPrScope._init_repo
+    _run = TestExpertReviewPrScope._run
+
+    def assert_ship(self, command):
+        out, code = self._run(command)
+        self.assertFalse(out.get("allowed"), f"{command!r} should be gated as a ship action")
+        self.assertEqual(code, 2, command)
+
+    def assert_not_ship(self, command):
+        out, code = self._run(command)
+        self.assertTrue(out.get("allowed"), f"{command!r} should not be a ship action")
+        self.assertIn("not a ship action", out.get("reason", ""), command)
+
+    # --- real ship actions must STILL be gated ---
+
+    def test_plain_git_push_is_a_ship_action(self):
+        self.assert_ship("git push origin master")
+
+    def test_rtk_wrapped_git_is_a_ship_action(self):
+        # The mandated form in this repo. Missing it would silently ungate
+        # every push and commit made here.
+        self.assert_ship("rtk git push origin master")
+
+    def test_ship_action_after_a_chained_command(self):
+        self.assert_ship("cd sub && git commit -m x")
+
+    def test_git_global_option_before_the_subcommand(self):
+        # `git -C <path> push` — not caught by the old pattern at all.
+        self.assert_ship("git -C /repo push")
+
+    def test_gh_pr_merge_is_a_ship_action(self):
+        self.assert_ship("gh pr merge 645 --squash")
+
+    # --- prose that merely NAMES a ship verb must not be ---
+
+    def test_quoted_ship_verb_is_prose(self):
+        self.assert_not_ship("echo 'gh pr merge 645'")
+
+    def test_grep_pattern_is_prose(self):
+        self.assert_not_ship("grep -r 'git push' docs/")
+
+    def test_heredoc_body_is_data_not_commands(self):
+        # The exact self-deadlock: writing the review artifact whose notes
+        # describe the gate being fixed.
+        self.assert_not_ship(
+            "python3 - <<'PY'\n"
+            "notes = 'refused because the notes mention gh pr merge'\n"
+            "print(notes)\n"
+            "PY"
+        )
+
+    # --- forms a command-position-only check LOSES ---
+    #
+    # A first attempt at this fix replaced the patterns with a verb-at-position-0
+    # check, copying self-protect. Measured against the old patterns it dropped
+    # 14 real detections, every one of them below: the loose patterns caught
+    # these by accident and the verb check does not. A gate that stops
+    # recognising a ship action stops gating, which is strictly worse than the
+    # false positives being fixed — so these are pinned.
+
+    def test_wrapper_with_its_own_argument_still_ships(self):
+        # The wrapper takes an argument, so the wrapped verb is not token 1.
+        self.assert_ship("timeout 30 git push")
+        self.assert_ship("sudo -u someone git push")
+
+    def test_subshell_and_brace_group_still_ship(self):
+        self.assert_ship("(git push)")
+        self.assert_ship("{ git push; }")
+
+    def test_negated_command_still_ships(self):
+        self.assert_ship("! git push")
+
+    def test_shell_exec_string_still_ships(self):
+        # The ship verb is inside quotes, but `bash -c` makes that text a
+        # command — which is exactly what separates it from `echo 'git push'`.
+        self.assert_ship("bash -c 'git push'")
+        self.assert_ship("sh -c 'git push'")
+
+    def test_xargs_and_find_exec_still_ship(self):
+        self.assert_ship("echo origin | xargs git push")
+        self.assert_ship("find . -exec git push ;")
+
+    def test_leading_redirect_still_ships(self):
+        # Bash allows a redirection before the command word.
+        self.assert_ship("> /tmp/uap-out.log git push")
+
+    def test_commit_message_naming_other_ship_verbs_still_ships(self):
+        # The quotes hold prose, but `git commit` is outside them.
+        self.assert_ship("git commit -m 'explain gh pr merge behaviour'")
+
+    # --- an interpreter's -c/-e payload is CODE, not prose ---
+    #
+    # Masking quoted spans assumed quoted text is inert. That holds for `echo`
+    # and fails for every interpreter: each command below really pushed in a
+    # throwaway repo (the bare origin gained the commit) while an earlier
+    # version of this fix blanked the payload and let it through.
+
+    def test_python_payload_that_shells_out_is_a_ship_action(self):
+        self.assert_ship(
+            "python3 -c " + DQ + "import os; os.system(" + SQ + "git push" + SQ + ")" + DQ
+        )
+
+    def test_perl_payload_that_shells_out_is_a_ship_action(self):
+        self.assert_ship("perl -e " + DQ + "system(" + SQ + "git push" + SQ + ")" + DQ)
+
+    def test_node_payload_that_shells_out_is_a_ship_action(self):
+        self.assert_ship(
+            "node -e " + DQ + "require(" + SQ + "child_process" + SQ
+            + ").execSync(" + SQ + "git push" + SQ + ")" + DQ
+        )
+
+    def test_an_inert_interpreter_payload_is_over_detected_on_purpose(self):
+        # `print('git push')` ships nothing, but is indistinguishable from
+        # `os.system('git push')` without running the interpreter. Gated on
+        # purpose: an unnecessary review is a nuisance, an ungated ship is not.
+        self.assert_ship("python3 -c " + DQ + "print(" + SQ + "git push" + SQ + ")" + DQ)
+
+    # --- executors nobody thought to list ---
+    #
+    # Quoting used to be masked by default, with an exemption list for things
+    # that execute: bash -c, then python/perl/node, and `script -qc` still got
+    # through — it really ships (a throwaway bare repo gained the commit). su,
+    # fish, expect, parallel and watch sat behind it. A denylist of executors
+    # cannot be completed, so masking is now allowlisted to verbs that print or
+    # search their arguments, and anything unrecognised scans the raw text.
+    #
+    # These cases exist to keep that inversion from being quietly undone: they
+    # pass because `script`/`su`/`fish` are NOT on the inert allowlist, not
+    # because anyone enumerated them.
+
+    def test_script_wrapped_ship_is_detected(self):
+        self.assert_ship("script -qc " + SQ + "git push" + SQ + " /dev/null")
+
+    def test_su_wrapped_ship_is_detected(self):
+        self.assert_ship("su -c " + SQ + "git push" + SQ)
+
+    def test_unlisted_shell_wrapped_ship_is_detected(self):
+        self.assert_ship("fish -c " + SQ + "git push" + SQ)
+        self.assert_ship("expect -c " + SQ + "git push" + SQ)
+
+    def test_remote_execution_is_detected(self):
+        # Ships on the far side; gated on purpose.
+        self.assert_ship("ssh somehost " + SQ + "git push" + SQ)
+
+    def test_inert_verbs_still_treat_quotes_as_prose(self):
+        # The allowlist half: these must stay unblocked, or the false positives
+        # this branch exists to fix come straight back.
+        self.assert_not_ship("printf " + SQ + "run gh pr merge later" + SQ)
+        self.assert_not_ship("cat docs/merge-strategy.md")
+
+    def test_read_only_git_is_not_a_ship_action(self):
+        self.assert_not_ship("git diff --merge-base main")
+        self.assert_not_ship("git status --short")
+
+
 if __name__ == "__main__":
     unittest.main()