@miller-tech/uap 2.1.7 → 2.11.0

package/docs/reference/review-prepass.md

@@ -0,0 +1,77 @@
+# Review Pre-Pass
+
+Deterministic ruleset scanner that runs **before** the LLM reviewers in the
+parallel review protocol — item 0.2 of the
+[System-1 uplift plan](../plans/system1-uplift-2026-09-18.md), after the
+open-code-review precedent (deterministic rule pipelines first, LLM agent
+second).
+
+## Running
+
+```bash
+uap review prepass              # scan changed files vs upstream base
+uap review prepass --files src/a.ts,src/b.py
+uap review prepass --write      # merge findings into the review artifact
+uap review prepass --json
+```
+
+Exit code is 1 when any HIGH finding fires (advisory — blocking stays with
+the `expert-review-required` enforcer), so CI and scripts can gate on it.
+
+## What it catches
+
+High-precision, line-anchored rules — the bar is "almost always worth a
+reviewer's glance," because a scanner that cries wolf teaches reviewers to
+ignore it:
+
+| Category | Rules |
+| --- | --- |
+| secrets | AWS access key ids, private key blocks, secret-named string literals, GitHub/Slack/LLM-provider/npm token prefixes, JWTs |
+| injection | `eval(`, `new Function(`, interpolated or concatenated `exec`, `shell=True`, `innerHTML =` / `dangerouslySetInnerHTML` / `document.write` / `insertAdjacentHTML`, CORS wildcards (header and middleware forms) |
+| sql | template interpolation or string concatenation building SQL |
+| error-handling | empty `catch` (single- and multi-line forms), Python `except: pass` (single- and two-line forms) |
+| concurrency | Python `threading.Thread` with no `Lock` in the file |
+
+Secret rules scan every file type (prose leaks keys too); code rules only
+fire on source extensions. Ambiguous heuristics deliberately stay with the
+LLM reviewers — this pass owns pattern-matching, not judgment.
+
+**Secrets findings are redacted**: the snippet in the artifact and on stdout
+replaces the matched secret with `***redacted***`, because the artifact's
+purpose is inclusion in LLM reviewer prompts — the scanner must not multiply
+copies of what it detects. The file:line anchor is enough to inspect the
+secret in place.
+
+## Review protocol integration
+
+The `parallel-expert-review` skill runs `uap review prepass --write` as step
+0. Findings are written to `.uap/reviews/<branch-slug>.pre-pass.json` — a
+**sibling** of the review artifact, never `<branch-slug>.json` itself, because
+the expert-review enforcer treats that file's existence as "a review
+happened". Writes are atomic (tmp + rename), and the slug encoding matches the
+enforcer's `slug_for` exactly. At consolidation the reviewers' verdict merges
+the pre-pass findings into the real artifact; every reviewer receives the
+pre-filtered findings in its prompt scope and must say so explicitly when
+dismissing one.
+
+## Decisions
+
+- **`src/review` vs reusing `src/quality/scanner.ts`:** the quality scanner is
+  a pure, I/O-free *metrics* scanner (complexity/CRAP/LOC) consumed by the
+  quality gate; the pre-pass is a security-*pattern* ruleset with git I/O
+  consumed by the review protocol. Different consumers and failure modes.
+- **Sibling artifact, not a `pre_pass` block in the enforcer's file:** the
+  enforcer's checks are all conditional on keys the pre-pass never writes, so
+  co-locating would let an advisory pass satisfy the blocking gate. (Found in
+  parallel review of the introducing PR.)
+- **Advisory exit code, blocking left to the enforcer:** HIGH findings exit 1
+  for CI/scripts, but the pre-pass itself never blocks a ship action.
+- **Slug encoding duplicated across TS/Python:** `branchSlug()` mirrors
+  `slug_for()` byte-for-byte and is pinned by a cross-checking test.
+
+## Proven on day one
+
+The first dogfood scan of this repo's own CLI found a real command-injection
+path (`uap worktree create <slug>` interpolating the argument into a shell
+string) — fixed in the same change that introduced the scanner. Remaining
+interpolated-`execSync` call sites are ticketed for a follow-up sweep.

package/docs/reference/routing-evals.md

@@ -0,0 +1,71 @@
+# Routing Evals
+
+CI-enforced measurement of how well UAP's routable surfaces stay separable as
+the registry grows: the pattern library (`.factory/patterns/index.json`), the
+droid registry (`.factory/droids/`), and skills (`.factory/skills/`).
+
+This is item 0.4 of the
+[System-1 uplift plan](../plans/system1-uplift-2026-09-18.md) (lands with the
+plan PR; merge order: plan first), after the
+agent-dev-team precedent: rank-1 routing evals with planted traps, enforced in
+CI, so a new or edited description that collides with an existing entry fails
+the build instead of silently degrading routing.
+
+This is a **separability proxy**, not a replica of production routing — the
+production pattern router is keyword-substring multi-match, and droids/skills
+are routed by the LLM reading descriptions. The report includes the production
+router's fixture inclusion rate as an informational baseline alongside the
+TF-IDF rank-1 numbers.
+
+## Running
+
+```bash
+npm run eval:routing                  # console report, exit 1 below threshold
+npm run eval:routing -- --json        # machine-readable report
+npm run eval:routing -- --threshold 0.95
+```
+
+The same eval also runs as a vitest gate (`test/routing-eval.test.ts`, the
+"shipped corpus eval" block) and in the `routing-evals` GitHub workflow.
+
+## How it works
+
+1. **Corpus loading** (`src/evals/routing-corpus.ts`): patterns, droids, and
+   skills become uniform entries keyed `<kind>:<id>`. Entries without a
+   frontmatter description fall back to their first body paragraph and are
+   reported as *weak entries* — an unroutable-surface finding in itself.
+2. **Ranking** (`src/evals/tfidf.ts`): pure-TypeScript TF-IDF with naive
+   suffix stemming and stopword removal. No embedding model, no network —
+   airgap-pure and deterministic.
+3. **Evaluation** (`src/evals/routing-eval.ts`): fixtures in
+   `evals/routing/cases.json` declare a kind, a natural-language query, and
+   the expected entry id. Ranking is **kind-scoped** (patterns only against
+   patterns, etc.), matching how the surfaces are actually consumed.
+
+## Gate semantics
+
+- **Rank-1 accuracy ≥ 90%** over positive cases (configurable via
+  `--threshold`).
+- **Negatives are hard-gated**: a case with `expect: null` fails the whole run
+  when its top match shares **2+ distinct content tokens** with the query (a
+  route claim resting on a single shared word is not a route), or scores above
+  a 0.5 cosine backstop. This is ranker-agnostic by design — calibration showed
+  raw cosine cannot separate near-domain negatives (single high-idf token, up
+  to ~0.31) from weak positives (down to ~0.23). False-routing garbage input
+  is not a percentage-point problem.
+- **Fixture integrity**: a case referencing an entry that no longer exists is
+  an error, not a failure — stale fixtures can never silently shrink the eval.
+
+Local runs read the working tree, so untracked `.factory/` leftovers enter
+the corpus; CI checkouts are clean, so the gate is deterministic there.
+Local failures that CI doesn't reproduce usually mean untracked files.
+
+## Maintaining fixtures
+
+- Add one positive case per new pattern/droid/skill when you add the entry.
+- Add a trap (`"trap": true`) whenever two entries are confusable — the
+  diff-scoped vs proactive reviewer pairs are the canonical example. A trap
+  must still have one defensibly correct answer.
+- If a legitimate case fails, prefer improving the entry's description (that
+  is the eval working as intended) over rewording the query to dodge the
+  collision.

package/docs/reference/semantic-supervisor.md

@@ -0,0 +1,140 @@
+# Semantic Supervisor (`uap supervise`)
+
+A watchdog loop for `uap deliver` missions. It observes a run, assesses nine
+dimensions, and applies a deterministic, reviewed policy. Models may only
+**assess** — the decision is never made by a model.
+
+```
+uap supervise [runId|latest] [--once] [--json] [--interval-ms N] [-d projectDir]
+```
+
+- **Watch mode** (default): reassesses at most every `debounceMs` (5s,
+  state-change triggered) and at least every `intervalMs` (30s, heartbeat).
+  STOP and FINISH end the watch; ESCALATE **keeps watching** — a paged human
+  may take a while — until the mission ends or 20 consecutive suppressed
+  ESCALATE repeats go unanswered, at which point the watcher writes a final
+  `escalation unanswered` event and detaches. Ctrl-C detaches the watcher at
+  any time; the mission is unaffected. Watch mode exits 2 when the final
+  decision is STOP or ESCALATE, 0 otherwise.
+- **`--once`**: one observe → assess → decide → persist cycle, prints the
+  decision, exits. Exit code 0, or 2 when the action is STOP/ESCALATE (or the
+  supervisor refused to run).
+- **`--json`**: machine-readable decision; errors are emitted as JSON too.
+
+## What it observes
+
+Bounded snapshots only: the sanitized run state from
+`.uap/deliver-runs/<runId>/state.json` (via the same loader `uap deliver
+--resume` uses), the last 8KB of the newest matching `.uap/deliver-logs/*.log`
+(fd seek, never a whole-file read), `git status --porcelain` line count, and a
+capped `git diff --stat` (both via arg-array `execFileSync` with
+`core.fsmonitor`/`core.untrackedCache` disabled, 5s timeout, fail-soft).
+Nothing unbounded is ever read.
+
+**Path discipline.** Log reads lstat first and silently skip anything that is
+not a plain regular file (symlinks, FIFOs). Every directory the supervisor
+writes through — `.uap/supervise/<runId>` and, for the STOP file,
+`.uap/deliver-runs/<runId>` — is lstat'd and realpath-checked before use; a
+symlinked or non-directory path throws `SupervisorError` instead of writing
+outside the project.
+
+## Dimensions
+
+Nine per cycle: `progress-stalled`, `off-track`, `human-needed`,
+`stuck-loop`, `completion-signaled`, `verification-pending` (flags), and
+`error-density`, `iteration-pressure`, `risk` (1–5 scores). Heuristics always
+answer. The human-needed matcher is interrogative-only: credential prompts
+and approve/confirm questions fire; declaratives like "Permission denied" or
+"approved the change" do not. Healthy summary lines like "0 failed" never
+count as error evidence.
+
+An optional classifier (SYS1 contract, injected structurally — see Decisions)
+is asked only the built-in questions (`escalation-risk` noul, `action-class`
+choice). `escalation-risk=true` at probability ≥ `classifierTau` and
+confidence ≥ `classifierConfidenceMin` raises `off-track`; `action-class`
+`escalate` raises `stuck-loop`, `stop` raises `off-track`. The classifier may
+**raise** a flag, never clear one, and a throwing or absent classifier leaves
+the heuristics fully in charge. That is the fail-closed posture: model
+failure degrades to reviewed heuristics, never to looser supervision.
+
+## Actions
+
+Priority is fixed and safety-first: **terminal status → FINISH (delivered) /
+CONTINUE · iteration bounds → STOP · human-needed → ESCALATE ·
+off-track/stuck → RETRY (else ESCALATE when retries are spent) ·
+verification-pending → VERIFY · else CONTINUE.**
+
+| Action | Effect |
+| --- | --- |
+| `CONTINUE` | none — mission is within bounds |
+| `STOP` | writes the run's cooperative **STOP file** (`requestStop`). The deliver loop checkpoints and exits at its next turn boundary. **Never a signal, never a kill.** Outranks even human-need: an over-budget mission that is also waiting on a human is stopped, with the human-need recorded as `alsoEscalate` evidence. |
+| `RETRY` | consumes one retry from the budget (recorded; persists across processes) |
+| `VERIFY` | recorded prompt to verify; advisory. Never twice consecutively, and bounded by `maxVerify` — an unanswered verification falls into the stuck path (RETRY/ESCALATE) |
+| `FINISH` | records completion. Requires the authoritative `status: delivered`; a log tail claiming "mission complete" on a still-running mission never detaches supervision |
+| `ESCALATE` | event + console warning only; once per streak |
+
+The supervisor cannot kill, signal, or restart a mission. The only mutation it
+ever performs on a run is the cooperative STOP file. A run that is no longer
+running (`delivered`/`failed`/`interrupted`) is never STOPped or ESCALATEd,
+whatever its log tail contains.
+
+## Oscillation guards
+
+- `VERIFY` can never fire twice consecutively — an intervening non-VERIFY
+  action must re-arm it (policy-level, unit-tested).
+- `VERIFY` is budgeted: after `maxVerify` unanswered requests the mission is
+  treated as stuck.
+- `ESCALATE` and `FINISH` warn/act once per streak; repeats are recorded with
+  `suppressed: true` instead of re-firing. After 20 consecutive suppressed
+  ESCALATEs the watcher writes `escalation unanswered` and detaches.
+
+## State and ledger
+
+Per supervised run under `.uap/supervise/<runId>/`:
+
+- `state.json` — assessments count, retry/verify budgets spent, last action
+  (atomic tmp+rename writes, mode 0600). This is what makes the retry budget
+  survive across separate `--once` invocations.
+- `events.jsonl` — one v-stamped record per cycle: action, reason, evidence,
+  and every dimension's value **with its source** (`heuristic` |
+  `classifier`). File mode 0600.
+
+## Policy config
+
+Thresholds ship reviewed in `config/supervise-policy.json`:
+
+```json
+{ "version": 1, "stallMinutes": 10, "maxMinutes": 120, "maxTurns": 50,
+  "maxRetries": 2, "maxFailures": 3, "debounceMs": 5000, "intervalMs": 30000,
+  "classifierConfidenceMin": 0.7, "classifierTau": 0.6, "maxVerify": 3 }
+```
+
+Loading is loud: a missing, corrupt, mis-versioned, or out-of-range file
+throws `SupervisorError` and the supervisor refuses to run — it never invents
+defaults. `UAP_SUPERVISE_POLICY` points at an alternate policy file (tests,
+staged rollouts).
+
+## Decisions
+
+- **Budget authority is `max(policy, deliver budget)`.** The STOP threshold
+  for elapsed time is `max(maxMinutes, runBudgetMinutes(projectRoot))` — an
+  operator who raised a mission's budget (`UAP_DELIVER_MAX_MINUTES` or
+  `.uap.json delivery.maxRunMinutes`) must not be overruled by the
+  supervisor's static 120. A *lower* operator budget needs no supervisor
+  support: the deliver loop stops itself first.
+- **Classifier is a structural contract, not an import.** The SYS1 classifier
+  lands in PR #807; importing unmerged code would break the build the moment
+  either branch moves. Until #807 merges, `ClassifierLike` mirrors its shape,
+  only the built-in question names are ever sent (the #807 baseline throws on
+  custom names), and `recordShadow` wiring is deferred — the per-dimension
+  `source` field in `events.jsonl` is the seam it will write through. When
+  #807 lands: replace the interface with the real import, reconcile the
+  `noul`/`choice` kind vocabulary, and wire shadow recording.
+- **STOP outranks ESCALATE.** A mission past its iteration budget stops even
+  when it is also blocked on a human — stopping is the safer default and the
+  human-need survives as `alsoEscalate` evidence in the ledger.
+- **FINISH requires authoritative state.** Only `status: delivered` ends
+  supervision; success-shaped log lines are evidence, never proof.
+- **Escalations are bounded.** Twenty unanswered ESCALATE repeats detach the
+  watcher with a final ledger event — supervision that nobody reads must not
+  run forever.

