@miller-tech/uap 1.40.1 → 1.42.0

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]
+```

package/src/policies/schemas/policies/mandatory-testing-deployment.md

@@ -0,0 +1,147 @@
+# Policy: Mandatory Testing & Deployment Verification
+
+**ID**: `policy-mandatory-testing-deployment`
+**Name**: Mandatory Testing and Deployment Verification
+**Category**: testing
+**Level**: REQUIRED
+**Enforcement Stage**: review
+**Version**: 1.0
+
+## Purpose
+
+This policy enforces that all code changes MUST complete testing, deployment verification, and quality checks before a task can be marked as DONE or closed. This prevents incomplete work from being considered finished.
+
+## Rules
+
+```rules
+- title: "Mandatory Test Creation"
+  keywords: ["done", "complete", "finish", "close", "resolve", "merge"]
+  antiPatterns: ["no new tests", "zero tests added", "skip test creation", "tests not written"]
+
+- title: "Testing Requirement"
+  keywords: ["done", "complete", "finish", "close", "resolve", "merge"]
+  antiPatterns: ["incomplete test", "no test coverage", "untested code", "skip test"]
+
+- title: "Version Bump Required"
+  keywords: ["done", "complete", "finish", "close", "resolve", "merge", "push"]
+  antiPatterns: ["manual version edit", "no version bump", "skip version", "version not bumped"]
+
+- title: "Deployment Verification Required"
+  keywords: ["deploy", "production", "release", "push", "merge"]
+  antiPatterns: ["unverified deployment", "no smoke test", "deployment failed"]
+
+- title: "Quality Gate Enforcement"
+  keywords: ["quality", "lint", "type-check", "coverage", "security"]
+  antiPatterns: ["disable lint", "bypass type check", "low coverage", "security warning"]
+
+- title: "Documentation Requirement"
+  keywords: ["document", "readme", "api", "changelog", "migration"]
+  antiPatterns: ["no documentation", "missing changelog", "undocumented change"]
+```
+
+## Enforcement Behavior
+
+### When Triggered
+
+This policy is enforced during the **review stage** when:
+
+- Task status is being changed to DONE, COMPLETE, or CLOSED
+- Pull request is being merged
+- Deployment is being finalized
+- Release is being published
+
+### Required Actions Before Completion
+
+1. **Mandatory Test Creation**
+   - At least 2 new test cases MUST be written for every code change
+   - Tests must cover the new or changed behavior (not unrelated code)
+   - Tests must follow existing patterns: `test/<feature>.test.ts` using vitest (`describe`/`it`/`expect`)
+   - Tests must assert correctness (not just "it doesn't throw")
+   - Bug fixes: at least one test must reproduce the bug scenario
+   - New features: tests must cover the happy path and at least one edge case
+
+2. **Testing Verification**
+   - All unit tests must pass including the new ones
+   - Test coverage maintained or improved (no regression)
+   - Integration tests must pass
+   - E2E tests must pass for critical paths
+   - No new test failures introduced
+
+3. **Version Bump**
+   - Version must be bumped via `npm run version:patch`, `version:minor`, or `version:major`
+   - Manual edits to `package.json` version field are prohibited
+   - Commit type determines bump level: fix->patch, feat->minor, breaking->major
+   - CHANGELOG.md is updated automatically by the version script
+   - Git tag is created automatically
+
+4. **Deployment Verification**
+   - Deployment to staging/preview environment successful
+   - Smoke tests passed in target environment
+   - Rollback plan verified (if applicable)
+   - No deployment warnings/errors
+
+5. **Quality Checks**
+   - Linting passes without errors
+   - Type checking passes (for TypeScript projects)
+   - Security scan shows no critical/high vulnerabilities
+   - Performance benchmarks within acceptable range
+
+6. **Documentation**
+   - Code comments updated for public APIs
+   - README.md updated if CLI/tools changed
+   - Changelog entry added (automated via version bump script)
+   - Breaking changes documented
+
+### Verification Checklist
+
+Before marking work as DONE, verify:
+
+- [ ] At least 2 new tests written for changed code
+- [ ] New tests assert correctness (not just "doesn't throw")
+- [ ] All tests passing (`npm test`)
+- [ ] Test coverage maintained or improved
+- [ ] Code linting passes (`npm run lint`)
+- [ ] Type checking passes (`tsc --noEmit`)
+- [ ] Version bumped via `npm run version:patch/minor/major`
+- [ ] CHANGELOG.md updated (automated via version script)
+- [ ] Git tag created (automated via version script)
+- [ ] Deployment to staging successful (if applicable)
+- [ ] Smoke tests passed in staging (if applicable)
+- [ ] No new security vulnerabilities
+- [ ] Documentation updated
+- [ ] Reviewers approved
+- [ ] No unresolved TODOs or FIXMEs
+
+### Anti-Patterns to Avoid
+
+❌ **DO NOT** mark tasks as DONE when:
+
+- No new tests were written for code changes
+- Tests are failing or skipped
+- Version was not bumped or was bumped manually
+- Deployment hasn't been verified
+- Code quality gates are bypassed
+- Documentation is missing or outdated
+- Critical bugs remain open
+- Security warnings are ignored
+- Rollback plan doesn't exist for breaking changes
+
+## Implementation Notes
+
+This policy should be enforced by:
+
+1. **CI/CD pipelines** - Block merges if tests fail
+2. **Code review tools** - Require passing quality checks
+3. **Task management systems** - Block status changes without verification
+4. **Policy gate system** - Validate before allowing completion commands
+
+## Related Policies
+
+- `policy-code-quality` - General code quality requirements
+- `policy-security-gate` - Security scanning requirements
+- `policy-deployment-safety` - Deployment safety checks
+
+---
+
+_Last Updated: 2026-03-18_
+_Author: Miller Tech UAP System_

package/src/policies/schemas/policies/mcp-router-first.md

@@ -0,0 +1,24 @@
+# mcp-router-first
+
+**Category**: custom
+**Level**: RECOMMENDED
+**Enforcement Stage**: pre-exec
+**Tags**: mcp, router, tokens, context
+
+## Rule
+
+When the session lists MCP tools as deferred (loaded on demand), agents MUST use `ToolSearch` / `uap mcp-router` to pull individual tool schemas on need rather than eagerly loading full MCP tool catalogs.
+
+## Why
+
+The session has 150+ deferred MCP tools (Playwright, Pay2U API, Terraform, Drive, etc.). Loading the full schema set burns ~30k+ tokens. UAP's MCP Router provides 98% token reduction (per CLI docs).
+
+## Enforcement
+
+Python enforcer `mcp_router_first.py` blocks bulk-load patterns and requires the specific tool name in the ToolSearch query.
+
+```rules
+- title: "Load MCP tools on demand"
+  keywords: [mcp, tool-schema, load-tools]
+  antiPatterns: [load-all, bulk-load, eager-schema]
+```

package/src/policies/schemas/policies/memory-before-plan.md

@@ -0,0 +1,24 @@
+# memory-before-plan
+
+**Category**: workflow
+**Level**: REQUIRED
+**Enforcement Stage**: pre-exec
+**Tags**: memory, uap, planning
+
+## Rule
+
+Before producing any implementation plan that spans 3+ steps or touches 3+ files, the agent MUST have queried `uap memory query <topic>` within the last 5 minutes. The UAP compliance protocol already mandates this; this policy enforces it.
+
+## Why
+
+Avoids re-deriving context already captured in prior sessions. Reduces duplicate work and keeps guidance coherent across agent runs.
+
+## Enforcement
+
+Python enforcer `memory_before_plan.py` checks `agents/data/memory/short_term.db` for a recent `uap memory query` action tagged with a relevant topic.
+
+```rules
+- title: "Plans must be preceded by memory query"
+  keywords: [plan, implement, build, design, architect]
+  antiPatterns: [no-memory-check, skip-history]
+```