@miller-tech/uap 1.40.0 → 1.41.0

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()

package/src/policies/schemas/policies/architecture-review.md

@@ -0,0 +1,51 @@
+# architecture-review
+
+**Category**: quality
+**Level**: REQUIRED
+**Enforcement Stage**: review
+**Tags**: uap, architecture, review, adr, enforcement
+
+## Rule
+
+When a PR-ready / merge operation is attempted and the diff vs. upstream touches
+architecturally significant paths, the change MUST be accompanied by either an
+ADR or an active waiver. Qualifying ("trigger") paths:
+
+- `src/types/**`
+- `**/schemas/**`
+- `src/index.ts`
+- `docs/architecture/**` (excluding `docs/architecture/adr/`)
+- `src/coordination/capability-router.ts`, `src/coordination/pattern-router.ts`
+
+The requirement is satisfied by either:
+
+- an ADR under `docs/architecture/adr/*.md` added or modified in the same diff, or
+- an active waiver `policies/waivers/*architecture-review*.md`.
+
+Otherwise the ship/merge op is blocked.
+
+## Why
+
+This policy backs the `architect-reviewer` droid's stated authority. The
+enforcer already existed and ran, but had **no policy document** describing it —
+agents and reviewers had no canonical reference for when architecture review is
+required or how to satisfy it. Significant decisions (public types, schemas,
+top-level exports, routing logic) carry high blast radius and cost of reversal;
+requiring an ADR (or an explicit waiver) ensures they are recorded and reviewed
+rather than slipping through in an unrelated change.
+
+## Enforcement
+
+Python enforcer `architecture_review.py` fires on PR-ready/merge operations,
+computes `git diff --name-only origin/master...HEAD` (falling back to
+`origin/main`), matches the trigger paths, and blocks unless an ADR is present
+in the diff or a matching waiver exists.
+
+Fail-open: if the upstream diff cannot be computed, the operation is allowed.
+Waivers are granted by `compliance-officer`.
+
+```rules
+- title: "Architecturally significant diffs require an ADR or waiver before merge"
+  keywords: [merge, pr-ready, gh pr create, signoff, ready-for-review, src/types, schemas, src/index.ts]
+  antiPatterns: [no-adr, unreviewed-architecture, skip-architecture-review]
+```

package/src/policies/schemas/policies/artifact-hygiene.md

@@ -0,0 +1,29 @@
+# artifact-hygiene
+
+**Category**: quality
+**Level**: REQUIRED
+**Enforcement Stage**: pre-exec
+**Tags**: git, hygiene, artifacts
+
+## Rule
+
+Binary artifacts (`*.png`, `*.jpg`, `*.pdf`, `*.zip`, `*.tar.gz`, `*.db`, `*.sqlite*`) MUST NOT be committed outside:
+
+- `docs/**`
+- `tests/**/__screenshots__/**`
+- `apps/**/public/**`, `apps/**/static/**`, `apps/**/assets/**`
+- `agents/data/memory/**` (scoped state)
+
+## Why
+
+Repo root currently has 80+ loose audit PNGs, screenshots, and stale DBs — bloats the repo, confuses reviewers, breaks shallow clones. Keeping artifacts in curated subdirs preserves git performance.
+
+## Enforcement
+
+Python enforcer `artifact_hygiene.py` inspects `git status` / new Write targets and rejects blocked paths.
+
+```rules
+- title: "Binary artifacts belong in curated dirs"
+  keywords: [write, create-file, commit, git-add]
+  antiPatterns: [.png, .jpg, .zip, .tar.gz, .sqlite]
+```

package/src/policies/schemas/policies/cluster-routing.md

@@ -0,0 +1,31 @@
+# cluster-routing
+
+**Category**: infrastructure
+**Level**: REQUIRED
+**Enforcement Stage**: pre-exec
+**Tags**: kubernetes, istio, multi-cluster, iac
+
+## Rule
+
+`kubectl apply|patch|create|edit|delete` and `helm install|upgrade|uninstall` MUST target the cluster context matching the component's domain:
+
+- **Observability** (Grafana, Prometheus, OpenObserve, Fluent Bit, ServiceMonitor, alerts, dashboards) → `do-syd1-pay2u-openobserve`
+- **Authentication / Identity** (Zitadel, OIDC, IAM CRDs) → `do-syd1-zitadel`
+- **Everything else** (apps, APIs, CMS, web, ML services, PgDog, Redis, Postgres/CNPG) → `do-syd1-pay2u`
+
+## Why
+
+AGENTS.md codifies the 3-cluster split. Cross-cluster mistakes cost 10–30 min per rollback plus reconciliation. Cross-cluster traffic MUST use public HTTPS URLs, never cluster-internal DNS.
+
+## Enforcement
+
+Python enforcer `cluster_routing.py` checks `kubectl config current-context` against the manifest's domain before allowing the command.
+
+```rules
+- title: "kubectl context must match component domain"
+  keywords: [kubectl, helm, apply, patch, install, upgrade]
+  antiPatterns: [wrong-context, cross-cluster-dns]
+- title: "Cross-cluster calls must use public HTTPS"
+  keywords: [cross-cluster, service-mesh]
+  antiPatterns: [svc.cluster.local, internal-dns]
+```

