@miller-tech/uap 1.93.0 → 1.93.1

package/README.md

@@ -2,16 +2,16 @@
 
 # Universal Agent Protocol (UAP)
 
-**Give your AI coding agents memory, judgment, and the discipline to finish the job.**
+**The discipline layer that turns a talented-but-unreliable AI coding agent into a dependable member of your software delivery line.**
 
 [![npm](https://img.shields.io/npm/v/@miller-tech/uap?color=blue&label=npm)](https://www.npmjs.com/package/@miller-tech/uap)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
-[![Tests](https://img.shields.io/badge/tests-117_suites-brightgreen)](#testing)
+[![Tests](https://img.shields.io/badge/tests-170%2B_suites-brightgreen)](#testing)
 [![License](https://img.shields.io/badge/license-MIT-black)](LICENSE)
 
-`v1.40.0` · 168 modules · 117 test suites · 9 agent harnesses
+`v1.93.1` · 220+ modules · 170+ test suites · 9 agent harnesses
 
-[Quickstart](#quickstart) · [Why UAP?](#why-uap) · [`uap deliver`](#the-deliver-harness) · [Architecture](#architecture) · [Benchmarks](#benchmarks) · [Docs](docs/INDEX.md)
+[Quickstart](#quickstart) · [Why UAP?](#why-uap) · [The delivery pipeline](docs/guides/DELIVERY_PIPELINE.md) · [`uap deliver`](#the-deliver-harness) · [Docs](docs/INDEX.md)
 
 </div>
 
@@ -19,19 +19,21 @@
 
 ## Why UAP?
 
-AI coding agents are capable but undisciplined. They forget everything between sessions, burn tokens echoing huge tool outputs, repeat the same mistakes, declare victory on work that doesn't compile, and trip over each other in shared repos. UAP is a production-tested layer that sits **underneath your agent harness** (Claude Code, Factory, Cursor, OpenCode, and more) and fixes these problems at the protocol level — no model change required.
+Shipping software with an AI agent is a lot like running a small factory floor. Intent comes in one end; working, verified, merged code should come out the other. In between are stations — understand the job, set up a bench, build it, **check it actually works**, ship it — and a jam at any one of them quietly ruins everything downstream.
 
-| The problem | What UAP does | Measured impact |
+Coding agents are capable but undisciplined line workers. They forget yesterday's shift, grab the wrong tool, build something that *looks* right, stamp it "done" without plugging it in, and trip over the other workers on the floor. That's not a problem you fix by swapping in a smarter model — it's a *process* problem. UAP is the process: it sits **underneath your agent harness** (Claude Code, Factory, Cursor, OpenCode, and more) and puts a station at every point where the line usually breaks — no model change required.
+
+| Where the line jams | What UAP puts there | What you get |
 |---|---|---|
-| Agents forget past sessions | 4-tier memory with semantic recall + write-gates | **49.7% fewer tokens** |
-| Tool output floods the context | MCP Router — tool-hiding + FTS5 output compression | **up to ~98%** on large tool calls |
-| Agents declare done on broken work | `uap deliver` — convergence loop against **real** gates | **+33pp** task success (25% → 58%) |
-| Repetitive mistakes | 23 Terminal-Bench patterns + learning loop | **68% fewer errors** |
-| Wrong model for the job | Multi-model router, 7 profiles | optimal cost/perf per task |
-| Agents step on each other | Worktree isolation + coordination service | conflict-free parallel work |
-| "Guidelines" get ignored | Policy gates as executable hooks, not prose | violations are **blocked**, not suggested |
+| Agent starts every session amnesiac | 4-tier memory with semantic recall + write-gates | It remembers your codebase and past decisions |
+| Tool output floods the context window | MCP Router — tool-hiding + output compression | Up to **~98%** smaller on big tool calls |
+| "Looks right" but doesn't run | `uap deliver` — a loop against your **real** gates | Code that compiles, not a mock-up of it |
+| Agent grades its own homework | Execution/runtime verify + a separate acceptance judge | "Done" means *verified* done |
+| Two agents clobber each other | Worktree isolation + live file coordination | Conflict-free parallel work |
+| "Guidelines" get ignored | Policy gates as executable hooks, not prose | Violations are **blocked**, not politely suggested |
+| Same mistake, every session | Memory promotion + pattern learning | The floor gets better every run |
 
-> Benchmarks below are from Terminal-Bench 2.0 (12 representative tasks). See [docs/benchmarks/](docs/benchmarks/) for the full methodology and raw data.
+**→ Take the full station-by-station tour: [The UAP Delivery Pipeline](docs/guides/DELIVERY_PIPELINE.md).**
 
 ---
 
@@ -41,12 +43,12 @@ AI coding agents are capable but undisciplined. They forget everything between s
 # Install globally
 npm install -g @miller-tech/uap
 
-# One-command setup in your project (memory, patterns, hooks, policies)
+# One friendly, arrow-key guided setup in your project
 cd your-project
 uap setup
 ```
 
-That's it. Your agent now has persistent memory, battle-tested patterns, policy gates, and multi-agent coordination wired into every session.
+`uap setup` walks you through the whole line — memory, patterns, policy gates, model routing, multi-agent coordination, and the verification gates — and wires it into every agent session. Take the defaults and you're one Enter away from a disciplined agent.
 
 ```bash
 uap memory query "how did we handle auth last time?"   # semantic recall
@@ -58,7 +60,7 @@ uap dashboard overview                                  # live task / agent / me
 
 ## The `deliver` harness
 
-`uap deliver` is the headline of the v1.27–v1.40 line: a **convergence loop that iterates a model against your project's real completion gates until the work is actually delivered** — build passes, tests pass, lint is clean — not until the model *thinks* it's done.
+The two stations that matter most are **Build** and **QC**, and `uap deliver` owns both. It's a **convergence loop that iterates a model against your project's real completion gates until the work is actually delivered** — build passes, tests pass, lint is clean — not until the model *thinks* it's done.
 
 ```bash
 uap deliver "implement the password reset flow"
@@ -66,36 +68,36 @@ uap deliver "implement the password reset flow"
 
 What happens under the hood:
 
-1. **Explore → plan → apply** — the model proposes changes; the applier writes them safely (pre-existing tests and gate configs are protected from being overwritten).
-2. **Verify against real gates** — a verifier ladder runs your build, tests, and lint. Nothing is "done" until they're green.
-3. **Critique & iterate** — failures feed back as structured guidance; the loop continues, **persisting until delivered** (extends past `--max-turns` to a ceiling, stopping on genuine stagnation).
-4. **Auto-optimization** — every task is classified by complexity and the matching aids (HALO trace analysis, divergent ideation, coordination, deploy batching) activate automatically.
+1. **Explore → plan → apply** — the model proposes changes; the applier writes them safely (existing tests and gate configs are protected from being overwritten).
+2. **Verify against real gates** — a verifier ladder runs your build, tests, and lint, and can *execute* the result (headless browser / vm-dom / child process) to prove it runs. Nothing is "done" until they're green.
+3. **Critique & iterate** — failures feed back as structured guidance and the loop continues, persisting until delivered.
+4. **Generator ≠ evaluator** — the check that signs off is deliberately not the model that wrote the code, so an agent can't confirm its own success.
 5. **Autonomy with a guidance channel** — runs the full mission without stopping to ask, while still accepting operator guidance mid-flight.
 
 It works with frontier models *and* local models (llama.cpp / Qwen) served over the Anthropic Messages API. See **[docs/guides/DELIVER.md](docs/guides/DELIVER.md)**.
 
 ---
 
-## Features
+## The line, station by station
 
-- **🧠 4-tier memory** — daily log → working cache → semantic (Qdrant) → long-term archive, with write-gates that block low-quality/duplicate memories and corrections that cascade across tiers.
-- **🗜️ MCP Router** — a token-optimizing tool proxy; large outputs are compressed via FTS5 intent search instead of dumped into context.
-- **🎯 `uap deliver`** — the convergence/delivery harness (above).
-- **🌳 Worktree workflow** — isolated branch-per-feature, auto-PR, safe cleanup; enforced so agents never edit the project root.
-- **🛡️ Policy gates** — 20 executable enforcers (worktree, test, schema-diff, expert-review, memory-before-plan, delivery-enforcement…) that *block* non-compliant tool calls.
-- **🤖 Expert droids & skills** — 38 specialized droids and 32 skills, with an expert-router that recommends a droid chain per task.
-- **🧭 Multi-model routing** — 7 profiles (Claude Opus/Sonnet/Haiku, GPT, Qwen, generic); the router picks by complexity, cost, and performance.
-- **🚦 Deploy batching & coordination** — batched git/deploy actions and overlap detection keep multi-agent work conflict-free.
-- **📊 Dashboard** — rich TUI/web views of tasks, agents, memory, benchmarks, and policy status.
-- **🔌 9 harnesses** — Claude Code, Factory, Cursor, VSCode, OpenCode, Codex, ForgeCode, Oh-My-Pi, Hermes.
+| Station | The break it prevents | Key machinery |
+|---|---|---|
+| **Intake** | Amnesiac sessions, invented scope | [Memory](docs/guides/MEMORY.md), reactor injection, [DESIGN.md](DESIGN.md) |
+| **Prep / routing** | Wrong approach, wrong-sized model | [Multi-model routing](docs/guides/MULTI_MODEL.md), [patterns](docs/reference/PATTERNS.md), [droids & skills](docs/guides/DROIDS_AND_SKILLS.md) |
+| **Isolation** | Editing `main`, clobbering files | [Worktrees](docs/guides/WORKTREE_WORKFLOW.md), live file coordination, delivery gate |
+| **Build** | Plausible-but-wrong code, stubs, empty output | [`uap deliver`](docs/guides/DELIVER.md), serving-layer recipes, [local-model guardrails](docs/guides/LOCAL_MODELS.md) |
+| **QC / verify** | "Done" on code that never ran | Completion gates, `uap verify`, acceptance judge, generator≠evaluator |
+| **Coordination** | Parallel agents colliding/deadlocking | [Coordination](docs/guides/COORDINATION.md), model-slot concurrency, [deploy batching](docs/guides/DEPLOY_BATCHING.md) |
+| **Shipping** | Regressions, red CI, skipped version bumps | Worktree→PR flow, version gates, CI feedback watcher |
+| **Feedback** | The same mistake every session | Memory promotion, pattern learning, session analysis |
 
-Full list with code-level detail: **[docs/reference/FEATURES.md](docs/reference/FEATURES.md)**.
+Running the whole length of the floor: **policy gates** (24 executable enforcers that *block* non-compliant tool calls — worktree, test, schema-diff, expert-review, delivery-enforcement…) and the **MCP Router** (keeps the context window lean). Full catalog: **[docs/reference/FEATURES.md](docs/reference/FEATURES.md)**.
 
 ---
 
 ## Architecture
 
-UAP installs hooks into your agent harness, then mediates every tool call through memory, policy, and token-optimization layers.
+UAP installs hooks into your agent harness, then mediates every tool call through the memory, policy, and token-optimization layers — a control booth over the whole line.
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
@@ -106,32 +108,29 @@ UAP installs hooks into your agent harness, then mediates every tool call throug
                             ▼
 ┌─────────────────────────────────────────────────────────────┐
 │                       UAP CLI (uap)                         │
-│  setup · memory · deliver · worktree · policy · deploy      │
-│  task · droids · model · mcp-router · harness · ideate …    │
+│  setup · memory · deliver · verify · worktree · policy      │
+│  task · coord · droids · model · mcp-router · design …      │
 └──┬─────────┬──────────┬──────────┬──────────┬───────────────┘
    ▼         ▼          ▼          ▼          ▼
  Memory   Policy    MCP Router   Delivery   Coordination
- 4 tiers  20 gates  FTS5 compr.  harness    + deploy batch
+ 4 tiers  24 gates  compression  + verify   + deploy batch
 ```
 
-- **30+ CLI commands** across 18 source subsystems (168 TypeScript modules).
+- **30+ CLI commands** across 18 source subsystems (220+ TypeScript modules).
 - Deep dive: **[docs/architecture/OVERVIEW.md](docs/architecture/OVERVIEW.md)** · protocol spec: **[docs/architecture/PROTOCOL.md](docs/architecture/PROTOCOL.md)**.
 
 ---
 
 ## Benchmarks
 
-The honest, controlled result (paired A/B — same model, tasks, and seeds,
-toggling only UAP, with confidence intervals): **UAP's accuracy lift depends on
-whether the base agent already self-verifies.**
+The honest, controlled result (paired A/B — same model, tasks, and seeds, toggling only UAP, with confidence intervals): **UAP's accuracy lift depends on whether the base agent already checks its own work at the QC station.**
 
 | Baseline | UAP accuracy lift | |
 |---|---|---|
 | Agentic harness (self-tests) | **~0pp** (CI spans 0) | overhead only — value is efficiency/coordination |
 | Non-agentic single-shot model | **+20pp** (78%→98%, 95% CI [+8,+32], p=0.008) | gate loop repairs edge-case bugs |
 
-Run it yourself: `uap bench paired --adapter raw --suite benchmarks/suites/real-gate-gated`.
-Full analysis: **[docs/benchmarks/PAIRED_FINDINGS.md](docs/benchmarks/PAIRED_FINDINGS.md)**.
+That's the pipeline thesis in one table: the more an agent skips the QC station on its own, the more UAP's gates are worth. Run it yourself: `uap bench paired --adapter raw --suite benchmarks/suites/real-gate-gated`. Full analysis: **[docs/benchmarks/PAIRED_FINDINGS.md](docs/benchmarks/PAIRED_FINDINGS.md)**.
 
 <details><summary>Earlier uncontrolled Terminal-Bench numbers (confounded — see TBench Investigation)</summary>
 
@@ -150,6 +149,8 @@ Methodology, raw runs, and cost analysis: **[docs/benchmarks/](docs/benchmarks/)
 
 ## Supported harnesses
 
+Same line, whichever floor you code on.
+
 | Harness | Hooks | MCP Router | Policy gates |
 |---|---|---|---|
 | Claude Code | ✅ | ✅ | ✅ |
@@ -170,6 +171,7 @@ Install into all detected harnesses with `uap hooks install`; audit coverage wit
 
 | | |
 |---|---|
+| **[The Delivery Pipeline](docs/guides/DELIVERY_PIPELINE.md)** | The station-by-station tour — start here for the big picture |
 | **[Getting Started](docs/getting-started/)** | Installation, quickstart, configuration |
 | **[Guides](docs/guides/)** | deliver, memory, MCP router, worktrees, policies, multi-model, local models |
 | **[Architecture](docs/architecture/)** | System overview + the UAP protocol |
@@ -186,7 +188,7 @@ Start at the **[documentation index](docs/INDEX.md)**.
 ```bash
 npm install
 npm run build      # TypeScript compile
-npm test           # vitest — 117 suites
+npm test           # vitest — 170+ suites
 npm run bench      # benchmark suite
 ```
 

package/docs/INDEX.md

@@ -1,8 +1,28 @@
 # UAP Documentation
 
-The complete documentation for the **Universal Agent Protocol** (`@miller-tech/uap` v1.50.0) — a layer that gives AI coding agents memory, judgment, and the discipline to finish the job.
+The complete documentation for the **Universal Agent Protocol** (`@miller-tech/uap` v1.93.1) — the discipline layer that turns a talented-but-unreliable AI coding agent into a dependable member of your software delivery line.
 
-New here? Start with the [project README](../README.md), then [Getting Started](getting-started/).
+New here? The friendliest way in is the **[Delivery Pipeline tour](guides/DELIVERY_PIPELINE.md)** — it walks the whole factory floor, station by station, showing where agents normally break and what UAP puts in place to catch it. Then grab the [Quickstart](getting-started/QUICKSTART.md).
+
+---
+
+## Find your way by station
+
+UAP is organized like a delivery line. If you know which part of the pipeline you're trying to fix, start here:
+
+| Station | The break it prevents | Start with |
+|---|---|---|
+| **Intake** — understand the work | Amnesiac sessions, invented scope | [Memory](guides/MEMORY.md) · [Reactor](design/UAP_REACTOR.md) |
+| **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) |
+| **QC / verify** — prove it runs | "Done" on code that never ran | [`uap deliver`](guides/DELIVER.md) · [Policies](guides/POLICIES.md) |
+| **Coordination** — many workers, one floor | Parallel agents colliding | [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) |
+| *Cross-cutting* — the whole line | Ignored rules, bloated context | [Policies](guides/POLICIES.md) · [MCP Router](guides/MCP_ROUTER.md) |
+
+Full map: **[The UAP Delivery Pipeline](guides/DELIVERY_PIPELINE.md)**.
 
 ---
 
@@ -12,14 +32,15 @@ New here? Start with the [project README](../README.md), then [Getting Started](
 |---|---|
 | [Installation](getting-started/INSTALLATION.md) | Prerequisites, `npm install -g @miller-tech/uap`, what `uap setup` does, per-harness hook install |
 | [Quickstart](getting-started/QUICKSTART.md) | 5-minute path: setup → memory → `uap deliver` → dashboard |
-| [Configuration](getting-started/CONFIGURATION.md) | `.uap.json`, environment variables, Qdrant, model profiles |
+| [Configuration](getting-started/CONFIGURATION.md) | `.uap.json`, environment variables, `.uap/proxy.env`, Qdrant, model profiles |
 
 ## Guides
 
 | Doc | What it covers |
 |---|---|
+| [**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 ⭐ |
-| [**`uap deliver`**](guides/DELIVER.md) | The delivery harness — convergence loop to verified completion, with tiered gates (fast → integration → deploy-dev) and a CI/deploy feedback loop ⭐ |
+| [**`uap deliver`**](guides/DELIVER.md) | The Build+QC harness — convergence loop to verified completion, tiered gates, CI/deploy feedback loop ⭐ |
 | [Memory](guides/MEMORY.md) | The 4-tier memory system, write-gates, semantic recall |
 | [MCP Router](guides/MCP_ROUTER.md) | Token-optimizing tool proxy + FTS5 output compression |
 | [Worktree Workflow](guides/WORKTREE_WORKFLOW.md) | Branch-per-feature isolation, auto-PR, enforcement |
@@ -35,10 +56,10 @@ New here? Start with the [project README](../README.md), then [Getting Started](
 
 | Doc | What it covers |
 |---|---|
-| [Overview](architecture/OVERVIEW.md) | System architecture, subsystems, tool-call flow |
+| [Overview](architecture/OVERVIEW.md) | System architecture as the delivery-line floor plan; subsystems, tool-call flow |
 | [Protocol](architecture/PROTOCOL.md) | The harness↔UAP contract, hook lifecycle, decision loop |
 | [Reactor (auto-apply)](design/UAP_REACTOR.md) | Dynamic experts/skills/patterns injected per prompt across harnesses; the assist vs enforce model, per-harness wiring |
-| [Self-Harness (proposal)](design/SELF_HARNESS.md) | Self-improving harness: autonomous mine→propose→validate loop over a bounded Mod DSL (scaffold/proxy-knob/middleware), cross-model transfer, online mining; grounds arXiv:2606.09498 in UAP's HALO + paired-bench |
+| [Self-Harness (proposal)](design/SELF_HARNESS.md) | Self-improving harness: autonomous mine→propose→validate loop over a bounded Mod DSL; cross-model transfer, online mining |
 
 ## Reference
 
@@ -46,7 +67,7 @@ New here? Start with the [project README](../README.md), then [Getting Started](
 |---|---|
 | [CLI](reference/CLI.md) | Every `uap` command and flag |
 | [API](reference/API.md) | Programmatic API surface |
-| [Features](reference/FEATURES.md) | Full feature catalog by subsystem |
+| [Features](reference/FEATURES.md) | Full feature catalog, mapped to the pipeline stages |
 | [Patterns](reference/PATTERNS.md) | The 23 Terminal-Bench patterns |
 | [Platforms](reference/PLATFORMS.md) | The 9 supported harnesses + support matrix |
 | [Configuration](reference/CONFIGURATION.md) | All config files and env vars |

package/docs/architecture/OVERVIEW.md

@@ -1,6 +1,21 @@
 # UAP Architecture Overview
 
-`v1.40.0` · 168 TypeScript modules across 18 `src/` subsystems · 117 test suites
+`v1.93.1` · 223 TypeScript modules across 18 `src/` subsystems · 170+ test suites
+
+> **🏭 Where this fits:** Whole pipeline — this is the factory-floor map. A bare
+> agent walks work from an idea to a shipped change with no stations in between,
+> so it forgets context, edits the wrong branch, writes plausible-but-broken
+> code, declares "done" on a red build, and repeats the mistake next session.
+> **What it delivers:** a station at every stage where an agentic workflow
+> normally breaks, so your agent's output comes off the line understood,
+> isolated, built, verified, coordinated, shipped, and remembered.
+
+Think of UAP as the **software-delivery pipeline** your agent runs on — a
+sausage-factory floor where each station guards one stage of turning an
+instruction into a merged, working change. The stations are UAP's subsystems.
+This document is the floor plan: what each station is, and which break it
+prevents. For the end-to-end walkthrough, see the
+[delivery pipeline guide](../guides/DELIVERY_PIPELINE.md).
 
 The Universal Agent Protocol (UAP) is a layer that sits **underneath** an AI
 coding agent's harness — Claude Code, Factory, Cursor, OpenCode, Codex, and
@@ -16,11 +31,36 @@ harness↔UAP contract, see [PROTOCOL.md](PROTOCOL.md).
 
 ---
 
+## The pipeline at a glance
+
+Every station below maps to a stage where a normal agentic workflow breaks, and
+to the subsystem that guards it. Read this as the conveyor belt your work rides:
+
+| Stage | What breaks without a station | Station (subsystem) |
+|-------|-------------------------------|---------------------|
+| **1. Intake** — understand the work | agent forgets past sessions, hallucinates scope | 4-tier **memory**, **reactor** per-prompt injection, DESIGN.md |
+| **2. Prep / routing** — pick the approach | wrong model, wrong tactic | pattern router, query-complexity, **multi-model routing**, recipe selection |
+| **3. Isolation** — protect the tree | agent edits `master`, clobbers files, collides | **worktree**-per-feature, **file coordination**, delivery gate |
+| **4. Build** — write the code | plausible-but-wrong code, stubs, empty/looping local-model output | **deliver** loop, serving-layer recipes, proxy guardrails, local-model handling |
+| **5. QC / verify** — prove it works | *the big one:* agent says "done" on broken code and self-grades wrong | **completion gates**, execution/runtime verify, **acceptance judge**, generator≠evaluator, tiered gates |
+| **6. Line coordination** — many hands | parallel agents collide, duplicate, deadlock | **coordination DB**, collaboration board + challenge, model-slot concurrency, deploy batching |
+| **7. Shipping** — merge & release | regressions, broken CI, skipped version bumps | worktree→PR flow, version/completion gates, CI feedback watcher, never-regress, git-safety |
+| **8. Feedback** — learn from it | same mistake every session | **memory promotion**, pattern RL, session analysis |
+
+Cross-cutting through every station: **policy gates** are the executable rules
+posted at each station, the **MCP Router** keeps the context lean so the belt
+never jams, and UAP runs across **9 harnesses** so the same floor plan applies
+wherever your agent works.
+
+---
+
 ## The hook-mediation model
 
 A bare agent harness calls a tool (Edit, Write, Bash, a spawned sub-agent, an
 MCP tool) and the model sees the raw result. UAP inserts itself between the
-harness and the tool by registering hooks at the harness's interception points:
+harness and the tool by registering hooks at the harness's interception points —
+this is how every station gets a chance to inspect the work before it moves down
+the line:
 
 - **Claude Code / VSCode / Factory / Cursor** — `PreToolUse` hooks
 - **OpenCode** — the `tool.execute.before` plugin hook
@@ -93,9 +133,14 @@ src/
 
 ---
 
-## Subsystems
+## Subsystems (station by station)
 
-### Memory (`src/memory/`)
+### Memory (`src/memory/`) — Intake & Feedback stations
+
+**The break it prevents:** at intake, a fresh agent has amnesia — it re-litigates
+solved problems and hallucinates scope. At feedback, it drops the lesson it just
+learned and repeats the mistake tomorrow. Memory is the station that carries
+context onto the belt and carries lessons back off it.
 
 A four-tier memory system that gives the agent persistent context across
 sessions. The tiers (`src/memory/README.md`):
@@ -124,7 +169,9 @@ Key modules:
 - `memory-consolidator.ts` — summarizes working entries into session memory,
   extracts lessons, and dedups by content hash + embedding similarity.
 - `write-gate.ts` — a quality filter that scores candidate memories and only
-  persists those above threshold (prevents memory pollution).
+  persists those above threshold (prevents memory pollution). This is the
+  feedback station's own gate: only lessons that change future behavior get
+  promoted.
 - `knowledge-graph.ts` — the L4 graph: upsert entities, strengthen
   relationships, recursive-CTE traversal.
 - `context-compressor.ts` / `semantic-compression.ts` — token budgeting and
@@ -135,7 +182,11 @@ Key modules:
 - `model-router.ts` — benchmark-fingerprint LLM routing with feedback learning
   (consumed by `src/models/unified-router.ts`).
 
-### MCP Router (`src/mcp-router/`)
+### MCP Router (`src/mcp-router/`) — cross-cutting: keep the belt from jamming
+
+**The break it prevents:** a context window flooded with tool schemas and raw
+tool output stalls every station downstream. The router keeps context lean so
+work keeps moving.
 
 A hierarchical Model Context Protocol router that achieves large token savings
 by two independent mechanisms (`src/mcp-router/server.ts`,
@@ -158,7 +209,12 @@ The design target documented in source is ~75,000 tokens of tool definitions
 collapsed to ~700 (98%+). Per-output FTS5 savings are computed live per call.
 See [../integrations/MCP_ROUTER.md](../integrations/MCP_ROUTER.md) for setup.
 
-### Policies (`src/policies/`)
+### Policies (`src/policies/`) — cross-cutting: the rules posted at every station
+
+**The break it prevents:** rules that live in a README are advisory and get
+skipped under pressure. Policies are the executable rules bolted to each
+station — worktree, task, delivery, tests, review — so a violation stops the
+belt instead of sliding through.
 
 Project guidelines expressed as **executable hook gates** rather than prose.
 Two layers:
@@ -179,14 +235,23 @@ Enforcers cover the worktree gate (`worktree_required.py`), task discipline
 (`schema_diff_gate.py`), memory-before-plan, MCP-router-first, RTK wrapping, and
 more. Levels: **REQUIRED** blocks, **RECOMMENDED** logs, **OPTIONAL** informs.
 
-### Delivery — `uap deliver` (`src/delivery/`)
+### Delivery — `uap deliver` (`src/delivery/`) — Build & QC stations
+
+**The break it prevents:** this is the heart of the floor. Left alone, an agent
+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
 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.
 
-### Coordination (`src/coordination/`)
+### Coordination (`src/coordination/`) — Isolation & Line-coordination stations
+
+**The break it prevents:** put two agents on one repo and they edit the same
+file, duplicate work, or deadlock. This station gives every agent its own lane,
+announces who's touching what, and blocks live same-file collisions.
 
 Lets multiple agents work the same repo without colliding. A singleton SQLite
 DB (`database.ts`) backs an agent registry, work announcements, work claims,
@@ -208,7 +273,11 @@ droids from `capability-router.ts`. `pattern-router.ts` matches tasks to
 Terminal-Bench patterns (always enforcing **P12** Output Existence and
 **P35** Decoder-First).
 
-### Models (`src/models/`)
+### Models (`src/models/`) — Prep / routing station
+
+**The break it prevents:** an agent that reaches for the same model on every task
+either overpays for trivial edits or under-powers a hard migration. This station
+picks the right approach and model before the work hits the belt.
 
 Multi-model routing. `router.ts` classifies a task (complexity + type from
 keyword scoring) and `selectModel()` picks a model per the routing strategy —
@@ -221,7 +290,12 @@ model per subtask; `executor.ts` runs the plan level-by-level with retries and
 fallback; `execution-profiles.ts` tunes *how* the chosen model runs
 (temperature, budgets); `analytics.ts` records outcomes so routing improves.
 
-### Tasks (`src/tasks/`)
+### Tasks (`src/tasks/`) — Prep / routing & Line-coordination stations
+
+**The break it prevents:** work without a tracked task drifts scope, races other
+agents on the same files, and starts before its prerequisites are ready. This
+station gates each task through a decoder-first check and hands claims to the
+coordination lane.
 
 A dependency-aware task tracker (a Beads alternative) backed by SQLite
 (`tasks`, `task_dependencies`, `task_history`, `task_activity`,
@@ -232,18 +306,29 @@ release with overlap detection); `decoder-gate.ts` implements the P35
 Decoder-First pre-execution validator (droid schema, tool availability,
 claim conflicts, worktree requirement, ambiguity).
 
-### Dashboard (`src/dashboard/`)
+### Dashboard (`src/dashboard/`) — floor visibility
+
+**The break it prevents:** a floor you can't see is a floor you can't trust. This
+gives you a live view of every station.
 
 A live visualization layer (`uap dashboard`) over tasks, agents, memory,
 policies, models, and benchmark/session history, with an event stream for
 real-time updates.
 
-### Observability (`src/observability/`)
+### Observability (`src/observability/`) — Feedback station
+
+**The break it prevents:** without traces you can't tell *why* a run failed, so
+the floor never improves. This station records what really happened so the
+pipeline can be tuned.
 
 Emits HALO / OpenInference spans for delivery runs and tool calls, consumed by
 `uap harness analyze` to optimize agent execution from real traces.
 
-### Benchmark harness (`src/benchmarks/paired/`)
+### Benchmark harness (`src/benchmarks/paired/`) — measuring the floor
+
+**The break it prevents:** claims that a station helps are worthless without a
+controlled measurement. This harness toggles only the UAP scaffold and reports
+the honest delta.
 
 A controlled paired-A/B harness (`uap bench paired`) for measuring UAP's impact
 without confounds. It holds the base model + agent constant and toggles **only**
@@ -261,7 +346,8 @@ is **+20pp** over a non-agentic baseline and **~0pp** over an agentic one.
 
 ## How a tool call flows: memory → policy → MCP Router
 
-For a representative `execute_tool` call routed through the UAP MCP server:
+This is one item riding the belt through the mediation stations. For a
+representative `execute_tool` call routed through the UAP MCP server:
 
 ```
 1. Tool call arrives at the PreToolUse hook.
@@ -294,8 +380,10 @@ decision loop defined normatively in [PROTOCOL.md](PROTOCOL.md#agent-decision-lo
 
 ## How `uap deliver` orchestrates
 
-`uap deliver "<instruction>"` runs `ConvergenceLoop.deliver()`
-(`src/delivery/convergence-loop.ts`). The staged flow:
+This is the Build/QC station's inner mechanism — the part that refuses to pass
+work down the line until it actually runs green. `uap deliver "<instruction>"`
+runs `ConvergenceLoop.deliver()` (`src/delivery/convergence-loop.ts`). The
+staged flow:
 
 ```
 detect gates ──▶ baseline check ──▶ protect files ──▶ ╔═════ turn loop ═════╗
@@ -344,6 +432,7 @@ ceiling (default 30, hard cap 50), and stops once progress stalls.
 ## See also
 
 - [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,13 @@
 # The UAP Protocol
 
-`v1.40.0`
+`v1.93.1`
+
+> **🏭 Where this fits:** Cross-cutting (the factory rulebook) — with no shared
+> contract, each station's rules are guesswork and your agent slips broken work
+> past whichever gate it doesn't recognize. **What it delivers:** the normative
+> hook-and-gate contract that makes every station on the
+> [delivery pipeline](../guides/DELIVERY_PIPELINE.md) enforceable and portable —
+> the same rules apply whichever harness runs the line.
 
 This document specifies the **Universal Agent Protocol** itself: the contract
 between an AI agent harness and the UAP layer beneath it. It is normative —
@@ -13,6 +20,12 @@ set of interception points the harness exposes, a defined hook lifecycle, an
 agent decision loop, and a set of gates that block work which violates the
 contract. Any harness that can run a hook before tool execution can host UAP.
 
+Read the sections below as the rules posted at each station on the floor:
+session start feeds the **intake** station, the pre-tool-use gates guard
+**isolation** and **build**, the decision loop threads **intake → build →
+feedback**, the worktree convention is the **isolation** station itself, and the
+completion gates are the **QC/verify** station that stops "done"-on-broken-code.
+
 ---
 
 ## 1. The harness ↔ UAP contract
@@ -55,7 +68,8 @@ Hook scripts are generated and installed by `uap hooks install`
 
 ### 2.1 Session start
 
-On session start the harness runs the session-start hook, which MUST:
+The **intake station.** On session start the harness runs the session-start
+hook, which MUST:
 
 1. **Inject memory.** Query the short-term store (last-24h top memories plus
    open "session" loops of type action/goal/decision with importance ≥ 7) and
@@ -70,8 +84,8 @@ context, not a gate.
 
 ### 2.2 Pre-tool-use
 
-Before each tool call the harness runs the pre-tool-use hook, which runs the
-relevant gates for that tool. Conceptually:
+The **isolation and build gates.** Before each tool call the harness runs the
+pre-tool-use hook, which runs the relevant gates for that tool. Conceptually:
 
 ```
 pre-tool-use(tool, args):
@@ -96,9 +110,10 @@ across context compaction; the stop hook runs a completion checklist.
 
 ## 3. Agent decision loop
 
-A conforming agent SHOULD execute each task through this loop. The TypeScript
-implementation lives in `src/memory/dynamic-retrieval.ts` (query) and the
-short-term store / consolidator (record, promote).
+The belt path itself: intake pulls context in, act builds, and feedback carries
+lessons back out. A conforming agent SHOULD execute each task through this loop.
+The TypeScript implementation lives in `src/memory/dynamic-retrieval.ts` (query)
+and the short-term store / consolidator (record, promote).
 
 ```
         ┌──────────────────────────────────────────────┐
@@ -131,9 +146,10 @@ transient debugging state, and secrets MUST NOT be promoted.
 
 ## 4. Worktree convention
 
-All file edits MUST happen inside a git worktree under `.worktrees/NNN-<slug>/`.
-Edits to the project root are blocked by the worktree gate
-(`worktree_required.py`).
+The **isolation station.** All file edits MUST happen inside a git worktree
+under `.worktrees/NNN-<slug>/`. Edits to the project root are blocked by the
+worktree gate (`worktree_required.py`) — this is what keeps your agent off
+`master` and out of another agent's lane.
 
 ```bash
 uap worktree ensure --strict     # verify you are inside a worktree (exit 0)
@@ -158,9 +174,11 @@ Rules:
 
 ## 5. Completion gates
 
-Claiming a code change is DONE is prohibited until all gates pass. The gates are
-decomposed across policy enforcers and the `review`-stage policy logic in
-`policy-gate.ts` (auto-forced on completion / merge / deploy operations):
+The **QC/verify station — the one everyone skips.** Claiming a code change is
+DONE is prohibited until all gates pass; this is where "the agent said done on a
+red build" gets caught. The gates are decomposed across policy enforcers and the
+`review`-stage policy logic in `policy-gate.ts` (auto-forced on completion /
+merge / deploy operations):
 
 | Gate | Enforcer / mechanism | Requirement |
 |------|----------------------|-------------|

package/docs/design/SELF_HARNESS.md

@@ -7,6 +7,14 @@
 > (Weakness Mining → Harness Proposal → Proposal Validation), no human engineer. Reports
 > Terminal-Bench-2.0 lifts incl. **Qwen3.5-35B-A3B 23.8%→38.1%** (our model's sibling).
 
+> **🏭 Where this fits:** Feedback station (the floor tunes its own machines) —
+> without it, the same failure mode recurs every run and a human has to hand-tune
+> the harness for each new model, which doesn't scale. **What it delivers:** an
+> autonomous loop that mines real failure traces, proposes bounded harness fixes,
+> validates them against real gates, and keeps only the winners — so the whole
+> [delivery pipeline](../guides/DELIVERY_PIPELINE.md) gets better at building the
+> next change instead of repeating the last mistake.
+
 ## 1. Why this, why now
 
 The paper's thesis is exactly the lesson of our manual harness-tuning campaign on Qwen3.6-35B-A3B: