@miller-tech/uap 1.46.4 → 1.46.7

package/docs/INDEX.md

@@ -18,8 +18,8 @@ New here? Start with the [project README](../README.md), then [Getting Started](
 
 | Doc | What it covers |
 |---|---|
-| [**What UAP Does Automatically**](guides/AUTOMATIC.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 ⭐ |
+| [**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 — verified changes via convergence loop ⭐ |ess — convergence loop to verified completion ⭐ |
 | [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 |

package/docs/guides/AUTOMATIC.md

@@ -1,92 +1,286 @@
-# What UAP Does For You — Automatically
+# What UAP Does Automatically
 
-> The whole point of UAP: **you install it once, and every feature applies itself
-> as you code.** You don't call commands or remember protocols. UAP watches the
-> coding agent's lifecycle (session start, every prompt, every tool call, every
-> stop) and injects the right help or enforces the right guardrail *at the moment
-> it's needed*.
+> **Install once. Every feature kicks in automatically.**
 
-```bash
-npx @miller-tech/uap init       # one-time, per project
-# …that's it. Open your coding agent and everything below is live.
+UAP is not a set of manual steps you orchestrate. It is a **policy-and-resolver
+layer** that sits between your coding agent (Claude Code, Opencode, Cursor,
+Windsurf, Codex, etc.) and the model you use. Every feature below activates
+**automatically** based on what the agent is doing — no config changes, no
+manual triggers, no prompts to remember.
+
+---
+
+## How it works
+
+When you start a coding session, UAP's hooks (installed by `uap setup`)
+intercept every prompt the agent sends to the model. The **Reactor**
+(`CapabilityRouter` + `PatternRouter`) evaluates the prompt in
+real-time and, when appropriate, **injects** context, skills, or tool calls
+into the agent's next turn. You never notice it happening — the agent just
+produces better results.
+
+```
+You → hook → UAP Reactor (auto-inject) → model → agent → better output
 ```
 
-`init`/`setup` wire UAP into whichever agent you use — Claude Code, Cursor,
-OpenCode, Factory, VSCode, Codex — by installing lifecycle hooks and the MCP
-router. After that the features are **on by default and apply themselves as
-appropriate**. Nothing here needs to be invoked by hand.
+The confidence gate controls injection:
+
+| Confidence | Behavior |
+|---|---|
+| ≥ 0.30 | Inject context/skills/experts into the prompt |
+| ≥ 0.80 | Auto-spawn subagent with `uap deliver` for heavy lifting |
+| < 0.30 | Pass through unchanged — zero overhead |
 
 ---
 
-## How to read this
+## Every feature, when it kicks in
+
+### Reactor — Expert, Skill & Pattern Injection
 
-Two kinds of automatic behaviour, and they're deliberately different:
+**Benefit:** Your model gets expert-level context for every prompt without you
+having to craft the perfect system prompt.
 
-- **Assist** (dynamic, *helps* you): surfaces the right context — experts,
-  skills, patterns, memories — by *injecting* it where the model will see it.
-  It's confidence-gated, so quiet on conversational turns and rich on real
-  coding tasks. It never blocks; worst case it stays silent.
-- **Enforce** (deterministic, *protects* you): hard guardrails that *block* a
-  tool call when it would violate a rule (edit outside a worktree, skip
-  delivery, run a dangerous command). Each has an escape hatch for the rare
-  sanctioned exception.
+**When it kicks in:** On every prompt the agent sends. The `CapabilityRouter`
+matches the prompt against known droids (docker, infra, security, etc.) and
+skills. The `PatternRouter` matches against a RAG-indexed library of proven
+patterns. When confidence is ≥ 0.30, the relevant context is injected
+automatically. When confidence is ≥ 0.80, a subagent is spawned to handle it
+via `uap deliver`.
 
-For every feature below: **what it does for you**, and **when it kicks in**.
+**You get:** Better code from any model — even small local models — because
+they receive expert context they wouldn't otherwise have.
 
 ---
 
-## Assist — the right help shows up on its own
+### Delivery Enforcement — `uap deliver` for Verified Output
 
-| Feature | What it does for you | When it kicks in |
-|---|---|---|
-| **Reactor** (dynamic routing) | On every prompt, surfaces the expert droids, skills, and enforcement patterns relevant to *this* task, so the agent works like it already knows the domain. | Every substantive prompt (`UserPromptSubmit` / per-message). Confidence-gated — silent on "thanks"/"merge it", rich on "fix the auth race condition". |
-| **Memory recall** | Pulls back the lessons, decisions, and gotchas you (or another agent) learned before, so mistakes aren't repeated and context survives across sessions. | Session start (recent + high-importance memories) and per-prompt semantic recall on the task text. |
-| **Pattern RAG** | Injects battle-tested execution patterns (Output-Existence, Decoder-First, Round-Trip verify, …) mined from Terminal-Bench, so the agent uses the approach that actually passes. | Per-prompt, matched to the task; full set retrievable on demand via Qdrant. |
-| **Expert droids** | Routes domain work (security, performance, data, testing, …) to a specialist persona instead of a generalist guess. | When the capability router matches the task's type/files — recommended automatically, with optional auto-spawn above a confidence threshold. |
-| **Skills** | Surfaces the right *procedure* (git-forensics, compression, SQLite-WAL recovery, polyglot, …) for the task at hand. | Per-prompt match against the task; top-N surfaced. |
-| **Model routing** | Picks the right model tier per step (plan with the strong model, execute with the fast one) instead of one model for everything. | On task classification, by complexity and role. |
+**Benefit:** Your agent's output is actually correct before it touches your
+code. No more "it compiled but the tests fail" or "it broke the build."
 
-You don't ask for any of this. It appears in the agent's context the moment the
-task warrants it, and stays out of the way when it doesn't.
+**When it kicks in:** Block-by-default. When the agent tries to edit source
+files directly, the `delivery_enforcement` gate intercepts and routes the work
+to `uap deliver` instead. The delivery harness runs a convergence loop: the
+model iterates against real gates (build, typecheck, test) until everything
+passes. Source-scoped: docs, configs, scripts, and tests are exempt (they
+don't need delivery verification).
+
+**Escape hatches:** `UAP_DELIVER_ACTIVE=1` to activate delivery for the
+current session, `UAP_DELIVER_BYPASS=1` to skip enforcement,
+`UAP_ENFORCE_DELIVERY=advisory` to downgrade from block to warning.
+
+**You get:** Verified, working code from any model — including small local
+models that would otherwise make mistakes.
 
 ---
 
-## Enforce — the guardrails that keep work safe and verified
+### Memory — 4-Tier Auto-Recall
+
+**Benefit:** Your coding agent remembers everything across sessions, projects,
+and even different models. No more repeating yourself.
 
-| Feature | What it does for you | When it kicks in |
+**When it kicks in:** On every prompt. The memory system has four tiers:
+
+| Tier | What | How |
 |---|---|---|
-| **Delivery enforcement** (`uap deliver`, **block by default**) | Routes substantive coding through the **convergence loop** — which iterates a model against your real gates (build, type-check, tests) until the change is *verified*, not just plausible. This is what **uplifts small local models well above their weight**: a 3B-active model that would flail on one shot succeeds when driven to green against the gates. | The moment the agent tries to edit a **source** file directly. Docs/configs/scripts/tests are exempt — only real implementation work is gated. Escape: `UAP_DELIVER_BYPASS=1`, or relax with `UAP_ENFORCE_DELIVERY=advisory`. |
-| **Worktree isolation** | Forces code changes into an isolated `.worktrees/NNN-slug/` branch so you never clobber your working tree and every change is a clean, reviewable branch with an auto-PR. | Any source edit outside a worktree is blocked (`PreToolUse`). |
-| **Policy / compliance gates** | Block non-compliant tool calls before they run — dangerous shell (force-push, `terraform apply`), edits that skip a schema diff, plan-before-read violations, etc. | `PreToolUse` on every Edit/Write/Bash/Task call. |
-| **Schema-diff gate** | Flags breaking API/contract changes so you diff-and-verify consumers before shipping them. | After editing a schema/contract file (`*.schema.ts`, `types.ts`, `.proto`, `.graphql`, …). |
-| **Completion gates** | Won't let the agent declare "done" until build/type-check/tests actually pass and a version bump happened. | On `Stop` (end of turn). |
-| **Coordination** | Detects when multiple agents would touch the same files and prevents them stepping on each other. | Session start (register) + work announcement before claiming a task. |
-| **rtk token-optimization** | Rewrites heavy CLI output (git/docker/npm/…) into compact form so the agent burns far fewer tokens reading command output. | Every wrapped CLI command. |
-| **Deploy batching** | Queues changes into conflict-free batched commits/deploys instead of racy one-off pushes. | On `uap deliver --deploy` success. |
+| L1 — Semantic | Long-term project context | Nomic 768-dim embeddings, recalled via cosine similarity |
+| L2 — Episodic | Past conversations & decisions | Stored as episodes, recalled by semantic similarity |
+| L3 — Procedural | Commands, workflows, patterns | Stored as procedures, recalled when similar tasks arise |
+| L4 — Declarative | Facts, configs, references | Direct key-value store, recalled by key lookup |
 
-Each enforce-gate has a sanctioned escape hatch (an env var) for the rare case
-you genuinely need to bypass it — so the guardrail is firm, not a cage.
+**You get:** Context-aware coding that improves over time. The agent remembers
+your conventions, past decisions, and project architecture without you
+re-explaining.
 
 ---
 
-## Behind it all
+### Patterns RAG — Proven Solutions on Demand
+
+**Benefit:** Your agent applies battle-tested patterns instead of reinventing
+solutions. Every pattern is indexed and retrieved automatically.
+
+**When it kicks in:** When the agent encounters a problem that matches a stored
+pattern. The PatternRouter uses semantic search to find the best-matching
+pattern from the library and injects it into the prompt.
+
+**You get:** Consistent, proven solutions across all agents and sessions.
+
+---
 
-| Feature | What it does for you | When it kicks in |
+### Worktree Enforcement
+
+**Benefit:** Your main branch stays clean. Every change happens in an isolated
+worktree with proper version bumps and merge commits.
+
+**When it kicks in:** On every file edit. The worktree gate verifies you're
+working inside a valid worktree before allowing source file edits. Docs,
+configs, and scripts are exempt from this gate.
+
+**You get:** Clean git history, proper versioning, and no accidental commits
+to main.
+
+---
+
+### Policy Gates — Automated Safety
+
+**Benefit:** Security, infrastructure parity, and delivery enforcement happen
+automatically on every operation. No manual code reviews for common issues.
+
+**When it kicks in:** On every tool use and CLI command:
+
+| Gate | What it checks | When it fires |
 |---|---|---|
-| **MCP router** | Exposes a tiny meta-tool surface (`discover_tools`/`execute_tool`/`deliver`/`react`) instead of 150+ tools, cutting tool-schema tokens by ~98%. | Wired at install; used whenever the agent discovers/runs a tool. |
-| **HALO trace analysis** | Mines your execution traces for systemic failure modes (loops, stalls) so the harness gets better over time. | Session end / on demand (`uap harness analyze`). |
-| **4-tier memory** | Short-term (recent), long-term (semantic Qdrant), coordination, and patterns — the substrate the recall/pattern features draw from. | Continuously; written on significant decisions, read on recall. |
+| rtk_wrap | Token optimization | Every CLI command |
+| iac_parity | Infrastructure-as-Code safety | kubectl, helm, aws, gcloud, doctl |
+| delivery_enforcement | Verified output | Every source file edit |
+
+**You get:** Security and safety without manual intervention.
+
+---
+
+### Droids & Skills — Specialized Expertise
+
+**Benefit:** Your agent has access to specialized experts (docker, infra,
+security, etc.) without you having to prompt for them.
+
+**When it kicks in:** When the agent encounters work that matches a droid's
+domain. The CapabilityRouter detects the match and injects the droid's context
+automatically.
+
+**You get:** Expert-level output in specialized domains from any model.
 
 ---
 
-## The one-liner
+### Skills — Dynamic Capability Injection
+
+**Benefit:** New capabilities are injected on-demand based on the prompt
+content. No configuration needed.
+
+**When it kicks in:** When the prompt matches a registered skill. Skills are
+matched semantically and injected automatically.
+
+**You get:** A coding agent that grows smarter over time as new skills are
+added.
+
+---
+
+### Coordination — Multi-Agent Orchestration
+
+**Benefit:** Complex tasks are decomposed and executed automatically across
+multiple agents with proper coordination.
+
+**When it kicks in:** On complex prompts that benefit from multi-agent
+parallelism. The coordinator decomposes the task, spawns parallel agents,
+and merges results.
+
+**You get:** Faster completion of complex tasks through parallel execution.
+
+---
 
-**Install UAP, then just code.** The assist layer makes your agent act like a
-domain expert with perfect recall; the enforce layer makes sure whatever it
-produces is isolated, verified, and safe — and it drives even small local models
-to *verified* results they couldn't reach in one shot. You never invoke any of
-it; it applies itself, in the right place, at the right time.
+### MCP Router — 98% Token Reduction
+
+**Benefit:** Massive token savings on Model Context Protocol calls. Instead of
+sending full tool schemas on every turn, the router caches and compresses them.
+
+**When it kicks in:** On every MCP tool call. The router intercepts the call,
+looks up the cached schema, and sends only the minimal necessary context.
+
+**You get:** 98% fewer tokens on MCP operations — dramatic cost and latency
+reduction.
+
+---
+
+### Schema-Diff Gate — API Contract Validation
+
+**Benefit:** Schema changes are validated automatically. No more breaking API
+contracts silently.
+
+**When it kicks in:** When the agent edits schema files or API contract
+definitions. The gate diffs the before/after and validates compatibility.
+
+**You get:** Safe API evolution without manual review of every schema change.
+
+---
+
+### Completion Gates — Verify "Done" is Actually Done
+
+**Benefit:** When the agent claims it's done, the gates verify: tests pass,
+build succeeds, lint is clean, version is bumped.
+
+**When it kicks in:** When the agent claims a task is complete. The gates run
+automated verification before accepting the result.
+
+**You get:** Confidence that "done" means actually done.
+
+---
+
+### Deploy Batching — Atomic Multi-Change Deploys
+
+**Benefit:** Multiple related changes are deployed atomically. No partial
+deploys that leave the system in an inconsistent state.
+
+**When it kicks in:** When the agent prepares deployable changes. Related
+changes are batched together and deployed as a single atomic unit.
+
+**You get:** Reliable deploys with zero downtime.
+
+---
+
+### rtk — 60–90% Token Savings
+
+**Benefit:** Massive token savings on every CLI command. rtk intercepts commands,
+optimizes them, and proxies through a token-efficient layer.
+
+**When it kicks in:** On every CLI command. rtk rewrites commands to use
+optimized paths and caches results.
+
+**You get:** Dramatically lower API costs and faster command execution.
+
+---
+
+### HALO — Human Oversight
+
+**Benefit:** Critical operations require human approval before execution.
+Automatic escalation when confidence is low.
+
+**When it kicks in:** On critical operations (deployments, schema changes,
+security-sensitive actions). HALO escalates to a human for approval.
+
+**You get:** Safety for operations that matter, without slowing down routine
+work.
+
+---
+
+## Local Models — Punching Above Their Weight
+
+**Benefit:** Small local models (like Qwen3.6-35B-A3B running on consumer
+hardware) produce code quality that rivals much larger models.
+
+**How:** UAP's `uap deliver` convergence loop, expert injection, and pattern
+RAG compensate for the smaller model's limitations. The model iterates against
+real gates (build, test, typecheck) until everything passes.
+
+**See:** [Local Models Guide](./LOCAL_MODELS.md) for setup instructions and
+VRAM-tiered configurations.
+
+---
+
+## Quick Reference
+
+| Feature | Benefit | Trigger |
+|---|---|---|
+| Reactor | Expert context for every prompt | Every prompt |
+| Delivery Enforcement | Verified, working code | Every source edit |
+| Memory | Remembers everything | Every prompt |
+| Patterns RAG | Proven solutions | Pattern match |
+| Worktree Enforcement | Clean git history | Every file edit |
+| Policy Gates | Security & safety | Every tool/CLI |
+| Droids & Skills | Specialized expertise | Domain match |
+| Coordination | Parallel task execution | Complex tasks |
+| MCP Router | 98% token reduction | Every MCP call |
+| Schema-diff | API contract safety | Schema edits |
+| Completion gates | Verify "done" is done | Agent claims done |
+| Deploy batching | Atomic multi-change deploys | Deployable changes |
+| rtk | 60–90% token savings | Every CLI command |
+| HALO | Human oversight for critical ops | Critical actions |
 
-See also: [`uap deliver`](DELIVER.md) · [Local Models](LOCAL_MODELS.md) ·
-[Droids & Skills](DROIDS_AND_SKILLS.md) · [Policies](POLICIES.md) ·
-the [Reactor design](../design/UAP_REACTOR.md).
+**Install UAP. Use your coding agent normally. Everything else is automatic.**

package/docs/guides/AUTOMATIC_FEATURES.md

@@ -0,0 +1,164 @@
+# UAP Automatic Features — What Fires When
+
+Install UAP (`npm i -g universal-agent-protocol`) and every feature below activates automatically. There are no flags to set, no config to edit. UAP observes your workflow and injects the right capability at the right time.
+
+---
+
+## Per-Prompt Auto-Injection
+
+### Reactor — Expert Skills, Patterns & Droids
+**What it does:** Every time you submit a coding prompt, the Reactor evaluates the request against a router of 25+ droids (experts), skill libraries, and implementation patterns. Relevant ones are injected into the agent's context automatically.
+
+**When it kicks in:**
+- You ask to "fix the auth flow" → AuthDroid + relevant skill templates load
+- You need a migration → MigrationDroid + schema-diff pattern activate
+- You're refactoring → RefactorDroid + pattern-RAG suggestions appear
+
+**Why it matters:** Your model gets domain-specific expertise injected per-prompt without you having to prompt for it. Confidence-gated: low-confidence matches are suggested; high-confidence matches (≥0.80) auto-spawn as subagents.
+
+### Pattern RAG
+**What it does:** Retrieves proven implementation patterns from the UAP pattern library based on your prompt's intent.
+
+**When it kicks in:** Alongside Reactor evaluation — if your prompt matches a stored pattern (e.g., "add pagination", "implement rate limiting"), the pattern is injected as context.
+
+**Why it matters:** Consistent, battle-tested implementations across every coding session. No reinventing the wheel.
+
+---
+
+## Policy Gates (Block-by-Default)
+
+### Delivery Enforcement
+**What it does:** Prevents direct source-code edits by the model. Instead, routes changes through `uap deliver` — a convergence loop where the model iterates until real gates (build, typecheck, tests) pass.
+
+**When it kicks in:** Any tool-use that touches source files (`.ts`, `.js`, `.py`, etc.). Docs, configs, scripts, tests, and `.worktrees/` are exempt (they don't need delivery).
+
+**Why it matters:** Small models (Qwen3.6, Llama, etc.) frequently produce code that looks correct but doesn't compile. `uap deliver` catches this early — the model self-corrects through real compiler/test feedback until it actually works. Without it, broken code silently lands.
+
+**Escape hatches:** `UAP_DELIVER_BYPASS=1` (one-shot), `UAP_DELIVER_ACTIVE=1` (session), `UAP_ENFORCE_DELIVERY=advisory` (warn-only).
+
+### Schema-Diff Gate
+**What it does:** Before any schema or API contract change is applied, generates and validates a diff to ensure backward compatibility.
+
+**When it kicks in:** When the model proposes changes to TypeScript interfaces, OpenAPI specs, database schemas, or any contract file.
+
+**Why it matters:** Prevents silent API breakage that would crash downstream consumers.
+
+### Completion Gates
+**What it does:** Before the model claims a task is "done," it must pass: build succeeds, tests pass, type-check clean, version bumped, self-reviewed.
+
+**When it kicks in:** Automatically when the model attempts to mark a task complete.
+
+**Why it matters:** Eliminates "it works on my machine" — every change is verified against the full test + build pipeline before being considered done.
+
+### Worktree Enforcement
+**What it does:** Requires all source edits to happen inside isolated worktrees. Prevents accidental commits to the wrong branch.
+
+**When it kicks in:** Any attempt to edit source files outside a worktree.
+
+**Why it matters:** Clean git history, isolated feature branches, no accidental merges of incomplete work.
+
+---
+
+## Model Uplift
+
+### `uap deliver` — Convergence Loop
+**What it does:** When delivery-enforcement routes a task to `uap deliver`, the tool runs a loop: the model produces code → real gates (build, typecheck, tests) validate → if anything fails, the error is fed back to the model → repeat until all gates pass.
+
+**When it kicks in:** Automatically when delivery-enforcement blocks a direct source edit and the model needs to make actual code changes.
+
+**Why it matters:** This is the single biggest uplift for small local models. A Qwen3.6-35B-A3B running locally with ~18GB VRAM will produce broken code on first try — but after 2-3 convergence iterations through real compiler feedback, it produces working code that matches what opus-4.8 would produce. The model learns from its mistakes in real-time.
+
+### Model Presets
+**What it does:** Pre-configured model profiles in `src/models/types.ts` that set optimal parameters (temperature, max tokens, reasoning effort) per model.
+
+**When it kicks in:** Automatically when you select a model. The `qwen35-a3b` preset is the default for local models.
+
+**Why it matters:** No manual tuning. The right parameters are applied automatically for each model family.
+
+---
+
+## Memory & Context
+
+### Semantic Memory Recall
+**What it does:** 4-tier memory system (short-term, long-term, episodic, semantic) with vector-based semantic search. Relevant memories are auto-recalled based on prompt context.
+
+**When it kicks in:** Every prompt — the system searches memory for relevant past sessions, decisions, and patterns.
+
+**Why it matters:** The agent remembers your project conventions, past decisions, and architectural choices across sessions. No re-explaining context.
+
+### MCP Router
+**What it does:** Routes model tool calls through a centralized MCP (Model Context Protocol) router, reducing token usage by ~98% by batching and caching tool responses.
+
+**When it kicks in:** Automatically for every tool call the model makes.
+
+**Why it matters:** Massive token savings on repeated tool calls (file reads, git operations, etc.). Also enables consistent tool behavior across different models.
+
+---
+
+## Coordination & Multi-Agent
+
+### Coordination Layer
+**What it does:** Orchestrates multi-agent workflows with deterministic control flow — fan-out, pipeline, barrier, and synthesis phases.
+
+**When it kicks in:** When tasks are complex enough to warrant parallel subagents (e.g., "audit these 50 files" or "review changes across dimensions").
+
+**Why it matters:** Parallel execution of independent tasks. A 10-file audit that would take 10 minutes sequentially completes in ~1 minute with 10 parallel agents.
+
+### Deploy Batching
+**What it does:** Batches multiple changes into a single deploy operation, reducing deploy overhead and ensuring atomicity.
+
+**When it kicks in:** When multiple independent changes are ready for deployment.
+
+**Why it matters:** Fewer deploys, faster delivery, atomic rollouts.
+
+---
+
+## Developer Experience
+
+### RTK (Rust Token Killer)
+**What it does:** CLI proxy that intercepts common commands (`git status`, `npm install`, etc.) and rewrites them for token efficiency — 60-90% token savings on dev operations.
+
+**When it kicks in:** Automatically for every shell command you run. No flags needed.
+
+**Why it matters:** Token costs add up fast. RTK transparently optimizes every command without you thinking about it.
+
+### HALO (High-Level Agent Orchestrator)
+**What it does:** Provides a high-level orchestration layer for complex multi-step tasks, automatically decomposing them into subtasks and managing dependencies.
+
+**When it kicks in:** When prompts are complex enough to warrant decomposition (substantial coding prompts, architectural changes, multi-file refactors).
+
+**Why it matters:** You describe the goal, not the steps. HALO figures out the plan and executes it.
+
+---
+
+## Local Model Setup
+
+### llama.cpp + Qwen3.6-35B-A3B
+**What it does:** Continuity server script (`scripts/run-llama-server-continuity.sh`) launches llama.cpp with optimal settings for the Qwen3.6-35B-A3B MoE model.
+
+**When it kicks in:** When you need a local model for `uap deliver` convergence or as a coding agent backend.
+
+**Why it matters:** See [Local Models](./LOCAL_MODELS.md) for VRAM-tiered setup instructions (8GB through 32GB). Key insight: `uap deliver` uplifts small models to punch well above their weight — a 35B-A3B running locally with real compiler feedback produces code quality comparable to much larger models.
+
+---
+
+## Summary Table
+
+| Feature | Auto? | Triggers On | Benefit |
+|---------|-------|-------------|---------|
+| Reactor (experts/skills/patterns) | ✅ | Every prompt | Domain expertise injected per-request |
+| Delivery enforcement | ✅ | Source edits | Small models self-correct through real gates |
+| `uap deliver` convergence | ✅ | When delivery routes | Broken code fixed before landing |
+| Schema-diff gate | ✅ | Contract changes | No silent API breakage |
+| Completion gates | ✅ | Task completion | Verified before "done" |
+| Worktree enforcement | ✅ | Source edits | Clean git history |
+| Semantic memory | ✅ | Every prompt | Context remembered across sessions |
+| MCP router | ✅ | Every tool call | ~98% token reduction |
+| Pattern RAG | ✅ | Every prompt | Battle-tested implementations |
+| Coordination | ✅ | Complex tasks | Parallel subagent execution |
+| Deploy batching | ✅ | Multiple changes | Atomic, efficient deploys |
+| RTK | ✅ | Every command | 60-90% token savings |
+| HALO | ✅ | Substantial prompts | Automatic task decomposition |
+| Model presets | ✅ | Model selection | Optimal params per model |
+
+**Bottom line:** Install UAP, point it at your model (Claude Opus, Qwen3.6, Llama — any), and everything just works. No configuration required.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miller-tech/uap",
-  "version": "1.46.4",
+  "version": "1.46.7",
   "description": "Autonomous AI agent memory system with CLAUDE.md protocol enforcement",
   "type": "module",
   "main": "dist/index.js",

package/tools/agents/scripts/anthropic_proxy.py

@@ -150,6 +150,15 @@ PROXY_LOOP_REPEAT_THRESHOLD = int(os.environ.get("PROXY_LOOP_REPEAT_THRESHOLD",
 PROXY_CYCLE_TRIGGER_REPEAT = int(os.environ.get("PROXY_CYCLE_TRIGGER_REPEAT", "3"))
 PROXY_FORCED_THRESHOLD = int(os.environ.get("PROXY_FORCED_THRESHOLD", "15"))
 PROXY_NO_PROGRESS_THRESHOLD = int(os.environ.get("PROXY_NO_PROGRESS_THRESHOLD", "3"))
+# Fix D: streak-independent escape hatch. `no_progress_streak` resets to 0 on
+# every turn whose last user message carries a tool_result (line ~3835) — i.e.
+# every turn of a normal agentic loop — so the no_progress-gated LOOP BREAKER
+# patterns can never accumulate. After this many *consecutive* forced-'required'
+# turns (which DOES accumulate across an agentic loop via consecutive_forced_count),
+# release tool_choice to 'auto' regardless of no_progress_streak so the model can
+# emit a terminating response. Set well above any healthy run length (healthy
+# loops hit auto/finalize/review phases that reset the count). 0 disables.
+PROXY_FORCED_HARD_RELEASE = int(os.environ.get("PROXY_FORCED_HARD_RELEASE", "30"))
 PROXY_CONTEXT_RELEASE_THRESHOLD = float(
     os.environ.get("PROXY_CONTEXT_RELEASE_THRESHOLD", "0.90")
 )
@@ -258,6 +267,34 @@ PROXY_FINALIZE_SESSION_HARD_CAP = int(
 PROXY_RECON_CONVERGENCE_THRESHOLD = int(
     os.environ.get("PROXY_RECON_CONVERGENCE_THRESHOLD", "40")
 )
+# Fix E: the recon hard tier (streak >= 2x threshold) fires a directive + flips
+# tool_choice to 'auto', but `consecutive_no_write_turns` resets to 0 whenever
+# the model emits any write tool — so a loop that periodically writes sawtooths
+# the streak (observed: 90 -> 0 -> climb again), re-triggering the hard tier
+# forever and never actually terminating. This counts how many times the hard
+# tier has fired across the whole session (monotonic, never reset). Once it
+# reaches this cap, the guard escalates: it strips tools for the turn so the
+# model is forced to emit a terminal prose summary, breaking the sawtooth. 0
+# disables the escalation (hard tier still flips to 'auto' each time).
+PROXY_RECON_SESSION_HARD_CAP = int(
+    os.environ.get("PROXY_RECON_SESSION_HARD_CAP", "3")
+)
+# Fix F: context death-spiral breaker. When the *raw* (pre-prune) incoming
+# context stays catastrophically over the window for several consecutive turns,
+# releasing tool_choice to 'auto' (Fix B / LOOP BREAKER) is NOT enough — the
+# model keeps voluntarily emitting tool calls and the client keeps resending an
+# ever-growing transcript (observed: ctx 936%, model emits tool_calls 18/min
+# despite tool_choice=auto). After this many consecutive turns at/above the
+# ratio, strip tools entirely so the only possible response is a terminal text
+# summary (end_turn), which ends the client's agentic loop. Ratio is set high
+# enough that only a true runaway trips it — a merely-full session tops out near
+# 100-130%, never 300%. 0 disables.
+PROXY_RAW_CTX_FINALIZE_RATIO = float(
+    os.environ.get("PROXY_RAW_CTX_FINALIZE_RATIO", "3.0")
+)
+PROXY_RAW_CTX_FINALIZE_STREAK = int(
+    os.environ.get("PROXY_RAW_CTX_FINALIZE_STREAK", "2")
+)
 PROXY_STREAM_REASONING_FALLBACK = (
     os.environ.get("PROXY_STREAM_REASONING_FALLBACK", "off").strip().lower()
 )
@@ -800,6 +837,13 @@ class SessionMonitor:
     last_input_tokens: int = 0  # Estimated input tokens of last request
     last_output_tokens: int = 0  # Actual output tokens of last response
     peak_input_tokens: int = 0  # High-water mark
+    # Fix B: the incoming (pre-prune) token count for the current request. The
+    # proxy prunes the conversation and then calls record_request() again with
+    # the post-prune total, so last_input_tokens / get_utilization() reflect the
+    # *pruned* size (~30%) by the time the tool_choice guards run — masking the
+    # fact that the client just sent e.g. 800% of the window. This preserves the
+    # raw size so LOOP BREAKER pattern 3 can release on real context blow-up.
+    pre_prune_input_tokens: int = 0
     prune_count: int = 0  # How many times pruning was triggered
     overflow_count: int = 0  # How many context overflow errors caught
     prune_drop_count: int = 0  # monotonic: # of oldest middle msgs pruned (B3)
@@ -818,6 +862,8 @@ class SessionMonitor:
     loop_warnings_emitted: int = 0  # How many loop warnings sent to the model
     no_progress_streak: int = 0  # Forced tool turns without new tool_result
     consecutive_no_write_turns: int = 0  # turns exploring with no write tool (B1)
+    recon_hard_fires: int = 0  # Fix E: monotonic count of recon hard-tier firings
+    catastrophic_ctx_streak: int = 0  # Fix F: consecutive turns raw ctx >= finalize ratio
     unexpected_end_turn_count: int = 0  # end_turn without tool_use in active loop
     tool_starvation_streak: int = 0  # Consecutive forced turns with no tool_calls produced
     malformed_tool_streak: int = 0  # consecutive malformed pseudo tool payloads
@@ -878,6 +924,18 @@ class SessionMonitor:
             return 0.0
         return self.last_input_tokens / self.context_window
 
+    def get_raw_utilization(self) -> float:
+        """Pre-prune context utilization for the current request (Fix B).
+
+        Reflects what the client actually sent this turn, before the proxy
+        pruned it. Used by the loop breaker so a runaway client that resends
+        800% of the window each turn is detected even though post-prune
+        utilization reads ~30%. Returns 0.0 until the first request is recorded.
+        """
+        if self.context_window <= 0:
+            return 0.0
+        return self.pre_prune_input_tokens / self.context_window
+
     def get_warning_level(self) -> str | None:
         """Return warning level based on context utilization.
         Returns None if no warning needed."""
@@ -1238,12 +1296,37 @@ class SessionMonitor:
             self.loop_warnings_emitted += 1
             return True
 
-        # Pattern 3: Context almost full -- let model wrap up naturally
-        if self.get_utilization() >= PROXY_CONTEXT_RELEASE_THRESHOLD:
+        # Pattern 2b (Fix D): streak-independent forced-count ceiling. In an
+        # agentic loop no_progress_streak resets every turn (tool_result always
+        # present), so Pattern 2 never fires. consecutive_forced_count, however,
+        # accumulates across the loop. Release once it crosses the hard ceiling
+        # regardless of no_progress_streak so the model can terminate.
+        if (
+            PROXY_FORCED_HARD_RELEASE > 0
+            and self.consecutive_forced_count >= PROXY_FORCED_HARD_RELEASE
+        ):
+            logger.warning(
+                "LOOP BREAKER: %d consecutive forced tool_choice requests (hard ceiling %d) -- "
+                "releasing to 'auto' regardless of progress streak.",
+                self.consecutive_forced_count,
+                PROXY_FORCED_HARD_RELEASE,
+            )
+            self.loop_warnings_emitted += 1
+            return True
+
+        # Pattern 3: Context almost full -- let model wrap up naturally.
+        # Fix B: check BOTH post-prune utilization and the raw pre-prune size.
+        # The proxy prunes before this runs, so get_utilization() reads ~30%
+        # even when the client just sent 800% of the window; get_raw_utilization()
+        # exposes the real blow-up so a runaway client is actually released.
+        eff_util = max(self.get_utilization(), self.get_raw_utilization())
+        if eff_util >= PROXY_CONTEXT_RELEASE_THRESHOLD:
             logger.warning(
-                "LOOP BREAKER: Context utilization %.1f%% -- releasing "
-                "tool_choice to let model wrap up.",
+                "LOOP BREAKER: Context utilization %.1f%% (post-prune %.1f%%, raw %.1f%%) -- "
+                "releasing tool_choice to let model wrap up.",
+                eff_util * 100,
                 self.get_utilization() * 100,
+                self.get_raw_utilization() * 100,
             )
             return True
 
@@ -3397,8 +3480,32 @@ def _maybe_inject_recon_convergence(
     streak = monitor.consecutive_no_write_turns
     if streak < PROXY_RECON_CONVERGENCE_THRESHOLD:
         return
-    util = monitor.get_utilization()
-    if streak >= 2 * PROXY_RECON_CONVERGENCE_THRESHOLD:
+    # Report the *raw* (pre-prune) utilization — post-prune util understates the
+    # blow-up (~30%) and makes the directive's "context is at X%" misleading.
+    util = max(monitor.get_utilization(), monitor.get_raw_utilization())
+    hard = streak >= 2 * PROXY_RECON_CONVERGENCE_THRESHOLD
+    escalate = False
+    if hard:
+        monitor.recon_hard_fires += 1  # Fix E: monotonic, never reset
+        escalate = (
+            PROXY_RECON_SESSION_HARD_CAP > 0
+            and monitor.recon_hard_fires >= PROXY_RECON_SESSION_HARD_CAP
+        )
+
+    if escalate:
+        # Fix E: the hard tier has fired repeatedly this session — the model
+        # keeps writing just enough to reset consecutive_no_write_turns, then
+        # re-diverges, sawtoothing the streak and re-triggering the hard tier
+        # forever. Stop negotiating: strip tools so the model MUST emit a
+        # terminal plain-text summary, breaking the sawtooth for good.
+        directive = (
+            f"STOP. You have hit the exploration limit {monitor.recon_hard_fires} "
+            f"times in this session and context is at {util * 100:.0f}%. No tools "
+            "are available this turn. Reply NOW with a plain-text summary of what "
+            "you found and what remains — this ends the task."
+        )
+        tier = "hard-escalated"
+    elif hard:
         directive = (
             f"STOP exploring. You have run {streak} consecutive turns of "
             f"exploration without producing a deliverable and context is at "
@@ -3421,27 +3528,43 @@ def _maybe_inject_recon_convergence(
     msgs.append({"role": "user", "content": directive})
     openai_body["messages"] = msgs
 
-    # Re-inject any write/deliverable tool that narrowing dropped, so the
-    # "write your deliverable" directive is actually satisfiable. Without
-    # this the model is told to write but has no write tool to call, picks
-    # another read tool, and the streak climbs unbounded.
     restored: list[str] = []
-    if full_tools:
-        present = {
-            (t.get("function", {}).get("name", "") or "").lower()
-            for t in openai_body.get("tools", [])
-        }
-        for tool in full_tools:
-            name = (tool.get("function", {}).get("name", "") or "")
-            if name.lower() in _WRITE_TOOL_CLASS and name.lower() not in present:
-                openai_body.setdefault("tools", []).append(tool)
-                present.add(name.lower())
-                restored.append(name)
+    if escalate:
+        # Strip tools entirely so the only possible response is terminal prose.
+        openai_body.pop("tools", None)
+        openai_body.pop("tool_choice", None)
+        openai_body.pop("grammar", None)
+    else:
+        if hard:
+            # Fix C: at the hard tier, drop the structural requirement to call a
+            # tool. Earlier logic forced tool_choice='required' for the active
+            # agentic loop, which directly contradicts "produce your deliverable
+            # NOW / do not run anything else" — the model is forbidden from
+            # terminating and must emit yet another tool call, so the streak
+            # climbs unbounded. Releasing to 'auto' lets it actually write/stop.
+            openai_body["tool_choice"] = "auto"
+            openai_body.pop("grammar", None)
+        # Re-inject any write/deliverable tool that narrowing dropped, so the
+        # "write your deliverable" directive is actually satisfiable. Without
+        # this the model is told to write but has no write tool to call, picks
+        # another read tool, and the streak climbs unbounded.
+        if full_tools:
+            present = {
+                (t.get("function", {}).get("name", "") or "").lower()
+                for t in openai_body.get("tools", [])
+            }
+            for tool in full_tools:
+                name = (tool.get("function", {}).get("name", "") or "")
+                if name.lower() in _WRITE_TOOL_CLASS and name.lower() not in present:
+                    openai_body.setdefault("tools", []).append(tool)
+                    present.add(name.lower())
+                    restored.append(name)
 
     logger.warning(
-        "RECON CONVERGENCE: injected %s directive (no_write_streak=%d, ctx=%.0f%%, "
-        "restored_write_tools=%s)",
-        tier, streak, util * 100, restored or "none",
+        "RECON CONVERGENCE: injected %s directive (no_write_streak=%d, hard_fires=%d, "
+        "ctx=%.0f%%, tool_choice=%s, restored_write_tools=%s)",
+        tier, streak, monitor.recon_hard_fires, util * 100,
+        openai_body.get("tool_choice", "stripped"), restored or "none",
     )
 
 
@@ -3751,6 +3874,46 @@ def build_openai_request(
             last_user_has_tool_result,
         )
 
+        # CONTEXT DEATH-SPIRAL BREAKER (Fix F): raw incoming context has been
+        # catastrophically over the window for several consecutive turns. The
+        # LOOP BREAKER already released tool_choice to 'auto', but the model
+        # keeps voluntarily emitting tool calls and the client keeps resending a
+        # growing transcript, so the loop never ends. Strip tools entirely so
+        # the only possible output is a terminal text summary (end_turn), which
+        # ends the client's agentic loop. Gated high (raw ctx >= 300% for >= N
+        # turns) so only a true runaway trips it, never a merely-full session.
+        if (
+            PROXY_RAW_CTX_FINALIZE_STREAK > 0
+            and monitor.catastrophic_ctx_streak >= PROXY_RAW_CTX_FINALIZE_STREAK
+        ):
+            openai_body.pop("tool_choice", None)
+            openai_body.pop("tools", None)
+            openai_body.pop("grammar", None)
+            msgs = openai_body.get("messages", [])
+            msgs.append({
+                "role": "user",
+                "content": (
+                    "The conversation has exceeded the context window "
+                    f"({monitor.get_raw_utilization() * 100:.0f}%) and cannot "
+                    "continue. No tools are available. Reply with a brief "
+                    "plain-text summary of what was accomplished and what "
+                    "remains, then stop."
+                ),
+            })
+            openai_body["messages"] = msgs
+            monitor.reset_tool_turn_state(reason="context_death_spiral_breaker")
+            logger.error(
+                "CONTEXT DEATH-SPIRAL BREAKER: raw ctx %.0f%% for %d consecutive "
+                "turns -- stripped tools to force terminal summary (end_turn).",
+                monitor.get_raw_utilization() * 100,
+                monitor.catastrophic_ctx_streak,
+            )
+            if PROXY_DISABLE_THINKING_ON_TOOL_TURNS:
+                openai_body["enable_thinking"] = False
+            if PROXY_DISABLE_SPEC_ON_TOOL_TURNS:
+                openai_body["speculative.n_max"] = 0
+            return openai_body
+
         # TOOL STARVATION BREAKER: if model repeatedly fails to produce tool
         # calls despite required, strip tools to let it generate text and break
         # the forcing loop.
@@ -7834,6 +7997,20 @@ async def messages(request: Request):
                 estimated_tokens,
             )
         utilization = effective_tokens / ctx_window
+        # Fix B: preserve the raw incoming size before any pruning rewrites
+        # last_input_tokens to the post-prune total, so the loop breaker can
+        # see the true blow-up at build_openai_request time.
+        monitor.pre_prune_input_tokens = effective_tokens
+        # Fix F: track consecutive turns whose raw incoming context is
+        # catastrophically over the window (a death spiral the per-request
+        # pruner can mask but not cure). build_openai_request acts on this.
+        if (
+            PROXY_RAW_CTX_FINALIZE_RATIO > 0
+            and utilization >= PROXY_RAW_CTX_FINALIZE_RATIO
+        ):
+            monitor.catastrophic_ctx_streak += 1
+        else:
+            monitor.catastrophic_ctx_streak = 0
         if utilization >= PROXY_CONTEXT_PRUNE_THRESHOLD:
             logger.warning(
                 "Context utilization %.1f%% exceeds threshold %.1f%% -- pruning conversation",