@miller-tech/uap 1.40.1 → 1.42.0

package/src/policies/enforcers/mcp_router_first.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+"""mcp-router-first enforcer: MCP tools must be loaded on demand."""
+from __future__ import annotations
+import re
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from _common import arg_str, emit, parse_cli  # noqa: E402
+
+BULK_PATTERNS = re.compile(r"(load[-_ ]all|bulk[-_ ]load|all[-_ ]tools|eager)", re.I)
+
+
+def main() -> None:
+    op, args = parse_cli()
+    blob = f"{op} {arg_str(args)}"
+
+    if op not in {"ToolSearch", "tool_search", "mcp-router", "mcp_router"}:
+        emit(True, "not an MCP-router op")
+
+    query = (args.get("query") or "").strip()
+    max_results = int(args.get("max_results") or 5)
+
+    if BULK_PATTERNS.search(blob):
+        emit(False, "mcp-router-first: bulk/eager MCP tool load detected; query by specific tool name instead")
+
+    if not query or max_results > 20:
+        emit(
+            False,
+            "mcp-router-first: ToolSearch must use a specific query and max_results<=20",
+        )
+
+    emit(True, "scoped MCP router query")
+
+
+if __name__ == "__main__":
+    main()

package/src/policies/enforcers/memory_before_plan.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""memory-before-plan enforcer: plans require a recent uap memory query."""
+from __future__ import annotations
+import re
+import sqlite3
+import sys
+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
+
+PLAN_OPS = {"ExitPlanMode", "Plan", "TodoWrite", "plan", "design"}
+# Only match standalone words, not compounds like 'validate-plan-before-build'
+PLAN_WORD_RE = re.compile(r"(?<![-\w/])(plan the|design the|architect the|propose a plan|roadmap for)", re.I)
+RECENT_SEC = 300
+
+
+def recent_memory_query(root: Path) -> bool:
+    db = root / "agents" / "data" / "memory" / "short_term.db"
+    if not db.exists():
+        return False
+    try:
+        con = sqlite3.connect(f"file:{db}?mode=ro", uri=True, timeout=1.0)
+        cur = con.execute(
+            "SELECT timestamp FROM session_memories "
+            "WHERE content LIKE '%uap memory query%' OR type='memory_query' "
+            "ORDER BY id DESC LIMIT 1"
+        )
+        row = cur.fetchone()
+        con.close()
+        if not row:
+            return False
+        raw = row[0][:19].replace("T", " ")
+        try:
+            ts = time.mktime(time.strptime(raw, "%Y-%m-%d %H:%M:%S"))
+        except Exception:  # noqa: BLE001
+            return False
+        # Memory is stored as UTC from datetime('now'); compare with UTC now
+        return (time.time() - (ts - time.timezone)) < RECENT_SEC
+    except sqlite3.Error:
+        return False
+
+
+def main() -> None:
+    op, args = parse_cli()
+    blob = f"{op} {arg_str(args)}"
+    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")
+
+    emit(
+        False,
+        "memory-before-plan: run `uap memory query <topic>` before planning to surface prior context",
+    )
+
+
+if __name__ == "__main__":
+    main()

package/src/policies/enforcers/parallel_reads.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+"""parallel-reads enforcer: nudge when serial read fan-out is detected."""
+from __future__ import annotations
+import os
+import sys
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from _common import emit, parse_cli  # noqa: E402
+
+READ_OPS = {"Read", "Grep", "Glob", "WebFetch", "read", "grep", "glob", "webfetch"}
+STATE = Path(os.environ.get("UAP_STATE_DIR", ".uap")) / "parallel_reads.state"
+WINDOW_SEC = 4.0
+THRESHOLD = 2
+
+
+def main() -> None:
+    op, _args = parse_cli()
+    if op not in READ_OPS:
+        emit(True, "not a read op")
+
+    STATE.parent.mkdir(parents=True, exist_ok=True)
+    now = time.time()
+    history: list[float] = []
+    if STATE.exists():
+        try:
+            history = [
+                float(l) for l in STATE.read_text().splitlines() if l.strip()
+            ]
+        except ValueError:
+            history = []
+
+    history = [t for t in history if now - t < WINDOW_SEC]
+    history.append(now)
+    STATE.write_text("\n".join(f"{t}" for t in history[-10:]))
+
+    if len(history) > THRESHOLD:
+        emit(
+            True,
+            f"parallel-reads: {len(history)} serial read ops in {WINDOW_SEC}s "
+            "— batch independent reads in a single tool-call message for 2-5x speed-up",
+            warning=True,
+        )
+
+    emit(True, "read cadence within batch window")
+
+
+if __name__ == "__main__":
+    main()

package/src/policies/enforcers/rtk_wrap.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""rtk-wrap enforcer: heavy CLIs must be invoked via rtk."""
+from __future__ import annotations
+import re
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from _common import emit, parse_cli  # noqa: E402
+
+WRAPPED = ("git", "kubectl", "docker", "docker-compose", "npm", "pnpm", "yarn", "helm", "terraform")
+RTK_META = re.compile(r"^\s*rtk\s+(gain|discover|proxy|--version|-V|--help)\b")
+ALREADY_WRAPPED = re.compile(r"^\s*rtk\s+\S+")
+
+
+def main() -> None:
+    op, args = parse_cli()
+    cmd = (args.get("command") or args.get("cmd") or "").strip()
+    if not cmd or op.lower() != "bash":
+        emit(True, "not a Bash command")
+
+    first = cmd.split(maxsplit=1)[0].lstrip("(").lstrip("{")
+    if first == "rtk" and RTK_META.search(cmd):
+        emit(True, "rtk meta command")
+    if ALREADY_WRAPPED.match(cmd):
+        emit(True, "already wrapped")
+
+    # Inspect tokens (ignore env assignments like FOO=bar cmd)
+    tokens = [t for t in cmd.split() if "=" not in t.split("/")[0]]
+    for tok in tokens[:3]:
+        bin_name = tok.split("/")[-1]
+        if bin_name in WRAPPED:
+            emit(
+                False,
+                f"rtk-wrap: '{bin_name}' must be invoked via rtk. "
+                f"Use: rtk {cmd}",
+                bin=bin_name,
+            )
+
+    emit(True, "no wrapped CLI in command")
+
+
+if __name__ == "__main__":
+    main()

package/src/policies/enforcers/schema_diff_gate.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""schema-diff-gate enforcer: schema/pool changes must pass uap schema-diff."""
+from __future__ import annotations
+import re
+import sqlite3
+import sys
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from _common import emit, parse_cli, repo_root, run, worktree_root  # noqa: E402
+
+WATCHED_RE = re.compile(
+    r"(migrations/.*\.sql|infra/postgres-spock/|infra/helm_charts/[^/]*pgdog|"
+    r"infra/helm_charts/[^/]*cnpg|infra/helm_charts/[^/]*redis|"
+    r"infra/helm_charts/[^/]*envoy|infra/helm_charts/[^/]*sentinel)",
+    re.I,
+)
+COMMIT_OPS = {"git-commit", "git commit", "Bash"}
+RECENT_SEC = 3600
+
+
+def touched_watched_paths(root: Path) -> list[str]:
+    rc, out, _ = run(["git", "diff", "--name-only", "HEAD"], cwd=root)
+    if rc != 0:
+        return []
+    rc2, staged, _ = run(["git", "diff", "--name-only", "--cached"], cwd=root)
+    all_files = (out + "\n" + (staged if rc2 == 0 else "")).splitlines()
+    return [f for f in all_files if f and WATCHED_RE.search(f)]
+
+
+def schema_diff_ok(root: Path) -> bool:
+    db = root / "agents" / "data" / "memory" / "short_term.db"
+    if not db.exists():
+        return False
+    try:
+        con = sqlite3.connect(f"file:{db}?mode=ro", uri=True, timeout=1.0)
+        cur = con.execute(
+            "SELECT timestamp FROM session_memories "
+            "WHERE content LIKE '%schema-diff%pass%' "
+            "ORDER BY id DESC LIMIT 1"
+        )
+        row = cur.fetchone()
+        con.close()
+        if not row:
+            return False
+        try:
+            ts = time.mktime(time.strptime(row[0][:19], "%Y-%m-%dT%H:%M:%S"))
+        except Exception:  # noqa: BLE001
+            return False
+        return (time.time() - ts) < RECENT_SEC
+    except sqlite3.Error:
+        return False
+
+
+def main() -> None:
+    op, args = parse_cli()
+    cmd = (args.get("command") or "").lower()
+    is_commit = op in COMMIT_OPS or "git commit" in cmd or "git push" in cmd
+    if not is_commit:
+        emit(True, "not a commit/push gate point")
+
+    # git diff runs against the working tree; short_term.db lives in MAIN_ROOT
+    watched = touched_watched_paths(worktree_root())
+    if not watched:
+        emit(True, "no watched schema/pool paths in diff")
+
+    if schema_diff_ok(repo_root()):
+        emit(True, f"recent schema-diff pass covers: {', '.join(watched[:5])}")
+
+    emit(
+        False,
+        "schema-diff-gate: changes to "
+        + ", ".join(watched[:5])
+        + " require `uap schema-diff` to pass (within 1h). Run it and re-commit.",
+    )
+
+
+if __name__ == "__main__":
+    main()

package/src/policies/enforcers/session_memory_write.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""session-memory-write enforcer: code-changing sessions must write a lesson."""
+from __future__ import annotations
+import sqlite3
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from _common import emit, parse_cli, repo_root  # noqa: E402
+
+END_OPS = {"session-end", "stop", "terminate", "SessionEnd"}
+
+
+def recent_lesson(root: Path) -> bool:
+    db = root / "agents" / "data" / "memory" / "short_term.db"
+    if not db.exists():
+        return False
+    try:
+        con = sqlite3.connect(f"file:{db}?mode=ro", uri=True, timeout=1.0)
+        cur = con.execute(
+            "SELECT COUNT(*) FROM session_memories "
+            "WHERE type IN ('decision','lesson','pattern') "
+            "AND session_id='current'"
+        )
+        n = cur.fetchone()[0]
+        con.close()
+        return n > 0
+    except sqlite3.Error:
+        return False
+
+
+def main() -> None:
+    op, args = parse_cli()
+    if op not in END_OPS:
+        emit(True, "not a session-end op")
+
+    code_changed = bool(args.get("code_changed"))
+    if not code_changed:
+        emit(True, "no code changes this session")
+
+    if recent_lesson(repo_root()):
+        emit(True, "lesson/decision recorded this session")
+
+    emit(
+        False,
+        "session-memory-write: code changed but no decision/lesson/pattern row in short_term.db. "
+        "Insert one before terminating.",
+    )
+
+
+if __name__ == "__main__":
+    main()

