@miller-tech/uap 1.40.1 → 1.41.0

package/src/policies/schemas/policies/merge-deploy-monitor-verify.md

@@ -0,0 +1,145 @@
+# Policy: Merge, Deploy, Monitor, Verify
+
+**ID**: `policy-merge-deploy-monitor-verify`
+**Name**: Merge, Deploy, Monitor, Verify Before Done
+**Category**: completion
+**Level**: REQUIRED
+**Enforcement Stage**: review
+**Version**: 1.0
+
+## Purpose
+
+This policy enforces that a change is NOT DONE until it has been merged, rolled out via the designated pipeline, observed healthy in the target environment for a defined monitoring window, and verified with captured evidence to behave correctly end-to-end. Local "build green + tests pass" is necessary but not sufficient — DONE requires evidence from the deployed system, not just CI.
+
+## Rules
+
+```rules
+- title: "Merge Gate"
+  keywords: ["done", "complete", "finish", "close", "resolve", "shipped"]
+  antiPatterns: ["direct push to master", "no pr", "skip review", "force merge", "ci failing", "merged with red ci"]
+
+- title: "Deploy Gate"
+  keywords: ["done", "complete", "deploy", "release", "ship", "rollout"]
+  antiPatterns: ["manual deploy", "ad-hoc cluster command", "hand-edited resource", "deploy skipped", "deployment failed", "pipeline bypassed", "out-of-band rollout"]
+
+- title: "Monitor Gate"
+  keywords: ["done", "complete", "monitor", "observe", "verify health"]
+  antiPatterns: ["no monitoring window", "skip observation", "no dashboard checked", "alerts not reviewed", "ignored error rate", "skipped post-deploy check"]
+
+- title: "Verify Gate"
+  keywords: ["done", "complete", "verify", "confirm", "validate behavior"]
+  antiPatterns: ["unverified", "tests passed so done", "ci is enough", "no end-to-end check", "no evidence captured", "happy path only", "negative case skipped"]
+
+- title: "Evidence Capture"
+  keywords: ["close task", "mark done", "complete task", "resolve task"]
+  antiPatterns: ["no merge sha", "no deploy url", "no monitoring evidence", "no verification output", "missing screenshot", "missing log excerpt"]
+```
+
+## Enforcement Behavior
+
+### When Triggered
+
+This policy is enforced during the **review stage** when:
+
+- Task status is being changed to DONE, COMPLETE, CLOSED, or RESOLVED
+- A pull request is being declared "shipped"
+- An incident or change request is being closed
+- Work is being declared finished in any form
+
+### Required Actions Before Completion
+
+1. **Merge Gate**
+   - Change merged via reviewed PR from a feature/worktree branch into the integration branch
+   - All CI required checks green on the merge commit (build, tests, lint, type-check)
+   - At least one approving review (or self-review with explicit documented justification for trivial changes)
+   - Merge commit SHA recorded
+
+2. **Deploy Gate**
+   - Designated automated deployment pipeline executed end-to-end without error
+   - Application changes: artifact published and rollout completed in target environment(s) (staging through production, as scoped)
+   - Infrastructure changes: IaC pipeline succeeded (composes with `definition-of-done-iac`)
+   - Pipeline run URL recorded
+   - Manual deploys, ad-hoc cluster commands, and hand-edited cloud resources are FORBIDDEN as the deploy path
+
+3. **Monitor Gate**
+   - Minimum post-deploy observation window elapsed:
+     - 15 minutes for low-risk changes
+     - 1 hour for service/infrastructure changes
+     - 24 hours for high-blast-radius changes (auth, payments, data migrations, schema changes, traffic routing)
+   - Health signals reviewed and clean during the window:
+     - Error rate (no new error classes, no rate increase above baseline)
+     - Latency (p50/p95/p99 within SLO)
+     - Saturation (CPU/memory/connections within healthy bounds)
+     - Logs (no new ERROR/FATAL lines tied to the change)
+     - Alerts (no new alerts firing related to the change)
+   - Dashboard/log links recorded
+   - Any degraded signal blocks DONE until rolled back or rolled forward with a fix
+
+4. **Verify Gate**
+   - The specific behavior introduced/fixed is exercised end-to-end against the deployed environment
+   - Verification method matches change type:
+     - API/backend: live request against deployed endpoint with expected response asserted
+     - UI/frontend: interactive walkthrough of golden path AND the specific edge case
+     - Infrastructure: cluster/cloud CLI query confirming the resource exists and behaves as designed
+     - Data/schema: query confirming migrated data is shaped correctly and reads/writes succeed
+   - At least one negative case explicitly checked (the failure mode the change prevents does not occur)
+   - Evidence captured: response body, screenshot, command output, or log excerpt
+   - CI green is NOT verification — verification requires evidence from the deployed system
+
+### Verification Checklist
+
+Before marking work as DONE, verify and attach:
+
+- [ ] Merge commit SHA and PR URL recorded
+- [ ] Deployment pipeline run URL recorded
+- [ ] Target environment(s) reached and recorded (e.g. staging, production)
+- [ ] Monitoring window start/end timestamps recorded
+- [ ] Dashboard/log links reviewed during the window and attached
+- [ ] Health signals (error rate, latency, saturation, logs, alerts) all clean
+- [ ] Verification evidence captured (command output, response body, screenshot)
+- [ ] Negative case checked and the prevented failure mode confirmed absent
+- [ ] No new alerts fired during or after the observation window
+
+### Anti-Patterns to Avoid
+
+DO NOT mark tasks as DONE when:
+
+- The PR has been merged but the rollout hasn't run yet ("merged != deployed")
+- The rollout succeeded but no one observed the system afterwards ("deployed != working")
+- CI is green but the deployed environment was never exercised ("CI != production")
+- The monitoring window was skipped because "it's a small change"
+- Verification consisted of "the tests cover it" — tests cover code paths, not deployed behavior
+- Only the happy path was verified and the negative case was skipped
+- "No alerts fired" was used as proof of health when no alerts exist for the changed surface area
+- The deploy/monitor/verify gates were deferred to "next sprint" or "ops can check later"
+- Evidence was claimed but not actually captured or attached
+
+## Implementation Notes
+
+This policy should be enforced by:
+
+1. **Task management gate** — block status transitions to DONE/CLOSED until evidence fields are populated
+2. **PR merge bots** — require deployment status checks before allowing merge to be marked "shipped"
+3. **CI/CD pipelines** — emit deployment and verification webhooks that the policy gate consumes
+4. **Policy gate system (`uap-policy check`)** — validate before allowing completion commands
+
+## Default Status
+
+**Default: ON**
+**Level: REQUIRED**
+
+This policy is on by default for all UAP-managed projects. Disable only with explicit project-level override and documented justification (e.g. local-only experiments, scratch projects).
+
+## Related Policies
+
+- `policy-completion-gate` — Local completion gates (tests, build, lint, version bump, worktree)
+- `policy-mandatory-testing-deployment` — Test creation and quality requirements
+- `policy-definition-of-done-iac` — IaC-specific deploy + cluster verify requirements
+- `policy-iac-pipeline-enforcement` — Pipeline-only deploy path for infrastructure
+
+The local completion gate gets a change ready to ship. This policy ensures the change actually shipped, stayed healthy, and demonstrably works in the environment that matters.
+
+---
+
+_Last Updated: 2026-05-04_
+_Author: Miller Tech UAP System_

