@miller-tech/uap 1.40.0 → 1.41.0

package/docs/reference/PATTERNS.md

@@ -0,0 +1,102 @@
+# Pattern Library Reference
+
+> Universal Agent Protocol (UAP) v1.40.0
+
+UAP ships an execution-pattern library: a set of reusable problem-solving
+strategies that are matched to the current task and surfaced to the agent.
+Patterns are defined as markdown files under `.factory/patterns/`, catalogued
+in `.factory/patterns/index.json`, and retrieved on demand via a Qdrant-backed
+RAG flow (`uap patterns query`).
+
+## The 23 Patterns
+
+The canonical roster lives in `.factory/patterns/index.json`. Each pattern has
+a numeric (or string) id, a markdown body file, a title, an abbreviation, a
+category, and a keyword set used for retrieval.
+
+| ID | Title | Abbreviation | Category | What it does |
+|----|-------|--------------|----------|--------------|
+| P12 | Output Existence Verification | OE-Verify | Verification | Confirm the artifact a task was supposed to produce actually exists before claiming done. **Always enforced.** |
+| P13 | Iterative Refinement Loop | Iter-Ref | Testing | Run tests, fix, and re-run in a loop until they pass. |
+| P14 | Output Format Validation | Format-Check | Verification | Validate that produced output matches the required format (JSON/YAML/CSV). |
+| P16 | Task-First Execution | Task-First | Execution | When the task is clear, execute directly instead of over-planning. |
+| P17 | Constraint Extraction | Extract-Constraints | Planning | Pull hard constraints ("exactly", "only", "no more than") out of the prompt before acting. |
+| P19 | Impossible Task Refusal | Refuse-Impossible | Safety | Detect and refuse tasks that are fundamentally impossible. |
+| P20 | Adversarial Thinking | Adversarial | Security | Reason about how something could be bypassed/exploited/evaded. |
+| P21 | Chess Engine Integration | Chess-Engine | Domain-Specific | Delegate chess reasoning (FEN, best move, checkmate) to an engine. |
+| P22 | Git Recovery Forensics | Git-Recovery | Recovery | Recover lost/corrupted git state via reflog and forensic inspection. |
+| P23 | Compression Impossibility Detection | Compress-Check | Verification | Detect already-compressed data so re-compression isn't attempted. |
+| P24 | Polyglot Code Construction | Polyglot | Code-Golf | Construct source that compiles/runs as multiple languages. |
+| P25 | Service Configuration Pipeline | Service-Config | DevOps | Configure, validate, and reload a service/daemon as a pipeline. |
+| P26 | Near-Miss Iteration | Near-Miss | Testing | When a test result is a small gap away, tweak and re-check. |
+| P28 | Service Smoke Test | Smoke-Test | Verification | After deploy/start, run a health check / smoke test to verify. |
+| P30 | Performance Threshold Tuning | Perf-Threshold | Optimization | Measure performance and tune against a percentage/threshold target. |
+| P31 | Round-Trip Verification | Round-Trip | Verification | Encode then decode (or compress/decompress) and verify the round trip. |
+| P32 | CLI Execution Verification | CLI-Verify | Verification | Verify a CLI/binary actually runs as expected. |
+| P33 | Numerical Stability Testing | Num-Stable | Testing | Test floating-point/numerical work for precision and stability. |
+| P34 | Image-to-Structured Pipeline | Image-Structured | Domain-Specific | Convert images (OCR/diagram/board) into structured data. |
+| P35 | Decoder-First Analysis | Decoder-First | Analysis | Build/understand the decoder/parser first when reverse-engineering a format. **Always enforced.** |
+| P36 | Competition Domain Research | Competition-Research | Research | Research the competitive domain (win rate, leaderboard, tournament) before optimizing. |
+| P37 | Ambiguity Detection & Resolution | Ambiguity-Detect | Planning | Detect vague/unspecified requirements and clarify before acting. |
+| IaC | Infrastructure as Code Parity | IaC-Parity | Infrastructure | Keep infrastructure changes reflected in IaC (terraform/kubernetes) for reproducibility. |
+
+### Always-on patterns
+
+Two patterns are unconditionally included regardless of the matched task, set
+in `src/coordination/pattern-router.ts`:
+
+```js
+const alwaysIncludeIds = ['P12', 'P35']; // Output Existence, Decoder-First
+```
+
+- **P12 (Output Existence Verification)** — guards against "claiming done"
+  without producing the artifact.
+- **P35 (Decoder-First Analysis)** — anchors format/reverse-engineering work.
+
+## How pattern RAG works
+
+Pattern retrieval is semantic, not keyword-based. The flow:
+
+1. **Indexing** (`uap patterns index`) runs a generated Python indexer
+   (`agents/scripts/index_patterns_to_qdrant.py`). It scans multiple sources —
+   `CLAUDE.md` (with `@include` resolution), additional source files
+   (`AGENTS.md`, etc.), `*/SKILL.md` skill files, and `.factory/patterns/*.md`
+   (using `index.json` to preserve the canonical `PNN: Title` identity and
+   keyword set). Documents are de-duplicated by content hash, embedded, and
+   upserted into the Qdrant collection.
+2. **Querying** (`uap patterns query "<task>"`) runs the generated query script
+   (`agents/scripts/query_patterns.py`), embeds the query with the same model,
+   and runs a cosine `query_points` search against the collection, returning the
+   top-K hits above the score threshold.
+3. **Fallback** — if the Python query script is absent, the CLI falls back to a
+   direct Qdrant `scroll` + keyword match (less accurate) and prints a notice.
+
+### RAG defaults
+
+From `src/cli/patterns.ts` (`getPatternRagConfig`), overridable via
+`.uap.json` under `memory.patternRag`:
+
+| Setting | Default |
+|---------|---------|
+| Collection | `agent_patterns` |
+| Embedding model | `all-MiniLM-L6-v2` |
+| Vector size | `384` (Cosine distance) |
+| Score threshold | `0.35` |
+| Top-K | `2` |
+| Index script | `./agents/scripts/index_patterns_to_qdrant.py` |
+| Query script | `./agents/scripts/query_patterns.py` |
+| Source file | `CLAUDE.md` |
+| Max body chars | `400` (display); indexer truncates bodies at 2000 |
+
+The query script requires a Python with `sentence-transformers` and
+`qdrant-client`. The CLI auto-discovers `agents/.venv/bin/python`,
+`.venv/bin/python`, then `python3`/`python`, and can bootstrap a venv.
+
+## `uap patterns` CLI
+
+| Command | Description |
+|---------|-------------|
+| `uap patterns status` | Show RAG config, Qdrant collection point count, Python/script availability. |
+| `uap patterns index` | (Re)index pattern/doc sources into the Qdrant collection. `--verbose` for full output. |
+| `uap patterns query "<task>"` | Semantic search for task-relevant patterns. Flags: `--top <n>`, `--min-score <f>`, `--format text\|json`. |
+| `uap patterns generate` | Generate the Python index/query scripts. `--force` to overwrite. |

