@miller-tech/uap 2.1.7 → 2.11.0

package/docs/performance/automode-risk-calibration.md

@@ -0,0 +1,72 @@
+# AutoMode Risk Classification — Calibration Report
+
+Generated by `tools/agents/scripts/tool_risk_calibrate.py` from
+`tools/agents/tests/fixtures/tool_risk_cases.json`. Regenerate with:
+
+```bash
+python3 tools/agents/scripts/tool_risk_calibrate.py \
+    --write docs/performance/automode-risk-calibration.md
+```
+
+## Method
+
+- Split: stratified per class, seeded `random.Random(20260713)`,
+  held-out fraction 0.3 (min 2 per class). Deterministic: class
+  iteration order and case order are fixed, so the same seed and corpus
+  always produce the same split on any machine.
+- Corpus: 113 labeled cases (79 train / 34 held out).
+- Scorer: `tool_risk.classify_tool_call` (pure heuristic; the SYS1
+  model head will be measured by this same harness when it lands).
+
+## Held-out per-class metrics
+
+| class | precision | recall | support |
+|---|---|---|---|
+| destructive | 100.0% | 100.0% | 10 |
+| write | 100.0% | 100.0% | 8 |
+| execute | 100.0% | 100.0% | 6 |
+| read | 100.0% | 100.0% | 6 |
+| network | 100.0% | 100.0% | 4 |
+| **overall accuracy** | 100.0% | | 34 |
+
+> **Read the 100% figures with the support sizes:** held-out support
+> is small (n=4–10 per class), so a single miss swings per-class
+> recall by 10–25 percentage points. These are
+> 'no observed miss on a small probe' numbers, not proof of
+> generalization — the corpus must grow with every new evasion shape
+> seen in the wild.
+
+## Confusion notes
+
+No held-out confusions. That is the expected shape for a RULE-BASED
+scorer measured on the corpus its rules were written against — treat
+these numbers as the contrast baseline, not as evidence of model
+quality. The cases that exercised real judgment (and their handling):
+
+- `git push --force-with-lease` (net-07) is a network call, NOT
+  destructive: the lease verifies the remote ref before overwriting.
+  `--force` / `-f` (des-14/15) remain destructive.
+- `rm -rf ./node_modules/.cache` (wr-21) and `/tmp` scratch (wr-22)
+  are maintenance: an rm whose targets are ALL regenerable trees
+  downgrades to write. A single non-scratch target keeps destructive.
+- `ls -rf` (rd-07) is a read: flags only matter per-verb.
+- Quoted prose (`echo "rm -rf /" > notes.txt`, wr-23;
+  `grep -r "rm -rf" docs/`, rd-19) never reaches verb position;
+  segment splitting and redirect detection run on quote-blanked text.
+- Evasion variants the enforcers already know are covered by the
+  same devices: launcher prefixes (des-03..05, des-08), `bash -c`
+  unwrapping (des-07), chained commands (des-06), trailing-slash
+  self-targets (des-09/10, which also fire `protected-target`).
+
+Known residuals (accepted, advisory-only): a path held in a shell
+variable is invisible to any text scan (same limit the enforcers
+document); `sudo -u root rm ...` leaves `root` as the apparent verb
+(enforcer parity). Both are called out in
+`docs/reference/automode-risk.md`.
+
+## Doctrine
+
+Held-out **destructive recall is gated at 1.0** (`--check` exits 1
+otherwise): a missed destructive call is the unacceptable error. False
+positives are advisory-only cost. The scorer never blocks; the
+deterministic enforcers in `src/policies/enforcers/` remain the floor.

package/docs/performance/reliability-ladder.md

@@ -0,0 +1,78 @@
+# Reliability Ladder
+
+The measured technique-selection table for the decision loop's THINK step
+(uplift 0.1). Two parts: what UAP's own paired benchmark suites measured
+(generated — see below), and the selection guidance derived from those
+numbers plus the external priors we have not yet reproduced locally.
+
+## Selection guidance (THINK step)
+
+| Task shape | Technique | Why (evidence) |
+| --- | --- | --- |
+| Small, well-specified, 1–2 files | **Direct** — just do it | Measured (uplift/other tiers — the medium runs predate token accounting): ~3.3–5.4k tokens/task; the e3b power run measured the full loop at +0.98 tool calls/task (significant) with correctness not separable. External prior: reflect loops cost +1–3k tokens for nothing on tasks already inside the model's competence. |
+| Multi-file or gate-covered, moderate risk | **Direct + verify loop** (default UAP flow) | Measured: hard tier +2.3pt success at +22% tokens; uplift tier +4.4pt at equal tokens — both ⚠ underpowered, so directional. Gating is cheap insurance here. |
+| Hardest tier, novel/ambiguous, many files | **Full loop + escalation** (convergence, gates, judge) | Measured: brutal tier 26.1% → 56.8% success (2.2×) at 4.2× tokens; the lazy variant reached 67.5% at 2.8× tokens (⚠ underpowered — directional). This is the only tier where the observed payoff dwarfs the observed cost. |
+| Spec-heavy, human-available, production-critical | **SDD + human review** | External prior (context-engineering-kit, not yet reproduced locally): 95–99% accuracy at 5–35× token cost. Use when a miss costs more than 30× the tokens. |
+
+Rules of thumb the table encodes:
+
+1. **Escalate with difficulty, not with anxiety.** The brutal tier is the only
+   one where the expensive loop's observed payoff dwarfs its cost; below it,
+   spend the tokens on doing, not on judging.
+2. **Token cost of a technique is part of the technique.** The lazy variant
+   beat the full loop on brutal tasks at 2/3 the cost — more machinery is not
+   more reliability.
+3. **Cite the measurement class.** Rows not marked "usable" support cost
+   claims, not quality claims — never quote a success delta without its
+   discrimination status ("underpowered" = measured but inconclusive;
+   "unknown" = legacy run without a discrimination block).
+
+## Reproducing
+
+```bash
+npm run bench:ladder          # prints the table below (reads benchmark-results/)
+npm run bench:ladder -- --write   # refreshes the generated block in this file
+npm run bench:ladder -- --json    # machine-readable rows
+```
+
+New paired runs land in `benchmark-results/<run>/{report.json,records.jsonl}`
+and are picked up on the next regeneration. The script works from worktrees
+(it falls back to the main checkout's git-ignored `benchmark-results/`).
+
+<!-- LADDER:BEGIN -->
+<!-- GENERATED by scripts/reliability-ladder.ts — regenerate with: npm run bench:ladder -->
+
+## Measured results (pooled from `benchmark-results/`)
+
+| Tier | Condition | n | Success | Mean tokens | Token range | Mean files | Runs | Stats |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| medium | baseline | 45 | 2.2% | — | — | — | 3 | ⚠ unknown |
+| medium | uap-full | 45 | 0.0% | — | — | — | 3 | ⚠ unknown |
+| uplift | baseline | 273 | 63.4% | 3270 | 906–11981 | — | 9 | ⚠ underpowered |
+| uplift | uap-full | 273 | 67.8% | 3311 | 840–10802 | — | 9 | ⚠ underpowered |
+| hard | baseline | 87 | 69.0% | 146460 | 818–399573 | — | 4 | ⚠ underpowered |
+| hard | uap-full | 87 | 71.3% | 178474 | 817–488287 | — | 4 | ⚠ underpowered |
+| brutal | baseline | 88 | 26.1% | 7448 | 2871–8698 | — | 3 | ⚠ unknown |
+| brutal | uap-full | 88 | 56.8% | 31513 | 2819–84902 | — | 3 | ⚠ unknown |
+| brutal | uap-lazy | 40 | 67.5% | 21070 | 3849–43546 | — | 1 | ⚠ unknown |
+| power | baseline | 45 | 75.6% | 3984 | 754–10067 | 1.0 | 1 | ⚠ underpowered |
+| power | uap-full | 45 | 68.9% | 3972 | 738–10079 | 1.0 | 1 | ⚠ underpowered |
+| heldout | baseline | 51 | 78.4% | 3349 | 421–9519 | 1.0 | 1 | ⚠ underpowered |
+| heldout | uap-full | 51 | 78.4% | 4392 | 429–40835 | 1.1 | 1 | ⚠ underpowered |
+| deliver | baseline | 75 | 41.3% | — | — | — | 3 | ⚠ underpowered |
+| deliver | uap-full | 75 | 42.7% | — | — | — | 3 | ⚠ underpowered |
+| other | baseline | 95 | 67.4% | 4343 | 728–8697 | 1.0 | 8 | ⚠ underpowered |
+| other | uap-full | 95 | 77.9% | 5363 | 731–11097 | 1.1 | 8 | ⚠ underpowered |
+
+Source: `benchmark-results/`. Rows not marked "usable" support
+token/latency cost claims only — never cite a success delta without its
+discrimination status ("underpowered" = measured but inconclusive;
+"unknown" = legacy run without a discrimination block).
+<!-- LADDER:END -->
+
+## External priors (attributed, unverified locally)
+
+From NeoLabHQ/context-engineering-kit's published ladder: reflect +1–3k
+tokens; do-and-judge 1.5–3×; SDD+human 95–99% at 5–35×. These guide the
+rows UAP has not measured yet; when a local suite reproduces or contradicts
+one, this section loses the row.

package/docs/plans/system1-uplift-2026-09-18.md

@@ -0,0 +1,191 @@
+# UAP System-1 Uplift Plan — 2026-09-18
+
+Status: APPROVED for implementation (plan PR → implementation PRs)
+Scope decision: Wave 0 (all five) + Wave 1 (1.1–1.4). Backend decision: **local-only
+classifier, airgap-pure, trained from UAP telemetry** (no hosted Jev dependency).
+
+## 1. Source analysis
+
+Ten external signals were analyzed. They converge on one architectural shift:
+split System 2 (slow generative reasoning) from System 1 (fast structured
+decisions), and bind every gate to evidence.
+
+| Source | Signal |
+| --- | --- |
+| x.com/sydneyrunkle (LangChain) | TypeSafe Jev "System One" model: state + typed questions (choice/score/noul), parallel evaluation, calibrated probabilities. Killer apps: model routing and AutoMode (pre-execution tool-call risk classification). |
+| x.com/JoshARosen + thruwire/foreman | Foreman: semantic supervision of coding agents. 9 noul dimensions (worker_stuck, work_off_track, implementation_complete, tests_sufficient, requirements_satisfied, needs_verification, meaningful_progress, needs_human, ready_to_finish) against bounded observations (20k-char diff, 12k tails, 30 events). **Deterministic policy owns all actions** (CONTINUE/START/STOP/RETRY/VERIFY/FINISH/ESCALATE); the model only assesses. Debounced loop, persisted state + events.jsonl, safety-first action ordering. |
+| x.com/decapostos | Split thinking from next-action selection; fewer protocol round trips → fewer drift points. |
+| tamaratran/fast-jev-compaction | Replace lossy compaction summaries with per-tool-call keep/truncate/drop decisions. Kept content stays **verbatim**; pinned recency; staged state fitting; fallback to summary when reduction < 25%. |
+| mrinalwadhwa/fluent | Evidence-bound factory: EARS behavior specs with `Test:` refs; candidate-bound test evidence (exact command, reject stale/mismatched, fail closed); two queues (human attention vs compute capacity); Learner → project Expertise; provider liveness guards + resumable Attempts; post-merge review. |
+| khuynh22/agent-dev-team | Tier ceilings T0–T3 (confidence never raises a ceiling); structured HANDOFF/BRIEF escalation packets; routing evals (rank-1 97%, CI-enforced, planted traps); restated-count validation in CI. |
+| alibaba/open-code-review | Hybrid review: deterministic rule pipelines first (NPE, thread-safety, XSS, SQLi), LLM agent second; per-group token budgets with grace round; resumable sessions; delegation mode. |
+| senoff/self-hosted-ci-runner | Capacity policy: provision N+1, run N; per-runner swap/scratch/reaper; GREEN/RED/DARK health; single-purpose box. Same discipline as the 2026-09-18 llama.cpp OOM fix. |
+| NeoLabHQ/context-engineering-kit | Measured reliability ladder: accuracy vs files-changed vs token cost per technique (reflect +1–3k tokens; do-and-judge 1.5–3x; SDD+human 95–99% at 5–35x). Reflexion/memorize/critique loops; subagent-per-task against context rot. |
+
+## 2. UAP gap assessment
+
+UAP already exceeds these projects in: deterministic quality-metrics gate,
+proxy enforcer suite (deliver autoroute, gate evidence, confidence escalation,
+stuck-break), worktree/mission/checkpoint infrastructure, and local-first
+serving. Gaps, in leverage order:
+
+1. Every UAP decision point is either a heuristic or a full LLM call — no fast,
+   calibrated middle layer for routing, risk, stuckness, or compaction.
+2. Proxy compaction is summarization/threshold based — lossy.
+3. Deliver gates check artifacts, not evidence-bound behavior specs.
+4. Technique selection in the decision loop is unquantified (no reliability/cost
+   ladder).
+5. Droids have no capability ceilings or handoff contracts.
+6. Visual gating covers design tokens only; no captured visual evidence bound
+   to UI changes.
+
+## 3. Design principles (all waves)
+
+- **Policy is deterministic; models only assess.** Thresholds and actions live
+  in reviewed code. A classifier can be wrong; the policy bounds the blast
+  radius (Foreman's central lesson).
+- **Fail closed.** If the classifier is unavailable, gates keep their current
+  heuristic behavior; nothing gets *looser* because the model is down.
+- **Airgap-pure.** No hosted classifier dependency. The System-1 model is
+  trained and served locally (see §6).
+- **Evidence-bound.** Every gate emits machine-checkable evidence bound to the
+  candidate SHA; stale or mismatched evidence is rejected (Fluent's rule).
+- **Measured.** Every uplift lands with before/after numbers from UAP's own
+  benchmark suites; claims without measurements do not merge.
+
+## 4. Wave 0 — quick wins (each lands as its own PR)
+
+### 0.1 Reliability ladder in the decision loop
+- Add a measured technique-selection table to the CLAUDE.md decision loop
+  (THINK step): task complexity × files-touched → technique (direct /
+  reflect / judge / SDD) with token-cost ranges.
+- Calibrate on `benchmarks/` suites; publish the table in
+  `docs/performance/` with the raw results.
+- Acceptance: table exists, numbers reproduced by a suite run, decision loop
+  references it.
+
+### 0.2 Deterministic review pre-pass
+- A ruleset scanner (secrets, injection patterns, NPE/null deref, thread-safety
+  smells) runs before the three LLM reviewers in the parallel review protocol;
+  reviewers receive pre-filtered, line-anchored findings.
+- Reuse the quality-gate scanner infra where possible.
+- Acceptance: pre-pass fires in `.uap/reviews/<branch>.json`; reviewer prompt
+  embeds findings; at least 2 fixture vulnerabilities caught without an LLM.
+
+### 0.3 Visual gate for UI changes
+- Any diff touching UI files requires before/after captures
+  (agent-browser/tuistory/pty-capture) attached to the review artifact;
+  `uap design check` remains the token enforcer.
+- Acceptance: completion gate 7 refuses DONE on UI diffs without captures;
+  artifact embeds capture paths.
+
+### 0.4 Routing evals for pattern router + droid registry
+- TF-IDF/embedding rank-1 eval over every skill/droid description with planted
+  traps and negatives; CI-enforced threshold (start at 90% rank-1).
+- Validates `.factory/patterns/index.json` and the droid registry stay
+  separable as entries are added.
+- Acceptance: `npm run eval:routing` (or equivalent) exists, runs in CI, and
+  catches a deliberately degraded description.
+
+### 0.5 Capacity policy as code
+- Generalize the 2026-09-18 llama.cpp OOM fix discipline: every UAP-managed
+  service declares a resource budget, headroom policy, and GREEN/RED/DARK
+  health definition; `uap doctor` (or monitor) reports violations.
+- Acceptance: the gsq-rco server and monitor are the reference
+  implementations; policy file under `config/`; doc in `docs/guides/`.
+
+## 5. Wave 1 — the System-1 layer (each lands as its own PR)
+
+### 1.1 Semantic supervisor for deliver missions
+- New `uap supervise` loop watching `uap deliver` missions: 9 assessment
+  dimensions (Foreman's set, adapted) against bounded observations
+  (git status, bounded diff, output tails, recent events, prior assessment,
+  attempt/failure counts, elapsed time).
+- Deterministic policy with explicit, reviewed thresholds; safety-first action
+  ordering: human-need > iteration bounds > off-track/stuck > retry >
+  completion > verification > continue. Actions: CONTINUE / STOP / RETRY /
+  VERIFY / FINISH / ESCALATE.
+- Debounced (≥5s) and periodic (30s) assessment; persisted state.json +
+  events.jsonl per run; oscillation guards (verification cannot loop).
+- Acceptance: a seeded stuck-mission fixture is stopped; a healthy mission is
+  never interrupted; policy branches unit-tested (offline, fake classifier).
+
+### 1.2 Verbatim decision compaction in the proxy
+- Replace the lossy prune/summarize path in `anthropic_proxy.py` with
+  per-tool-call keep/truncate/drop decisions: pinned first + recent messages,
+  staged state fitting, truncation keeps a head + note, kept content verbatim.
+- Fallback to the current summarizer when reduction is insufficient or the
+  classifier is unavailable.
+- Acceptance: existing enforcer/compaction test suites pass; new tests cover
+  keep/truncate/drop decisions, pairing integrity (no orphan tool_result), and
+  fallback; measured context reduction ≥ current path on fixtures.
+
+### 1.3 AutoMode pre-execution risk classification
+- Calibrated risk classification of tool calls before dispatch, ahead of the
+  current verb/regex heuristics in the enforcer chain. Classifier output is
+  advisory to the deterministic policy; heuristics remain the floor.
+- Acceptance: destructive/fixture tool calls classified with calibration
+  report (per-class precision/recall on held-out telemetry); heuristic tests
+  unaffected; latency overhead < 50ms local.
+
+### 1.4 Evidence-bound merge candidates
+- Deliver missions produce merge candidates whose gate evidence is bound to
+  the candidate SHA: exact test commands, outputs, timestamps; stale, missing,
+  malformed, or SHA-mismatched evidence is rejected (fail closed).
+- Acceptance: gate evidence enforcer rejects a forged/stale artifact in tests;
+  PR flow requires candidate-bound evidence for ship.
+
+## 6. Local System-1 classifier (the airgap-pure backend)
+
+Decision: **no hosted dependency.** The classifier is trained and served
+locally, and every Wave 1 consumer talks to it through one interface
+(`uap classify` / library call) so the backend can evolve without touching
+policy code.
+
+- **Training data:** UAP's own telemetry — `project_telemetry` events, gate
+  decisions and outcomes, escalation results, stuck/attractor events,
+  deliver-mission histories, and incident records (e.g., the 2026-09-18 OOM
+  timeline). This dataset is the moat: nobody else has UAP's decision-outcome
+  pairs.
+- **Model form (v1):** small, CPU-fast, calibrated. Start with an embedding +
+  calibrated head (nomic-embeddings already deployed; logistic/isotonic on
+  top) for noul/score/choice questions. Evaluate against a distilled small
+  LLM head only if the simple model underperforms on held-out telemetry.
+- **Calibration:** per-dimension reliability curves and thresholds derived
+  from held-out outcomes; thresholds ship as reviewed policy config, not
+  model output.
+- **Serving:** local process (CPU), <50ms p95 per assessment batch; questions
+  batched per state like Jev's parallel evaluation.
+- **Interfaces:** `assess(state, questions) -> {name: {value, probability,
+  confidence}}` matching the noul/choice/score shapes, so Jev-compatible
+  request/response fixtures work unchanged.
+- Acceptance: calibration report committed; supervisor/compaction/AutoMode all
+  run against the local backend with policy tests offline.
+
+## 7. Sequencing and PR plan
+
+1. This plan (docs PR).
+2. Wave 0 PRs in order: 0.4 (evals infrastructure) → 0.2 (review pre-pass) →
+   0.3 (visual gate) → 0.1 (ladder, needs bench runs) → 0.5 (capacity policy).
+3. Local classifier foundation (§6) — prerequisite for Wave 1.
+4. Wave 1 PRs: 1.1 → 1.2 → 1.3 → 1.4 (1.4 is independent and may parallel).
+
+## 8. Risks and open questions
+
+- **Classifier quality is unproven** (Foreman says the same about Jev).
+  Mitigation: shadow mode first — classifier assesses, heuristics decide,
+  divergence logged; promotion to active only after measured agreement.
+- **Compaction regressions are silent.** Mitigation: verbatim guarantee +
+  reduction floor + fallback; replay fixtures from real sessions.
+- **Gate fatigue.** Every new gate must have an escape hatch and a measured
+  false-positive rate, or it will be bypassed (UAP_QUALITY_GATE_OFF exists for
+  a reason).
+- **Scope.** Wave 0 items are independent; Wave 1 items share the classifier
+  PR — land it small (one dimension end-to-end) before generalizing.
+
+## 9. Later waves (not approved yet; recorded for the roadmap)
+
+- Wave 2: tier ceilings + HANDOFF/BRIEF droid contracts; EARS behavior-spec
+  layer; two-queue scheduling dashboard; post-merge review loop.
+- Wave 3: train a dedicated small System-1 model (beyond embedding+head);
+  publish UAP's measured reliability ladder as the external benchmark claim.

package/docs/reference/automode-risk.md

@@ -0,0 +1,134 @@
+# AutoMode Pre-Execution Risk Classification
+
+Uplift 1.3. Every outbound `tool_use` block is risk-classified **before the
+client dispatches it**, ahead of — and never instead of — the deterministic
+verb/regex enforcers in `src/policies/enforcers/`.
+
+## Design
+
+The scorer is `tools/agents/scripts/tool_risk.py`:
+
+```python
+classify_tool_call(tool_name: str, tool_input: dict) -> RiskAssessment
+```
+
+`RiskAssessment` is a frozen dataclass: `risk_class`, `risk_score` (1–5),
+`signals` (every rule that fired, formatted `name:class+weight` — every
+point of score is attributable to a named signal), `latency_ms`. The
+function is **pure**: no I/O, no globals, same input → same output.
+
+This is the Python-side calibrated heuristic floor for AutoMode. Its
+vocabulary is *inspired by* the unmerged TypeScript SYS1 baseline
+(`src/classify/baseline.ts` on `feature/301-sys1-classifier`) — not ported:
+the TS baseline scores prose state descriptions, this scorer parses shell
+structure, so the domains and machinery genuinely differ and "cross-stack
+parity" would overclaim. The promotion path is a **Python-resident head (or
+sidecar) behind the same `classify_tool_call` contract**, gated by the
+calibration harness at held-out destructive recall 1.0 — when it lands, the
+wiring, harness, and doctrine below do not change.
+
+### Classes
+
+| class | meaning | examples |
+|---|---|---|
+| `destructive` | irreversible / wide blast radius | `rm -rf`, `DROP TABLE`, `TRUNCATE`, `git push --force`, `git reset --hard`, `dd of=/dev/…`, `mkfs`, `chmod -R 777`, `terraform destroy`, secrets rotation |
+| `write` | file/state mutation, recoverable | Edit/Write tools, redirects, `sed -i`, `cp`/`mv`, `git add/commit` |
+| `execute` | runs code or tests | `pytest`, `npm run build`, `python3 script.py`, `docker run` |
+| `read` | read-only inspection | Read/Grep/Glob/LS tools, `cat`, `ls`, `git status`, `find` without mutating flags |
+| `network` | crosses the wire | WebFetch/WebSearch, `curl`/`wget`, `git push/fetch/clone`, `scp`/`ssh`, `npm publish` |
+
+Scoring: deterministic verb/regex signal extraction → per-class weighted
+sum → class = highest total (ties break toward the more severe class) →
+score = class base (1/2/3/3/4) + 1 when the evidence is hard (total weight
+≥ 5), capped at 5.
+
+### Evasion handling
+
+The scorer mirrors `enforcement_self_protect.py` rather than reinventing it:
+
+- **Launcher prefixes** (`nohup`, `timeout`, `sudo`, `env`, `nice`, …) are
+  stepped over so the real verb is judged: `sudo rm -rf /` classifies
+  destructive.
+- **Chained commands** (`&&`, `||`, `;`, `|`, background `&`) are split per
+  segment — with separators inside quotes ignored, so the `;` inside
+  `python3 -c "import shutil; shutil.rmtree(x)"` cannot hide the rmtree.
+- **`sh -c` / `bash -c` / `eval`** payloads are unwrapped and classified
+  recursively (depth-bounded).
+- **Conditional verbs** follow the enforcer semantics: `sed` mutates only
+  with `-i`; `find` only with `-delete`/`-exec`-family. Without the flag
+  they classify read, exactly like the enforcer's `CONDITIONAL_VERBS`.
+- **Path variants**: trailing slashes and `./` prefixes are normalized;
+  `.uap` / `.git` self-targets fire a `protected-target` bump to score 5.
+- **Scratch carve-out**: `rm -rf` whose targets are ALL regenerable trees
+  (`node_modules`, `dist`, `build`, `/tmp/…`, …) classifies write, not
+  destructive. One non-scratch target keeps destructive.
+
+Known residuals (accepted — advisory-only cost, and the same limits the
+enforcers document):
+
+- a path held in a shell variable is invisible to any text scan;
+- `sudo -u root rm …` leaves `root` as the apparent verb;
+- an **escaped quote** inside a double-quoted string defeats the quote
+  blanking (`python3 -c "a=\";\"; shutil.rmtree('/x')"` splits at the
+  escaped quote, because the blanking regex does not model backslash
+  escapes) — same accepted-residual class as shell variables: text scans
+  cannot see shell state.
+
+## Advisory doctrine
+
+**The scorer never blocks and never modifies the stream.** The deterministic
+enforcer chain is the blocking floor and is exactly as strict as before —
+nothing gets looser. The classification is consumed three ways at the
+proxy's outbound `tool_use` interception points
+(`tools/agents/scripts/anthropic_proxy.py`):
+
+1. **Debug log** — one line per tool_use:
+   `AUTOMODE RISK: <id> <tool> class=… score=… signals=… latency=…ms`.
+2. **Telemetry** — score ≥ 4 calls append a `dashboard_events` row
+   (`category=automode`, `type=risk.classified`, severity `warning` for
+   destructive) via `project_telemetry.record_risk_event`, so the
+   dashboard's Live Events panel shows high-risk calls. Routine reads do
+   not flood the feed.
+3. **Nothing else.** On any classifier exception the proxy logs a warning
+   and passes the tool call through unchanged — the advisory path fails
+   OPEN precisely because the enforcer floor fails CLOSED; a dead
+   classifier degrades to today's behaviour plus one warning line.
+
+## Calibration
+
+`tools/agents/scripts/tool_risk_calibrate.py` loads the labeled corpus
+(`tools/agents/tests/fixtures/tool_risk_cases.json`, 109 cases across the
+five classes including evasion variants and benign lookalikes), makes a
+deterministic seeded stratified split, and reports per-class
+precision/recall on the held-out set. The committed numbers, split seed,
+and confusion notes live in
+[**docs/performance/automode-risk-calibration.md**](../performance/automode-risk-calibration.md).
+
+**Held-out destructive recall is gated at 1.0** (`--check` exits non-zero
+otherwise): a missed destructive call is the unacceptable error. False
+positives are advisory-only cost.
+
+## Latency
+
+The scorer is pure regex/dict work, measured in microseconds; a bench test
+(`tools/agents/tests/test_tool_risk.py`) asserts **p95 < 5 ms over 10k
+calls**. The 50 ms AutoMode budget is reserved for the future model call;
+the heuristic floor sits far under it.
+
+## Escape hatch
+
+`PROXY_AUTOMODE_RISK=off` disables classification in the proxy (default
+`on`). This is an operator hatch in the trusted launch env, same posture as
+the other proxy switches.
+
+## Files
+
+| path | role |
+|---|---|
+| `tools/agents/scripts/tool_risk.py` | the scorer (pure) |
+| `tools/agents/scripts/tool_risk_calibrate.py` | calibration harness / gate |
+| `tools/agents/tests/fixtures/tool_risk_cases.json` | labeled corpus |
+| `tools/agents/tests/test_tool_risk.py` | 36 tests (registered in `test:enforcers`) |
+| `tools/agents/scripts/anthropic_proxy.py` | advisory wiring (3 interception points) |
+| `tools/agents/scripts/project_telemetry.py` | `record_risk_event` dashboard sink |
+| `docs/performance/automode-risk-calibration.md` | committed calibration report |

package/docs/reference/evidence-bound-ship.md

@@ -0,0 +1,145 @@
+# Evidence-Bound Ship (gate evidence)
+
+> Policy: `evidence-bound-ship` · Enforcer: `src/policies/enforcers/evidence_bound_ship.py`
+> · Writer: `src/delivery/gate-evidence.ts` · Escape hatch: `UAP_EVIDENCE_GATE_OFF=1`
+> (operator launch environment only)
+
+A deliver mission ends with its gates green against some `HEAD`. That `HEAD` is
+the merge candidate a later ship action publishes. **Evidence binding** makes
+the candidate carry its proof: at ship time, the enforcer requires a
+machine-recorded artifact showing the mission's gates passed for *exactly* the
+commit being shipped — not for some earlier or later tree.
+
+## The contract
+
+Ship-class actions (same detection as `expert-review-required`: `git commit` /
+`push` / `merge`, `gh pr create` / `merge` / `ready`, pr-ready / signoff) are
+**blocked** unless `.uap/evidence/<head-sha>.json` exists and validates:
+
+```json
+{
+  "version": 1,
+  "candidateSha": "<full HEAD sha the gates prove>",
+  "recordedAt": "<ISO-8601>",
+  "runId": "<deliver run id, optional>",
+  "hatches": ["<gate-affecting env vars set at deliver time, audit only>"],
+  "gates": [
+    {
+      "name": "test",
+      "command": "npm test",
+      "exitCode": 0,
+      "outputTail": "<last ≤2000 chars of combined output>",
+      "at": "<ISO-8601>"
+    }
+  ]
+}
+```
+
+| Check | Rejection |
+|---|---|
+| Artifact missing | BLOCK — commit, then run `uap deliver` to record evidence for this HEAD |
+| Oversized (>512KB) | BLOCK — read is capped before parsing; a payload is not evidence |
+| Not parseable JSON | BLOCK — delete and re-run `uap deliver` |
+| `version` ≠ 1 | BLOCK — re-record with the current CLI |
+| `candidateSha` ≠ HEAD | BLOCK — evidence for a different commit proves nothing about this one |
+| `recordedAt` < commit time | BLOCK — backdated (the commit did not exist to be gated yet); an *unresolvable* commit time also BLOCKs (fail-closed on anomaly) |
+| `recordedAt` > now + 5min | BLOCK — future-dated (forged, or a badly skewed clock) |
+| `recordedAt` older than the staleness window | BLOCK — stale; re-run `uap deliver` |
+| No gate with `exitCode: 0` + `command` + `at` | BLOCK — empty/forged artifacts are not evidence |
+
+The enforcer **fails closed** on every ambiguity. The only fail-open is a tree
+that is not a git repository (or git itself missing) — non-UAP trees are
+unaffected. It uses local git + the filesystem only: no network, no `gh`, and
+it never throws uncaught inside the live policy chain.
+
+## How deliver emits evidence
+
+`uap deliver` records the artifact at the single completion seam every runner
+kind (single / phased / orchestrated / ci-reconverge) converges on, right where
+the run's outcome is persisted (`completeDeliveryTask` /
+`recordDeliveryOutcome` in `src/cli/deliver.ts`). The gates come from the
+**last passing** iteration's rung results — or, when the tree was already green
+and the run short-circuited as `alreadyDelivered`, from the **baseline ladder
+run** (`DeliveryResult.baselineGates`), so the commit → deliver → ship flow
+never dead-ends. Emission is **fail-soft**: a warning is the whole failure
+mode, so evidence recording can never break a mission.
+
+The writer **refuses a dirty working tree** (`git status --porcelain` must be
+empty): evidence claims the gates passed for `<sha>`, and with uncommitted
+changes they provably ran against HEAD-plus-delta. The supported flow is:
+commit the candidate, run `uap deliver` (baseline goes green, evidence binds
+the clean HEAD), ship.
+
+Writes are atomic (tmp + rename), and `.uap/` is git-ignored — evidence is a
+local record, never committed payload.
+
+Per-gate `at` is **reconstructed**, not measured: rungs carry durations but no
+wall-clock finish time, so a gate's stamp is the recording time minus the
+durations of the gates that ran after it. Honest ordering, approximate clock.
+
+## Forgery resistance
+
+`.uap/evidence/` is listed in enforcement-self-protect's `PROTECTED_TARGETS`
+with **no agent carve-out**, and the interpreter-write rule (built for the
+trust anchors) covers the directory too: shell redirects, Write/Edit tool
+calls, `python3 -c`, `node -e`, and heredoc-fed interpreter writes are all
+refused. The deliver CLI writes artifacts; the agent cannot. The trust root is
+"only the tooling could have written this".
+
+## Scope & limitations
+
+This gate is a **local** perimeter, and it is honest about what that means:
+
+- **Enforcement fires only on ship actions routed through the local policy
+  chain.** A merge pressed in the GitHub web UI, or a push from a machine
+  without the chain installed, never consults the enforcer. The remote-side
+  complement is ordinary branch protection / required status checks; this
+  policy is the local half, not a replacement for it.
+- **`.uap/` never reaches CI** — it is git-ignored by design, so evidence is
+  not a portable attestation another machine can verify. It proves something
+  to *this* checkout about *this* HEAD.
+- **`gh pr merge <N>` binds the LOCAL worktree HEAD.** The enforcer runs
+  without network or `gh`, so it cannot resolve the PR's head ref. If the
+  local branch has diverged from the PR head, the evidence validates the wrong
+  commit. Ship from the branch you deliver on.
+- **Squash/rebase merges mint a new remote commit** that no local evidence can
+  bind — the merged SHA differs from the gated HEAD by construction. Treat
+  those merges as covered by the remote-side controls above.
+- **`git merge master` (upstream sync) requires evidence for HEAD**, the same
+  as any ship action — consistent with `expert-review-required`. Re-run
+  `uap deliver` on the synced tree first.
+- **`--keep-best` rollback edge**: when a deliver run rolls the tree back to a
+  pre-run snapshot, HEAD is unchanged but the recorded evidence describes the
+  pre-rollback tree. The gates passed on that exact commit in both states, so
+  the claim still holds — but the output tails describe a tree you may no
+  longer have.
+
+## Staleness semantics
+
+Default window: **24 hours** from `recordedAt`. Rationale: evidence certifies a
+commit, and a commit's content cannot drift — but the *environment* the gates
+ran in can (dependencies updated, base branch moved, services changed). A day
+is long enough to cover a normal deliver → review → ship cycle and short enough
+that week-old green runs cannot launder a rebased branch. Operators can tune it
+with `UAP_EVIDENCE_MAX_AGE_HOURS` in the **launch environment** — the agent
+cannot set it (enforcement-self-protect refuses any assignment of the name,
+inline or persisted, because a huge window quietly retires the check).
+
+Note the flow-through consequence: ship gates bind evidence to `HEAD`, and the
+writer requires a clean tree, so the order is commit → `uap deliver` → ship.
+Amending or adding commits after the deliver run requires a fresh deliver run
+to re-record evidence for the new candidate. That is the intended posture —
+the gates must have passed on the exact commit being pushed.
+
+## Escape hatch
+
+`UAP_EVIDENCE_GATE_OFF=1` in the **launch environment** (operator-only). The
+inline form (`UAP_EVIDENCE_GATE_OFF=1 git push`) is refused by
+enforcement-self-protect — the agent composes its own command strings, so an
+inline override would be self-granted, the same reasoning as `UAP_NO_REVIEW`.
+
+## Related
+
+- [Policies guide](../guides/POLICIES.md) — the executable policy framework
+- [`uap deliver`](../guides/DELIVER.md) — the convergence harness that records evidence
+- Schema doc: `src/policies/schemas/policies/evidence-bound-ship.md`