package/src/policies/schemas/policies/parallel-reads.md

@@ -0,0 +1,24 @@
+# parallel-reads
+
+**Category**: custom
+**Level**: RECOMMENDED
+**Enforcement Stage**: pre-exec
+**Tags**: performance, parallelism, exploration
+
+## Rule
+
+Two or more independent read-only operations (`Read`, `Grep`, `Glob`, non-mutating `Bash`, `WebFetch`) with no data dependency MUST be dispatched in a single tool-call batch.
+
+## Why
+
+Serial fan-out multiplies wall-clock by N on every exploration. Claude Code supports parallel tool calls in one message. Measured speed-up on codebase surveys: 2–5×.
+
+## Enforcement
+
+Python enforcer `parallel_reads.py` (post-exec sampler) detects serial read patterns within a tight time window and warns on the next message.
+
+```rules
+- title: "Batch independent reads"
+  keywords: [read, grep, glob, webfetch, inspect]
+  antiPatterns: [serial-read, one-by-one, sequential-survey]
+```

package/src/policies/schemas/policies/rtk-wrap.md

@@ -0,0 +1,26 @@
+# rtk-wrap
+
+**Category**: custom
+**Level**: REQUIRED
+**Enforcement Stage**: pre-exec
+**Tags**: rtk, tokens, efficiency
+
+## Rule
+
+These commands MUST be invoked via `rtk` wrapper, not directly: `git`, `kubectl`, `docker`, `docker-compose`, `npm`, `pnpm`, `yarn`, `helm`, `terraform`.
+
+Exception: `rtk` meta-commands (`rtk gain`, `rtk discover`, `rtk proxy`, `rtk --version`).
+
+## Why
+
+RTK delivers 60–90% token reduction on dev ops (`~/.claude/RTK.md`). Missing the wrap = proportional context waste.
+
+## Enforcement
+
+Python enforcer `rtk_wrap.py` inspects the Bash command string and blocks if a wrapped binary is invoked without the `rtk ` prefix.
+
+```rules
+- title: "Wrap heavy CLIs with rtk"
+  keywords: [bash, shell, git, kubectl, docker, npm, pnpm, yarn, helm, terraform]
+  antiPatterns: [raw-kubectl, raw-git, raw-docker, raw-npm]
+```

package/src/policies/schemas/policies/schema-diff-gate.md

@@ -0,0 +1,30 @@
+# schema-diff-gate
+
+**Category**: infrastructure
+**Level**: REQUIRED
+**Enforcement Stage**: pre-exec
+**Tags**: postgres, cnpg, pgdog, migrations, schema, spock, redis
+
+## Rule
+
+Changes to DB schema, connection pooler config, or replication topology MUST pass `uap schema-diff` before commit:
+
+- `migrations/**/*.sql`
+- `infra/postgres-spock/**`
+- `infra/helm_charts/**/pgdog*`
+- CNPG `Cluster` spec (pool sizes, instance count, connection limits)
+- Redis Sentinel / Envoy HA-write proxy configs
+
+## Why
+
+Branch `fix/zitadel-pgdog-capacity-v2` exists because a prior capacity change escaped review. PgDog connection limits cascade into Zitadel auth outages. Pre-commit gating prevents "v2 hotfix" cycles.
+
+## Enforcement
+
+Python enforcer `schema_diff_gate.py` runs `uap schema-diff` (or checks recent successful run in memory ≤1h) when the diff touches the listed paths.
+
+```rules
+- title: "Schema/capacity changes must pass schema-diff"
+  keywords: [migration, schema, pgdog, cnpg, spock, postgres, redis, sentinel, envoy, pool]
+  antiPatterns: [ALTER TABLE, max_connections, pool_size, instances:, replicas:]
+```

package/src/policies/schemas/policies/session-memory-write.md

@@ -0,0 +1,24 @@
+# session-memory-write
+
+**Category**: workflow
+**Level**: REQUIRED
+**Enforcement Stage**: post-exec
+**Tags**: memory, session, uap
+
+## Rule
+
+A session that changed code (Edit/Write/MultiEdit occurred) MUST insert at least one `session_memories` row with `type IN ('decision','lesson','pattern')` before terminating.
+
+## Why
+
+Session-end logs show most sessions end with no memory write even when code changed. Lessons evaporate. UAP's memory system only works if write-back happens.
+
+## Enforcement
+
+Python enforcer `session_memory_write.py` runs on session-end hook: if code_changed=true, verify a matching row exists in `agents/data/memory/short_term.db`.
+
+```rules
+- title: "Close the learning loop on code sessions"
+  keywords: [session-end, stop, terminate, finish]
+  antiPatterns: [no-memory-write, skip-lesson]
+```

package/src/policies/schemas/policies/task-required.md

@@ -0,0 +1,49 @@
+# task-required
+
+**Category**: workflow
+**Level**: REQUIRED
+**Enforcement Stage**: pre-exec
+**Tags**: uap, task, workflow, enforcement
+
+## Rule
+
+A UAP task MUST be `in_progress` before any mutating work. When no row in
+`.uap/tasks/tasks.db` has `status='in_progress'`, the enforcer blocks:
+
+- `Edit` / `Write` / `MultiEdit` on non-exempt paths
+- Bash ship actions: `git commit`, `git push`, `gh pr create`
+
+Exempt path prefixes (no task required): `.claude/`, `.cursor/`, `.opencode/`,
+`.codex/`, `.forge/`, `.uap/`, `.policy-tools/`, `src/policies/`, `scripts/`,
+`docs/`.
+
+To proceed: `uap task create --type <task|bug|feature> --title "<desc>"` then
+`uap task update <id> --status in_progress` (or `uap task claim <id>`).
+
+## Why
+
+The UAP compliance protocol's "create a task before work" step has historically
+been delivered as SessionStart text injection — advisory guidance the agent can
+silently skip. Observed in practice: a full multi-PR session completed with zero
+`uap task create` calls because nothing enforced it.
+
+A `pre-exec` policy enforcer makes the task requirement a hard gate rather than a
+suggestion, so UAP task tracking is guaranteed rather than best-effort. This is
+the task-tracking analogue of `worktree-required`.
+
+## Enforcement
+
+Python enforcer `task_required.py` resolves the primary worktree root via
+`git rev-parse --git-common-dir` (so it works from linked worktrees), reads
+`.uap/tasks/tasks.db`, and blocks when `COUNT(*) WHERE status='in_progress'` is
+zero.
+
+Fail-open: if UAP task tracking is not initialised (no `tasks.db`) or the DB is
+unreadable, the operation is allowed — non-UAP repositories are unaffected.
+Override for one-off meta-work: `UAP_NO_TASK=1`.
+
+```rules
+- title: "A UAP task must be in_progress before mutating work"
+  keywords: [edit, write, multiedit, bash, git commit, git push, gh pr create]
+  antiPatterns: [no-task, untracked-work, skip-task-create]
+```

package/src/policies/schemas/policies/test-gate.md