package/docs/reference/PLATFORMS.md

@@ -0,0 +1,83 @@
+# Platform & Harness Reference
+
+> Universal Agent Protocol (UAP) v1.40.0
+
+UAP integrates with 9 agent harnesses. The canonical list is `ALL_TARGETS` in
+`src/cli/hooks.ts`. Every platform receives the UAP enforcement layer: lifecycle
+hooks, the DB-driven policy gate, and (where supported) the hierarchical MCP
+router.
+
+## Supported platforms
+
+| Target flag | Platform | Config location | Integration style |
+|-------------|----------|-----------------|-------------------|
+| `claude` | Claude Code | `.claude/settings.local.json` + `.claude/hooks/` | Native hook events |
+| `factory` | Factory.AI Droid | `.factory/settings.local.json` + `.factory/hooks/` | Native hook events (`$FACTORY_PROJECT_DIR`) |
+| `cursor` | Cursor | `.cursor/hooks.json` + `.cursor/hooks/` | Native hook events |
+| `vscode` | VSCode | `.claude/settings.local.json` + `.claude/hooks/` | Claude Code hook format (via third-party skills) |
+| `opencode` | OpenCode | `.opencode/plugin/uap-session-hooks.ts` + `.opencode/hooks/` | TypeScript plugin |
+| `codex` | Codex CLI | `AGENTS.md`, `.codex/config.toml`, `.codex/hooks/`, `.agents/skills/` | AGENTS.md + skills + MCP server |
+| `forgecode` | ForgeCode | `.forge/forgecode.plugin.sh` + `.forge/hooks/` | ZSH plugin |
+| `omp` | Oh-My-Pi | `.uap/omp/settings.json` + `.uap/omp/hooks/{pre,post}/` | omp pre/post hook dirs |
+| `hermes` | Hermes Agent (NousResearch) | `~/.hermes/config.yaml` + `~/.hermes/agent-hooks/` | **Global** YAML config + MCP |
+
+> **Hermes is global.** Its config lives under `~/.hermes` (or `$HERMES_HOME`),
+> so it is excluded from the default project install loop (`PROJECT_TARGETS`).
+> Installing it requires an explicit `-t hermes`. `status`/`doctor` still report it.
+
+## Support matrix
+
+| Platform | Lifecycle hooks | Worktree/Bash guards | Policy gate | MCP router |
+|----------|-----------------|----------------------|-------------|------------|
+| Claude Code | Native | Yes | Hard (PreToolUse) | Yes |
+| Factory.AI | Native | Yes | Hard (PreToolUse) | Yes |
+| Cursor | Native | Yes | Hard (preToolUse) | Yes |
+| VSCode | Native (Claude format) | Yes | Hard (PreToolUse) | Yes |
+| OpenCode | Plugin events | Yes | Hard (`tool.execute.before` → exit 2 blocks) | Yes |
+| Codex CLI | Advisory (no native pre-tool event) | Advisory | Hard for MCP-routed tools; advisory for native edit/bash | Yes (`[mcp_servers.uap]`) |
+| ForgeCode | ZSH plugin | Yes (scripts) | Via gate script | — |
+| Oh-My-Pi | pre/post dirs | Yes | Yes (`uap-policy-gate.sh`) | — |
+| Hermes | `pre_tool_call` / `on_session_start` | `pre_tool_call` matcher | Hard via `uap-policy-gate-hermes.sh` (emits block JSON) | Yes (`mcp_servers.uap`) |
+
+> **Gating notes.** Codex CLI has no native pre-tool-use hook event, so policy
+> gating is **hard** only for tools routed through the UAP MCP server
+> (`execute_tool` runs the PolicyGate) and **advisory** for Codex-native
+> edit/bash. `uap hooks doctor` reports Codex as MCP-gated. Hermes hooks are
+> fail-open by design, but the UAP gate always emits a decision JSON so real
+> blocks are enforced; Hermes prompts once to approve each hook command
+> (`~/.hermes/shell-hooks-allowlist.json`) unless `hooks_auto_accept: true`.
+
+## Lifecycle hooks installed
+
+The shared hook scripts (copied from `templates/hooks/`) are wired into each
+platform's lifecycle events:
+
+| Script | Event | Purpose |
+|--------|-------|---------|
+| `session-start.sh` | SessionStart | Injects recent memory context. |
+| `pre-tool-use-edit-write.sh` | PreToolUse (Edit/Write/MultiEdit) | Worktree file guard — **blocks** edits outside worktree dirs. |
+| `pre-tool-use-bash.sh` | PreToolUse (Bash) | Dangerous-command guard — **blocks** force push, `terraform apply`, etc. |
+| `uap-policy-gate.sh` | PreToolUse | DB-driven policy gate (`policies.db` + `.policy-tools/*.py`). |
+| `post-tool-use-edit-write.sh` | PostToolUse (Edit/Write) | Build gate + backup reminder after edits. |
+| `pre-compact.sh` | PreCompact | Flushes a compaction marker to memory. |
+| `post-compact.sh` | PostCompact | Re-injects policy awareness after compaction. |
+| `stop.sh` | Stop | Completion-gate checklist + session cleanup. |
+| `session-end.sh` | SessionEnd | Agent deregistration + backup retention. |
+| `loop-protection.sh` | — | Loop/spawn protection. |
+
+## Install & verify
+
+```bash
+uap hooks install              # install for all PROJECT_TARGETS (excludes hermes)
+uap hooks install -t claude    # install for a single platform
+uap hooks install -t hermes    # required to install the global Hermes config
+uap hooks status               # per-platform script + settings status (all targets)
+uap hooks doctor               # health check across all targets
+```
+
+The MCP router is configured separately and across all harnesses with:
+
+```bash
+uap mcp-setup                  # configure the hierarchical MCP router everywhere
+uap mcp-router start           # run the stdio MCP router server
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miller-tech/uap",
-  "version": "1.40.0",
+  "version": "1.41.0",
   "description": "Autonomous AI agent memory system with CLAUDE.md protocol enforcement",
   "type": "module",
   "main": "dist/index.js",
@@ -107,6 +107,8 @@
     "docs",
     "config",
     "templates",
+    "src/policies/schemas/policies",
+    "src/policies/enforcers",
     "tools/agents",
     "scripts/setup",
     "scripts/version-bump.sh",

package/src/policies/enforcers/7ebbc721-7540-4e9f-879a-770e0213a09b_architecture_review.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""architecture-review-required enforcer.
+
+Triggered when merge / PR-ready operations are attempted and the diff
+touches qualifying paths. Requires either:
+  - An ADR file under docs/architecture/adr/ added or modified in the same diff, OR
+  - An active waiver under policies/waivers/ matching this policy slug
+"""
+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, repo_root, run  # noqa: E402
+
+PR_OPS_RE = re.compile(
+    r"\b(pr[-_ ]?ready|pr-create|gh pr create|signoff|ready[-_ ]for[-_ ]review|merge)\b",
+    re.I,
+)
+
+# Paths whose modification triggers the architecture-review requirement.
+TRIGGER_PATTERNS = [
+    re.compile(r"^src/types/"),
+    re.compile(r".*/schemas/"),
+    re.compile(r"^src/index\.ts$"),
+    re.compile(r"^docs/architecture/(?!adr/)"),  # docs/architecture/ but NOT the adr/ we want
+    re.compile(r"^src/coordination/(capability|pattern)-router\.ts$"),
+]
+
+ADR_PATH_RE = re.compile(r"^docs/architecture/adr/.+\.md$")
+WAIVER_RE = re.compile(r"^policies/waivers/.*architecture-review.*\.md$", re.I)
+
+
+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 = repo_root()
+    rc, out, _ = run(
+        ["git", "diff", "--name-only", "origin/master...HEAD"], cwd=root, timeout=10
+    )
+    if rc != 0:
+        # Try origin/main as fallback
+        rc, out, _ = run(
+            ["git", "diff", "--name-only", "origin/main...HEAD"], cwd=root, timeout=10
+        )
+    if rc != 0:
+        emit(True, "cannot compute diff vs upstream; allowing")
+
+    changed = [line for line in out.splitlines() if line.strip()]
+
+    # Detect qualifying changes
+    triggered = []
+    for f in changed:
+        for pat in TRIGGER_PATTERNS:
+            if pat.match(f):
+                triggered.append(f)
+                break
+
+    if not triggered:
+        emit(True, "no architecture-qualifying paths touched in diff")
+
+    # Look for an ADR in the diff
+    adr_present = any(ADR_PATH_RE.match(f) for f in changed)
+
+    # Look for an active waiver
+    waiver_present = False
+    waivers_dir = root / "policies" / "waivers"
+    if waivers_dir.exists():
+        for waiver in waivers_dir.glob("*architecture-review*.md"):
+            if waiver.is_file():
+                waiver_present = True
+                break
+
+    if adr_present or waiver_present:
+        emit(
+            True,
+            f"architecture-review satisfied "
+            f"({'adr-in-diff' if adr_present else 'active-waiver'})",
+            adr=adr_present,
+            waiver=waiver_present,
+            triggers=sorted(set(triggered)),
+        )
+
+    emit(
+        False,
+        "architecture-review-required: diff touches "
+        f"{', '.join(sorted(set(triggered))[:3])} but no ADR under "
+        "docs/architecture/adr/ and no active waiver. "
+        "Add an ADR or request a waiver from compliance-officer.",
+        triggers=sorted(set(triggered)),
+    )
+
+
+if __name__ == "__main__":
+    main()

package/src/policies/enforcers/_common.py

@@ -0,0 +1,100 @@
+"""Shared helpers for UAP policy enforcers."""
+from __future__ import annotations
+import argparse
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+
+def parse_cli() -> tuple[str, dict[str, Any]]:
+    p = argparse.ArgumentParser()
+    p.add_argument("--operation", required=True)
+    p.add_argument("--args", default="{}")
+    ns = p.parse_args()
+    try:
+        args = json.loads(ns.args)
+    except json.JSONDecodeError:
+        args = {}
+    return ns.operation, args
+
+
+def emit(allowed: bool, reason: str, **extra: Any) -> None:
+    payload: dict[str, Any] = {"allowed": allowed, "reason": reason}
+    payload.update(extra)
+    json.dump(payload, sys.stdout)
+    sys.exit(0 if allowed else 2)
+
+
+def repo_root() -> Path:
+    env = os.environ.get("UAP_REPO_ROOT")
+    if env:
+        return Path(env)
+    cwd = Path.cwd()
+    for p in [cwd, *cwd.parents]:
+        if (p / ".git").exists():
+            return p
+    return cwd
+
+
+def worktree_root() -> Path:
+    """Root of the current WORKING TREE for git operations.
+
+    Distinct from repo_root() (the main checkout, where runtime data like
+    policies.db lives). git-diff based enforcers must run against the working
+    tree — which is the worktree when an operation runs from inside one. The
+    policy gate exports UAP_WORKTREE_ROOT; fall back to `git rev-parse` from cwd,
+    then to repo_root().
+    """
+    env = os.environ.get("UAP_WORKTREE_ROOT")
+    if env:
+        return Path(env)
+    try:
+        r = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            capture_output=True, text=True, timeout=3, env=_clean_env(),
+        )
+        if r.returncode == 0 and r.stdout.strip():
+            return Path(r.stdout.strip())
+    except Exception:  # noqa: BLE001
+        pass
+    return repo_root()
+
+
+# git exports repo-context vars (GIT_DIR, GIT_WORK_TREE, GIT_INDEX_FILE, ...)
+# into hook environments. An enforcer spawned during a hook would then run its
+# own git calls against the HOOK'S repo instead of cwd — silently no-op'ing
+# every git-diff based check. Strip them so cwd decides the repo.
+_GIT_CONTEXT_VARS = (
+    "GIT_DIR",
+    "GIT_WORK_TREE",
+    "GIT_INDEX_FILE",
+    "GIT_COMMON_DIR",
+    "GIT_OBJECT_DIRECTORY",
+    "GIT_PREFIX",
+)
+
+
+def _clean_env() -> dict[str, str]:
+    return {k: v for k, v in os.environ.items() if k not in _GIT_CONTEXT_VARS}
+
+
+def run(cmd: list[str], cwd: Path | None = None, timeout: int = 5) -> tuple[int, str, str]:
+    try:
+        r = subprocess.run(
+            cmd, cwd=cwd, capture_output=True, text=True, timeout=timeout,
+            env=_clean_env(),
+        )
+        return r.returncode, r.stdout, r.stderr
+    except Exception as e:  # noqa: BLE001
+        return 1, "", str(e)
+
+
+def arg_str(args: dict[str, Any]) -> str:
+    """Flatten args to a single lowercase string for substring checks."""
+    try:
+        return json.dumps(args, default=str).lower()
+    except Exception:  # noqa: BLE001
+        return str(args).lower()

package/src/policies/enforcers/artifact_hygiene.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""artifact-hygiene enforcer: block binary artifacts outside curated dirs."""
+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
+
+BINARY_RE = re.compile(r"\.(png|jpe?g|gif|pdf|zip|tar\.gz|tgz|db|sqlite\d?)$", re.I)
+ALLOWED_PREFIXES = (
+    "docs/",
+    "tests/",
+    "apps/",
+    "agents/data/memory/",
+    ".playwright-mcp/",
+    "observability/",
+)
+ALLOWED_SUBSTRINGS = ("/__screenshots__/", "/public/", "/static/", "/assets/")
+WRITE_OPS = {"Write", "write", "create-file"}
+
+
+def main() -> None:
+    op, args = parse_cli()
+    if op not in WRITE_OPS:
+        emit(True, "not a write op")
+
+    path = (args.get("file_path") or args.get("path") or "").replace("\\", "/")
+    if not BINARY_RE.search(path):
+        emit(True, "not a binary artifact")
+
+    rel = path
+    for marker in ("/pay2u/", "/miller-tech/"):
+        if marker in rel:
+            rel = rel.split(marker, 1)[1]
+            break
+
+    if any(rel.startswith(p) for p in ALLOWED_PREFIXES):
+        emit(True, f"allowed prefix: {rel}")
+    if any(s in rel for s in ALLOWED_SUBSTRINGS):
+        emit(True, f"allowed subdir: {rel}")
+
+    emit(
+        False,
+        f"artifact-hygiene: binary '{rel}' must live under docs/, tests/, or apps/**/public|static|assets. "
+        "Do not litter repo root.",
+    )
+
+
+if __name__ == "__main__":
+    main()

package/src/policies/enforcers/cluster_routing.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+"""cluster-routing enforcer: kubectl/helm context must match component domain."""
+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, run  # noqa: E402
+
+DOMAINS = {
+    "openobserve": re.compile(
+        r"grafana|prometheus|openobserve|fluent-?bit|servicemonitor|alertmanager|loki|tempo|jaeger",
+        re.I,
+    ),
+    "zitadel": re.compile(r"zitadel|oidc|keycloak|iam-crd", re.I),
+}
+CONTEXTS = {
+    "openobserve": "do-syd1-pay2u-openobserve",
+    "zitadel": "do-syd1-zitadel",
+    "main": "do-syd1-pay2u",
+}
+
+
+def pick_domain(blob: str) -> str:
+    for d, rx in DOMAINS.items():
+        if rx.search(blob):
+            return d
+    return "main"
+
+
+def main() -> None:
+    op, args = parse_cli()
+    blob = f"{op} {arg_str(args)}"
+
+    if not re.search(r"\b(kubectl|helm)\b", blob):
+        emit(True, "not a kubectl/helm call")
+
+    if not re.search(
+        r"\b(apply|patch|create|edit|delete|install|upgrade|uninstall|rollout)\b", blob
+    ):
+        emit(True, "read-only kubectl/helm call")
+
+    rc, out, _ = run(["kubectl", "config", "current-context"])
+    ctx = out.strip() if rc == 0 else ""
+
+    wanted_domain = pick_domain(blob)
+    wanted_ctx = CONTEXTS[wanted_domain]
+
+    if ctx != wanted_ctx:
+        emit(
+            False,
+            f"cluster-routing: context '{ctx}' does not match domain "
+            f"'{wanted_domain}'. Run: kubectl config use-context {wanted_ctx}",
+            wanted_context=wanted_ctx,
+            current_context=ctx,
+        )
+
+    emit(True, f"context '{ctx}' matches domain '{wanted_domain}'")
+
+
+if __name__ == "__main__":
+    main()

package/src/policies/enforcers/codebase_read_before_plan.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""codebase-read-before-plan enforcer: plans require prior reads of target paths."""
+from __future__ import annotations
+import os
+import re
+import sys
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from _common import arg_str, emit, parse_cli  # 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
+
+
+def recent_reads() -> set[str]:
+    if not READ_LOG.exists():
+        return set()
+    out: set[str] = set()
+    now = time.time()
+    for line in READ_LOG.read_text().splitlines():
+        try:
+            ts, path = line.split("\t", 1)
+            if now - float(ts) < RECENT_SEC:
+                out.add(path)
+        except ValueError:
+            continue
+    return out
+
+
+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 op")
+
+    reads = recent_reads()
+    if reads:
+        emit(True, f"{len(reads)} recent codebase reads on record")
+
+    emit(
+        False,
+        "codebase-read-before-plan: no Read/Grep/Glob within the last 30 min. "
+        "Read the existing codebase in the target scope before emitting a plan.",
+    )
+
+
+if __name__ == "__main__":
+    main()

package/src/policies/enforcers/coord_overlap.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""coord-overlap enforcer: check for in-flight agent path reservations."""
+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
+
+AGENT_OPS = {"Agent", "spawn-agent", "subagent", "delegate"}
+
+
+def overlapping_reservations(root: Path, paths: list[str]) -> list[str]:
+    db = root / "agents" / "data" / "coordination" / "coordination.db"
+    if not db.exists() or not paths:
+        return []
+    try:
+        con = sqlite3.connect(f"file:{db}?mode=ro", uri=True, timeout=1.0)
+        # Best-effort: look for any reservations table with path-like column
+        cur = con.execute(
+            "SELECT name FROM sqlite_master WHERE type='table'"
+        )
+        tables = [r[0] for r in cur.fetchall()]
+        hits: list[str] = []
+        for t in tables:
+            try:
+                cols = [r[1] for r in con.execute(f"PRAGMA table_info({t})")]
+                path_col = next(
+                    (c for c in cols if c.lower() in ("path", "paths", "file", "scope")),
+                    None,
+                )
+                status_col = next(
+                    (c for c in cols if c.lower() in ("status", "state", "active")), None
+                )
+                if not path_col:
+                    continue
+                where = f" WHERE {status_col} IN ('active','in_progress',1)" if status_col else ""
+                rows = con.execute(f"SELECT {path_col} FROM {t}{where}").fetchall()
+                for (v,) in rows:
+                    if not v:
+                        continue
+                    for p in paths:
+                        if p and p in str(v):
+                            hits.append(f"{t}:{v}")
+            except sqlite3.Error:
+                continue
+        con.close()
+        return hits
+    except sqlite3.Error:
+        return []
+
+
+def main() -> None:
+    op, args = parse_cli()
+    if op not in AGENT_OPS:
+        emit(True, "not an agent-spawn op")
+
+    paths_raw = (
+        args.get("paths")
+        or args.get("scope")
+        or args.get("prompt", "")
+    )
+    if isinstance(paths_raw, list):
+        paths = [str(p) for p in paths_raw]
+    else:
+        paths = [p for p in str(paths_raw).split() if "/" in p]
+
+    hits = overlapping_reservations(repo_root(), paths)
+    if hits:
+        emit(
+            False,
+            f"coord-overlap: active reservations on: {', '.join(hits[:5])}. "
+            "Run `uap coordination check` before spawning.",
+        )
+
+    emit(True, "no overlapping reservations")
+
+
+if __name__ == "__main__":
+    main()