@miller-tech/uap 1.48.0 → 1.48.1

package/docs/INDEX.md

@@ -1,6 +1,6 @@
 # UAP Documentation
 
-The complete documentation for the **Universal Agent Protocol** (`@miller-tech/uap` v1.40.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.48.0) — a layer that gives AI coding agents memory, judgment, and the discipline to finish the job.
 
 New here? Start with the [project README](../README.md), then [Getting Started](getting-started/).
 
@@ -19,7 +19,7 @@ New here? Start with the [project README](../README.md), then [Getting Started](
 | Doc | What it covers |
 |---|---|
 | [**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 ⭐ |
+| [**`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 ⭐ |
 | [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/getting-started/INSTALLATION.md

@@ -2,7 +2,7 @@
 
 The Universal Agent Protocol (UAP) is an autonomous AI agent memory system with
 CLAUDE.md protocol enforcement. It ships as a single npm package
-(`@miller-tech/uap`, v1.40.0) that installs the `uap` CLI.
+(`@miller-tech/uap`, v1.48.0) that installs the `uap` CLI.
 
 ## Prerequisites
 
@@ -32,7 +32,7 @@ npm install -g @miller-tech/uap
 uap --version
 ```
 
-This prints the installed package version (e.g. `1.40.0`).
+This prints the installed package version (e.g. `1.48.0`).
 
 ## One-command setup
 
@@ -45,6 +45,14 @@ uap setup
 `uap setup` chains the individual commands so the whole system "just works". It
 runs the following steps in order:
 
+0. **Self-update the CLI** — before anything else, `setup` checks npm and
+   **auto-updates the globally-installed `uap` to the latest published version**
+   if it is behind, so every setup runs against current behaviour. It is
+   non-fatal and self-limiting: only a real global install is updated (a source
+   checkout or a local/monorepo dependency is left alone), it is downgrade-proof,
+   and it is **skipped in CI** for reproducibility (`UAP_SELF_UPDATE=1` forces
+   it). The update applies on the next `uap` invocation. Disable with
+   `--no-self-update` or `UAP_NO_SELF_UPDATE=1`.
 1. **Initialize the project** (`uap init` under the hood) — creates `.uap.json`,
    the `agents/data/memory` directory structure, the short-term memory database,
    a `CLAUDE.md` (or `AGENT.md`), the worktree workflow scaffold, and the Python
@@ -68,11 +76,12 @@ runs the following steps in order:
 ### Useful `uap setup` flags
 
 ```bash
-uap setup --no-memory      # init only, skip Qdrant/memory services
-uap setup --no-patterns    # skip pattern RAG setup and indexing
-uap setup -i               # interactive wizard with feature toggles
-uap setup --verbose        # detailed output
-uap setup -d <path>        # set up a project directory other than the cwd
+uap setup --no-memory       # init only, skip Qdrant/memory services
+uap setup --no-patterns     # skip pattern RAG setup and indexing
+uap setup --no-self-update  # do not auto-update the global CLI
+uap setup -i                # interactive wizard with feature toggles
+uap setup --verbose         # detailed output
+uap setup -d <path>         # set up a project directory other than the cwd
 ```
 
 ### Init only

package/docs/guides/AUTOMATIC_FEATURES.md

@@ -68,6 +68,13 @@ Install UAP (`npm i -g universal-agent-protocol`) and every feature below activa
 
 **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.
 
+### `uap deliver` — Tiered Gates & CI/Deploy Feedback
+**What it does:** Gates are grouped into cheap-first tiers — `fast` (build/typecheck/test/lint) → `integration` (test:integration/e2e, pytest markers) → `deploy-dev` (local compose-up + smoke + teardown) — and only promote to the next, more expensive tier once the prior one is green. With `--watch-ci`/`--until-deployed`, once local tiers pass the loop commits + pushes the worktree branch, watches the CI run, and re-converges on CI/staging/prod deploy failure using the sanitized failure logs.
+
+**When it kicks in:** The integration tier auto-enables when a suite is detected; `--optimize` also turns on `deploy-dev`. The CI watch boundary is opt-in (`--watch-ci`/`--until-deployed`) since it pushes.
+
+**Why it matters:** "Delivered" comes to mean *integrates and deploys*, not just "unit tests pass locally" — and the loop gets real dev/staging/prod feedback to converge on, while never paying for expensive tiers until the cheap ones are green.
+
 ### 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.
 
@@ -129,6 +136,13 @@ Install UAP (`npm i -g universal-agent-protocol`) and every feature below activa
 
 **Why it matters:** You describe the goal, not the steps. HALO figures out the plan and executes it.
 
+### CLI Self-Update on Setup
+**What it does:** `uap setup` checks npm and auto-updates the globally-installed `uap` CLI to the latest published version before configuring a project.
+
+**When it kicks in:** At the start of every `uap setup`. Only a real global install is updated (source checkouts and local/monorepo deps are left alone), it is downgrade-proof, and it is skipped in CI for reproducibility (`UAP_SELF_UPDATE=1` forces). Opt out with `--no-self-update` / `UAP_NO_SELF_UPDATE=1`.
+
+**Why it matters:** Install once; every subsequent setup self-applies the latest behaviour without a manual `npm install -g`. The update takes effect on the next `uap` invocation.
+
 ---
 
 ## Local Model Setup

package/docs/guides/DELIVER.md

@@ -51,7 +51,46 @@ uap deliver "big refactor across modules" --optimize   # enable every aid
 uap deliver "trivial typo fix"           --no-auto     # disable dynamic optimization
 ```
 
-`--optimize` enables exploration, critic, practices, escalation, ideation, HALO spans, and coordination together.
+`--optimize` enables exploration, critic, practices, escalation, ideation, HALO spans, and coordination together. It also turns on the local **integration** and **deploy-dev** gate tiers (below); the commit/push boundary (`--watch-ci`) stays opt-in.
+
+---
+
+## Tiered validation gates (cheap-first)
+
+Real delivery is more than unit tests — it also has to integrate and deploy. `deliver` groups gates into **tiers** and runs them **cheapest-first**, only promoting to the next, more expensive tier once the prior one is green:
+
+```
+fast → integration → deploy-dev → │ commit │ → ci → deploy-staging → deploy-prod
+└──────── run locally ───────────┘          └──── verified by CI (the watcher) ────┘
+```
+
+- **`fast`** — build, typecheck, unit tests, lint (the original ladder). Always on.
+- **`integration`** — `test:integration` / `test:e2e` scripts, or a pytest `integration` marker. **Auto-detected and on by default** (like lint); disable with `--no-integration`.
+- **`deploy-dev`** — a local dev deploy + smoke check: brings a `docker compose` stack up (or runs a `deploy:dev` / `smoke` script), health-checks it, then **always tears it down**. Opt-in with `--deploy-dev`. If docker is unavailable the tier is *skipped*, never failed.
+
+Because promotion is cheap-first, a turn that fails the build never pays for integration or deploy — the expensive tiers run only once the cheap ones pass.
+
+### CI / deploy feedback loop
+
+The `ci`, `deploy-staging`, and `deploy-prod` tiers are **never run locally** — they are verified by CI after commit. With `--watch-ci`, once the local tiers are green `deliver`:
+
+1. commits the applied files and **pushes the current worktree branch** (never `master`/`main`, never force-push);
+2. resolves the CI run for that exact commit (matched by SHA) and watches it;
+3. on CI / deploy failure, feeds the **sanitized failure logs back into a fresh convergence pass** and re-converges (bounded by `--ci-passes`).
+
+`--until-deployed` implies `--watch-ci` and additionally requires the `deploy-staging` and `deploy-prod` jobs to be green before exiting 0 — so "delivered" means *deployed and verified*, not just "tests pass locally".
+
+The bundled workflow [`.github/workflows/deploy-verify.yml`](../../.github/workflows/deploy-verify.yml) provides the `deploy-dev` / `deploy-staging` / `deploy-prod` jobs the watcher reads. Add `deploy:dev` / `deploy:staging` / `deploy:prod` and `smoke` npm scripts to your project and the no-op verification steps become real.
+
+```bash
+# iterate locally through fast → integration → local dev deploy+smoke
+uap deliver "add the orders endpoint" --deploy-dev
+
+# …then push, watch CI, and re-converge until staging + prod deploy verify green
+uap deliver "add the orders endpoint" --until-deployed
+```
+
+> Gate inputs are protected like tests: the model cannot "pass" by editing `docker-compose.yml`, `Dockerfile`, `*.tf`, CI workflows, or runner configs (`--no-protect-tests` lifts this).
 
 ---
 
@@ -67,6 +106,13 @@ uap deliver "trivial typo fix"           --no-auto     # disable dynamic optimiz
 | `--escalate-model <preset>` | Stronger model for escalation (default `$UAP_ESCALATE_MODEL`) |
 | `--temperature <t>` | Sampling temperature (default: execution-profile value) |
 | `--gates <ids>` | Gate subset: `build,typecheck,test,lint` |
+| `--tiers <list>` | Explicit local tiers to run, e.g. `fast,integration,deploy-dev` (overrides auto-detection) |
+| `--integration` / `--no-integration` | Run the integration tier (on by default when a suite is detected) |
+| `--deploy-dev` / `--no-deploy-dev` | Run a local dev deploy + smoke tier (compose up → smoke → teardown) |
+| `--watch-ci` | After local-green, commit + push the worktree branch and watch CI; re-converge on failure |
+| `--until-deployed` | Imply `--watch-ci` and require CI + staging/prod deploy jobs green before exiting 0 |
+| `--ci-passes <n>` | Max CI re-converge passes on failure (1–10, default `2`) |
+| `--ci-timeout <minutes>` | CI watch budget in minutes (1–120, default `20`) |
 | `--candidates <n>` | Best-of-N exploration: candidates per turn (2–8) |
 | `--critic` | Structured critique of failed turns |
 | `--practices` / `--no-semantic` | Inject/record best-practice cards (keyword retrieval with `--no-semantic`) |

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.40.0.
+> Version v1.48.0.
 
 The `uap` binary is the single entry point for every UAP capability: project
 initialization, the tiered memory system, git worktree workflow, multi-agent
@@ -97,13 +97,23 @@ uap setup [options]
 | `-p, --platform <platforms...>` | Targets: `claude`, `factory`, `vscode`, `opencode`, `omp`, `cline`, `codex`, `aider`, `continue`, `windsurf`, `zed`, `copilot`, `jetbrains`, `swe-agent`, `all` (default `all`) |
 | `--no-patterns` | Skip pattern RAG setup |
 | `--no-memory` | Skip memory system setup |
+| `--no-self-update` | Skip the automatic UAP CLI version check / self-update (also `UAP_NO_SELF_UPDATE=1`) |
 | `--systemd-services` | Scaffold user systemd services for llama.cpp + anthropic proxy |
 | `-d, --project-dir <path>` | Target project directory (defaults to cwd) |
 | `-i, --interactive` | Run the interactive setup wizard with feature toggles |
 
+Before configuring the project, `setup` ensures the **globally-installed UAP CLI
+is at the latest published npm version** and self-updates if it is behind. It is
+safe and non-fatal: it only updates a real global install (a source checkout or a
+local/monorepo dependency is left untouched), is downgrade-proof, and is
+**skipped in CI** for reproducibility (`UAP_SELF_UPDATE=1` forces it). The update
+takes effect on the next `uap` invocation. Disable with `--no-self-update` or
+`UAP_NO_SELF_UPDATE=1`.
+
 ```bash
 uap setup -i
 uap setup -p claude -d ~/projects/myapp
+uap setup --no-self-update          # configure without touching the global CLI
 ```
 
 ---
@@ -293,6 +303,13 @@ uap deliver <instruction...> [options]
 | `--endpoint <url>` | Override the model endpoint (OpenAI-compatible `/v1`) |
 | `--temperature <t>` | Sampling temperature (default: execution-profile value) |
 | `--gates <ids>` | Comma-separated gate subset: `build,typecheck,test,lint` |
+| `--tiers <list>` | Local tiers to run: `fast,integration,deploy-dev` (overrides auto-detection) |
+| `--integration` / `--no-integration` | Run the integration tier (on by default when `test:integration`/`test:e2e`/pytest marker is detected) |
+| `--deploy-dev` / `--no-deploy-dev` | Run a local dev deploy + smoke tier (compose up -> smoke -> teardown) |
+| `--watch-ci` | After local-green, commit + push the worktree branch and watch CI; re-converge on CI/deploy failure (never pushes master/main) |
+| `--until-deployed` | Imply `--watch-ci` and require CI + staging/prod deploy jobs green before exiting 0 |
+| `--ci-passes <n>` | Max CI re-converge passes on failure (1-10, default 2) |
+| `--ci-timeout <minutes>` | CI watch budget in minutes (1-120, default 20) |
 | `--candidates <n>` | Best-of-N exploration: candidates per turn (2-8) |
 | `--critic` | Structured critique of failed turns (extra model call per failure) |
 | `--practices` | Inject learned best-practice cards; record new ones on success |
@@ -316,9 +333,14 @@ uap deliver <instruction...> [options]
 ```bash
 uap deliver "add a /healthz endpoint with a test" --gates build,test
 uap deliver "refactor the auth module" --optimize --ceiling 20
+uap deliver "add the orders endpoint" --deploy-dev          # incl. local dev deploy+smoke
+uap deliver "add the orders endpoint" --until-deployed      # push, watch CI, verify staging/prod
 uap deliver "fix the failing CI" --dry-run
 ```
 
+See the [deliver guide](../guides/DELIVER.md#tiered-validation-gates-cheap-first)
+for the tiered gate model and the CI/deploy feedback loop.
+
 ---
 
 ## `harness`

package/package.json

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