package/src/policies/schemas/policies/codebase-read-before-plan.md

@@ -0,0 +1,30 @@
+# codebase-read-before-plan
+
+**Category**: workflow
+**Level**: REQUIRED
+**Enforcement Stage**: pre-exec
+**Tags**: planning, exploration, accuracy
+
+## Rule
+
+Before emitting any implementation plan (plans with ≥2 steps or touching any code path), the agent MUST have read the relevant existing codebase in the same session:
+
+- At least one `Read` of a file in the target service/app, OR
+- At least one `Grep` / `Glob` over the target paths, OR
+- A completed `Agent(subagent_type=Explore)` for the target domain
+
+Plans produced without this evidence are rejected.
+
+## Why
+
+Planning without reading generates drift-prone, hallucinated plans that conflict with existing conventions. User's directive: ground plans in the actual codebase first.
+
+## Enforcement
+
+Python enforcer `codebase_read_before_plan.py` scans the recent tool-call log for read operations against files within the plan's declared scope; blocks plan emission if none found.
+
+```rules
+- title: "Plans must follow codebase reads"
+  keywords: [plan, design, propose, architect, implement]
+  antiPatterns: [plan-without-read, unread-scope, blind-plan]
+```

package/src/policies/schemas/policies/coord-overlap.md

@@ -0,0 +1,24 @@
+# coord-overlap
+
+**Category**: workflow
+**Level**: RECOMMENDED
+**Enforcement Stage**: pre-exec
+**Tags**: agents, coordination, parallelism
+
+## Rule
+
+Before spawning a second or subsequent Agent/sub-agent that will write files, call `uap coordination check <paths>` to detect overlap with in-flight agents.
+
+## Why
+
+Multi-harness setup (.claude, .cursor, .opencode, .codex, .forge all present) creates collision risk. Overlap causes lost work and merge pain. `uap coordination check` is already available — unused.
+
+## Enforcement
+
+Python enforcer `coord_overlap.py` queries `agents/data/coordination/coordination.db` for active reservations on the target paths and blocks if conflicts exist.
+
+```rules
+- title: "Parallel agents require overlap check"
+  keywords: [agent, spawn, subagent, parallel, delegate]
+  antiPatterns: [skip-coord, no-reservation, overlap-ignore]
+```

package/src/policies/schemas/policies/delivery-enforcement.md

@@ -0,0 +1,45 @@
+# delivery-enforcement
+
+**Category**: safety
+**Level**: RECOMMENDED
+**Enforcement Stage**: pre-exec
+**Tags**: uap, delivery, deliver, convergence, enforcement
+
+## Rule
+
+Substantive coding work SHOULD go through the `uap deliver` convergence loop,
+which drives a model to verified completion against the project's real gates
+(build, type-check, tests) rather than ad-hoc hand edits.
+
+The enforcer fires on `Edit` / `Write` / `MultiEdit` operations targeting
+source-code files. It is satisfied when any of the following holds:
+
+- the edit runs inside a deliver-driven context (`UAP_DELIVER_ACTIVE=1`),
+- an explicit operator override is set (`UAP_DELIVER_BYPASS=1`),
+- the target is not source code, or is a docs/config/script/policy/test path.
+
+Otherwise the policy applies.
+
+## Why
+
+`uap deliver` exists and is auto-routable (CLI + MCP `deliver` tool), and it
+classifies task complexity to enable the right convergence aids automatically.
+But nothing previously *encouraged or required* coding agents to use it — the
+capability was available, not enforced. This policy closes that gap: it makes
+the expectation explicit and, when a team opts in, enforces it.
+
+## Enforcement
+
+Python enforcer `delivery_enforcement.py`.
+
+**Default mode is ADVISORY** — it always allows the edit and logs a one-line
+nudge toward `uap deliver`. Installing the policy therefore never breaks normal
+editing.
+
+**Strict mode is opt-in** via `UAP_ENFORCE_DELIVERY=block`: a direct source
+edit outside a deliver context is then blocked (exit 2) until the work is routed
+through `uap deliver` or `UAP_DELIVER_BYPASS=1` is set.
+
+Exempt by construction: non-source files; `docs/`, `scripts/`, `policies/`,
+`src/policies/`, test files (deliver protects those itself); and tooling
+dot-dirs (`.claude/`, `.uap/`, `.worktrees/`, …).

package/src/policies/schemas/policies/doc-live-over-report.md

