@miller-tech/uap 1.221.0 → 2.0.0

package/docs/ATTRIBUTION.md

@@ -30,7 +30,6 @@ because UAP embeds, vendors, or builds core workflows around them:
 - **Qwen** (Alibaba) — the local models UAP's local-first delivery pipeline is tuned for and benchmarked with.
 - **[Qdrant](https://qdrant.tech/)** + **nomic-embed-text** — the semantic long-term memory store and its embeddings.
 - **[uPlot](https://github.com/leeoniya/uPlot)** (MIT) — vendored (with license) in `web/vendor/` for the dashboard's charts.
-- **[RTK — Rust Token Killer](https://github.com/rtk-rs)** — the token-optimized CLI proxy the hook layer routes shell commands through.
 - **commander**, **@clack/prompts**, **vitest**, **better-sqlite3**, **zod** — the CLI, wizard, test, storage, and schema backbones.
 
 ## Conventions

package/docs/INDEX.md

@@ -1,6 +1,6 @@
 # UAP Documentation
 
-The complete documentation for the **Universal Agent Protocol** (`@miller-tech/uap` v1.163) — the discipline layer that turns a talented-but-unreliable AI coding agent into a dependable member of your software delivery line.
+The complete documentation for the **Universal Agent Protocol** (`@miller-tech/uap` v1.224.0) — the discipline layer that turns a talented-but-unreliable AI coding agent into a dependable member of your software delivery line. 367 TypeScript modules across 26 subsystems, 459 vitest suites plus a ~1,200-test Python enforcer/proxy suite, 60 CLI command registrations, 32 executable policy enforcers, 9 supported agent harnesses.
 
 > **Reviewing the system?** The reverse-engineered, code-verified reference set lives in
 > [`documentation/`](../documentation/architecture.md): architecture, flows, permissions
@@ -21,7 +21,7 @@ UAP is organized like a delivery line. If you know which part of the pipeline yo
 | **Prep / routing** — right job, right station | Wrong approach or wrong-sized model | [Multi-Model Routing](guides/MULTI_MODEL.md) · [Patterns](reference/PATTERNS.md) · [Droids & Skills](guides/DROIDS_AND_SKILLS.md) |
 | **Isolation** — a bench per job | Editing `main`, clobbering files | [Worktree Workflow](guides/WORKTREE_WORKFLOW.md) |
 | **Build** — make the thing | Plausible-but-wrong code, stubs, empty output | [`uap deliver`](guides/DELIVER.md) · [Local Models](guides/LOCAL_MODELS.md) · [Inference Proxy](guides/PROXY.md) |
-| **QC / verify** — prove it runs | "Done" on code that never ran | [`uap deliver`](guides/DELIVER.md) · [Policies](guides/POLICIES.md) |
+| **QC / verify** — prove it runs | "Done" on code that never ran | [`uap deliver`](guides/DELIVER.md) · [Policies](guides/POLICIES.md) · [Quality gate](../CLAUDE.md) (`uap quality check`) |
 | **Coordination** — many workers, one floor | Parallel agents colliding, stale branches overwriting landed work | [Parallel Agents](guides/PARALLEL_AGENTS.md) · [Coordination](guides/COORDINATION.md) · [Deploy Batching](guides/DEPLOY_BATCHING.md) |
 | **Shipping** — out the door safely | Regressions, red CI, skipped bumps | [Worktree Workflow](guides/WORKTREE_WORKFLOW.md) · [Policies](guides/POLICIES.md) |
 | **Feedback** — the floor learns | The same mistake every session | [Memory](guides/MEMORY.md) · [Self-Harness](design/SELF_HARNESS.md) · [Self-Tuning](guides/SELF_TUNING.md) |
@@ -45,6 +45,7 @@ Full map: **[The UAP Delivery Pipeline](guides/DELIVERY_PIPELINE.md)**.
 |---|---|
 | [**The Delivery Pipeline**](guides/DELIVERY_PIPELINE.md) | The station-by-station tour — the big-picture map of the whole floor ⭐ |
 | [**What UAP Does Automatically**](guides/AUTOMATIC_FEATURES.md) | Every feature in benefit / when-it-kicks-in terms — install once, it all self-applies ⭐ |
+| [What UAP Does Automatically (compact)](guides/AUTOMATIC.md) | A shorter, trigger-by-trigger telling of the same ground as AUTOMATIC_FEATURES |
 | [**`uap deliver`**](guides/DELIVER.md) | The Build+QC harness — convergence loop to verified completion, tiered gates, CI/deploy feedback loop ⭐ |
 | [**Orchestrator & Hands-Free**](guides/ORCHESTRATOR.md) | The long-task autonomy layer — blackboard orchestrator, epic controller, completion ledger, auto-seed/resume; any model runs a huge build to 100% hands-free ⭐ |
 | [**UAP Across Two Agents & Uplift**](guides/TWO_AGENTS_AND_UPLIFT.md) | The whole line applied seam-by-seam to opencode+Qwen3.6 (local) and Claude Code+Opus 4.8 (cloud), plus the benchmark that measures UAP uplift — diagrams + `benchmarks/suites/swe-bench-pro/` config |
@@ -56,13 +57,14 @@ Full map: **[The UAP Delivery Pipeline](guides/DELIVERY_PIPELINE.md)**.
 | [**Policy Selection & Recommendations**](guides/POLICY_SELECTION.md) | Which policies to enable for your workflow — a recommended core + tailored sets by scenario; `uap policy recommend` ⭐ |
 | [Pay2U Policy Pack](guides/POLICY_PACK_PAY2U.md) | The pay2u-tailored policy bundle |
 | [Multi-Model Routing](guides/MULTI_MODEL.md) | Plan → route → execute across 7 model profiles |
-| [Droids & Skills](guides/DROIDS_AND_SKILLS.md) | 38 expert droids, 36 skills, the expert router |
+| [Droids & Skills](guides/DROIDS_AND_SKILLS.md) | 38 expert droids, 6 bundled skills (plus per-harness skill surfaces), the expert router |
 | [Deploy Batching](guides/DEPLOY_BATCHING.md) | Conflict-free batched git/deploy actions |
 | [Coordination](guides/COORDINATION.md) | Multi-agent overlap detection |
 | [**Parallel Agents**](guides/PARALLEL_AGENTS.md) | Many agents, one codebase: fresh bases, drift blocking, `uap worktree sync`, the merge queue, ownership lanes ⭐ |
 | [Local Models](guides/LOCAL_MODELS.md) | Running agents against local llama.cpp / Qwen models |
 | [Inference Proxy](guides/PROXY.md) | The Anthropic↔local gateway: `uap proxy` lifecycle, reliability guardrails, security, serving recipes |
 | [Qwen3.6 on llama.cpp by VRAM](guides/QWEN36_LLAMACPP.md) | Tiered 8/12/16/24/32 GB setup; how `uap deliver` uplifts small local models |
+| [Qwen3.8-27B on exllamav3 (EXL3)](guides/QWEN38_EXL3.md) | The production serving stack since 2026-09-04: EXL3 3.5bpw + DFlash2 draft on a 3090, the sm_86 adaptations, local kit patches, rollback to llama.cpp |
 | [**LLM Self-Tuning**](guides/SELF_TUNING.md) | `uap tune` — raise a small model toward Opus by tuning UAP's flag surface with a benchmark-validated LLM/GP-BO loop; quality scoring, model profiles, auto-on real-time adaptation ⭐ |
 
 ## Architecture
@@ -81,6 +83,7 @@ Full map: **[The UAP Delivery Pipeline](guides/DELIVERY_PIPELINE.md)**.
 | Doc | What it covers |
 |---|---|
 | [CLI](reference/CLI.md) | Every `uap` command and flag |
+| [Comparison](reference/COMPARISON.md) | UAP vs other agent harnesses and adjacent tooling (memory, orchestration, spec-driven, review/policy) — positioning, honest trade-offs, sources |
 | [API](reference/API.md) | Programmatic API surface |
 | [Features](reference/FEATURES.md) | Full feature catalog, mapped to the pipeline stages |
 | [Patterns](reference/PATTERNS.md) | The 23 Terminal-Bench patterns |
@@ -94,18 +97,49 @@ Full map: **[The UAP Delivery Pipeline](guides/DELIVERY_PIPELINE.md)**.
 | Doc | What it covers |
 |---|---|
 | [MCP Router](integrations/MCP_ROUTER.md) | Setting up the MCP router across harnesses |
-| [RTK](integrations/RTK.md) | Rust Token Killer integration |
 
 ## Benchmarks
 
 | Doc | What it covers |
 |---|---|
+| [Benchmarks overview](benchmarks/README.md) | The headline numbers, what to trust, and where the raw runs and task suites live |
 | [**Paired Findings**](benchmarks/PAIRED_FINDINGS.md) | Controlled A/B results: UAP gate value is +20pp vs a non-agentic baseline [CI +8,+32], ~0pp vs an agentic one — with confidence intervals ⭐ |
 | [Paired Harness](benchmarks/PAIRED_HARNESS.md) | The `uap bench paired` controlled-A/B harness: design, adapters (mock/opencode/claude/raw), authoring tasks |
 | [TBench Investigation](benchmarks/TBENCH_INVESTIGATION.md) | Earlier finding: no measurable UAP-context lift (every uncontrolled gain was a confound), methodology lessons |
 | [Validation Results](benchmarks/VALIDATION_RESULTS.md) | Terminal-Bench 2.0 results (−49.7% tokens, +33pp success) |
 | [Token Optimization](benchmarks/TOKEN_OPTIMIZATION.md) | Where the token savings come from |
 | [Accuracy Analysis](benchmarks/ACCURACY_ANALYSIS.md) | Success-rate and error analysis |
+| [Comprehensive Benchmarks](benchmarks/COMPREHENSIVE_BENCHMARKS.md) | Extended measurements |
+
+## Analysis
+
+Dated, strategy-level reads of the market UAP operates in. For the evergreen
+feature-level comparison, see [Comparison](reference/COMPARISON.md).
+
+| Doc | What it covers |
+|---|---|
+| [Market Position & Competitive Analysis (2026-09)](analysis/MARKET_POSITION.md) | The 2026 agentic-delivery market, UAP's category (agent discipline layer), competitive dynamics per adjacent category, moats, honest weaknesses, and strategic options |
+
+## Plans & post-mortems
+
+Working documents that explain *why* the code looks the way it does — kept as
+the decision record.
+
+| Doc | What it covers |
+|---|---|
+| [Deliver hardening plan](plans/deliver-hardening-plan-2026-07-13.md) | The 14-defect audit (batches A–D) that became v1.224.0: scoped rollback, declared gates, polyglot execution, config routing, liveness, operator overrides |
+| [Deliver hardening review response](plans/deliver-hardening-review-response-2026-07-13.md) | Parallel-review findings and their dispositions — the rationale behind the root-owned trust model |
+| [Harness engineering uplift](plans/harness-engineering-uplift-2026-07-31.md) | Three-paper analysis of harness variance and what UAP does about it |
+| [K3 UAP uplift validation](plans/k3-uap-uplift-validation.md) | Plan to measure UAP's paired uplift on Kimi K3 by re-running Terminal-Bench 2.1 with Factory Droid as the harness, UAP on vs off |
+| [Qwen3.8 UAP re-test plan](plans/qwen38-uap-retest-plan.md) | Plan to re-run the paired benchmark matrix on the current local Qwen3.8-27B stack with UAP v1.224.x, replicating the +20pp gate-loop finding and checking the hardened deliver pipeline |
+
+## Specs & performance
+
+| Doc | What it covers |
+|---|---|
+| [P0 anti-vacuous spec](specs/p0-anti-vacuous.md) | The verbatim-operations spec behind deliver's anti-stub hardening |
+| [Dashboard uplift spec](DASHBOARD_UPLIFT_SPEC.md) | Replacing the monolithic dashboard with the modular token-locked console |
+| [Performance baseline](performance/baseline-2026-03-27.json) | Machine-recorded perf baseline (heap, query latency) |
 
 ## Contributing
 

package/docs/analysis/MARKET_POSITION.md

@@ -0,0 +1,179 @@
+# UAP Market Position & Competitive Analysis (2026-09)
+
+**Date:** 2026-09-06 · **Subject:** Universal Agent Protocol v1.224.8 (`@miller-tech/uap`)
+**Scope:** market-level position and competitive dynamics. For the evergreen
+feature-level comparison and honest trade-offs, see
+[reference/COMPARISON.md](../reference/COMPARISON.md) — this document is the dated,
+strategy-level companion: what the market looks like, where UAP sits in it, what protects
+the position, and what to do next.
+
+---
+
+## 1. Executive summary
+
+UAP is **not** a coding agent, an agent framework, or a communication protocol. It is a
+**process-governance layer for AI-driven software delivery** — a discipline substrate that
+installs *underneath* any agent harness (9 supported) and enforces the stations of a
+delivery line: memory, routing, isolation, build, verification, coordination, shipping,
+and feedback.
+
+That category — the **agent discipline layer** — is sparsely occupied. The 2026 market has
+consolidated around protocols (MCP, A2A), commoditized agent frameworks, and a crowded,
+churny field of coding-agent harnesses, while memory and guardrails have each become their
+own product category. What none of those categories sell is *verified delivery process*:
+the guarantee that an agent's output survived real gates, that parallel agents didn't
+clobber each other, and that "done" was graded by something other than the model that
+wrote the code. UAP's thesis: reliability in agentic development is a **process problem,
+not a model problem** — and UAP productizes the process.
+
+**Positioning statement:** *For teams running AI coding agents on real codebases, UAP is
+the discipline layer that turns a talented-but-unreliable agent into a dependable line
+worker — harness-agnostic, model-agnostic (frontier cloud to fully local), enforced by
+executable gates rather than prompt prose.*
+
+---
+
+## 2. Market context (2026)
+
+Five structural facts define the market UAP sells into:
+
+1. **Coding agents are mainstream and multi-vendor.** Terminal-Bench 2.1 leaders sit at
+   ~89% (Codex CLI/GPT-5.6 Sol 89.5%, Claude Code/Opus 5 89.1%); OpenCode (MIT) is the
+   most-starred open-source agent (~199k stars). Buyers run *several* harnesses and switch
+   frequently — harness churn is a market feature. (Sources 5–8.)
+2. **Protocols have consolidated; they are complements, not competitors.** MCP (~97M
+   downloads) owns agent↔tool; A2A (150+ orgs, in enterprise production 18 months after
+   launch) owns agent↔agent; AG-UI owns agent↔UI; ACP/ANP and payment protocols (AP2,
+   x402) fill niches. The protocol war is effectively over — value moved up the stack to
+   what you *do* with connected agents. (Sources 1–4.)
+3. **Memory is a recognized product category with benchmarked leaders.** Zep/Graphiti,
+   mem0, Letta, and Cognee compete on LoCoMo/LongMemEval/BEAM scores (e.g., Zep 63.8% vs
+   mem0 49.0% on LongMemEval) and on enterprise gates (SOC 2). General-purpose,
+   conversation-scoped memory is commoditizing. (Sources 9–12.)
+4. **Guardrails spend is rising but aims at content safety and compliance, not delivery
+   process.** The 2026 guardrails market (Galileo lists 8 serious vendors; "NeMo
+   Guardrails alternatives" is a genre) is built around hallucination detection, PII, IAM
+   boundaries, and EU AI Act checklists. "Did the agent run the tests before claiming
+   done" is not in their feature matrix. (Sources 13–15.)
+5. **Spec-driven development and AGENTS.md prove demand for process scaffolding** — but
+   they are *authored intent* (60,000+ repos read AGENTS.md; ETH Zurich has studied
+   context-file quality). Prose and specs describe process; they cannot enforce it at
+   runtime. The gap between "written guidelines" and "enforced process" is exactly UAP's
+   seam. (Sources 16–18.)
+
+---
+
+## 3. Category map
+
+```
+  Protocols    MCP · A2A · AG-UI · ACP · AP2/x402           plumbing (settled)
+  Harnesses    Claude Code · Codex · Cursor · Factory ·      the workers
+               OpenCode · Devin · Antigravity · Junie        (crowded, churny)
+  Frameworks   LangGraph · CrewAI · AutoGen · OAI Agents     agent construction
+  Memory       Zep · mem0 · Letta · Cognee · Supermemory     recall (per-agent)
+  Guardrails   Guardrails AI · NeMo · Galileo-class vendors  content/compliance
+  SDD/context  spec-kit · Kiro · AGENTS.md convention        intent, authored
+
+  ▶ UAP: none of the above — the layer *between* harness and codebase that owns
+    process enforcement: SDLC-scoped memory, model routing, worktree isolation,
+    convergence-to-gates delivery, executable policy, multi-agent coordination,
+    and a measured-uplift benchmark program. Harness- and model-agnostic.
+```
+
+UAP's deliberate stance: **it does not compete with harnesses; it makes every harness
+better.** Harness churn (fact #1) is therefore a tailwind — each new harness release is a
+new distribution surface, not a threat.
+
+---
+
+## 4. Competitive dynamics by category
+
+Feature-by-feature tables live in [reference/COMPARISON.md](../reference/COMPARISON.md);
+this section is about *dynamics* — who can move into UAP's space and why they haven't.
+
+| Category | Relation | Why they don't absorb UAP's function |
+|---|---|---|
+| **Protocols** (MCP, A2A) | Complement — MCP Router consumes MCP, adds tool-hiding + ~98% output compression | Protocol vendors are structurally neutral; opinionated per-repo SDLC process is off-mission. An A2A bridge for inter-org coordination is an opportunity, not overlap |
+| **Harnesses** (Claude Code, Codex, Cursor, Factory, OpenCode, Devin) | Distribution, not competition | Their blind spot is structural: the harness grades its own homework, and harness-owned enforcement dies at the harness boundary. Roadmaps optimize session UX and autonomy depth, not cross-harness process governance |
+| **Frameworks** (LangGraph, CrewAI, AutoGen) | Different buyer moment | Frameworks answer "how do I *build* an agent system"; UAP answers "how do the agents I already run *deliver reliably*." Both coexist in one org |
+| **Memory vendors** (Zep, mem0, Letta, Cognee) | Nearest single-feature competitors | They win general memory bake-offs; UAP wins where memory is wired to process (evidence-gated writes, patterns that become executable gates, task-outcome feedback). UAP memory is local-first files+SQLite — no vendor schema lock-in. Backend pluggability would convert them into integrations |
+| **Guardrails vendors** (Guardrails AI, NeMo, Galileo-class) | Adjacent, non-overlapping | Their unit of enforcement is the *model response* (PII, injection, compliance); UAP's is the *tool call and the delivery claim*. Regulated enterprises plausibly buy both |
+| **SDD / context files** (spec-kit, Kiro, AGENTS.md) | Philosophical complement | Declarative intent relies on model cooperation; UAP's premise (measured, repeatedly) is that prose gets ignored, so process must execute. "spec-kit authors the spec; UAP enforces delivery against it" |
+| **CI/CD & code quality** (Actions, SonarQube, Stryker) | Complement; UAP moves the gate left | Their gates fire post-push; UAP's fire in-session, before the PR exists — each in-session catch saves a CI round-trip and a human review cycle |
+
+No single competitor covers more than two cells of UAP's capability row (see the matrix in
+COMPARISON.md).
+
+---
+
+## 5. Moats
+
+1. **Incident-derived guardrail corpus.** The proxy/enforcer suite isn't a feature list —
+   each breaker (cycle, starvation, contamination, death-spiral, truncation-repair,
+   disconnect-abandonment) is annotated with the production failure that motivated it.
+   Reproducing it requires *living through* those failures, not reading a spec.
+2. **Measured, honest uplift evidence.** A paired A/B harness (same task, same model,
+   ±UAP) with published confidence intervals — including published *falsifications* of its
+   own earlier claims (the +20pp pooled claim was re-tested and corrected). In a market of
+   cherry-picked benchmark marketing, falsifiable self-measurement is a credibility moat.
+3. **Harness-agnostic enforcement surface.** 9 harness integrations with per-harness hook
+   installers; switching costs flow the other way (teams keep UAP when they churn
+   harnesses).
+4. **Local-model depth.** Production-proven guidance for self-hosted stacks (llama.cpp,
+   exllamav3/EXL3 with speculative decoding), context-window management, and routing —
+   validated on real hardware (3090-class) as a daily driver, not a demo.
+5. **Test mass as correctness evidence.** 459 vitest suites + ~1,200 Python enforcer/proxy
+   tests, with suite-coverage meta-tests that fail CI if a test module is unlisted.
+
+## 6. Honest weaknesses & risks
+
+| Weakness | Consequence | Mitigation path |
+|---|---|---|
+| Single-maintainer scale | Bus factor; support ceiling | Community building; docs already onboarding-oriented |
+| Self-run benchmarks only | Skeptical buyers discount in-house numbers | Third-party replication; publish raw cell data (already in `benchmark-results/`) |
+| No SOC 2 / enterprise compliance posture | Blocked at regulated procurement | Scope honestly; partner with compliance-layer vendors |
+| No hosted control plane | Teams wanting SaaS dashboards self-host everything | Optional cloud telemetry sync later |
+| Proxy speaks Anthropic Messages shape | OpenAI-native clients need adaptation | Widen proxy dialects as demand appears |
+| Distribution = npm + word of mouth | Discovery limited | Presence in AGENTS.md ecosystem, spec-kit integrations, benchmark publications |
+| Category education required | "Discipline layer" isn't a budget line item yet | Content around the factory-floor metaphor and measured uplift |
+
+## 7. Opportunities & recommendations
+
+1. **Own the category name.** Publish the "agent discipline layer" thesis with the paired
+   benchmark methodology as the proof artifact; the falsification-correction story is the
+   strongest credibility asset available.
+2. **Alliance with SDD, not competition.** A `spec-kit`/AGENTS.md integration story
+   ("they author intent; UAP enforces delivery") rides an established, growing convention.
+3. **A2A bridge for inter-org coordination.** UAP's intra-floor coordination + A2A's
+   inter-agent standard pair naturally as multi-org agent workflows appear.
+4. **Memory-backend pluggability.** Formalize the memory backend interface so Zep/mem0 can
+   slot behind UAP's write-gates — converts the nearest competitors into integrations.
+5. **Enterprise wedge: local-first regulated teams.** The fully-local path (local models +
+   local memory + local gates, zero egress) is a genuine differentiator for defense,
+   health, and finance teams that can't ship code context to vendor clouds.
+
+---
+
+## 8. Sources
+
+1. AI Agent Protocol Ecosystem Map 2026 — digitalapplied.com/blog/ai-agent-protocol-ecosystem-map-2026-mcp-… (2026-03-18)
+2. Agent Interoperability Protocols 2026: MCP, A2A, ACP — zylos.ai/research/2026-03-26-agent-interoperability-protocols-mcp-a2a-… (2026-03-26)
+3. A2A Protocol: ecosystem 2026 — aniketkarneai.com/blog/2026-07-06-a2a-protocol-ecosystem-2026 (2026-07-06)
+4. Six Agent Protocols Every AI Builder Needs to Know in 2026 — mindstudio.ai/blog/six-agent-protocols-ai-builders-2026 (2026-05-20)
+5. Best AI Coding Agents in 2026 — firecrawl.dev/blog/best-ai-coding-agents (2026-08-03)
+6. Best AI Coding Agent (Terminal-Bench 2.1 rankings) — morphllm.com/ai-coding-agent (2026-08-21)
+7. 12 AI Coding Agents Compared in 2026 — ssojet.com/blog/ai-coding-agents-compared (2026-06-08)
+8. AI Coding Agents: Adoption Trends — blog.jetbrains.com/research/2026/08/ai-coding-agent-adoption-2026 (2026-08-19)
+9. State of AI Agent Memory 2026 — mem0.ai/blog/state-of-ai-agent-memory-2026 (2026-09-03)
+10. Best AI Agent Memory Providers in 2026 — developersdigest.tech/blog/best-ai-agent-memory-providers-2026 (2026-07-31)
+11. Mem0 vs Zep vs Letta vs Cognee — particula.tech/blog/agent-memory-frameworks-tested-mem0-zep-letta-cognee (2026-06-04)
+12. Mem0 vs Zep vs Letta vs Cognee vs Supermemory (Q3 2026) — mnemoverse.com/docs/library/ai-memory-solutions-2026-q3 (2026-08-06)
+13. 8 Best AI Agent Guardrails Solutions in 2026 — galileo.ai/blog/best-ai-agent-guardrails-solutions (2026-03-17)
+14. Enterprise AI Governance & Policy Enforcement (NeMo alternatives) — deepinspect.ai/blog/nemo-guardrails-alternatives (2026-08-17)
+15. Enterprise AI Agent Guardrails: A Compliance Checklist for 2026 — atlan.com/know/ai-agent/enterprise-ai-agent-guardrails-checklist/ (2026-06-15)
+16. Spec-Driven Development with AI Coding Agents (2026) — tryzeroshot.com/blog/spec-driven-development-with-ai-coding-agents (2026-07-25)
+17. AGENTS.md Specification — asdlc.io/practices/agents-md-spec/ (2026-03-16)
+18. How to Build Your AGENTS.md (2026) — augmentcode.com/guides/how-to-build-agents-md (2026-06-18)
+
+*UAP-internal figures (module/suite/enforcer counts, measured uplift, ~98% compression)
+are from this repository's README, docs/INDEX.md, and benchmark-results/ as of v1.224.8.*

package/docs/architecture/OVERVIEW.md

@@ -1,6 +1,6 @@
 # UAP Architecture Overview
 
-`v1.124.1` · ~223 TypeScript modules across 18 `src/` subsystems · 200+ test suites
+`v1.224.0` · 367 TypeScript modules across 26 `src/` subsystems · 459 vitest suites (+ a ~1,200-test Python enforcer/proxy suite)
 
 > **Code-verified reference:** this narrative overview is the intent-level floor plan. For
 > the reverse-engineered, implementation-accurate map — including trust boundaries,
@@ -115,23 +115,32 @@ the harness aborts the call). Hook scripts are generated and installed by
 
 ```
 src/
+├── delivery/       `uap deliver` convergence loop (86 modules: ladder, critic,
+│                   judge, applier, snapshot/rollback, orchestrator, CI watcher…)
+├── cli/            60 command modules wired into bin/cli.ts
 ├── memory/         4-tier memory: working, session, semantic (Qdrant), graph
-├── mcp-router/     hierarchical MCP router — tool hiding + FTS5 output compression
-├── policies/       hook-based policy gates + 20 Python enforcers
-├── delivery/       `uap deliver` convergence loop (15 modules)
+├── benchmarks/     paired A/B harness + Terminal-Bench scoring
 ├── coordination/   multi-agent registry, overlap detection, deploy batching
+├── self-tuning/    `uap tune` — LLM/GP-BO search over UAP's flag surface
+├── self-harness/   `uap self-harness` — mine → propose → validate loop
 ├── models/         multi-model routing, planning, execution profiles
+├── mcp-router/     hierarchical MCP router — tool hiding + FTS5 output compression
+├── policies/       hook-based policy gates + 32 Python enforcers
+├── quality/        quality-metrics gate: complexity/CRAP/coverage/mutation budgets
+│                   with a ratchet baseline (`uap quality`)
 ├── tasks/          dependency-aware task tracker (SQLite, DAG)
 ├── dashboard/      live task / agent / memory / policy visualization
+├── principles/     engineering-principles store (`uap principles`)
+├── design/         DESIGN.md interrogation + design-token gate support
+├── telemetry/      run telemetry
+├── state/          shared run state
+├── config/         configuration loading
+├── browser/        cloaked browser automation for agents
 ├── observability/  HALO / OpenInference span export for harness analysis
-├── analyzers/      project structure analysis + metadata generation
+├── integrity/      protected-file byte verification
 ├── generators/     CLAUDE.md / config generation
-├── benchmarks/     Terminal-Bench harness + scoring
-├── browser/        cloaked browser automation for agents
-├── telemetry/      run telemetry
-├── models/…        (see above)
+├── analyzers/      project structure analysis + metadata generation
 ├── bin/            CLI entry (cli.ts), policy bin, llama-server-optimize
-├── cli/            ~35 command modules wired into bin/cli.ts
 ├── types/          shared types
 └── utils/          logging and shared helpers
 ```
@@ -231,14 +240,52 @@ Two layers:
   on a REQUIRED violation. Stages: `pre-exec | post-exec | review | always`;
   completion/merge/deploy operations auto-force a `review` stage.
 - **Shell gate + Python enforcers** — `templates/hooks/uap-policy-gate.sh`
-  binds to harness hook events and invokes the ~20 enforcers in
+  binds to harness hook events and invokes the 32 enforcers in
   `src/policies/enforcers/`. A blocked verdict is **exit code 2** (hard block).
 
 Enforcers cover the worktree gate (`worktree_required.py`), task discipline
 (`task_required.py`), delivery routing (`delivery_enforcement.py`), test deltas
 (`test_gate.py`), expert review (`expert_review_required.py`), schema diffs
-(`schema_diff_gate.py`), memory-before-plan, MCP-router-first, RTK wrapping, and
-more. Levels: **REQUIRED** blocks, **RECOMMENDED** logs, **OPTIONAL** informs.
+(`schema_diff_gate.py`), quality metrics (`quality_metrics_gate.py`), design
+tokens (`design_token_gate.py`), visual verification (`visual_verification.py`),
+branch freshness (`branch_freshness.py`), self-protection
+(`enforcement_self_protect.py` — guards the policy DB, hook scripts, and trust
+anchors like `.uap/operator-overrides.json` against tampering, including
+interpreter-mediated writes), memory-before-plan, MCP-router-first,
+and more. Levels: **REQUIRED** blocks, **RECOMMENDED** logs,
+**OPTIONAL** informs.
+
+Two trust anchors sit above the policies themselves (v1.224): the
+**operator-overrides file** (`.uap/operator-overrides.json` — temporary,
+expiring bypasses) and the **liveness cache** (`.uap/policy-liveness.json` —
+for policies that declare liveness requirements, a record that their compliant
+path — the PATH commands, agent-writable dirs, resolvable skills they depend
+on — is still satisfiable, so a policy whose sanctioned route has rotted can
+degrade gracefully instead of silently blocking or silently passing). Both are
+honored only when root-owned, symlink-free, not group/world-writable, and (the
+cache) fresh — so a compromised or misbehaving agent running as the same uid
+cannot mint its own bypass.
+
+### Quality gate (`src/quality/`) — QC station, deterministic edition
+
+**The break it prevents:** review-by-eyeball lets complexity and coverage rot
+compound invisibly until the codebase fights every change. This station turns
+ten software-quality metrics into a machine-checked budget that can only
+tighten.
+
+The quality-metrics gate (v1.223) polices cyclomatic/cognitive complexity,
+Halstead difficulty, LOC-per-file, coverage, CRAP, surviving mutants, dead
+code, duplicate blocks, and explicit `any`/`unknown` — deterministically, with
+no LLM in the loop. The built-in scanner (LOC, complexity, any-types) always
+runs; external tools (lizard, jscpd, rust-code-analysis, knip, Stryker) are
+probed and skipped with a warning when absent. Existing debt is frozen in a
+**ratchet baseline** (`.uap/quality-baseline.json`): only *new or worsened*
+violations block, and regenerating the baseline is a deliberate,
+reviewer-signed-off act. Enforcement lands at edit time
+(`quality_metrics_gate.py`) and at commit/CI time (`uap quality check`); when
+active, the parallel-review artifact must embed a `quality` block and
+`quality.pass: false` vetoes the ship — reviewers adjudicate the numbers, they
+can't outvote them.
 
 ### Delivery — `uap deliver` (`src/delivery/`) — Build & QC stations
 
@@ -247,7 +294,7 @@ emits plausible-but-wrong code and declares victory on a red build. The deliver
 loop won't let the work leave the Build/QC stations until the project's *real*
 gates actually pass.
 
-A 15-module convergence loop that drives an underlying model against the
+An 86-module convergence loop that drives an underlying model against the
 project's **real** completion gates until the work actually passes — the
 mechanism behind UAP's "agents stop declaring victory on broken code." See the
 [deliver flow](#how-uap-deliver-orchestrates) below.
@@ -406,9 +453,27 @@ detect gates ──▶ baseline check ──▶ protect files ──▶ ╔═
 ```
 
 - **Verifier ladder** (`verifier-ladder.ts`) — derives gate rungs from
-  `package.json` scripts (build → typecheck via `tsc --noEmit` → test → lint),
-  runs each as a real command in a secret-stripped env, fails fast on required
-  rungs. "Delivered" means all *required* rungs pass; lint is optional.
+  `package.json` scripts (build → typecheck via `tsc --noEmit` → test → lint)
+  and merges in **project-declared gates** from `delivery.gates[]` in
+  `.uap.json` (each declared `cwd` is contained to the project root), runs each
+  as a real command in a secret-stripped env, fails fast on required rungs.
+  "Delivered" means all *required* rungs pass; lint is optional.
+- **Polyglot execution gate** (`execution-gate.ts`) — beyond Node: Python
+  packages get a venv-aware import smoke test (`.venv/bin/python` is probed
+  before the ambient interpreter), and native binaries are executed with
+  honest verdicts — a signal death fails, while deliberate exit codes,
+  timeouts, and not-executable-here are reported as passes/skips rather than
+  fabricated evidence.
+- **Scoped rollback** (`snapshot.ts`) — keep-best rollbacks restore **only the
+  run's own write-set** (tracked per-tool-write plus a bash sweep of
+  stat-moved paths), never the whole tree, so a rollback in a shared worktree
+  can't silently revert another agent's work. Restore is realpath-contained
+  to the project root; when the write-set is empty but rollback is warranted,
+  the run fails loudly and preserves the snapshot instead of guessing.
+- **Config-driven model routing** — `delivery.model`, `delivery.routing`, and
+  `delivery.criticality` in `.uap.json` steer the deliver model (precedence:
+  CLI flag > config > criticality > env), and the acceptance judge follows the
+  same resolution so the grader matches the builder.
 - **Explorer + ideation** (`explorer.ts`, `ideation.ts`) — best-of-N: generate
   N candidates with distinct strategy seeds, apply/verify/rollback each on the
   same baseline, commit only the winner. A model **judge** (`judge.ts`)
@@ -439,5 +504,4 @@ ceiling (default 30, hard cap 50), and stops once progress stalls.
 - [PROTOCOL.md](PROTOCOL.md) — the harness↔UAP contract and agent loop
 - [../guides/DELIVERY_PIPELINE.md](../guides/DELIVERY_PIPELINE.md) — the end-to-end delivery-pipeline walkthrough
 - [../integrations/MCP_ROUTER.md](../integrations/MCP_ROUTER.md) — MCP Router setup
-- [../integrations/RTK.md](../integrations/RTK.md) — RTK (Rust Token Killer)
 - [../../CONTRIBUTING.md](../../CONTRIBUTING.md) — development workflow

package/docs/architecture/PROTOCOL.md

@@ -1,6 +1,6 @@
 # The UAP Protocol
 
-`v1.93.1`
+`v1.224.0`
 
 > **🏭 Where this fits:** Cross-cutting (the factory rulebook) — with no shared
 > contract, each station's rules are guesswork and your agent slips broken work

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.