package/src/policies/enforcers/task_required.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+"""task-required enforcer: a UAP task must be in_progress before mutating work.
+
+Blocks Edit/Write/MultiEdit (outside exempt prefixes) and the ship actions
+git commit / git push / gh pr create when no row in .uap/tasks/tasks.db has
+status='in_progress'. Closes UAP protocol step 4 — which was previously
+text-injection only and therefore skippable.
+
+Fail-open: if UAP task tracking is not initialised (no tasks.db) or the DB is
+unreadable, the operation is allowed — so non-UAP repos are unaffected.
+Override: set UAP_NO_TASK=1 to bypass.
+"""
+from __future__ import annotations
+import os
+import re
+import sqlite3
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from _common import emit, parse_cli, repo_root, run  # noqa: E402
+
+EDIT_OPS = {"edit", "write", "multiedit"}
+
+# Meta / infra / docs paths that do not require a task (mirror worktree_required,
+# plus .policy-tools/ which is the policy-system's own runtime artifact dir).
+EXEMPT_PREFIXES = (
+    ".claude/",
+    ".cursor/",
+    ".opencode/",
+    ".codex/",
+    ".forge/",
+    ".uap/",
+    ".policy-tools/",
+    "src/policies/",
+    "scripts/",
+    "docs/",
+)
+
+# Bash ship actions gated even though Bash itself is otherwise unrestricted.
+SHIP_PATTERNS = (
+    re.compile(r"\bgit\s+(commit|push)\b"),
+    re.compile(r"\bgh\s+pr\s+create\b"),
+)
+
+
+def main_repo_root() -> Path:
+    """Resolve the primary worktree root, even when invoked from a linked
+    worktree — `git rev-parse --git-common-dir` always points at the main
+    .git, whose parent is the primary checkout."""
+    rc, out, _ = run(["git", "rev-parse", "--git-common-dir"])
+    if rc == 0 and out.strip():
+        p = Path(out.strip())
+        if not p.is_absolute():
+            p = (Path.cwd() / p).resolve()
+        return p.parent
+    return repo_root()
+
+
+def in_progress_task_state():
+    """True if an in_progress task exists, False if none, None if UAP task
+    tracking is not set up / DB unreadable (caller treats None as allow)."""
+    db = main_repo_root() / ".uap" / "tasks" / "tasks.db"
+    if not db.exists():
+        return None
+    try:
+        con = sqlite3.connect(f"file:{db}?mode=ro", uri=True, timeout=2)
+        try:
+            n = con.execute(
+                "SELECT COUNT(*) FROM tasks WHERE status='in_progress'"
+            ).fetchone()[0]
+        finally:
+            con.close()
+        return n > 0
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def main() -> None:
+    op, args = parse_cli()
+
+    if os.environ.get("UAP_NO_TASK") == "1":
+        emit(True, "UAP_NO_TASK override set")
+
+    op_l = op.lower()
+    is_edit = op_l in EDIT_OPS
+    is_bash = op_l == "bash"
+    if not is_edit and not is_bash:
+        emit(True, "not a mutating operation")
+
+    if is_bash:
+        cmd = args.get("command") or args.get("cmd") or ""
+        if not any(p.search(cmd) for p in SHIP_PATTERNS):
+            emit(True, "not a ship action")
+        gate_label = "ship action (git commit/push, gh pr create)"
+    else:
+        target = (
+            args.get("file_path")
+            or args.get("path")
+            or args.get("target")
+            or ""
+        )
+        if not target:
+            emit(True, "no file path in args")
+        root = repo_root()
+        try:
+            rel = str(Path(target).resolve().relative_to(root))
+        except ValueError:
+            emit(True, "target outside repo")
+        if any(rel.startswith(p) for p in EXEMPT_PREFIXES):
+            emit(True, f"exempt path: {rel}")
+        gate_label = f"edit of '{rel}'"
+
+    state = in_progress_task_state()
+    if state is None:
+        emit(True, "UAP task tracking not initialised — fail-open")
+    if state:
+        emit(True, "in_progress UAP task present")
+
+    emit(
+        False,
+        f"task-required: no in_progress UAP task — {gate_label} blocked. "
+        'Run:  uap task create --type <task|bug|feature> --title "<desc>"  '
+        "then:  uap task update <id> --status in_progress  "
+        "(or:  uap task claim <id>  to also spin a worktree). "
+        "Override for one-off meta-work: UAP_NO_TASK=1.",
+    )
+
+
+if __name__ == "__main__":
+    main()

package/src/policies/enforcers/test_gate.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+"""test-gate enforcer: changed services under services|apps need test deltas."""
+from __future__ import annotations
+import re
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from _common import emit, parse_cli, run, worktree_root  # noqa: E402
+
+PR_OPS_RE = re.compile(
+    r"\b(pr[-_ ]?ready|pr-create|gh pr create|signoff|ready[-_ ]for[-_ ]review|merge)\b",
+    re.I,
+)
+SVC_RE = re.compile(r"^(services|apps)/([^/]+)/")
+TEST_RE = re.compile(
+    r"(/tests?/|__tests__/|\.test\.(ts|tsx|js|py)$|_test\.(py|go)$|\.spec\.(ts|tsx|js)$)"
+)
+
+
+def main() -> None:
+    op, args = parse_cli()
+    cmd = (args.get("command") or "").lower()
+    if not (PR_OPS_RE.search(op) or PR_OPS_RE.search(cmd)):
+        emit(True, "not a PR-ready gate point")
+
+    root = worktree_root()  # git diff must run against the working tree, not MAIN_ROOT
+    rc, out, _ = run(
+        ["git", "diff", "--name-only", "origin/main...HEAD"], cwd=root, timeout=10
+    )
+    if rc != 0:
+        emit(True, "cannot compute diff vs origin/main")
+
+    changed = [l for l in out.splitlines() if l.strip()]
+    svcs_touched: set[str] = set()
+    for f in changed:
+        m = SVC_RE.match(f)
+        if m:
+            svcs_touched.add(f"{m.group(1)}/{m.group(2)}")
+
+    if not svcs_touched:
+        emit(True, "no services/apps changes in diff")
+
+    svcs_with_tests = {
+        s for s in svcs_touched if any(f.startswith(s) and TEST_RE.search(f) for f in changed)
+    }
+    missing = svcs_touched - svcs_with_tests
+    if missing:
+        emit(
+            False,
+            f"test-gate: the following services changed without test deltas: {', '.join(sorted(missing))}",
+        )
+
+    emit(True, "all changed services include test deltas")
+
+
+if __name__ == "__main__":
+    main()

package/src/policies/enforcers/validate_plan_before_build.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""validate-plan-before-build enforcer.
+
+On the first mutating tool call after a plan is marked ready, block and require
+the agent to run the `validate the plan` prompt. State tracked in .uap/plan_state.json.
+"""
+from __future__ import annotations
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from _common import emit, parse_cli  # noqa: E402
+
+STATE = Path(os.environ.get("UAP_STATE_DIR", ".uap")) / "plan_state.json"
+MUTATING_OPS = {"Edit", "Write", "MultiEdit", "edit", "write", "multiedit"}
+BUILD_BASH_RE = (
+    "git commit",
+    "git push",
+    "kubectl apply",
+    "helm upgrade",
+    "helm install",
+    "terraform apply",
+    "npm run build",
+    "pnpm build",
+)
+
+
+def load_state() -> dict:
+    if not STATE.exists():
+        return {}
+    try:
+        return json.loads(STATE.read_text())
+    except json.JSONDecodeError:
+        return {}
+
+
+def save_state(s: dict) -> None:
+    STATE.parent.mkdir(parents=True, exist_ok=True)
+    STATE.write_text(json.dumps(s))
+
+
+def main() -> None:
+    op, args = parse_cli()
+    state = load_state()
+
+    # Mutating?
+    cmd = (args.get("command") or "").lower()
+    mutating = op in MUTATING_OPS or any(p in cmd for p in BUILD_BASH_RE)
+    if not mutating:
+        emit(True, "not a build/mutation op")
+
+    plan_ready = bool(state.get("plan_ready"))
+    validated_at = float(state.get("validated_at", 0))
+    ready_at = float(state.get("ready_at", 0))
+
+    if not plan_ready:
+        emit(True, "no active plan-ready marker")
+
+    if validated_at and validated_at >= ready_at:
+        emit(True, "plan validated since marking ready")
+
+    emit(
+        False,
+        "validate-plan-before-build: plan is ready but not validated. "
+        "Run the prompt `validate the plan` before making changes. "
+        "After a pass, write {\"validated_at\": <epoch>} to .uap/plan_state.json.",
+        inject_prompt="validate the plan",
+    )
+
+
+if __name__ == "__main__":
+    main()

package/src/policies/enforcers/worktree_required.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+"""worktree-required enforcer: Edit/Write must target a .worktrees/ path."""
+from __future__ import annotations
+import os
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from _common import emit, parse_cli, repo_root  # noqa: E402
+
+EXEMPT_PREFIXES = (
+    ".claude/",
+    ".cursor/",
+    ".opencode/",
+    ".codex/",
+    ".forge/",
+    ".uap/",
+    "src/policies/",
+    "scripts/",
+    "docs/",
+)
+EDIT_OPS = {"Edit", "Write", "MultiEdit", "edit", "write", "multiedit"}
+
+
+def main() -> None:
+    op, args = parse_cli()
+    if op not in EDIT_OPS:
+        emit(True, "not a file-edit operation")
+
+    target = args.get("file_path") or args.get("path") or args.get("target") or ""
+    if not target:
+        emit(True, "no file path in args")
+
+    root = repo_root()
+    try:
+        rel = str(Path(target).resolve().relative_to(root))
+    except ValueError:
+        emit(True, "target outside repo")
+
+    if rel.startswith(".worktrees/"):
+        emit(True, "target inside a worktree")
+
+    if any(rel.startswith(p) for p in EXEMPT_PREFIXES):
+        emit(True, f"exempt path: {rel}")
+
+    if os.environ.get("UAP_NO_WORKTREE") == "1":
+        emit(True, "UAP_NO_WORKTREE override set")
+
+    emit(
+        False,
+        f"worktree-required: '{rel}' must be edited inside .worktrees/NNN-<slug>/. "
+        "Run: uap worktree create <slug>",
+    )
+
+
+if __name__ == "__main__":
+    main()