@@ -0,0 +1,32 @@
+# doc-live-over-report
+
+**Category**: quality
+**Level**: REQUIRED
+**Enforcement Stage**: pre-exec
+**Tags**: docs, hygiene, debt
+
+## Rule
+
+New files matching these patterns under `infra/**`, `docs/**`, or repo root are BLOCKED:
+
+- `*_REPORT.md`
+- `*_COMPLETE.md`
+- `*_SUMMARY.md`
+- `*_FIX_<date>.md`, `*_<YYYY-MM-DD>.md`
+- `*_PLAN.md` (use tasks, not doc files)
+
+Agents MUST update canonical README.md / runbooks instead.
+
+## Why
+
+The repo contains ~30 retrospective markdown reports under `infra/` — they rot, nobody reads them, and they bury live docs. The user's global rule: truth lives in code + canonical docs, not dated reports.
+
+## Enforcement
+
+Python enforcer `doc_live_over_report.py` inspects the target path of `Write` operations and rejects matching filenames.
+
+```rules
+- title: "No dated retrospective doc files"
+  keywords: [write, create-file, markdown]
+  antiPatterns: [_REPORT.md, _COMPLETE.md, _SUMMARY.md, _PLAN.md, _FIX_]
+```

package/src/policies/schemas/policies/expert-review-required.md

@@ -0,0 +1,60 @@
+# expert-review-required
+
+**Category**: quality
+**Level**: REQUIRED
+**Enforcement Stage**: review
+**Tags**: uap, review, quality, enforcement, parallel-expert-review
+
+## Rule
+
+A parallel expert review MUST precede shipping a non-trivial change. When no
+review artifact exists for the current branch (or the artifact is stale relative
+to `HEAD`), the enforcer blocks the ship actions:
+
+- `git commit`, `git push`
+- `gh pr create`
+- merge / pr-ready / signoff / ready-for-review operations
+
+Review artifact: `.uap/reviews/<branch-slug>.json`, written by the
+`parallel-expert-review` skill on consolidation. The slug is an **injective
+percent-encoding** of the branch name (`%`→`%25`, `/`→`%2F`) so distinct refs
+like `feature/foo` and `feature-foo` never collide on one artifact. Recognised
+shape:
+
+```json
+{ "branch": "<name>", "head": "<sha>", "verdict": "approve", "reviewers": ["code-quality-reviewer", "security-code-reviewer", "..."] }
+```
+
+If the artifact records a `branch` that differs from the current branch, or a
+`head` that differs from the current `HEAD`, the review is rejected (mismatch /
+stale) and the op is blocked until a fresh review is recorded. Including
+`branch` and `head` is strongly recommended so the artifact unambiguously
+identifies what it covers.
+
+## Why
+
+The `parallel-expert-review` skill (and the `architect-reviewer` droid) claim
+review is "REQUIRED by policy", but no enforcer ever checked that a review
+actually ran — the requirement was advisory and silently skippable. This policy
+makes review a hard, artifact-backed gate: ship actions fail until the review
+fan-out (code-quality, security, performance, documentation, test-coverage) has
+run and its consolidated verdict is recorded for the current HEAD.
+
+This is the review analogue of `task-required` and `worktree-required`: convert
+a protocol step that was best-effort into an enforced precondition.
+
+## Enforcement
+
+Python enforcer `expert_review_required.py` resolves the current branch and
+HEAD via git, then checks `.uap/reviews/<branch-slug>.json` (slug = branch name
+with `/` → `-`). Missing artifact → block; present but `head` mismatch → block
+(stale); present and current → allow.
+
+Fail-open: if the branch/HEAD cannot be resolved (detached HEAD, non-git tree),
+the operation is allowed. Override for one-off meta-work: `UAP_NO_REVIEW=1`.
+
+```rules
+- title: "A parallel expert review must precede ship"
+  keywords: [git commit, git push, gh pr create, merge, pr-ready, signoff, ready-for-review]
+  antiPatterns: [no-review, unreviewed-ship, skip-review]
+```

package/src/policies/schemas/policies/iac-parity.md

@@ -0,0 +1,31 @@
+# iac-parity
+
+**Category**: infrastructure
+**Level**: REQUIRED
+**Enforcement Stage**: pre-exec
+**Tags**: terraform, helm, iac, drift, reproducibility
+
+## Rule
+
+Any live-state change MUST be paired with an IaC change in the same worktree:
+
+- `kubectl patch|apply|edit|create|delete` → must also modify `infra/terraform/**`, `infra/helm_charts/**`, or `infra/kubernetes/**`
+- Helm `--set` overrides → must also update `values.yaml`
+- DigitalOcean / cloud console changes are forbidden; use Terraform
+
+## Why
+
+User's global rule: "always apply state changes to IaC to ensure reproducibility." The repo has ~30 `IAC_PARITY_*`/`DRIFT_ANALYSIS_*` retrospectives — each a drift incident. Catching at author-time eliminates the loop.
+
+## Enforcement
+
+Python enforcer `iac_parity.py` verifies the worktree has staged/unstaged diffs under the IaC paths when a mutating cluster command is issued.
+
+```rules
+- title: "Live state changes require IaC diff"
+  keywords: [kubectl, helm, doctl, terraform, aws, gcloud, apply, patch, create, delete, edit]
+  antiPatterns: [--force, --no-iac, manual-console]
+- title: "No ad-hoc cloud console changes"
+  keywords: [doctl, aws, gcloud, console]
+  antiPatterns: [click-ops, manual-edit]
+```