@miller-tech/uap 1.222.0 → 2.0.0

package/docs/plans/qwen38-uap-retest-plan.md

@@ -0,0 +1,196 @@
+# Qwen3.8-27B — With-UAP vs Without-UAP Comparison Plan (UAP v1.224.x)
+
+**Status:** Proposed (no benchmark runs start without an explicit go)
+**Date:** 2026-09-02
+**Supersedes:** nothing — extends [PAIRED_FINDINGS.md](../benchmarks/PAIRED_FINDINGS.md) to the current model and current UAP
+
+## Goal
+
+Run the **same Qwen3.8-27B model, same tasks, same seeds, twice — once with
+UAP, once without** — and quantify the difference. The model under test is the
+current production local stack: **Qwen3.8-27B (dense, UD-IQ4_XS, native
+draft-mtp)** on llama.cpp, and the UAP under test is the **latest (v1.224.x)**.
+
+Every experiment below produces one headline number: the **paired delta
+(UAP-on minus UAP-off)** for accuracy, with the cost side of the ledger
+(tokens, turns, latency) reported alongside it. Two questions the existing
+findings cannot answer:
+
+1. **Replication:** does the decisive non-agentic gate-loop result — **+20pp
+   accuracy [95% CI +8, +32], p=0.008**, measured on qwen36-35b-a3b — hold on
+   this denser, stronger 27B model, or was it partly a property of the older
+   MoE?
+2. **Regression check:** the findings predate the two biggest recent ships —
+   the quality-metrics gate (v1.223.0) and the deliver-pipeline hardening
+   (v1.224.0: scoped rollback, declared gates, polyglot execution, config
+   routing, liveness, signed overrides). The paired harness's gate loop is the
+   `uap deliver` mechanism in miniature; confirm the hardened pipeline did not
+   regress the measured lift or its token economics.
+
+## Why now
+
+- **Model changed under the findings.** Production serving switched
+  2026-08-20 from qwen36-35b-a3b (MoE, ~3B active) to Qwen3.8-27B (dense,
+  qwen35-arch, native MTP head, 60–91% draft acceptance) — profile
+  `config/llama-profiles/qwen38-27b-mtp.env`, served as alias `Qwen3.8-27B`
+  on `:8080` (legacy aliases retained, so old client configs still resolve).
+- **UAP changed under the findings.** The paired runs are from the v1.21x era;
+  the deliver loop they exercise has since been substantially hardened.
+- **Newer suites exist that were not in the findings.** `real-gate-medium`,
+  `real-gate-power`, `real-gate-brutal`, and `real-gate-heldout` directly
+  address the findings' own ceiling-effect caveat (agentic baseline pinned at
+  100% on the older suites, so UAP showed 0pp there).
+
+## Stack preflight (Phase 0 — before any measurement)
+
+1. Bring up / verify the serving stack:
+   `scripts/bootstrap/bootstrap-uap-llama-proxy-stack.sh` (llama-server
+   `:8080` + anthropic proxy `:4100`). Server is currently live with
+   `Qwen3.8-27B` loaded (131072 ctx/slot, 2 slots); the proxy did not answer
+   `/v1/models` at plan time — confirm it is up and routing.
+2. Confirm tool-call plumbing: `uap tool-calls status` (qwen-sharp.jinja
+   active, `--jinja` on).
+3. Freeze the served model id used by every run (`Qwen3.8-27B` or the proxy's
+   advertised id — verify once via `/props`, then hold it fixed across all
+   arms and phases so the paired design is not contaminated by an alias swap).
+4. Plumbing check with the deterministic mock adapter:
+   `uap bench paired --suite benchmarks/suites/smoke --adapter mock --epochs 8`.
+5. Concurrency discipline: the box is a single RTX 3090 with **2 server
+   slots** — run the harness at `--concurrency 2` max and keep
+   `PROXY_CONCURRENCY_LIMIT` == slot count. Latency numbers remain
+   queue-confounded (known caveat from the prior findings); we read
+   correctness and token deltas, not wall-clock.
+
+## Experimental design — the two arms
+
+Every run pair toggles **only** the UAP surface. Model (`Qwen3.8-27B`),
+serving stack, task fixture, seed, and prompt are identical in both arms.
+
+| | **WITHOUT UAP** (baseline arm) | **WITH UAP** (treatment arm) |
+|---|---|---|
+| Raw (non-agentic) experiments | One raw completion endpoint call; whatever the model writes is final | The UAP gate loop (the `uap deliver` mechanism in miniature): execute → run the visible in-repo gate → feed failures back → regenerate until green |
+| Agentic experiments (opencode adapter) | Bare opencode on the same model and prompt, no UAP files injected | Identical opencode run plus the paired-harness UAP surface: `AGENTS.md` operating protocol, `.uap-bench.json` manifest, `UAP_BENCH_COMPONENTS` env — the inspectable, diffable "treatment" |
+| Deliver-path spot check (E4) | Model without the deliver pipeline | The actual hardened v1.224.0 `uap deliver` surface: scoped rollback, declared gates, liveness |
+
+What "the difference" means, precisely, per run:
+
+- **Accuracy Δ** — UAP-on success rate minus UAP-off success rate, with a
+  bootstrap 95% CI and permutation p-value; McNemar 2×2 ("UAP fixed" vs
+  "UAP regressed") on discordant pairs.
+- **Cost Δ** — paired deltas for tokens, turns, tool-calls, latency. A win is
+  higher accuracy at acceptable cost, or equal accuracy at lower cost.
+- **Ablation (E2)** — the WITH-UAP arm decomposed: leave-one-out per
+  component (gates / worktree / memory / experts / skills / patterns) so we
+  can see which parts of UAP earn their token overhead on this model.
+
+All scoring is deterministic `verifyCmd` (no LLM judge). Artifacts land in
+`benchmark-results/paired-qwen38-*`. Statistics per the established format:
+bootstrap 95% CI (10k seeded resamples) + sign-flip permutation p.
+
+## Experiments
+
+| # | Question | Suite | Adapter | WITHOUT UAP | WITH UAP |
+|---|---|---|---|---|---|
+| E1 | Does the gate loop still rescue one-shot failures? | `real-gate-gated` × 10 epochs | raw | single-shot | gate loop |
+| E2 | Does UAP cost or add anything on a self-verifying agent? | `real-gate-hard` × 4 epochs | opencode | bare opencode | opencode + UAP surface (+ per-component ablation) |
+| E3 | Is there headroom for UAP lift on harder/held-out tasks? | `real-gate-heldout`, `-power`, `-medium`, `-brutal` | raw + opencode | both baselines | both treatments |
+| E4 | Does the hardened v1.224.0 deliver path converge as well as the miniature? | `real-gate-gated` subset | raw → deliver | no deliver | full deliver surface |
+
+### E1 — Headline replication (raw adapter, non-agentic gate value)
+
+```bash
+UAP_RAW_TEMPERATURE=0.6 uap bench paired \
+  --adapter raw --model "Qwen3.8-27B" \
+  --suite benchmarks/suites/real-gate-gated \
+  --epochs 10 --concurrency 2
+```
+
+Identical design to the decisive qwen36 run (5 edge-case tasks ×
+{single-shot, gate-loop} × 10 epochs, temp 0.6). The comparison to beat:
+**+20.0pp [+8.0, +32.0], McNemar net +10, +1,072 tokens / +0.3 turns.**
+Hypotheses to distinguish: (a) lift replicates ≈ +20pp — gate value is
+model-independent; (b) lift shrinks because the stronger model one-shots more
+edge cases (baseline above 78%) — ceiling moves, gate still nets positive on
+the remainder; (c) lift vanishes — report honestly.
+
+### E2 — Agentic ceiling check + component ablation (opencode adapter)
+
+```bash
+uap bench paired --adapter opencode --model "Qwen3.8-27B" \
+  --suite benchmarks/suites/real-gate-hard --ablation --epochs 4
+```
+
+Replicates the 0pp-at-ceiling agentic result and re-ranks per-component token
+overhead (gates / worktree / memory / experts / skills / patterns) on the new
+model. Watch for the known harness wedge (detached opencode process tree
+surviving SIGTERM) — the process-group SIGKILL fix is in, but flag any
+158–190/192-style shortfall.
+
+### E3 — Headroom re-openers (the suites the findings never saw)
+
+Paired runs (raw + opencode adapters) over, in priority order:
+
+1. `real-gate-heldout` — held-out tasks; guards against suite overfitting of
+   the E1/E2 conclusions.
+2. `real-gate-power` — designed for statistical power; the primary candidate
+   for a tighter CI on the agentic delta.
+3. `real-gate-medium`, then `real-gate-brutal` — harder multi-file tasks
+   where even a self-verifying agentic baseline should drop below 100%,
+   re-opening the headroom the older suites lacked. This is the run that can
+   show UAP lift *inside* an agentic harness, which the prior findings could
+   not measure.
+
+### E4 — Deliver-pipeline spot check (post-hardening)
+
+E1's gate loop is the deliver mechanism in miniature; it does not exercise
+the actual v1.224.0 deliver path (scoped rollback, declared gates, liveness).
+Unit/integration coverage for those shipped with the feature (90+ tests), so
+E4 is a small paired run where the UAP arm routes through the **current full
+deliver surface** rather than the raw miniature, confirming the hardened loop
+converges at least as well on the same suite. If the paired harness cannot
+drive the real deliver path today, note the gap and scope the adapter
+extension instead of hand-waving it.
+
+## Analysis plan
+
+- Primary claims are the **with-UAP vs without-UAP paired deltas** (E1–E4),
+  each with CI + p, in the `PAIRED_FINDINGS.md` report format. The summary
+  table leads with one row per experiment: suite, UAP-off accuracy, UAP-on
+  accuracy, Δ, CI, p, token Δ.
+- Cross-model (qwen36 → qwen38) comparisons are **not paired** — report as
+  side-by-side findings with the confound named (model, serving stack, and
+  UAP version all moved).
+- Success criteria, decided in advance: E1 CI excludes 0 with the same sign
+  as before; E3 shows at least one suite where the agentic baseline leaves
+  headroom (else the 0pp agentic conclusion stands, strengthened); E4 shows
+  no convergence regression vs E1's loop.
+- Write-up lands as an update section in `docs/benchmarks/PAIRED_FINDINGS.md`
+  (new runs, same tables), not a parallel document.
+
+## Cost
+
+Local GPU, so the currency is wall-clock, not dollars. Rough budget on one
+RTX 3090 at 2-slot concurrency: E1 ≈ 100 runs, E2 ≈ 192 runs (ablation), E3
+similar order per suite. Expect several GPU-hours per experiment; schedule
+sequentially, keep `--concurrency 2`, and watch the host's kernel OOM-kill
+history at the 131072-ctx tier (~0.95 GiB free VRAM) — drop to 65536/slot if
+instability appears, and re-derive `PROXY_CONTEXT_WINDOW` to match.
+
+## Risks
+
+| Risk | Mitigation |
+|---|---|
+| Proxy `:4100` not answering at plan time | Phase 0 preflight before any run |
+| Stronger model lifts the non-agentic baseline, shrinking measurable headroom | Expected; report baseline→UAP pair regardless, lean on E3 suites for headroom |
+| Thin VRAM headroom at 131072 ctx/slot under harness load | Drop to 65536/slot tier, re-derive proxy limits |
+| Alias confusion (`Qwen3.8-27B` vs legacy qwen35/36 aliases on the same server) | Freeze one id in Phase 0, assert it in run metadata |
+| Harness process-tree wedge under opencode adapter | Group-SIGKILL fix is in; verify completion counts per run |
+
+## Deliverables when executed
+
+1. `benchmark-results/paired-qwen38-*` artifacts (records.jsonl, report.json,
+   report.md) for E1–E4
+2. An update to `docs/benchmarks/PAIRED_FINDINGS.md` adding the qwen38 /
+   UAP-v1.224.x tables alongside the qwen36 originals
+3. If E4 surfaces the deliver-path adapter gap: a scoped follow-up task for
+   the paired-harness extension