package/docs/reference/system1-classifier.md

@@ -0,0 +1,103 @@
+# System-1 Classifier
+
+Uplift §6: the local, airgap-pure backend every Wave 1 consumer (semantic
+supervisor 1.1, compaction 1.2, AutoMode 1.3) talks to through **one
+interface**, so the model can evolve without touching policy code.
+
+## Interface
+
+```ts
+assess(state, questions) -> { [name]: { value, probability, confidence, backend } }
+```
+
+Question shapes mirror the noul/score/choice families so Jev-compatible
+fixtures work unchanged:
+
+| Question | Kind | Asks |
+| --- | --- | --- |
+| `escalation-risk` | noul | Does this state need escalation to a stronger technique or human review? |
+| `task-risk` | score (1–5) | How risky is the operation (1 trivial, 5 irreversible/destructive)? |
+| `action-class` | choice | `proceed` / `verify-first` / `escalate` / `stop` |
+
+v1 ships **one dimension end-to-end** (escalation risk) per the plan's scope
+discipline; the other two questions ride the same plumbing.
+
+## CLI
+
+```bash
+uap classify "<state text>"                  # all built-in questions
+uap classify "<state>" -q escalation-risk
+uap classify "<state>" --shadow              # also append to the shadow log
+uap classify --bench 500                     # latency self-check
+uap classify "<state>" --json
+```
+
+Advisory: exit 0 on success, 1 on usage errors or a failed latency bench.
+
+## Backend
+
+`baseline-tfidf-v1`: deterministic token scoring against incident/destructive
+vocabulary seeded from UAP's own telemetry language (the 2026-09-18 OOM
+timeline, gate outcomes), squashed through a logistic curve. CPU-only, no
+dependencies, no network, measured **p95 ≈ 0.02ms** against the 50ms budget.
+The trained-head slot (embedding + logistic/isotonic on nomic embeddings)
+inserts into `defaultBackend()` when a head ships — consumers don't change.
+
+## Thresholds are policy, not model output
+
+`config/classify-thresholds.json` (project) or
+`~/.config/uap/classify-thresholds.json` (operator):
+
+```json
+{ "version": 1, "questions": { "escalation-risk": { "tau": 0.6, "confidenceFloor": 0.3 } } }
+```
+
+- `tau` decides noul questions (`probability >= tau`) — noul only;
+  score/choice return their value directly, gated by `confidenceFloor`.
+- Below `confidenceFloor` the assessment carries `defer: true` — **the
+  heuristic decides**. That is the shadow-mode contract.
+
+Probability semantics per kind (consumers must rely on 0..1 ordering only):
+noul = probability the answer is true; score = 1 − normalized rounding
+distance; choice = winning score's share. The calibrated head replaces these
+approximations with true probabilities when it ships.
+
+## Shadow mode and promotion
+
+`--shadow` appends to `.uap/classify-shadow.jsonl` (git-ignored, local-only,
+mode 0600). The record is `{v, ts, stateHash, wordCount, questions, result,
+heuristicDecision?}` — a SHA-256 of the state text, never the text itself,
+so the log carries no raw-text surface (the hash is equality-revealing for
+low-entropy boilerplate states; acceptable for a local join key).
+`heuristicDecision` is the other half of the divergence loop: Wave 1
+consumers record what their heuristic actually decided, so the promotion
+gate can measure agreement from the log alone. Calibration joins outcome
+labels by hash.
+
+Promotion path (per the plan's risk section): classifier assesses, heuristics
+decide, divergence accumulates in the shadow log; a trained head is promoted
+only after measured agreement, and the calibration report lands in-repo with
+the thresholds that came from it.
+
+## Decisions
+
+- **Baseline before head.** An untrained embedding+head is unproven; the
+  deterministic baseline is the floor a head must beat on held-out shadow
+  data before it serves policy.
+- **Empty states get zero confidence**, not a confident guess — a blind
+  classifier must say so (same doctrine as `uap doctor`'s UNKNOWN).
+- **One GPU/CPU probe budget.** Assessments are synchronous and batched per
+  call; Wave 1 consumers batch questions per state.
+- **The baseline is question-scoped, not question-blind.** It answers only
+  the built-in questions and refuses others loudly — a custom noul question
+  must not silently inherit the escalation vocabulary. The trained head is
+  the generalizer.
+- **Kinship:** `src/models/complexity.ts` runs the same
+  heuristic-now-model-behind-the-same-interface-later play for task
+  complexity. The two should converge deliberately when the trained head
+  lands, not drift apart.
+
+Scope note: this is the **foundation slice** of uplift §6. The acceptance
+items that need shadow data and consumers — calibration report committed,
+supervisor/compaction/AutoMode running against the backend — land with the
+Wave 1 PRs that wire those consumers.

package/docs/reference/visual-captures.md

@@ -0,0 +1,113 @@
+# Visual Captures (Review Binding)
+
+Uplift 0.3 of the [System-1 uplift plan](../plans/system1-uplift-2026-09-18.md):
+any diff touching UI files requires before/after captures bound to the
+review, and completion gate 7 (self-review) refuses DONE without them.
+
+`uap design check` remains the design-token enforcer; `uap verify` /
+`visual_verification.py` remain the runtime render gate. This layer closes
+the gap between them: deterministic proof that a human-or-vision reviewer
+*looked at rendered before/after evidence* for the exact diff being shipped.
+
+## Surface definition
+
+A file is UI when its extension is `.css .scss .sass .less .tsx .jsx .vue
+.svelte .html .astro`, or it lives under `web/`, `src/dashboard/`, or
+`public/`. The same definition is mirrored in
+`src/review/visual-captures.ts` (`UI_EXT`/`UI_DIR_PREFIXES`),
+`src/policies/enforcers/expert_review_required.py`, and
+`visual_verification.py` — keep all three in sync.
+
+## CLI
+
+```bash
+uap review captures add --before <img> --after <img> [--tool tuistory] [--note "..."]
+uap review captures check [--json]   # also: bare `uap review captures`
+```
+
+- `add` registers one before/after pair for the current branch. Capture files
+  must exist inside the project (absolute paths under the project are
+  relativized; paths escaping the project are refused). Pairs accumulate.
+- `check` validates the current diff and exits 1 when UI files lack a
+  complete, fresh pair — on the `--json` path too, so CI can gate on it.
+
+Captures are produced by the agent with a capture tool: `agent-browser` for
+web surfaces, `tuistory`/`pty-capture` for terminal ones. The tool only
+proves pairing and freshness; judgment about what the captures show stays
+with the (vision-capable) reviewer.
+
+## Artifact
+
+`.uap/reviews/<branch-slug>.captures.json` — a **sibling** of the review
+artifact, never `<branch-slug>.json` itself, because the expert-review
+enforcer treats that file's existence as "a review happened" (the same
+decision as the [review pre-pass](review-prepass.md)). Writes are atomic
+(tmp + rename), and review consolidation embeds the capture paths into the
+real artifact.
+
+```json
+{
+  "branch": "feature/x",
+  "head": "…",
+  "ui_files": ["src/app.tsx"],
+  "captures": [
+    { "tool": "tuistory", "before": ".uap/visual/before.png",
+      "after": ".uap/visual/after.png", "at": "2026-09-18T…" }
+  ],
+  "at": "2026-09-18T…"
+}
+```
+
+## Ship-time enforcement
+
+`expert_review_required.py` runs the captures check **before** its low-risk
+early-allow: UI-only diffs are exactly what the gate exists for, and they
+would otherwise wave through unobserved. The check blocks the ship when:
+
+1. the diff vs the upstream base touches UI files and no captures artifact
+   exists;
+2. the artifact has no complete before/after pair;
+3. a referenced capture file is missing on disk;
+4. any UI file's mtime postdates the captures (stale — re-capture), with the
+   same 1-second grace the commit-time visual enforcer uses.
+
+Fail-open posture matches the rest of the enforcer: when no upstream base
+resolves, or a PR is shipped by reference (`gh pr merge <N>`) so the local
+diff is not the PR's contents, the check is skipped. In the PR-ship case the
+captures reach the trail through the review artifact's embedded capture paths
+(the consolidation contract), not through a mechanical check.
+
+The gate fires on every ship verb, so on a branch that already contains UI
+commits, each later commit needs captures fresher than the newest UI mtime —
+per-commit freshness, deliberately heavier than per-review.
+
+**Bypass surface (all three routes, deliberately):**
+
+1. `UAP_VISUAL_GATE_OFF=1` — environment-only, set by whoever launches the
+   session; never parsed from the command line (an inline form would be
+   self-grantable), and inline/persisted assignments are refused by
+   `enforcement_self_protect.py`.
+2. `UAP_NO_REVIEW=1` — the operator's global ship-gate override, same shape.
+3. An expert-review waiver file (`policies/waivers/*expert-review*.md` or
+   `.uap/reviews/WAIVER`) — a deliberate, committable act; waiving review
+   waives captures too (the waiver check precedes the captures check).
+
+Artifact fields `branch`, `head`, and `ui_files` are informational context
+for reviewers, not verified claims: the gate checks pairing, existence, and
+freshness only — an agent can self-author an artifact, which is accepted
+scope ("deterministic pairing, not judgment"; mtime freshness is gameable
+with `touch` and is an honesty scaffold, not a tamper-proof log).
+
+## Decisions
+
+- **Why a separate layer when `uap verify` already renders?** The render gate
+  proves the UI *runs* (not blank/static/erroring) on entry pages it can
+  find headlessly. Captures prove a reviewer *looked at the change* —
+  including surfaces the render gate cannot reach (TUI flows, states behind
+  interaction) — and bind that evidence to the review trail.
+- **Why the enforcer and not just the skill?** The skill is prose; the
+  enforcer makes "gate 7 refuses DONE on UI diffs without captures" a
+  deterministic fact at ship time, including UI-only diffs that skip the
+  parallel review.
+- **Freshness by mtime, like `visual_verification.py`:** cheap, deterministic,
+  and matches the existing commit-time backstop's semantics (1s grace).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miller-tech/uap",
-  "version": "2.1.7",
+  "version": "2.11.0",
   "description": "Autonomous AI agent memory system with CLAUDE.md protocol enforcement",
   "type": "module",
   "main": "dist/index.js",
@@ -21,9 +21,10 @@
     "start": "node dist/bin/cli.js",
     "test": "vitest",
     "test:ci": "vitest run",
-    "test:enforcers": "UAP_PROXY_ENV_AUTOLOAD=0 python3 -m unittest tools.agents.tests.test_enforcement_self_protect tools.agents.tests.test_conditional_destructive_verbs tools.agents.tests.test_live_deliver_kill tools.agents.tests.test_schema_diff_gate tools.agents.tests.test_schema_diff_inline tools.agents.tests.test_stream_telemetry tools.agents.tests.test_project_telemetry_events tools.agents.tests.test_workdir_scope_enforcer tools.agents.tests.test_gate_evidence tools.agents.tests.test_repeat_call_guard tools.agents.tests.test_repeat_guard tools.agents.tests.test_gate_integrity tools.agents.tests.test_gate_failclosed_indirection tools.agents.tests.test_gate_failclosed_schema_diff tools.agents.tests.test_expert_review_pr_scope tools.agents.tests.test_path_containment tools.agents.tests.test_path_normalizer_hardened tools.agents.tests.test_sandbox_tool_strip tools.agents.tests.test_proxy_env_loader tools.agents.tests.test_stream_required_tool tools.agents.tests.test_tool_call_wrapper_profiles tools.agents.tests.test_tool_convert_cache tools.agents.tests.test_doubling_break tools.agents.tests.test_error_loop_ignores_correctives tools.agents.tests.test_anthropic_proxy_tool_arg_types tools.agents.tests.test_anthropic_sse_schema tools.agents.tests.test_attractor_detection tools.agents.tests.test_client_disconnect tools.agents.tests.test_confidence_escalation tools.agents.tests.test_coordination_ban tools.agents.tests.test_coordination_early_ban tools.agents.tests.test_cycle_break_exploration tools.agents.tests.test_deferral_break tools.agents.tests.test_deliver_autoroute tools.agents.tests.test_delivery_enforcement_all_langs tools.agents.tests.test_delivery_enforcement_exemptions tools.agents.tests.test_delivery_enforcement_filepath tools.agents.tests.test_delivery_enforcement_write_complexity tools.agents.tests.test_fastpath_config tools.agents.tests.test_delivery_enforcement_web_and_bash tools.agents.tests.test_disconnect_watcher tools.agents.tests.test_empty_maxtokens_recovery tools.agents.tests.test_empty_tool_loop_break tools.agents.tests.test_enforcer_escape_hatches tools.agents.tests.test_error_loop_break tools.agents.tests.test_finalize_suppression tools.agents.tests.test_malformed_unclosed_think tools.agents.tests.test_mandate_beats_recon tools.agents.tests.test_mandate_deliver tools.agents.tests.test_overflow_truncate_count_tokens tools.agents.tests.test_passthrough_oauth tools.agents.tests.test_project_telemetry tools.agents.tests.test_proxy_auth_headers tools.agents.tests.test_prune_preserve_force_write tools.agents.tests.test_recon_deliver_gate tools.agents.tests.test_session_admission tools.agents.tests.test_stream_heartbeat tools.agents.tests.test_stuck_break_reattach tools.agents.tests.test_stuck_break_hard tools.agents.tests.test_turn_count_breaker_periodic tools.agents.tests.test_upstream_chokepoint tools.agents.tests.test_vision_passthrough tools.agents.tests.test_worktree_required tools.agents.tests.test_enforcer_suite_coverage tools.agents.tests.test_validate_plan_gate tools.agents.tests.test_validate_plan_inside_project tools.agents.tests.test_anthropic_proxy_streaming tools.agents.tests.test_non_stream_resp_log tools.agents.tests.test_delivery_enforcement_worktree tools.agents.tests.test_output_token_ceilings tools.agents.tests.test_tool_narrowing_core tools.agents.tests.test_models_context_window tools.agents.tests.test_thinking_template_kwargs tools.agents.tests.test_cycle_break_wait_poll tools.agents.tests.test_upstream_model_aliases tools.agents.tests.test_stream_thinking_deltas",
+    "test:enforcers": "UAP_PROXY_ENV_AUTOLOAD=0 python3 -m unittest tools.agents.tests.test_enforcement_self_protect tools.agents.tests.test_conditional_destructive_verbs tools.agents.tests.test_live_deliver_kill tools.agents.tests.test_schema_diff_gate tools.agents.tests.test_schema_diff_inline tools.agents.tests.test_stream_telemetry tools.agents.tests.test_project_telemetry_events tools.agents.tests.test_workdir_scope_enforcer tools.agents.tests.test_gate_evidence tools.agents.tests.test_repeat_call_guard tools.agents.tests.test_repeat_guard tools.agents.tests.test_gate_integrity tools.agents.tests.test_gate_failclosed_indirection tools.agents.tests.test_gate_failclosed_schema_diff tools.agents.tests.test_expert_review_pr_scope tools.agents.tests.test_path_containment tools.agents.tests.test_path_normalizer_hardened tools.agents.tests.test_sandbox_tool_strip tools.agents.tests.test_proxy_env_loader tools.agents.tests.test_stream_required_tool tools.agents.tests.test_tool_call_wrapper_profiles tools.agents.tests.test_tool_convert_cache tools.agents.tests.test_doubling_break tools.agents.tests.test_error_loop_ignores_correctives tools.agents.tests.test_anthropic_proxy_tool_arg_types tools.agents.tests.test_anthropic_sse_schema tools.agents.tests.test_attractor_detection tools.agents.tests.test_client_disconnect tools.agents.tests.test_confidence_escalation tools.agents.tests.test_coordination_ban tools.agents.tests.test_coordination_early_ban tools.agents.tests.test_cycle_break_exploration tools.agents.tests.test_deferral_break tools.agents.tests.test_deliver_autoroute tools.agents.tests.test_delivery_enforcement_all_langs tools.agents.tests.test_delivery_enforcement_exemptions tools.agents.tests.test_delivery_enforcement_filepath tools.agents.tests.test_delivery_enforcement_write_complexity tools.agents.tests.test_fastpath_config tools.agents.tests.test_delivery_enforcement_web_and_bash tools.agents.tests.test_disconnect_watcher tools.agents.tests.test_empty_maxtokens_recovery tools.agents.tests.test_empty_tool_loop_break tools.agents.tests.test_enforcer_escape_hatches tools.agents.tests.test_error_loop_break tools.agents.tests.test_finalize_suppression tools.agents.tests.test_malformed_unclosed_think tools.agents.tests.test_mandate_beats_recon tools.agents.tests.test_mandate_deliver tools.agents.tests.test_overflow_truncate_count_tokens tools.agents.tests.test_passthrough_oauth tools.agents.tests.test_project_telemetry tools.agents.tests.test_proxy_auth_headers tools.agents.tests.test_prune_preserve_force_write tools.agents.tests.test_recon_deliver_gate tools.agents.tests.test_session_admission tools.agents.tests.test_stream_heartbeat tools.agents.tests.test_stuck_break_reattach tools.agents.tests.test_stuck_break_hard tools.agents.tests.test_turn_count_breaker_periodic tools.agents.tests.test_upstream_chokepoint tools.agents.tests.test_vision_passthrough tools.agents.tests.test_worktree_required tools.agents.tests.test_enforcer_suite_coverage tools.agents.tests.test_validate_plan_gate tools.agents.tests.test_validate_plan_inside_project tools.agents.tests.test_anthropic_proxy_streaming tools.agents.tests.test_non_stream_resp_log tools.agents.tests.test_delivery_enforcement_worktree tools.agents.tests.test_output_token_ceilings tools.agents.tests.test_tool_narrowing_core tools.agents.tests.test_models_context_window tools.agents.tests.test_thinking_template_kwargs tools.agents.tests.test_cycle_break_wait_poll tools.agents.tests.test_upstream_model_aliases tools.agents.tests.test_stream_thinking_deltas tools.agents.tests.test_verbatim_compact tools.agents.tests.test_tool_risk",
     "test:coverage": "vitest --coverage",
     "bench": "vitest --config vitest.bench.config.ts",
+    "eval:routing": "tsx scripts/eval-routing.ts",
     "lint": "eslint src --ext .ts",
     "lint:fix": "eslint src --ext .ts --fix",
     "format": "prettier --write src/**/*.ts",
@@ -37,7 +38,8 @@
     "version:major": "bash scripts/version-bump.sh major",
     "update-uap": "bash scripts/maintenance/update-uap-compliance.sh",
     "verify-uap": "bash scripts/maintenance/verify-compliance.sh",
-    "check-claude": "bash scripts/maintenance/verify-compliance.sh"
+    "check-claude": "bash scripts/maintenance/verify-compliance.sh",
+    "bench:ladder": "tsx scripts/reliability-ladder.ts"
   },
   "keywords": [
     "claude",

package/src/policies/enforcers/enforcement_self_protect.py

@@ -67,10 +67,21 @@ BYPASS_PATTERNS = (
     # agent writes its own command strings, so an inline form waives its own
     # review. Refuse it here so the attempt is visible rather than silent.
     re.compile(r"UAP_NO_REVIEW\s*=\s*['\"]?1", re.I),
+    # evidence-bound-ship's hatch is environment-only for the same reason: the
+    # agent writes its own command strings, so an inline form would let it
+    # ship a candidate with no gate evidence at all.
+    re.compile(r"UAP_EVIDENCE_GATE_OFF\s*=\s*['\"]?1", re.I),
+    # The staleness WINDOW is a gate parameter: any assignment, not just =1.
+    # An agent persisting UAP_EVIDENCE_MAX_AGE_HOURS=8760 into ~/.bashrc would
+    # quietly retire the staleness check for every later session, so the
+    # assignment itself is refused wherever it appears.
+    re.compile(r"UAP_EVIDENCE_MAX_AGE_HOURS\s*=", re.I),
     # quality-metrics gate hatch, same operator-only shape: the enforcer reads
     # the launch env, so the only agent-reachable move is PERSISTING the flag
     # (rc files, proxy env) — which is exactly what this pattern refuses.
     re.compile(r"UAP_QUALITY_GATE_OFF\s*=\s*['\"]?1", re.I),
+    # visual-captures gate hatch (uplift 0.3), same operator-only shape.
+    re.compile(r"UAP_VISUAL_GATE_OFF\s*=\s*['\"]?1", re.I),
     re.compile(r"UAP_USER_VALIDATION\s*=\s*['\"]?0", re.I),
     # Single-flight is a DATA-SAFETY control, not a policy preference: deliver
     # runs each candidate in a git worktree, and two runs against one repo are
@@ -572,6 +583,17 @@ def _kills_live_deliver_run(command: str, root) -> str:
 # is what makes this narrow list sufficient — anything else the agent writes
 # is distrusted on READ, so it need not be write-blocked here.
 _TRUST_ANCHORS = (".uap/operator-overrides.json", ".uap/policy-liveness.json")
+# Gate-evidence artifacts (.uap/evidence/<sha>.json for evidence-bound-ship,
+# plus the read/memory evidence logs) get the SAME interpreter-write
+# protection as the trust anchors: they are proof a ship/plan gate accepts, so
+#   python3 -c 'open(".uap/evidence/<sha>.json","w").write("{}')   # forgery
+#   node -e 'require("fs").writeFileSync(".uap/evidence/x.json",…)'
+# must be refused even though the Write-tool path into that directory is
+# already covered by PROTECTED_TARGETS — the interpreter path carried no
+# destructive verb and walked straight past that scan. The dir is matched with
+# a trailing separator/quote so a sibling like `.uap/evidence-notes` is NOT
+# caught.
+_EVIDENCE_DIR_RE = re.compile(r"\.uap/evidence(?:[/\"'\\)\s]|$)")
 _INTERPRETER_RE = re.compile(r"(?:^|[\s;|&('\"`])(?:python\d*(?:\.\d+)?|perl|ruby|node)(?:\s|$)")
 # A write primitive in interpreter code: open(…, "w"/"a"/"x"/"+"), or a
 # mutating method call. Reads (open without a mode, json.load, print) match
@@ -583,9 +605,10 @@ _INTERPRETER_WRITE_RE = re.compile(
 
 
 def _interpreter_write_to_anchor(command: str) -> bool:
-    """True when an interpreter command names a trust anchor with write intent."""
+    """True when an interpreter command names a trust anchor OR the gate
+    evidence directory with write intent."""
     lowered = command.lower()
-    if not any(anchor in lowered for anchor in _TRUST_ANCHORS):
+    if not any(anchor in lowered for anchor in _TRUST_ANCHORS) and not _EVIDENCE_DIR_RE.search(lowered):
         return False
     return bool(_INTERPRETER_RE.search(command) and _INTERPRETER_WRITE_RE.search(command))