@@ -0,0 +1,24 @@
+# test-gate
+
+**Category**: quality
+**Level**: REQUIRED
+**Enforcement Stage**: review
+**Tags**: testing, pr, quality
+
+## Rule
+
+At PR-ready time, every changed service under `services/**` or `apps/**` MUST have a corresponding test delta (`tests/**` or `<service>/**/*.test.*`, `*_test.py`, `*.spec.ts`).
+
+## Why
+
+Session-end logs show `Tests: false` far more often than `true`. Review-stage gating ensures shipping code without tests is an explicit override, not the default.
+
+## Enforcement
+
+Python enforcer `test_gate.py` diffs `git diff --name-only origin/main...HEAD` against test-path regexes; blocks PR signoff if any changed service lacks a test file in the same PR.
+
+```rules
+- title: "Changed services require test deltas"
+  keywords: [pr, commit, merge, review, signoff]
+  antiPatterns: [no-tests, skip-tests, tests-later]
+```

package/src/policies/schemas/policies/validate-plan-before-build.md

@@ -0,0 +1,28 @@
+# validate-plan-before-build
+
+**Category**: workflow
+**Level**: REQUIRED
+**Enforcement Stage**: pre-exec
+**Tags**: planning, validation, accuracy
+
+## Rule
+
+When a plan is marked ready and the agent is about to begin implementation (first mutating tool call after plan emission: `Edit`, `Write`, `MultiEdit`, `Bash` that modifies state), the agent MUST first execute the prompt `validate the plan` and receive an explicit pass before proceeding.
+
+A plan is "ready" when:
+- User approves with "go", "build", "implement", "proceed", "ship it", "complete all", or similar
+- OR the agent emits ExitPlanMode / transitions out of a Plan phase
+
+## Why
+
+User directive: "when a plan is ready to build, execute prompt 'validate the plan'". Prevents shipping on stale/unvalidated plans — catches last-mile gaps before code changes begin.
+
+## Enforcement
+
+Python enforcer `validate_plan_before_build.py` tracks plan-ready state in session memory; on first mutating tool call post-ready, blocks and injects the `validate the plan` prompt. Unblocks only after a validation result is recorded.
+
+```rules
+- title: "Ready plans require explicit validation"
+  keywords: [edit, write, multiedit, implement, build, ship, commit]
+  antiPatterns: [unvalidated-plan, skip-validation, plan-stale]
+```

package/src/policies/schemas/policies/worktree-required.md

@@ -0,0 +1,28 @@
+# worktree-required
+
+**Category**: workflow
+**Level**: REQUIRED
+**Enforcement Stage**: pre-exec
+**Tags**: git, worktree, isolation, uap
+
+## Rule
+
+All `Edit`, `Write`, `MultiEdit` calls on tracked files MUST occur inside a UAP worktree at `.worktrees/NNN-<slug>/`. Exemptions:
+
+- Harness config under `.claude/`, `.cursor/`, `.opencode/`, `.codex/`, `.uap/`
+- New files under `src/policies/`, `scripts/`, `docs/`
+- Explicit override: user says "work directly" or `--no-worktree`
+
+## Why
+
+CLAUDE.md v2.3.0 mandates worktrees; the existing hook warns but doesn't block. Formalizing closes the gap — protects in-flight user edits from agent collisions.
+
+## Enforcement
+
+Python enforcer `worktree_required.py` checks whether the target file path is under `.worktrees/` and whether the session has an active worktree slug.
+
+```rules
+- title: "File edits must occur in a worktree"
+  keywords: [edit, write, multiedit, create-file, modify-file]
+  antiPatterns: [primary-checkout, no-worktree, direct-main]
+```

package/templates/hooks/uap-policy-gate.sh

@@ -30,6 +30,11 @@ export UAP_REPO_ROOT="$MAIN_ROOT"
 # actual WORKING TREE, not the (possibly bare) MAIN_ROOT. Expose the current checkout
 # so _common.worktree_root() targets the worktree when an op runs from inside one.
 export UAP_WORKTREE_ROOT="$CHECKOUT_ROOT"
+# Delivery enforcement defaults to BLOCK for UAP-managed projects: substantive
+# source edits must route through `uap deliver` (verified completion against the
+# gates). The `:-` preserves any explicit operator/CI override (advisory|block).
+# Escape hatches still apply: UAP_DELIVER_ACTIVE=1 (inside deliver) / UAP_DELIVER_BYPASS=1.
+export UAP_ENFORCE_DELIVERY="${UAP_ENFORCE_DELIVERY:-block}"
 cd "$MAIN_ROOT"
 
 TOOL="$(printf '%s' "$PAYLOAD" | python3 -c 'import json,sys; d=json.load(sys.stdin); print(d.get("tool_name") or d.get("tool") or "")' 2>/dev/null || true)"