package/docs/reference/API.md

@@ -1,6 +1,6 @@
 # UAP Programmatic API Reference
 
-> Public API of the `@miller-tech/uap` package. Version v1.93.1.
+> Public API of the `@miller-tech/uap` package. Version v1.224.0.
 
 > **🏭 Where this fits:** Cross-cutting — the machine parts behind the line.
 > **What it delivers:** when the `uap` CLI isn't the right shape for your job,

package/docs/reference/CLI.md

@@ -1,7 +1,7 @@
 # UAP CLI Reference
 
 > Complete command reference for the Universal Agent Protocol command-line interface (`uap`).
-> Version v1.93.1.
+> Version v1.224.0.
 
 > **🏭 Where this fits:** Every station — this is the control panel for the whole
 > line. **What it delivers:** one binary that drives each stage of your
@@ -36,6 +36,7 @@ runs, keeping `--help` fast.
 | [`memory`](#memory) | Manage the agent memory system |
 | [`patterns`](#patterns) | Manage pattern RAG (on-demand retrieval via Qdrant) |
 | [`worktree`](#worktree) | Manage git worktrees |
+| [`merge`](#merge) | Serialized landing of concurrent agent PRs |
 | [`sync`](#sync) | Sync configuration between platforms |
 | [`droids`](#droids) | Manage custom droids/agents |
 | [`expert-route`](#expert-route) | Recommend an expert droid chain for a task |
@@ -67,10 +68,23 @@ runs, keeping `--help` fast.
 | [`mcp-router`](#mcp-router) | Hierarchical MCP router for 98%+ token reduction |
 | [`hooks`](#hooks) | Manage session hooks across platforms |
 | [`tool-calls`](#tool-calls) | Manage Qwen3.5 tool call fixes and chat templates |
-| [`rtk`](#rtk) | Manage RTK (Rust Token Killer) integration |
 | [`mcp-setup`](#mcp-setup) | Configure MCP Router for all AI harnesses |
 | [`schema-diff`](#schema-diff) | Detect breaking schema changes between branches |
 | [`policy`](#policy) | UAP policy management |
+| [`quality`](#quality) | Quality-metrics gate: complexity, coverage, CRAP, mutation, duplication, any-types |
+| `plan` | Validate + record plan validation (validate-plan-on-change gate): `uap plan validate [file]` reviews the plan, then stamps |
+| `principles` | Engineering principles: show them, and answer the backward-compatibility stance (`status \| ask \| compat \| maturity \| show`) |
+| `fidelity` | Inspect or set the maximum-fidelity verification mode (raised gates + always-on visual/vision review) |
+| `interaction` | Interaction gate: derive probes from the requirements and play the artifact through them |
+| `harness card` | ETCSOVG harness disclosure card for the current configuration |
+| `harness evidence` | Per-tool-call evidence corpus: failure classes, component attribution, edit-tool health |
+| `ideate ideas` | Print the curated ideas produced for a project |
+| `self-harness mine-prod` | Mine weaknesses from production traces (HALO + proxy log) and enqueue proposals for gated validation (never applies) |
+| `self-harness pending` | List queued proposals awaiting validation + gate (from mine-prod) |
+| `bench paired` | Run the paired A/B over a real-gate suite; reports accuracy + efficiency deltas with CIs |
+| `self-harness prune` | Ablation-prune: drop stale / no-longer-paying-off transfer + pending entries |
+| `self-harness run` | Autonomous loop: mine → propose → validate (real paired bench per Mod) → decide → (with `--apply`) commit + versioned snapshot |
+| `self-harness transfer` | List the cross-model transfer store (accepted/rejected Mods keyed by failure signature) |
 | [`uap-omp`](#uap-omp) | UAP integration commands for oh-my-pi (omp) users |
 
 ---
@@ -1000,18 +1014,6 @@ Manage Qwen3.5 tool call fixes and chat templates.
 
 ---
 
-## `rtk`
-
-Manage RTK (Rust Token Killer) integration for token optimization.
-
-| Subcommand | Key flags | Purpose |
-|------------|-----------|---------|
-| `install` | `--force`, `--method` (npm/cargo/binary) | Install the RTK CLI proxy for 60-90% token savings |
-| `status` | — | Check RTK installation and token savings |
-| `help` | — | Show RTK usage information |
-
----
-
 ## `mcp-setup`
 
 Configure MCP Router for all AI harnesses (Claude, Factory, VSCode, Cursor).
@@ -1080,6 +1082,39 @@ uap policy stage POL-1 -s pre-exec
 
 ---
 
+## `quality`
+
+Quality-metrics gate: deterministic policing of complexity, coverage, CRAP,
+surviving mutants, duplication, dead code, and explicit `any`/`unknown` types.
+Activated by `.uap/quality-metrics.json`; existing debt is frozen in the
+ratchet baseline `.uap/quality-baseline.json` so only NEW or WORSENED
+violations block. The proxy enforcer `quality_metrics_gate.py` mirrors the fast
+path (LOC, complexity, any-types) so agent edits are blocked pre-exec with the
+same thresholds this command enforces at commit/CI time.
+
+| Subcommand | Key flags | Purpose |
+|------------|-----------|---------|
+| `init` | — | Write `.uap/quality-metrics.json` with the default thresholds (activates the gate) |
+| `check` | `--staged`, `--files <list>`, `-f, --file <path>`, `--json` | Scan files for metric violations and ratchet against the baseline; exit 2 on blocking violations |
+| `baseline` | `--update` | Show, or with `--update` regenerate, `.uap/quality-baseline.json` from a fresh scan |
+| `report` | `--files <list>`, `--json` | Verbose report including grandfathered violations, improvements, and skips |
+| `mutate` | `--changed` | Stryker incremental mutation run scoped to files changed vs the upstream base (advisory when Stryker is not installed) |
+
+Global flags: `-d, --project-dir <path>`.
+
+```bash
+uap quality init                  # write the config
+uap quality baseline --update     # freeze current debt (commit the diff — it is the reviewable record)
+uap quality check                 # full scan; fails on new/worsened violations
+uap quality check --staged        # scan only files changed vs upstream
+uap quality check --file src/x.ts # single file (content may come from stdin — enforcer parity path)
+```
+
+Escape hatch for agents: `UAP_QUALITY_GATE_OFF=1`. Regenerating the baseline is
+a deliberate act — do it only with reviewer sign-off.
+
+---
+
 ## `uap-omp`
 
 UAP integration commands for oh-my-pi (omp) users. Thin wrappers over the

package/docs/reference/COMPARISON.md

@@ -0,0 +1,248 @@
+# UAP vs Other Agent Harnesses and Tooling
+
+> Applies to UAP v1.224.0. Competitor profiles reflect public sources as of
+> September 2026; vendor-reported numbers are flagged as such, and claims we
+> could not verify are marked or omitted. UAP's own claims in this document
+> were verified against the code.
+>
+> Companion: [Market Position & Competitive Analysis](../analysis/MARKET_POSITION.md)
+> (2026-09) — the dated, strategy-level read (market structure, moats, risks,
+> options) above this feature-level comparison.
+
+UAP is frequently miscast as "another agent harness." It isn't one — it's the
+**discipline layer that sits underneath the harness you're already using**, and
+that positioning determines what an honest comparison looks like. Against
+harnesses (Claude Code, Codex, Cursor, Aider, …) UAP is *complementary*: it
+installs into them. Against per-capability tooling (memory systems,
+orchestration frameworks, spec-driven-development products, review bots,
+policy engines) UAP is *comparable*: it ships its own answer to the same
+problem. This document does both comparisons, then says plainly where UAP
+loses.
+
+---
+
+## The one-slide version
+
+| | Typical agent harness | Typical point tool | **UAP** |
+|---|---|---|---|
+| What it is | The agent's runtime/UI | One capability (memory OR review OR orchestration) | A process layer under the harness: memory + policy + verification + coordination |
+| Model lock-in | Often (Claude Code, Codex, Jules) or partial (Cursor) | Usually none | None — frontier or local llama.cpp/Qwen |
+| Rules are | Conventions in a context file | Config of the point tool | **Executable hooks that block** (exit 2), 32 enforcers |
+| "Done" means | The model says so | N/A | Your **real gates pass**, judged by a different checker than the writer |
+| Memory | Context files (CLAUDE.md / AGENTS.md / rules) | The product (Mem0, Zep, Letta) | 4-tier memory with write-gates + promotion, built in |
+| Multi-agent | Subagents, cloud task pools | N/A or framework | Live file-claim blocking across worktrees + deploy batching |
+| Cost | Subscription / API | Free tier → per-seat SaaS | MIT, self-hosted, free |
+
+---
+
+## 1. UAP vs agent harnesses (complementary, not competitive)
+
+UAP installs hooks into the harness and mediates its tool calls; it does not
+replace the model, the UI, or the session runtime. It currently supports
+[9 harnesses](PLATFORMS.md) — Claude Code, Factory, Cursor, VSCode, OpenCode,
+Codex, ForgeCode, Oh-My-Pi, Hermes.
+
+| Harness | Layer | Memory | Extensibility | Verification gate | Multi-agent | Models | License |
+|---|---|---|---|---|---|---|---|
+| **Claude Code** | CLI + IDE/web | CLAUDE.md, skills | Richest hook surface (PreToolUse etc.), MCP, subagents | Convention + hooks; `/verify` skill (2026) | Subagents, Agent SDK | Anthropic only | Proprietary |
+| **OpenAI Codex** | CLI + cloud + IDE | AGENTS.md | MCP, skills, sandbox/approvals | Cloud sandbox + diffs; tests user-configured | Parallel cloud tasks | OpenAI only | CLI Apache-2.0, usage paid |
+| **Cursor** | IDE + CLI | .cursor/rules, Memories | MCP, rules, BugBot | Prompt/rule-driven | Background/cloud agents | Multi + own Composer | Proprietary freemium |
+| **Aider** | Terminal CLI | CONVENTIONS.md, config | Config, scripting (no MCP) | **Auto-lint/auto-test built in** — the closest to UAP's gate loop among harnesses | Single-session | Fully agnostic | Apache-2.0 |
+| **OpenCode** | TUI + desktop + IDE | AGENTS.md | MCP, plugins, custom agents | In-session commands; no hard gate | Subagents, headless run | 75+ providers | Open source |
+| **Cline** | IDE ext + CLI/SDK | .clinerules, Memory Bank | MCP (originated the marketplace), approvals | Human approval per step; checkpoints | Single; SDK scripting | BYOK 30+ providers | Apache-2.0 |
+| **Factory Droid** | Harness platform | Sessions, instruction files, skills | Skills, MCP, plugins, Spec Mode | Spec Mode + CI droids; configurable | Missions, parallel droids, worktrees | Model-agnostic | Proprietary SaaS |
+| **Gemini CLI / Jules → Antigravity** | CLI (sunset 2026) + async cloud | GEMINI.md | MCP, extensions | Jules runs tests in VM + PR approval | Task pool; Antigravity multi-agent | Gemini only | Mixed |
+| **Devin (Cognition)** | Autonomous cloud agent + IDE (absorbed Windsurf, June 2026) | Playbooks, persistent VMs | API, webhooks | Runs tests in own VM before PR | Parallel sessions | Proprietary SWE + frontier | Commercial |
+
+### What a harness gives you that UAP doesn't
+
+The agent itself: the UI, the session loop, the tool surface, the model
+subscription, and (for the commercial ones) support. If you have no harness,
+UAP is not the thing to install first.
+
+### What UAP adds underneath any of them
+
+- **Executable policy, not conventions.** Every harness above persists guidance
+  as *context files* (CLAUDE.md, AGENTS.md, .cursor/rules) — prose the model
+  may honor or ignore. UAP turns the same rules into hook-bound Python
+  enforcers that return exit 2 and **block** the tool call: worktree isolation,
+  test deltas, schema diffs, expert review, quality budgets. The harness's own
+  hook surface (Claude Code's is the strongest) is the mounting point, not a
+  substitute.
+- **A hard definition of done.** Aider's auto-test and Jules's VM runs are
+  real verification, but they answer "did the edit pass" for one edit. UAP's
+  `deliver` loop iterates against your *project's* gates (build → typecheck →
+  test → lint → declared custom gates → execution/polyglot gates) until they
+  pass, with a separate acceptance judge — the generator never grades its own
+  homework.
+- **Cross-harness consistency.** The same policy file, memory, and gate set
+  applies whether today's session runs in Claude Code and tomorrow's in
+  OpenCode — harness choice becomes a preference, not a process change.
+- **Local-model viability.** The inference proxy's guardrails (loop-breakers,
+  empty-output recovery, grammar constraints, model-slot leases) make cheap
+  local models (llama.cpp/Qwen) usable on the same floor as frontier models.
+
+---
+
+## 2. UAP vs memory & context tooling
+
+| Tool | Layer | Memory model | Write quality control | Consumption | Benchmarks | License |
+|---|---|---|---|---|---|---|
+| **Mem0** | Library + SaaS (+ MCP via OpenMemory) | Semantic facts, multi-scope; optional graph | LLM ADD/UPDATE/DELETE/NOOP gate with dedup | SDK, REST, MCP | LoCoMo 92.5, LongMemEval 94.4 *(vendor-reported)* | Apache-2.0 + paid tiers |
+| **Zep / Graphiti** | Service + OSS engine | Temporal bi-temporal knowledge graph | Entity resolution + edge invalidation | SDK, REST, MCP | DMR > MemGPT (2025 paper) | Graphiti Apache-2.0; Zep commercial |
+| **Letta** | Agent runtime | Core/archival/recall blocks, agent self-edits | Agent's own tool-call judgment; no auto-dedup | SDK, REST, ADE, MCP | No fresh 2026 public numbers | Apache-2.0 + cloud |
+| **Context7** | MCP server | None — doc injection, not memory | Server-side curation | MCP | None published | OSS + freemium |
+| **LLMLingua line** | Library | None — prompt compression | N/A | pip | 20× compression (EMNLP'23) | MIT; stable, low momentum |
+| **LangMem / LlamaIndex memory** | Framework modules | Semantic/episodic/procedural | Configurable extractors | SDK | None public | OSS |
+| **UAP memory** | Built into the discipline layer | **4 tiers**: working (SQLite FTS5) → session → semantic (Qdrant, 768-dim) → knowledge graph | Score-gated writes + consolidation + promotion; dedup by hash + embedding similarity | CLI + hook injection into 9 harnesses | Not independently benchmarked on LoCoMo/LongMemEval | MIT |
+
+### Where the specialists win
+
+Mem0, Zep, and Letta are *products about memory*: managed services, enterprise
+compliance (Zep is SOC 2), published benchmark numbers (Mem0's are
+vendor-reported), SDK ecosystems, and 20+ framework integrations. If you are
+*building* an agent product and need a memory API, use one of them — UAP's
+memory is not exposed as a general-purpose service, has no hosted tier, and
+has not been run against the standard memory benchmarks.
+
+### Where UAP differs
+
+UAP's memory is **operational, not archival**: its tiers exist to keep a coding
+agent's *workflow* honest (recent actions, open loops, promoted lessons), and
+its distinguishing feature is the feedback loop — lessons graduate from
+session notes to long-term memory only through a quality write-gate, and
+patterns that stop paying off fade (pattern reinforcement). It is also the
+only option in the table that arrives pre-wired into the agent's session
+lifecycle (injected at session start, recorded per turn) across nine harnesses
+with zero application code. Context7-style doc injection and LLMLingua-style
+compression have their UAP analogues in the MCP Router (tool hiding + FTS5
+BM25 output compression, ~98% smaller big-tool payloads) — again, hook-native
+rather than an API you integrate.
+
+---
+
+## 3. UAP vs orchestration frameworks
+
+| Framework | Model-agnostic | Durable state | Human-in-loop | Executable gates | License | Maturity |
+|---|---|---|---|---|---|---|
+| **LangGraph** | Yes | Strong (checkpoints; Temporal plugin) | Strong (interrupts) | Advisory/external (LangSmith evals) | MIT | Very high — the default |
+| **CrewAI** | Yes | Partial | Per-task | Output validators; enterprise governance tier | MIT + commercial | High |
+| **AutoGen → MS Agent Framework** | Yes | Legacy → improved in successor | Yes | Advisory | MIT | AutoGen in maintenance; successor young |
+| **OpenAI Agents SDK** | OpenAI-first | Sessions only | Patterns | Guardrails primitive (LLM-level) | MIT | High |
+| **Google ADK** | Gemini-first | Pluggable sessions | Callbacks | Built-in eval framework (`adk eval`) | Apache-2.0 | High, growing |
+| **UAP** | Yes (incl. local models) | SQLite task DAG + coordination DB + run state | Operator guidance channel mid-run | **Yes — exit-code-blocking enforcers + real-gate convergence loop** | MIT | Single-operator production use |
+
+These frameworks answer "how do I *build* a multi-agent application in code";
+UAP answers "how do I *govern* the coding agents I already run." The overlap
+is real but narrow — if you use LangGraph to build an agent product, you could
+still put UAP under the coding agents that maintain that product's repo. The
+sharpest differences: none of the frameworks ship executable, deterministic
+gates on what the agent may *do to a codebase* (their guardrails are LLM-level
+validators), and none carry a verification loop tied to the project's real
+build/test/lint. Conversely, UAP has no visual graph builder, no
+checkpoint-replay durability à la LangGraph+Temporal, and no framework-level
+abstractions for novel agent topologies.
+
+---
+
+## 4. UAP vs spec-driven development & agent governance
+
+| Tool | What it does | Enforcement mode | License |
+|---|---|---|---|
+| **GitHub spec-kit** | Structured specify → plan → tasks → implement workflow with a project "constitution" | Prompt-level templates and checklists | MIT |
+| **AWS Kiro** | Spec workflow (EARS requirements → design → tasks) + event-driven agent hooks | **Mixed**: hooks are executable; specs/steering are prompt-level | Proprietary |
+| **Tessl** | Pivoted Jan 2026 to an "Agent Enablement Platform" (skills registry); spec-driven skills remain | Prompt-level + eval scenarios | Proprietary |
+| **AGENTS.md convention** | The de facto standard agent-readme; 60k+ repos, 20+ tools read it | None — convention only | Open format |
+| **UAP** | Reads the same instruction files (CLAUDE.md/AGENTS.md) *and* binds their rules to hook-enforced gates; plan validation gate; P35 decoder-first pre-execution check | **Executable** for the rules it covers (edit/commit/ship plane); prompt-level for everything else | MIT |
+
+The axis that matters here is *suggests vs blocks*. Spec-kit, AGENTS.md, and
+Tessl's skills improve what the agent *knows*; Kiro's hooks and UAP's
+enforcers constrain what the agent *does*. UAP and Kiro are the only two with
+an executable component; Kiro's hooks automate *tasks* (on file save, run X),
+while UAP's hooks *gate the action itself* (block the write, the push, the
+merge). They compose fine — a spec-kit constitution can name UAP's gates as
+the enforcement mechanism.
+
+---
+
+## 5. UAP vs verification, review & policy engines
+
+| Tool | What it gates | Where it sits | Executable? | License |
+|---|---|---|---|---|
+| **SWE-agent** | Nothing itself — research scaffold measured by SWE-bench | Task execution | N/A | MIT |
+| **CodeRabbit** | PR review (bugs, security, custom rules) | **PR stage** | Via platform merge checks; findings advisory | Proprietary SaaS |
+| **Greptile** | PR review with full-repo context | PR stage (self-host option in v3) | Via merge checks; advisory by default | Proprietary |
+| **NeMo Guardrails** | Agent I/O: injection, dialog, tool-call constraints | Runtime middleware | Yes — blocking rails | Apache-2.0 |
+| **OPA (agent use)** | Which tools an agent may call, with what parameters — now a first-class OPA use case (OWASP Agentic Top 10 write-ups) | Runtime middleware | Yes — deterministic Rego deny | Apache-2.0 (CNCF) |
+| **UAP** | Codebase integrity: where edits land, whether tests/builds/schema/review gates ran, quality budgets, trust anchors | **Edit/commit/ship plane**, pre-PR | Yes — exit-2 hook enforcers, fail-closed | MIT |
+
+### The real distinctions
+
+- **Stage.** CodeRabbit/Greptile review *after* the code is written, at the PR.
+  UAP gates *while* the agent is writing — the violation never becomes a commit.
+  They compose well: UAP reduces what the PR reviewer has to catch.
+- **Determinism.** OPA and UAP are the deterministic options: policy-as-code
+  with no LLM in the verdict path. OPA is the more general, more battle-tested
+  engine (CNCF-graduated, huge ecosystem) and the better choice for
+  platform-wide authorization. UAP's enforcers trade that generality for being
+  **pre-built for coding-agent failure modes** (worktree discipline, test
+  gates, self-protection against an agent disabling its own guardrails —
+  including interpreter-mediated tampering) and for hooking directly into
+  harness events with no sidecar to run.
+- **Verification depth.** Nobody else in this table runs the project's real
+  build/test/lint as a convergence gate with a separate acceptance judge.
+  SWE-agent measures agents; UAP's paired harness (`uap bench paired`)
+  measures *its own* uplift with controlled A/B — see
+  [benchmarks](../benchmarks/PAIRED_FINDINGS.md).
+- **UAP's quality gate vs review bots.** CodeRabbit-style review is LLM
+  judgment; UAP's `quality` gate is deterministic budgets (complexity, CRAP,
+  coverage, mutants, duplicates, `any` types) with a ratchet baseline — the
+  two catch different things.
+
+---
+
+## 6. Where UAP loses — honest trade-offs
+
+1. **Single-operator tool.** No user auth, no teams, no hosted service, no
+   enterprise compliance story (Zep/Mem0/Cognition all have one). The
+   dashboard binds unauthenticated; it's a local console.
+2. **Not a harness.** You still need Claude Code/OpenCode/etc. underneath;
+   UAP alone runs no agent.
+3. **Not a framework.** No graph builder, no replay durability, no agent-topology
+   abstractions — LangGraph/ADK territory.
+4. **Memory is not benchmarked.** Mem0/Zep publish LoCoMo/LongMemEval/DMR
+   numbers (vendor caveats aside); UAP's memory has none. Its benchmark
+   discipline is applied to *delivery uplift* instead (paired A/B with CIs).
+5. **Platform breadth.** The kernel sandbox is Linux-only (bubblewrap); hook
+   depth varies by harness; the full memory tier wants Docker/Qdrant.
+6. **Ecosystem size.** One vendor, MIT, small community vs LangChain-scale
+   ecosystems; fewer integrations, fewer eyes.
+7. **Enforcement has a known escape hatch.** `--dangerously-skip-permissions`
+   bypasses harness hooks by design; UAP's compensating control is the bwrap
+   sandbox, not the hook plane.
+8. **Vendor momentum elsewhere.** The 2026 market moved fast (Windsurf → Devin
+   Desktop, Gemini CLI → Antigravity, AutoGen → Agent Framework, Tessl's
+   pivot); harness-specific UAP integrations can lag those shifts.
+
+---
+
+## 7. Choosing
+
+- **Building an agent product in code** → LangGraph / Google ADK (+ Mem0 or
+  Zep for memory). UAP is irrelevant to your runtime, useful for your repo.
+- **Running coding agents on a real codebase and tired of unverified "done"** →
+  UAP under your current harness; add CodeRabbit/Greptile at the PR if you
+  want a second, post-hoc net.
+- **Regulated / multi-tenant agent authorization** → OPA as the policy engine;
+  UAP's enforcers are the coding-agent-specific complement.
+- **Local-model shop** → UAP's proxy + guardrails + routing are the differentiator;
+  nothing else in this document is built for that floor.
+
+## Sources & method
+
+UAP capabilities verified against the v1.224.0 codebase (see
+[FEATURES.md](FEATURES.md), [architecture](../architecture/OVERVIEW.md)).
+Competitor profiles compiled September 2026 from vendor docs and secondary
+reviews; vendor-reported benchmark and adoption figures are flagged inline,
+and market events we could not confirm from primary sources (e.g. a reported
+Cursor–Continue acquisition) were omitted. Corrections welcome via PR.

package/docs/reference/CONFIGURATION.md

@@ -1,6 +1,6 @@
 # Configuration Reference
 
-> Universal Agent Protocol (UAP) v1.163
+> Universal Agent Protocol (UAP) v1.224.0
 
 > **🏭 Where this fits:** Cross-cutting — the settings that tune every station.
 > **What it delivers:** the dials that decide how your [delivery pipeline](../guides/DELIVERY_PIPELINE.md)
@@ -111,8 +111,6 @@ Top level: `version`, `project`, `memory`, `worktree`, `costOptimization`,
 | `FACTORY_API_KEY` / `DROID_API_KEY` | Factory/droid benchmark API key | — |
 | `NODE_ENV` / `UAM_ENV` / `CI` | Serverless env detection | — |
 | `HOME` | `~/.uap/omp`, droids dir resolution | — |
-| `TMPDIR` | rtk temp dir | `/tmp` |
-| `FORCE_INSTALL` | Force rtk reinstall | off |
 | `APPDATA` / `USERPROFILE` | Windows MCP config path expansion | — |
 
 Per-model API key env var names are configurable via the model config field

package/docs/reference/DATABASE_SCHEMA.md

@@ -1,6 +1,6 @@
 # Database Schema Reference
 
-> Universal Agent Protocol (UAP) v1.93.1
+> Universal Agent Protocol (UAP) v1.224.0
 
 > **🏭 Where this fits:** Cross-cutting — the shop's records and shift log.
 > **What it delivers:** the durable memory of your [delivery pipeline](../guides/DELIVERY_PIPELINE.md)

package/docs/reference/FEATURES.md

@@ -1,6 +1,6 @@
 # Feature Catalog
 
-> Universal Agent Protocol (UAP) v1.163
+> Universal Agent Protocol (UAP) v1.224.0
 
 > **🏭 Where this fits:** Every station on the line — this catalog is the parts list for the whole factory. **What it delivers:** each feature below is mapped to the stage of your [delivery pipeline](../guides/DELIVERY_PIPELINE.md) it protects, so you can see exactly where your agent's work stops being plausible-looking and starts being genuinely shippable.
 
@@ -153,7 +153,7 @@ DB-driven policy enforcement engine.
 | Policy memory (`policy-memory.ts`) | Persists policies (`policies.db`). |
 | Enforced tool router (`enforced-tool-router.ts`) | Routes tool calls through the gate. |
 | CLAUDE.md conversion (`convert-policy-to-claude.ts`) | Renders policies into CLAUDE.md. |
-| Enforcers (`enforcers/`) | ~20 Python enforcers (worktree_required, test_gate, schema_diff_gate, memory_before_plan, coord_overlap, mcp_router_first, rtk_wrap, iac_parity, expert_review_required, etc.). |
+| Enforcers (`enforcers/`) | ~20 Python enforcers (worktree_required, test_gate, schema_diff_gate, memory_before_plan, coord_overlap, mcp_router_first, iac_parity, expert_review_required, etc.). |
 
 ## Delivery (`src/delivery/`) — Build & QC / Verify
 
@@ -284,5 +284,5 @@ The `uap` CLI is the single door into the whole factory (top-level commands):
 `handsfree` (`hf`), `challenge`, `sandbox`, `react`, `ideate`, `coord`, `agent`,
 `deploy`, `task`, `compliance`, `coordination`, `skill`, `update`,
 `dashboard` (alias `dash`), `model`, `mcp-router`, `hooks`, `tool-calls`,
-`rtk`, `mcp-setup`, `schema-diff`, `policy`, `uap-omp`. See
+`mcp-setup`, `schema-diff`, `policy`, `uap-omp`. See
 [CLI reference](CLI.md) for every command and flag.

package/docs/reference/PATTERNS.md

@@ -1,6 +1,6 @@
 # Pattern Library Reference
 
-> Universal Agent Protocol (UAP) v1.93.1
+> Universal Agent Protocol (UAP) v1.224.0
 
 > **🏭 Where this fits:** Prep / Routing — before your agent starts cutting, it
 > should pick the right technique for the job. **What it delivers:** the right

package/docs/reference/PLATFORMS.md

@@ -1,6 +1,6 @@
 # Platform & Harness Reference
 
-> Universal Agent Protocol (UAP) v1.93.1
+> Universal Agent Protocol (UAP) v1.224.0
 
 > **🏭 Where this fits:** Cross-cutting — the same line, whichever floor you work
 > on. **What it delivers:** every station of your [delivery pipeline](../guides/DELIVERY_PIPELINE.md)