@miller-tech/uap 1.222.0 → 2.0.0

package/docs/benchmarks/PAIRED_FINDINGS.md

@@ -1,5 +1,14 @@
 # Paired Benchmark Findings — When Does UAP Actually Help?
 
+> **2026-09-02 replication available:** re-run on Qwen3.8-27B × UAP v1.224.x —
+> the +20pp lift did not replicate. The stronger model moved the ceiling
+> (baseline 78%→94% on the same suite), and pooled across 146 raw-adapter
+> cells the gate loop is an exact wash: **82.9% vs 82.9%, Δ 0.0pp
+> [−5.5, +6.9]** — the CI excludes +20pp. UAP never significantly hurt
+> accuracy on any surface; the one actionable regression is deliver-path
+> stop-criteria latency on slow local models. See
+> [the replication section](#2026-09-02-replication--qwen38-27b-dense--uap-v1224x).
+
 Results from the controlled paired harness (`uap bench paired`, see
 [PAIRED_HARNESS.md](PAIRED_HARNESS.md)). These supersede earlier uncontrolled
 numbers and complete the story the [TBench Investigation](TBENCH_INVESTIGATION.md)
@@ -119,6 +128,103 @@ from the hidden superset `verifyCmd` that remains the authoritative scorer.
   detached tree that keeps the pipe open. Fixed with a detached process-group
   spawn + group SIGKILL; subsequent runs completed 158–190/192 cleanly.
 
+## 2026-09-02 replication — Qwen3.8-27B (dense) × UAP v1.224.x
+
+Same paired design, re-run on the current production local stack:
+**Qwen3.8-27B** (dense qwen35-arch, UD-IQ4_XS, native draft-mtp on llama.cpp,
+131k ctx/slot × 2 slots, RTX 3090) against **UAP v1.224.x** — i.e. *after* the
+quality-metrics gate (v1.223.0) and the deliver-pipeline hardening (v1.224.0)
+shipped. Plan: [qwen38-uap-retest-plan](../plans/qwen38-uap-retest-plan.md).
+
+**Headline: the +20pp gate-loop lift did not replicate at that magnitude —
+because the stronger model moved the ceiling.** On the identical gated suite
+the without-UAP baseline rose from 78% (qwen36 MoE) to **94%**, leaving almost
+no headroom; UAP fixed every remaining baseline failure and regressed none.
+On never-before-seen held-out tasks with real headroom (78.4% baseline), the
+raw gate loop was net-neutral (5 fixed, 5 regressed). UAP never significantly
+hurt accuracy on any surface; its costs (tokens, turns, latency) are real and
+quantified below.
+
+| Surface | n/arm | WITHOUT UAP | WITH UAP | Δ accuracy (95% CI) | McNemar fixed/regressed | Cost Δ |
+|---|---|---|---|---|---|---|
+| E1 raw, `real-gate-gated`, 10 ep | 50 | 94.0% | **100%** | **+6.0pp [0, +14]**, p=0.25 | **3 / 0** | +272 tok (n.s.) |
+| E3a raw, `real-gate-heldout`, 3 ep | 51 | 78.4% | 78.4% | 0pp [−11.8, +11.8] | 5 / 5 | +1,044 tok [+101, +2,571] |
+| E3b raw, `real-gate-power`, 3 ep | 45 | 75.6% | 68.9% | −6.7pp [−20, +6.7], p=0.51 | 3 / 6 | +117 tok (n.s.; loop never fired — see below) |
+| E2 opencode, `real-gate-hard`, 4 ep | 36 | 94.4% | 97.2% | +2.8pp [0, +8.3], p=1 | 1 / 0 | +52.0k tok [+20.8k, +86.8k], +1.2 turns |
+| E4 `uap deliver` (real pipeline), `real-gate-gated`, 5 ep | 25 | 68.0% | 60.0% | −8.0pp [−32, +16], p=0.75 | 4 / 6 | **+7.7 min/cell, p=0.0007** |
+
+**Pooled raw-adapter estimate (E1+E3a+E3b, 146 paired cells, 38 distinct
+tasks): 82.9% vs 82.9% — Δ 0.0pp, sign-flip 95% CI [−5.5, +6.9], p=1.0;
+McNemar 11 fixed / 11 regressed.** The CI now *excludes* the original +20pp:
+for this model, that lift is falsified, not replicated. (Pooled analysis:
+paired sign-flip bootstrap over the union of the three runs' records, seed 1,
+10k resamples — same method as the per-run reports.)
+
+### How to read it
+
+- **E1 (direct replication of the decisive qwen36 run):** same suite, same
+  temp (0.6), same epochs. Baseline 78%→94% across model generations is the
+  story — Qwen3.8-27B one-shots most edge cases the older MoE missed. UAP's
+  gate loop converted the remaining 3 baseline failures into passes with zero
+  regressions: same sign as the original +20pp, smaller magnitude because the
+  headroom shrank. CI touches 0 at n=50, so treat as directional.
+- **E3a (held-out tasks):** the honest counterweight. On tasks neither the
+  model tuning nor this repo's earlier analysis could have overfit to, the
+  loop's fixes (5) were exactly offset by rewrites that broke working
+  single-shot answers (5). The +1,044-token overhead is real. Net accuracy
+  claim on unseen tasks: **no measurable gain, no measurable harm**.
+- **E3b (power suite):** a different null mechanism — uap-full turns = 1.0
+  exactly. On these tasks the model's solution passes the *visible* in-repo
+  gate but fails the *hidden* verify superset, so the gate loop has nothing
+  to catch and never iterates; the arms differ only by prompt-surface
+  sampling noise at temp 0.6 (3 flips one way, 6 the other). Lesson for suite
+  design: gate-loop value requires the visible gate to correlate with the
+  hidden edges; where it doesn't, UAP can neither help nor systematically
+  hurt.
+- **E2 (agentic harness):** replicates the original 0pp-at-ceiling finding in
+  spirit (94.4% baseline; +2.8pp, 1 fixed / 0 regressed) and confirms the
+  cost side precisely: the UAP surface costs ~52k tokens and ~1.2 turns per
+  task on opencode. On a self-verifying agent, UAP's contribution is not
+  first-pass accuracy.
+- **E4 (the actual v1.224.x deliver pipeline, not the raw miniature):** the
+  one surface where UAP underperformed its own bare-turn baseline (−8pp, CI
+  spans 0, underpowered at n=25). The mechanism is visible in the records:
+  **29 of 50 cells hit the 21-minute cell timeout** (median treatment latency
+  = the cap), and every treatment mission ended in a not-delivered verdict —
+  including 15 that had in fact written a verify-passing solution. The
+  convergence loop does not stop in time on a slow local 27B: stop-criteria
+  and acceptance-judge latency are calibrated for fast API models.
+  **Actionable follow-up:** tune deliver stop criteria / judge timeouts for
+  slow local backends (or auto-scale the cell budget to model speed) before
+  quoting deliver-path numbers on this class of hardware.
+
+### Cross-model caveat
+
+The qwen36 → qwen38 comparison is **not paired**: model, serving stack
+(llama.cpp build, template, speculative decoding), and UAP version all moved
+between June and September. The per-model paired deltas above are the claims;
+the generational baseline shift (78%→94% on the same suite) is context, not a
+measurement of the model alone.
+
+### Reproduce (this stack)
+
+```bash
+# Raw single-shot vs gate loop (E1):
+UAP_RAW_TEMPERATURE=0.6 uap bench paired --adapter raw --model "Qwen3.8-27B" \
+  --suite benchmarks/suites/real-gate-gated --epochs 10 --concurrency 2
+
+# Agentic with/without (E2 — model id is opencode's provider/model form):
+uap bench paired --adapter opencode --model "qwen-proxy/Qwen3.8-27B" \
+  --suite benchmarks/suites/real-gate-hard --epochs 4 --concurrency 2
+
+# Real deliver pipeline (E4 — model is a deliver preset, not the served alias):
+uap bench paired --adapter deliver --model "qwen38-27b" \
+  --suite benchmarks/suites/real-gate-gated --epochs 5 --concurrency 2
+```
+
+Artifacts: `benchmark-results/paired-qwen38-e1-gated`,
+`-e2-hard-opencode`, `-e3a-heldout`, `-e3b-power`, `-e4-deliver2`.
+
 ## Reproduce
 
 ```bash

package/docs/benchmarks/PAIRED_HARNESS.md

@@ -107,6 +107,22 @@ and **pass** once the task is correctly solved.
 | `mock` | none (deterministic simulation) | exercises the pipeline offline; **not** a source of real claims |
 | `opencode` | `opencode run --model <m> <instruction>` | tokens, cost, steps, tool-calls (best-effort JSON) |
 | `claude` | `claude -p <instruction> --output-format json --model <m>` | tokens, cost, turns |
+| `raw` | one chat completion per cell; UAP arm loops it against the visible gate | tokens, turns, latency |
+| `mini` | `mini -y -m <m> -t <instruction>` (mini-SWE-agent) | external comparability anchor |
+| `deliver` | real `uap deliver` CLI per cell (baseline arm runs one bare turn) | verdict + turns from the JSON result |
 
 New agents are a few lines: implement `AgentAdapter` (or configure a
 `SubprocessAdapter` with a `parseUsage` function) in `src/benchmarks/paired/adapter.ts`.
+
+### Time budgets on slow local models
+
+A `deliver` cell's budget is `agentTimeoutSec × UAP_BENCH_DELIVER_TIMEOUT_MULT`
+(default 6, raised from 3 in 2026-09). The ×3 era was calibrated on fast hosted
+models; a full convergence mission on a slow local model (plan + self-gate +
+N turns + acceptance judge, each model call costing minutes) blew through it
+and the harness killed missions whose workdir already passed verification —
+paired-qwen38-e4 lost 21/25 treatment cells that way, manufacturing a -8pp
+"regression" out of pure budget starvation. Raise the multiplier (never
+disable it — an unbounded cell is a wedged overnight run) when the backing
+model is slow, and read a `timeout`-errored cell as *harness budget*, not a
+model failure.

package/docs/benchmarks/README.md

@@ -2,6 +2,27 @@
 
 Performance and accuracy results for the Universal Agent Protocol.
 
+## How to read these numbers (the rationale)
+
+UAP's core claim is *process* value: gates, memory, and coordination make an
+agent's output more reliable. Measuring that honestly is hard, because an
+agentic scaffold changes many variables at once (prompts, retries, tools,
+budgets). So the benchmark program runs in two tiers, and they answer
+different questions:
+
+1. **Controlled paired A/B** (`uap bench paired`) — same model, same tasks,
+   same seeds, same harness; the *only* thing toggled is the UAP scaffold.
+   This is the only design that isolates UAP's causal contribution, and it's
+   the tier whose numbers we quote as findings.
+2. **Uncontrolled field runs** (Terminal-Bench 2.0, uplift sweeps) — real
+   tasks, real agents, real token bills. These show magnitude and cost shape
+   but can't attribute causation; the
+   [TBench Investigation](TBENCH_INVESTIGATION.md) documents exactly how
+   apparent lifts dissolve into confounds when you control the variables.
+
+The headline below is therefore deliberately narrower than a marketing page
+would like — that's the point.
+
 ## Controlled paired result (start here)
 
 The rigorous, reproducible finding from the [paired harness](PAIRED_HARNESS.md)
@@ -41,4 +62,42 @@ authoritative.
 | [Accuracy Analysis](ACCURACY_ANALYSIS.md) | Success-rate and error analysis |
 | [Comprehensive Benchmarks](COMPREHENSIVE_BENCHMARKS.md) | Extended measurements |
 
+## Task suites and raw runs
+
+Reproduce or extend any of it:
+
+- **Task suites** (`benchmarks/suites/`) — the paired-harness suites, ordered
+  roughly by difficulty: `smoke/` (easy/medium/hard sanity checks),
+  `real-gate/` and `real-gate-medium/` (small real tasks), `real-gate-hard/`,
+  `real-gate-brutal/`, `real-gate-power/`, `real-gate-gated/` (tasks with a
+  deterministic `verifyCmd` as ground truth — no LLM judge),
+  `real-gate-heldout/` (kept out of tuning), and `swe-bench-pro/` (generator +
+  A/B runner for SWE-bench-style tasks).
+- **Cluster jobs** (`benchmarks/harbor-*.yaml`, `benchmarks/harbor-configs/`,
+  `benchmarks/harbor-tasks/`) — Harbor job definitions for running the suites
+  on a GPU box against local llama.cpp models (e.g. the Qwen3.5/3.6 configs).
+- **Terminal-Bench shim** (`benchmarks/terminal_bench/`) — the opencode agent
+  adapter used for the TBench runs.
+- **Raw results** (`benchmark-results/`, untracked — local only) — every
+  paired run drops a named directory (timestamped or version-labeled) with
+  `records.jsonl`, `report.json`, and `report.md`. Notable series: the June
+  2026 `paired-qwen36-*` sweeps (model/adapter/budget ablations), the
+  `paired-uplift-*` regression series (per-version uplift tracking), and
+  `real-uplift-1610/` (an agentic-baseline run: 100% → 83.3%, Δ −16.7pp with
+  CI [−0.50, 0.00] spanning 0 — i.e. no measurable lift against an agent that
+  already self-verifies, matching the paired finding).
+
+A typical reproduction:
+
+```bash
+uap bench paired --adapter raw --suite benchmarks/suites/real-gate-gated
+```
+
+## What we measure
+
+Each paired run reports a vector, not a single score: correctness delta with a
+bootstrap 95% CI, a McNemar gate-value 2×2 (tasks the gates rescued vs tasks
+they broke), token/turn/latency deltas, and a leave-one-out ablation over UAP
+components so you can see which station earns its keep.
+
 See the [documentation index](../INDEX.md) for the rest of the docs.

package/docs/design/UAP_REACTOR.md

@@ -137,7 +137,6 @@ mode (Assist = intake/routing context; Enforce = a station gate):
 | completion gate | stop | Enforce |
 | HALO analyze | session-end | Assist |
 | deploy flush | on deliver success | Enforce |
-| rtk token-opt | pre-tool (bash) | Enforce (already) |
 | ideate | on-demand only (router suggests when stuck) | Assist |
 
 ## 5. Per-harness wiring

package/docs/getting-started/INSTALLATION.md

@@ -9,7 +9,7 @@ edits your main branch, writes plausible-but-wrong code, and cheerfully declares
 "done" on something that never actually ran. UAP puts a station at each of those
 break points so the work that comes off the line is trustworthy.
 
-It ships as a single npm package (`@miller-tech/uap`, v1.93.1) that installs the
+It ships as a single npm package (`@miller-tech/uap`, v1.224.0) that installs the
 `uap` CLI. This page gets it onto your machine and wired into your project.
 
 ## Prerequisites

package/docs/guides/AUTOMATIC.md

@@ -137,7 +137,6 @@ automatically on every operation. No manual code reviews for common issues.
 
 | Gate | What it checks | When it fires |
 |---|---|---|
-| rtk_wrap | Token optimization | Every CLI command |
 | iac_parity | Infrastructure-as-Code safety | kubectl, helm, aws, gcloud, doctl |
 | delivery_enforcement | Verified output | Every source file edit |
 
@@ -233,18 +232,6 @@ changes are batched together and deployed as a single atomic unit.
 
 ---
 
-### rtk — 60–90% Token Savings
-
-**Benefit:** Massive token savings on every CLI command. rtk intercepts commands,
-optimizes them, and proxies through a token-efficient layer.
-
-**When it kicks in:** On every CLI command. rtk rewrites commands to use
-optimized paths and caches results.
-
-**You get:** Dramatically lower API costs and faster command execution.
-
----
-
 ### HALO — Human Oversight
 
 **Benefit:** Critical operations require human approval before execution.
@@ -288,7 +275,6 @@ VRAM-tiered configurations.
 | Schema-diff | API contract safety | Schema edits |
 | Completion gates | Verify "done" is done | Agent claims done |
 | Deploy batching | Atomic multi-change deploys | Deployable changes |
-| rtk | 60–90% token savings | Every CLI command |
 | HALO | Human oversight for critical ops | Critical actions |
 
 **Install UAP. Use your coding agent normally. Everything else is automatic.**

package/docs/guides/AUTOMATIC_FEATURES.md

@@ -195,16 +195,9 @@ the definition of done, and work resumes across sessions without being asked.
 
 ## Developer Experience
 
-### RTK (Rust Token Killer)
-**What it does:** CLI proxy that intercepts common commands (`git status`, `npm install`, etc.) and rewrites them for token efficiency — 60-90% token savings on dev operations.
-
-**When it kicks in:** Automatically for every shell command you run. No flags needed.
-
-**Why it matters:** Token costs add up fast. RTK transparently optimizes every command without you thinking about it.
-
 ### Dashboard — Savings & Orchestration Visibility
 **What it does:** `uap dash serve` shows **Token Savings by Influence** (real
-tokens/cost saved per mechanism — RTK, model routing, context compression — with
+tokens/cost saved per mechanism — model routing, context compression — with
 honest *measured/estimated* labels) and an **Orchestrations & Hierarchy** tree
 (the live mission → epic → task tree with the agents on each node and the active
 build ledger's progress).
@@ -277,7 +270,6 @@ long-running build is progressing — no guesswork.
 | Pattern RAG | ✅ | Every prompt | Battle-tested implementations |
 | Coordination | ✅ | Complex tasks | Parallel subagent execution |
 | Deploy batching | ✅ | Multiple changes | Atomic, efficient deploys |
-| RTK | ✅ | Every command | 60-90% token savings |
 | HALO | ✅ | Substantial prompts | Automatic task decomposition |
 | Model presets | ✅ | Model selection | Optimal params per model |
 

package/docs/guides/COORDINATION.md

@@ -1,6 +1,6 @@
 # Multi-Agent Coordination
 
-> UAP v1.163
+> UAP v1.224.0
 
 > **🏭 Where this fits:** LINE COORDINATION — the station where parallel agents on the [delivery pipeline](./DELIVERY_PIPELINE.md) quietly step on each other: two of them editing the same file, duplicating work, or deadlocking at merge. **What it delivers:** agents register, announce what they're about to touch, and check for overlaps *before* they start — so the line runs many workers at once and still stays conflict-free.
 

package/docs/guides/DELIVERY_PIPELINE.md

@@ -62,6 +62,8 @@ Two things run the length of the whole line: **policy gates** (the rules are *ex
 
 **What UAP puts here:**
 - **[`uap deliver`](DELIVER.md)** — a convergence loop that keeps iterating a model against your real gates until the work is actually built.
+- **Your gates, including the ones you declare** — build/test/lint are discovered from `package.json`, and anything extra (a migration check, a codegen diff, a contract test) can be declared in `delivery.gates[]` in `.uap.json` and joins the same ladder.
+- **A polyglot execution gate** — not everything is `node`: Python packages get a venv-aware import smoke test, native binaries are actually executed, and a binary that can't run on this host is an honest *skip*, never fabricated pass-evidence.
 - **Serving-layer recipes** — Fusion / Confidence / Ratings / ReMoM run behind the proxy to raise output quality, *escalating to a stronger, distinct judge* when it counts. (A same-model judge — qwen grading qwen — was measured to add nothing, so recipes only spend that budget when a genuinely stronger judge is wired.)
 - **[Local-model handling](LOCAL_MODELS.md)** — the proxy's guardrails (loop-breaker, recon-convergence, the no-tool empty-output guard, path normalization) keep a cheap local model on the rails so it produces real modules, not scaffolding.
 
@@ -74,8 +76,10 @@ Two things run the length of the whole line: **policy gates** (the rules are *ex
 **What UAP puts here:**
 - **Completion gates** — build, tests, lint, type-check must be green before anything can claim "done."
 - **Execution / runtime verify** (`uap verify`) — the generated code is actually *run* (headless browser, vm-dom, or child process) to prove it works, not just that it parses.
+- **The quality-metrics gate** (`uap quality check`) — ten code-quality budgets (complexity, coverage, CRAP, surviving mutants, dead code, duplicates, `any` types…) enforced deterministically, with a ratchet baseline so existing debt is frozen but the floor can only rise. Reviewers adjudicate the numbers; they can't outvote them.
 - **The acceptance judge** — an independent check that the behaviour matches the spec.
 - **Generator ≠ evaluator** — the thing that grades the work is deliberately *not* the thing that wrote it.
+- **Scoped rollback** — when a turn makes things worse, keep-best restores *only the files that run actually wrote* (tracked per-write plus a shell sweep), never the whole tree — so a rollback on a shared floor can't eat another agent's work.
 
 **Delivered:** "done" you can trust, because a different checker signed off.
 
@@ -98,6 +102,7 @@ Two things run the length of the whole line: **policy gates** (the rules are *ex
 - **Worktree → PR flow** with completion and version gates, so merges are clean and versioned.
 - **CI feedback watcher** — when CI goes red after a push, the loop re-converges instead of walking away.
 - **Never-regress + git-safety** — destructive git operations are guarded; passing work stays passing.
+- **Policy liveness + operator overrides** — the gates themselves are watched: a liveness registry tracks whether each liveness-declaring policy's compliant path (its tools, dirs, skills) is still satisfiable, and emergency bypasses live in a root-owned, expiring `.uap/operator-overrides.json` — so an agent can neither quietly let a gate rot nor mint its own exemption.
 
 **Delivered:** changes reach `main` clean, versioned, and CI-verified.
 

package/docs/guides/DEPLOY_BATCHING.md

@@ -1,6 +1,6 @@
 # Deploy Batching
 
-> UAP v1.163
+> UAP v1.224.0
 
 > **🏭 Where this fits:** LINE COORDINATION → SHIPPING — this is the station
 > where parallel agents collide: two push to the same branch within seconds and

package/docs/guides/DROIDS_AND_SKILLS.md

@@ -1,6 +1,6 @@
 # Droids and Skills
 
-> Applies to UAP **v1.163**
+> Applies to UAP **v1.224.0**
 
 > **🏭 Where this fits:** PREP/ROUTING — this is the station where a
 > generalist agent takes the wrong approach on specialist work: reviewing

package/docs/guides/LOCAL_MODELS.md

@@ -1,6 +1,6 @@
 # Running UAP Against Local Models
 
-> UAP v1.163
+> UAP v1.224.0
 
 > **🏭 Where this fits:** BUILD — this is the station where a cheap local model
 > flails: plausible-but-wrong code, empty output, or a loop that never lands a
@@ -23,6 +23,11 @@ productive station on your [delivery pipeline](./DELIVERY_PIPELINE.md).
 > [Qwen3.6 35B-A3B on llama.cpp, by VRAM tier](QWEN36_LLAMACPP.md) for
 > copy-paste launch commands for 8 / 12 / 16 / 24 / 32 GB GPUs, and how
 > `uap deliver` uplifts a small local model to *verified* results.
+>
+> **Production note (2026-09-04):** the reference box now serves Qwen3.8-27B
+> via **exllamav3/EXL3** (~1.5x faster decode at the same 131k context) —
+> see [Qwen3.8-27B on exllamav3 (EXL3)](QWEN38_EXL3.md). The llama.cpp path
+> below remains fully supported and is the rollback stack there.
 
 There are two endpoint shapes involved, and it matters which client speaks
 which protocol:

package/docs/guides/MCP_ROUTER.md

@@ -1,6 +1,6 @@
 # MCP Router
 
-> UAP v1.163
+> UAP v1.224.0
 
 > **🏭 Where this fits:** CROSS-CUTTING — keeping the context window lean at every station of the [delivery pipeline](./DELIVERY_PIPELINE.md). In a normal agentic workflow every tool call dumps its full result into context, so mostly-irrelevant output crowds out the details your agent actually needs. **What it delivers:** a proxy that compresses tool output before it reaches the model — up to 98% fewer tokens on large results — so the agent keeps room for real work and you spend less per session.
 

package/docs/guides/MEMORY.md

@@ -1,6 +1,6 @@
 # Memory System
 
-> UAP v1.163
+> UAP v1.224.0
 
 > **🏭 Where this fits:** INTAKE + FEEDBACK — the front and back doors of the [delivery pipeline](./DELIVERY_PIPELINE.md). At intake, a fresh agent forgets everything the last session learned and re-hallucinates scope; at feedback, nobody records the lesson, so the same mistake ships again next week. **What it delivers:** a persistent, searchable memory that hands each new agent the relevant past learnings on the way in, and captures durable lessons on the way out — so your team of agents gets smarter every run instead of starting from zero.
 

package/docs/guides/MULTI_MODEL.md

@@ -1,6 +1,6 @@
 # Multi-Model Routing
 
-> Applies to UAP **v1.163**
+> Applies to UAP **v1.224.0**
 
 > **🏭 Where this fits:** PREP/ROUTING — this is the station where a normal
 > agentic workflow sends *everything* to one model: paying premium-model rates

package/docs/guides/ORCHESTRATOR.md

@@ -186,7 +186,7 @@ this machinery:
   per-node status and the agents working each node, plus the active build
   ledger's progress.
 - **Token Savings by Influence** — real tokens/cost saved, attributed per
-  mechanism (RTK, model routing, context compression), with honest
+  mechanism (model routing, context compression), with honest
   *measured / estimated* labels.
 
 ---

package/docs/guides/POLICIES.md

@@ -1,6 +1,6 @@
 # Policies
 
-> Applies to UAP v1.163
+> Applies to UAP v1.224.0
 
 > **🏭 Where this fits:** CROSS-CUTTING — the executable rules bolted to every station of the [delivery pipeline](./DELIVERY_PIPELINE.md). In a normal agentic workflow the "rules" live in a prose prompt the model is free to ignore; that's how work escapes isolation, skips tests, or ships without review. **What it delivers:** each rule is a Python enforcer that actually inspects an operation and can *block* it before it runs — worktree isolation, test deltas, expert review, schema diffs, artifact hygiene, and more — so the guardrails hold instead of merely being suggested.
 
@@ -62,10 +62,13 @@ Each enforcer guards a specific station of the pipeline. The enforcers in
 | Enforcer | What it gates |
 |----------|---------------|
 | `worktree_required` | Edit/Write/MultiEdit must target a `.worktrees/` path |
+| `workdir_scope` | File-mutating tool calls must stay within the project working directory |
 | `task_required` | A UAP task must be `in_progress` before mutating work |
 | `coord_overlap` | Checks for in-flight agent path reservations (parallel-agent overlap) |
 | `branch_freshness` | Worktree edits blocked once the branch drifts too far from the integration branch (warn 50, block 200) |
 | `delivery_enforcement` | Route substantive coding through `uap deliver` |
+| `commitment_reserve` | Blocks all-in, no-way-back moves that exhaust the commitment reserve |
+| `adr_guard` | Generic ADR-driven tool-call gate |
 
 ### Plan discipline
 
@@ -73,7 +76,7 @@ Each enforcer guards a specific station of the pipeline. The enforcers in
 |----------|---------------|
 | `memory_before_plan` | Plans require a recent `uap memory query` |
 | `codebase_read_before_plan` | Plans require prior reads of the target paths |
-| `validate_plan_before_build` | A plan must be validated before building |
+| `validate_plan_on_change` | A plan must be validated before building (fires before the build, not on the write) |
 
 ### Quality & review gates
 
@@ -83,6 +86,11 @@ Each enforcer guards a specific station of the pipeline. The enforcers in
 | `schema_diff_gate` | Schema/pool changes must pass `uap schema-diff` |
 | `expert_review_required` | A parallel expert review must precede ship |
 | `architecture_review` | Merge / PR-ready operations need an architecture review when the diff warrants it |
+| `quality_metrics_gate` | Edits must not introduce NEW or WORSENED metric debt (complexity, coverage, duplication, `any` types) against the ratchet baseline |
+| `design_token_gate` | UI edits must stay on the project's DESIGN.md token system |
+| `visual_verification` | Under MAX fidelity, a commit that changes UI files requires visual verification |
+| `local_build_before_push` | Branches with C++ API source changes need a local Docker `--target builder` compile before `git push` / `gh pr create` / `gh pr merge` |
+| `ship_loop_gate` | A task may only transition to `completed` with evidence it was merged, deployed, monitored, and verified |
 
 ### Hygiene & artifacts
 
@@ -97,7 +105,6 @@ Each enforcer guards a specific station of the pipeline. The enforcers in
 | Enforcer | What it gates |
 |----------|---------------|
 | `mcp_router_first` | MCP tools must be loaded on demand |
-| `rtk_wrap` | Heavy CLIs must be invoked via `rtk` |
 | `parallel_reads` | Nudge when serial read fan-out is detected |
 
 ### Infrastructure
@@ -105,8 +112,17 @@ Each enforcer guards a specific station of the pipeline. The enforcers in
 | Enforcer | What it gates |
 |----------|---------------|
 | `iac_parity` | Live-state changes must have a matching infrastructure-as-code diff |
+| `iac_plan_destruction_check` | Destructive IaC plan operations are blocked |
 | `cluster_routing` | Cluster tooling context must match the component domain |
 
+### Enforcement protection
+
+| Enforcer | What it gates |
+|----------|---------------|
+| `enforcement_self_protect` | The model must not be able to disable the enforcement layer |
+| `enforcement_infra_protect` | The model must not kill or displace the inference stack (the Anthropic proxy, llama-server, their ports) |
+| `bearer_lockdown` | ADR-0007 cookie-only frontend gate — blocks bearer-token auth in the frontend |
+
 > The `architecture_review` enforcer file is stored with a policy-ID prefix
 > (`<uuid>_architecture_review.py`) because it is attached to a specific
 > installed policy; the others are named directly after their policy slug.

package/docs/guides/QWEN38_EXL3.md

@@ -0,0 +1,114 @@
+# Qwen3.8-27B on exllamav3 (EXL3) — the production serving stack
+
+> UAP v1.224.7 — added 2026-09-04, the day the box switched over.
+
+Since 2026-09-04 the production local model is served by **exllamav3**
+(MiaAI-Lab fork 1.4.2), not llama.cpp: **Qwen3.8-27B EXL3 3.5bpw** (14.2 GB,
+workload-calibrated) with a **DFlash2 EXL3 5.0bpw** draft model (1.4 GB) for
+speculative decoding. The recipe comes from yume_arasaki's RTX 4090 write-up
+and the Mia-AiLab quant cards, adapted for this box's RTX 3090.
+
+The llama.cpp stack (binary, `config/llama-profiles/`, `uap-llama-server`
+unit) is untouched and remains the **rollback path** — see the bottom of this
+doc.
+
+## Why switch
+
+| | llama.cpp (UD-IQ4_XS GGUF) | exllamav3 (EXL3 3.5bpw) |
+|---|---|---|
+| decode, short ctx, warm | ~55 tok/s (measured essay probe) | **~82 tok/s** (same probe) |
+| decode, deep into a long ctx | similar falloff | ~41–51 tok/s (KV grows) |
+| context | 131072 per slot, `--parallel 1` | 131072 per request, batch-1 + queue |
+| VRAM | ~21.9 GB resident | 20964 MiB resident |
+| tool calling | jinja template + grammar | native OpenAI-style, verified |
+| model id handling | `--alias` list, std::set-ordered | accepts any client-sent id |
+
+## The 3090 adaptation (read before copying the 4090 recipe)
+
+The article's `CACHE_QUANT=nvfp4` (and `fp8`) **does not compile on this
+box**: those Triton kernels need compute capability ≥ 8.9 (Ada/Hopper). The
+RTX 3090 is Ampere, **sm_86 — compute capability is fixed in hardware**, no
+driver or toolkit update changes it. The equivalent-density fallback is
+`CACHE_QUANT=4` (Hadamard int4, same ~4.5 bits/element), which is what runs.
+
+Second 3090 gotcha: the kit's default torch index (cu130) cannot compile the
+engine's CUDA kernels against this box's nvcc 12.4 — `TORCH_INDEX_URL` is
+pinned to `cu124` in the kit `.env`.
+
+## Layout
+
+Everything lives outside the repo at `/home/cogtek/Qwen3.8-EXL3-kit/`:
+
+```
+Qwen3.8-EXL3-kit/
+├── .env                  # the config (PORT, CONTEXT_SIZE, CACHE_QUANT, …)
+├── start.sh / stop.sh    # launcher (bootstraps venv on first run)
+├── models/
+│   ├── Qwen3.8-27B-EXL3-3.5bpw/          # target, 15 GB
+│   └── Qwen3.8-27B-DFlash2-EXL3-5.0bpw/  # draft, 1.4 GB
+├── .venv/                # torch 2.6.0+cu124, exllamav3 fork 1.4.2, triton 3.3.1
+└── tools/
+    ├── serve_openai.py   # OpenAI-compatible server (+ local shim, below)
+    ├── healthcheck.py    # start.sh's venv gate (local addition)
+    └── tokps.sh          # live tok/s monitor: tools/tokps.sh [interval] [port]
+```
+
+A reference copy of the `.env` is versioned at
+[`config/exl3-profiles/qwen38-27b-exl3.env`](../../config/exl3-profiles/qwen38-27b-exl3.env).
+
+## Local patches in the kit (reapply if the kit is re-cloned)
+
+1. **`triton_paged.py` parenthesization** — the fork's jit kernel used chained
+   boolean operators (`A and not B and not C`) that current Triton rejects;
+   lines ~1698/1719 parenthesized to `A and (not B and not C)`.
+2. **`torch.compile` → identity shim** in `tools/serve_openai.py` — the fork's
+   Hadamard-4 KV path needs triton ≥ 3.3 (`ASTSource(constexprs=…)`), but
+   torch 2.6's inductor imports `AttrsDescriptor`, which triton 3.3 removed,
+   so fla's import-time `@torch.compile` decorators exploded the import chain.
+   Nothing on the serving hot path uses inductor (the speed comes from
+   hand-written Triton kernels), so the shim falls back to the undecorated
+   function. torch 2.7 was not an option: no cu124 wheels.
+3. **`tools/healthcheck.py`** — start.sh gates its bootstrap on a bare
+   `import torch, exllamav3, aiohttp, huggingface_hub`, which fails for the
+   reason in (2) and re-entered setup, downgrading triton back to 3.2 (torch's
+   pin) and breaking the engine again. The health check now applies the same
+   shim, so bootstrap runs only when the venv is genuinely incomplete.
+
+Do **not** "fix" the triton version to match torch's pin: torch 2.6.0 asks
+for triton 3.2.0, but the engine fork requires ≥ 3.3. The pair
+(torch 2.6.0+cu124, triton 3.3.1, shim) is the working combination; pip will
+keep printing a dependency-conflict warning about it — that warning is the
+price of admission, not a problem.
+
+## Service management
+
+```bash
+systemctl --user status uap-exl3-server    # enabled, Restart=always
+journalctl --user -u uap-exl3-server -f    # live log
+/home/cogtek/Qwen3.8-EXL3-kit/tools/tokps.sh   # live tok/s
+```
+
+Unit: `~/.config/systemd/user/uap-exl3-server.service` → kit `start.sh`.
+The server binds `0.0.0.0:8080` (the port every client config already points
+at) and reports `max_model_len=131072` at `/v1/models`.
+
+**Proxy rails unchanged and still correct:** `PROXY_CONTEXT_WINDOW=131072`
+(exllamav3's `--cache_size` is per-request, matching llama.cpp's per-slot
+131072 at `--parallel 1`) and `PROXY_CONCURRENCY_LIMIT=1` (the EXL3 server is
+batch-1 and serializes concurrent callers internally — same shape as the
+1-slot llama.cpp config these rails were last tuned for). The server's
+`/v1/models` id is `qwen3.8-27b-exl3-3.5bpw-wm`, but it accepts any
+client-sent model id, so presets (`qwen3.8-27b`, etc.) flow through
+unmodified.
+
+## Rollback
+
+```bash
+systemctl --user stop uap-exl3-server
+systemctl --user enable --now uap-llama-server   # unit + env + binary untouched
+```
+
+The llama.cpp env (`~/.config/uap/llama-server.env` →
+`config/llama-profiles/qwen38-27b-dflash2.env`) and the ik/DFlash2 binary are
+exactly as they were; the service was only `disable`d so it stops competing
+for VRAM and port 8080 on boot.

package/docs/guides/WORKTREE_WORKFLOW.md

@@ -1,6 +1,6 @@
 # Worktree Workflow
 
-> Applies to UAP v1.163
+> Applies to UAP v1.224.0
 
 > **🏭 Where this fits:** ISOLATION — the station where a normal agentic workflow smears half-finished edits across `main`, clobbers files, and lets parallel agents collide into corrupt merge state. **What it delivers:** every agent works on its own branch in its own checkout, so the project root stays clean, each unit of work has a tidy PR boundary, and any number of agents can run at once without stepping on each other.
 
@@ -85,6 +85,50 @@ check; the advisory variant is for interactive orientation.
 The same `.worktrees/` containment is enforced at edit time by the
 `worktree-required` policy enforcer — see [POLICIES.md](./POLICIES.md).
 
+### Making enforcement optional
+
+Worktree *enforcement* is a project choice, asked at setup time. In the guided
+setup wizard (`uap setup`), the **Worktree isolation** toggle under
+"Multi-agent coordination" drives it:
+
+- **On (default)** — the pre-edit hooks hard-block edits outside
+  `.worktrees/`, the `worktree-required` policy enforcer stays active, and
+  generated CLAUDE.md files carry the MANDATORY worktree section.
+- **Off** — setup writes `"worktrees": { "enabled": true, "enforce": false }`
+  to `.uap.json`, deactivates the `worktree-required` policy, and omits the
+  MANDATORY section from generated CLAUDE.md. Worktrees remain fully
+  *supported* (`uap worktree create/pr/finish` all work); edits in the project
+  root are simply no longer blocked.
+
+You can flip it later by editing `.uap.json` — set both keys so every layer
+agrees:
+
+```json
+"worktrees": { "enabled": true, "enforce": false },
+"template":  { "sections": { "worktreeWorkflow": false } }
+```
+
+and stand the policy enforcer down with:
+
+```bash
+uap policy disable worktree-required
+```
+
+The three enforcement layers read different signals: the pre-edit hooks and
+`uap worktree ensure` honor the `.uap.json` flags at runtime (no reinstall
+needed), while the `worktree-required` policy enforcer follows its active
+state in the policy database. A missing or unreadable flag defaults to
+`enforce: true` (the historical behavior). For a one-off bypass,
+`UAP_NO_WORKTREE=1` wins over the file for the edit and commit/push guards
+(the `git reset --hard` / `git clean -f` data-loss guard keys on the config
+only).
+
+**Integrity note:** the self-disable path relies on the
+`enforcement-self-protect` policy (installed by `uap init`) — it hard-blocks
+agent edits to `.uap.json` on both the Edit/Write and Bash channels, so an
+agent cannot flip `enforce` itself. Projects that deploy the hook templates
+*without* the seeded policy DB get no such protection on the Bash channel.
+
 ## Parallel-agent safety
 
 The numeric ID is allocated from the SQLite registry, not from a directory