@miller-tech/uap 1.40.0 → 1.41.0

package/docs/guides/MULTI_MODEL.md

@@ -0,0 +1,223 @@
+# Multi-Model Routing
+
+> Applies to UAP **v1.40.0**
+
+UAP runs agentic work across multiple LLMs instead of one. A high-capability
+model plans, a cheaper or local model executes, and a reviewer model checks the
+result. Routing decisions are made per task (and per subtask) so you pay for
+expensive reasoning only when the work actually needs it.
+
+## Why multi-model
+
+A single frontier model is the simplest setup, but most of the tokens an agent
+spends are on routine execution — applying an edit, running a tool, writing a
+test — not on hard reasoning. Sending all of that to a premium model is
+expensive and slow.
+
+Multi-model routing lets you:
+
+- Use a strong **planner** (e.g. Claude Opus) for decomposition and review.
+- Use a cheap or **local executor** (e.g. Qwen 3.5 on llama.cpp) for the bulk
+  of the work, at near-zero marginal cost.
+- Fall back to another model automatically when the executor struggles.
+- Pick a routing strategy that trades cost against quality on your terms.
+
+## The 3-tier plan → route → execute flow
+
+UAP separates planning, routing, and execution into three components:
+
+1. **TaskPlanner** (`src/models/planner.ts`) — decomposes a task into subtasks.
+   It classifies the task's complexity, and for non-trivial work it breaks the
+   task into ordered subtasks with inputs, outputs, and constraints. Every plan
+   is auto-validated by a plan validator (`src/models/plan-validator.ts`) at all
+   complexity levels before it is returned.
+
+2. **ModelRouter** (`src/models/router.ts`) — assigns a model to the overall
+   task and to each subtask. It classifies the task by complexity and type,
+   applies the routing rules, and selects a model for the matched role
+   (planner / executor / reviewer / fallback). Classification results are cached
+   to avoid repeated work on near-identical task descriptions.
+
+3. **TaskExecutor** (`src/models/executor.ts`) — executes the plan. Subtasks run
+   with a bounded level of parallelism, each call has retry-with-backoff logic
+   (`retryDelayMs`, default 1000 ms), and failed attempts feed retry context
+   into subsequent tries. The executor produces per-subtask results and a
+   run summary.
+
+The router and planner are wired together by the CLI and the programmatic API
+(`createRouter`, `createPlanner`, `createExecutor` from `src/models/index.js`).
+
+## The model presets
+
+The router ships with built-in presets (`ModelPresets` in
+`src/models/types.ts`). These are the ids you reference in role assignments and
+in `uap model` output:
+
+| Preset id      | Name                      | Provider  | Context  | $/1M in | $/1M out | Capabilities                                                    |
+| -------------- | ------------------------- | --------- | -------- | ------- | -------- | -------------------------------------------------------------- |
+| `opus-4.6`     | Claude Opus 4.6           | anthropic | 200,000  | 7.5     | 37.5     | planning, complex-reasoning, code-generation, review, advanced-planning |
+| `sonnet-4.6`   | Claude Sonnet 4.6         | anthropic | 200,000  | 3.0     | 15.0     | code-generation, execution, review, agentic                    |
+| `haiku`        | Claude Haiku (Latest)     | anthropic | 200,000  | 0.8     | 4.0      | code-generation, execution, simple-tasks                       |
+| `qwen35-a3b`   | Qwen 3.5 35B A3B (llama.cpp) | custom | 262,144  | 0       | 0        | code-generation, execution, planning, simple-tasks             |
+| `gpt-5.4`      | GPT 5.4                   | openai    | 128,000  | 2.5     | 10.0     | planning, code-generation, complex-reasoning                   |
+| `gpt-5.3-codex`| GPT 5.3 Codex             | openai    | 192,000  | 3.0     | 12.0     | code-generation, execution, complex-reasoning, agentic         |
+
+Run `uap model presets` to print the live list.
+
+### Runtime profiles
+
+In addition to the presets above, UAP ships seven detailed JSON **profiles** in
+[`config/model-profiles/`](../../config/model-profiles/). These carry richer
+runtime settings the presets lack — pricing tiers, rate limits, tool-calling
+options, extended-thinking budgets, server-optimization flags, and ready-to-run
+launch commands:
+
+| Profile (`_profile`) | `model` id                 | Provider  | Context  |
+| -------------------- | -------------------------- | --------- | -------- |
+| `claude-opus-4.6`    | `claude-opus-4-6-20250616` | anthropic | 200,000  |
+| `claude-sonnet-4.6`  | `claude-sonnet-4-6-20250514` | anthropic | 200,000 |
+| `claude-haiku-3.5`   | `claude-3-5-haiku-20241022` | anthropic | 200,000 |
+| `gpt-5.4`            | `gpt-5.4`                  | openai    | 128,000  |
+| `gpt-5.3-codex`      | `gpt-5.3-codex`            | openai    | 192,000  |
+| `qwen35`             | `qwen3.5-a3b-iq4xs`        | custom (llama.cpp) | 262,144 |
+| `generic`            | `default`                  | any OpenAI-compatible | 32,768 |
+
+The active profile is selected by the `UAP_MODEL_PROFILE` environment variable
+(defaults to `generic`). The loader lives in `src/models/profile-loader.ts`.
+
+## How routing decides
+
+The router first classifies the task, then applies rules.
+
+**Complexity** is inferred from keywords. Examples (from
+`COMPLEXITY_KEYWORDS` in `src/models/router.ts`):
+
+- `critical` — security, authentication, authorization, deployment, migration,
+  production, database, encryption, credentials, secrets
+- `high` — architecture, design, refactor, performance, optimization,
+  algorithm, distributed, concurrent, multi-step, complex
+- `medium` — feature, implement, add, create, update, integrate, api, endpoint
+- `low` — fix, typo, comment, rename, format, style, simple, minor, quick,
+  documentation
+
+**Task type** is inferred similarly: `planning`, `coding`, `refactoring`,
+`bug-fix`, `review`, `documentation`.
+
+**Routing rules** (`DEFAULT_ROUTING_RULES`) map complexity/type to a role by
+priority (higher wins):
+
+| Match                                                       | Role       | Priority |
+| ---------------------------------------------------------- | ---------- | -------- |
+| complexity `critical`                                      | planner    | 100      |
+| keywords: security, authentication, deployment, migration | planner    | 90       |
+| complexity `high`                                          | planner    | 80       |
+| keywords: architecture, design, refactor                  | planner    | 70       |
+| task type `planning`                                       | planner    | 70       |
+| task type `review`                                         | reviewer   | 60       |
+| complexity `medium`                                        | executor   | 50       |
+| task type `coding`                                         | executor   | 50       |
+| task type `bug-fix`                                        | executor   | 50       |
+| complexity `low`                                           | executor   | 30       |
+| task type `documentation`                                  | executor   | 30       |
+
+The matched role is resolved to a concrete model via your role assignments.
+
+**Routing strategy** further shapes selection. Four strategies are supported
+(`routingStrategy`, default `balanced`):
+
+- `cost-optimized` — minimize cost, use the cheapest capable model
+- `performance-first` — maximize quality, use the best model
+- `balanced` — balance cost and performance (default)
+- `adaptive` — learn from task results over time
+
+## The `uap model` CLI
+
+All subcommands are defined in `src/cli/model.ts`.
+
+```bash
+uap model status              # show configured models, role assignments, strategy
+uap model route <task>        # analyze how a task would be routed
+uap model route <task> -v     # + matched rules and cost comparison
+uap model plan <task>         # build an execution plan (decomposition + assignments)
+uap model plan <task> -v      # + per-subtask detail
+uap model plan <task> -e      # execute the plan (mock client unless API keys set)
+uap model compare             # compare cost/performance across sample configs
+uap model presets             # list all built-in model presets
+uap model select              # interactively assign models to each role
+uap model select --save       # persist the selection to .uap.json
+uap model export              # print current config as JSON
+uap model export -f yaml      # ... or YAML
+uap model health              # validate that assigned models exist and resolve
+```
+
+Example — see how a task routes:
+
+```bash
+uap model route "add OAuth2 login with JWT sessions" --verbose
+```
+
+This prints the inferred complexity, task type, the selected and fallback
+models, the matched rules, and an estimated cost comparison.
+
+## Configuring profiles
+
+### Role assignments
+
+Configure the multi-model setup under `multiModel` in your `.uap.json`. The
+default configuration is:
+
+```json
+{
+  "multiModel": {
+    "enabled": true,
+    "models": ["opus-4.6", "qwen35-a3b"],
+    "roles": {
+      "planner": "opus-4.6",
+      "executor": "qwen35-a3b",
+      "fallback": "qwen35-a3b"
+    },
+    "routingStrategy": "balanced"
+  }
+}
+```
+
+A `reviewer` role is also supported; if unset it falls back to the planner.
+You can add `costOptimization` (with `targetReduction`,
+`maxPerformanceDegradation`, and `fallbackThreshold`) when using a
+cost-oriented strategy.
+
+The fastest way to edit this is interactively:
+
+```bash
+uap model select --save
+```
+
+### Runtime profile + endpoints
+
+Pick a runtime profile and provide credentials/endpoints via environment
+variables (see each file's `running_config` in
+[`config/model-profiles/`](../../config/model-profiles/)):
+
+```bash
+# Anthropic-hosted models
+export ANTHROPIC_API_KEY=<your-key>
+export UAP_MODEL_PROFILE=claude-opus-4.6
+
+# OpenAI-hosted models
+export OPENAI_API_KEY=<your-key>
+export UAP_MODEL_PROFILE=gpt-5.4
+
+# Local / any OpenAI-compatible server
+export TARGET_URL=http://127.0.0.1:8080
+export UAP_MODEL_PROFILE=generic
+```
+
+To customize a model's runtime behavior — temperature, tool-call batching,
+extended-thinking budget, rate limits, or server-optimization flags — edit the
+corresponding JSON file in `config/model-profiles/`. Each file is documented
+inline with `_comment` fields.
+
+## See also
+
+- [Droids and Skills](./DROIDS_AND_SKILLS.md) — specialist agents and reusable
+  workflows that run on top of the routed models.

package/docs/guides/POLICIES.md

@@ -0,0 +1,190 @@
+# Policies
+
+> Applies to UAP v1.40.0
+
+UAP policies are **executable gates, not prose**. Each policy can carry a Python
+enforcer that inspects an operation and decides whether it may proceed. A
+`PreToolUse` hook queries the policy store and runs the relevant enforcers
+before a tool call executes; an enforcer that exits with status `2` blocks the
+call.
+
+The engine lives in
+[`src/policies/policy-gate.ts`](../../src/policies/policy-gate.ts); enforcers
+live in [`src/policies/enforcers/`](../../src/policies/enforcers/); the CLI is
+in [`src/cli/policy.ts`](../../src/cli/policy.ts).
+
+## The policy-gate model
+
+The flow is **hook to DB to enforcer to block**:
+
+1. **Hook** — A `PreToolUse` hook fires before a tool call (Edit, Write, Bash,
+   etc.). Tools registered through the enforced tool router
+   ([`src/policies/enforced-tool-router.ts`](../../src/policies/enforced-tool-router.ts))
+   are automatically routed through the policy gate.
+2. **DB** — The gate
+   ([`PolicyGate`](../../src/policies/policy-gate.ts)) loads all active policies
+   from the policy store (a SQLite-backed DB, cached with a short TTL) and
+   filters them to the ones matching the current enforcement stage
+   (`pre-exec`, `post-exec`, `review`, or `always`).
+3. **Enforcer** — Each matching policy that has an attached Python enforcer is
+   invoked as `python3 <enforcer>.py --operation <op> --args <json>`. Enforcers
+   receive the operation name and its arguments and return a JSON verdict.
+4. **Block** — An enforcer emits `{"allowed": true, ...}` and exits `0` to
+   allow, or `{"allowed": false, "reason": ...}` and **exits `2` to block** (see
+   the shared `emit()` helper in
+   [`src/policies/enforcers/_common.py`](../../src/policies/enforcers/_common.py)).
+   When a `REQUIRED` policy blocks, the gate raises a `PolicyViolationError` and
+   the tool call never runs. Every check is written to an audit trail.
+
+Task-completion operations (anything that looks like merge / deploy / release /
+"mark done") are automatically re-checked at the `review` stage, so completion
+gates fire even if the operation was issued at `pre-exec`.
+
+### Cooperative-guardrail caveat
+
+The policy gate is a **cooperative-agent guardrail, not a hard security
+boundary.** It steers well-behaved agents away from unsafe or out-of-process
+actions; it does not sandbox a hostile process. Enforcers also honor explicit
+overrides (for example the `worktree-required` enforcer respects
+`UAP_NO_WORKTREE=1`). Treat policies as guardrails that keep cooperating agents
+on the rails — not as a containment mechanism against untrusted code.
+
+## The enforcers
+
+The enforcers in
+[`src/policies/enforcers/`](../../src/policies/enforcers/) group as follows.
+`_common.py` is shared helper code, not an enforcer.
+
+### Workflow & isolation
+
+| Enforcer | What it gates |
+|----------|---------------|
+| `worktree_required` | Edit/Write/MultiEdit must target a `.worktrees/` path |
+| `task_required` | A UAP task must be `in_progress` before mutating work |
+| `coord_overlap` | Checks for in-flight agent path reservations (parallel-agent overlap) |
+| `delivery_enforcement` | Route substantive coding through `uap deliver` |
+
+### Plan discipline
+
+| Enforcer | What it gates |
+|----------|---------------|
+| `memory_before_plan` | Plans require a recent `uap memory query` |
+| `codebase_read_before_plan` | Plans require prior reads of the target paths |
+| `validate_plan_before_build` | A plan must be validated before building |
+
+### Quality & review gates
+
+| Enforcer | What it gates |
+|----------|---------------|
+| `test_gate` | Changed services need accompanying test deltas |
+| `schema_diff_gate` | Schema/pool changes must pass `uap schema-diff` |
+| `expert_review_required` | A parallel expert review must precede ship |
+| `architecture_review` | Merge / PR-ready operations need an architecture review when the diff warrants it |
+
+### Hygiene & artifacts
+
+| Enforcer | What it gates |
+|----------|---------------|
+| `artifact_hygiene` | Block binary artifacts outside curated directories |
+| `doc_live_over_report` | Block new `*_REPORT` / `*_COMPLETE` / `*_SUMMARY` / `*_PLAN` markdown files |
+| `session_memory_write` | Code-changing sessions must write a lesson to memory |
+
+### Tooling & routing
+
+| Enforcer | What it gates |
+|----------|---------------|
+| `mcp_router_first` | MCP tools must be loaded on demand |
+| `rtk_wrap` | Heavy CLIs must be invoked via `rtk` |
+| `parallel_reads` | Nudge when serial read fan-out is detected |
+
+### Infrastructure
+
+| Enforcer | What it gates |
+|----------|---------------|
+| `iac_parity` | Live-state changes must have a matching infrastructure-as-code diff |
+| `cluster_routing` | Cluster tooling context must match the component domain |
+
+> The `architecture_review` enforcer file is stored with a policy-ID prefix
+> (`<uuid>_architecture_review.py`) because it is attached to a specific
+> installed policy; the others are named directly after their policy slug.
+
+## The `uap policy` CLI
+
+All commands are subcommands of `uap policy`, implemented in
+[`src/cli/policy.ts`](../../src/cli/policy.ts).
+
+### Inspect
+
+```bash
+uap policy list      # list all policies with status, level, category, stage, version
+uap policy status    # summary of enabled/disabled plus enforcement stages
+```
+
+### Install & attach
+
+`install` reads a built-in policy markdown file and stores it. If a Python
+enforcer with the matching name lives in `src/policies/enforcers/`, it is
+auto-attached.
+
+```bash
+uap policy install worktree-enforcement
+```
+
+Add a policy from an arbitrary markdown file, or attach tool code to an existing
+policy:
+
+```bash
+uap policy add --file ./my-policy.md --category custom --level RECOMMENDED --tags "a,b"
+uap policy add-tool --policy <id> --tool <name> --code ./enforcer.py
+```
+
+### Enable / disable / toggle
+
+```bash
+uap policy enable <id>      # turn a policy on
+uap policy disable <id>     # turn a policy off
+uap policy toggle <id>      # flip current state
+uap policy toggle <id> --on
+uap policy toggle <id> --off
+```
+
+### Tune enforcement
+
+```bash
+uap policy level <id> --level REQUIRED      # REQUIRED | RECOMMENDED | OPTIONAL
+uap policy stage <id> --stage pre-exec      # pre-exec | post-exec | review | always
+```
+
+Only `REQUIRED` policies can block an operation; `RECOMMENDED` and `OPTIONAL`
+checks are recorded but do not deny the call.
+
+### Check & audit
+
+```bash
+uap policy check --operation Write --args '{"file_path":"src/x.ts"}'   # dry-run a gate
+uap policy audit --limit 20                                            # enforcement audit trail
+uap policy audit --policy <id>                                         # filter to one policy
+```
+
+### Other
+
+```bash
+uap policy get-relevant --task "ship the api" --top 3     # context-relevant policies
+uap policy convert --input <id|file.md> --output out.md   # render to CLAUDE.md format
+```
+
+## How to add, enable, and disable a policy
+
+1. **Author** a policy markdown file (and, optionally, a Python enforcer named
+   after the policy slug with hyphens replaced by underscores).
+2. **Install / add** it: `uap policy install <name>` for a built-in, or
+   `uap policy add --file <path>` for a custom one. A co-located enforcer is
+   auto-attached on install; otherwise attach it with `uap policy add-tool`.
+3. **Set its teeth**: `uap policy level <id> --level REQUIRED` so it can block,
+   and `uap policy stage <id> --stage <stage>` to choose when it fires.
+4. **Enable / disable** at any time with `uap policy enable <id>` /
+   `uap policy disable <id>` (or `toggle`). Disabled policies are skipped by the
+   gate entirely.
+
+Changes invalidate the gate's policy cache immediately, so they take effect on
+the next tool call.

package/docs/guides/WORKTREE_WORKFLOW.md

@@ -0,0 +1,185 @@
+# Worktree Workflow
+
+> Applies to UAP v1.40.0
+
+UAP runs agents — often many of them at once — against a single repository. The
+worktree workflow exists to keep every edit an agent makes isolated on its own
+branch and its own checkout, so that agent work never touches the project root
+and parallel agents never collide. This guide explains why that matters, walks
+through the full lifecycle, and documents every `uap worktree` subcommand.
+
+The implementation lives in [`src/cli/worktree.ts`](../../src/cli/worktree.ts).
+
+## Why isolation matters
+
+When an agent edits files directly in the project root, three problems appear:
+
+- **Cross-contamination** — a half-finished change sits in the working tree
+  where the next operation (build, test, another agent) can trip over it.
+- **No clean PR boundary** — there is no branch that contains *only* this unit
+  of work, so review and rollback become guesswork.
+- **Parallel collisions** — two agents writing to the same files at the same
+  time produce corrupt, non-deterministic state.
+
+A git worktree solves all three. Each feature gets its own directory under
+`.worktrees/NNN-<slug>/` backed by its own branch (`feature/NNN-<slug>`). An
+agent works entirely inside that directory; the project root stays clean, and
+any number of worktrees can be active simultaneously without interfering.
+
+## The lifecycle
+
+```
+uap worktree create <slug>     # 1. isolate: new branch + checkout under .worktrees/NNN-<slug>/
+cd .worktrees/NNN-<slug>/      # 2. work: all edits happen here
+uap worktree pr <id>           # 3. publish: sync with master, push, open a PR
+uap worktree finish <id>       # 4. land: sync, push, merge the PR, then clean up
+# (or) uap worktree cleanup <id>   manual teardown without merging
+```
+
+1. **Create** — `create` allocates the next numeric ID from a registry,
+   builds the branch name `feature/NNN-<slug>`, and runs
+   `git worktree add -b <branch> .worktrees/NNN-<slug> <base>`. The base branch
+   defaults to your current branch (override with `--from`). The new worktree is
+   recorded in a SQLite registry at `.uap/worktree_registry.db` so concurrent
+   `create` calls never race on the same ID.
+2. **Work** — `cd` into the worktree and make changes. Everything stays on the
+   feature branch and inside the worktree directory.
+3. **Publish** — `pr` syncs the branch with `origin/master` (a clean merge, or a
+   clear failure asking you to resolve conflicts in the worktree), pushes the
+   branch, and opens a PR via the `gh` CLI.
+4. **Land** — `finish` does the full sync → push → ensure-PR → merge sequence,
+   deletes the remote branch, then runs `cleanup` for you.
+5. **Clean up** — `cleanup` removes the worktree, deletes the local and remote
+   branch, and marks the registry entry as `cleaned`.
+
+## The enforcement gate
+
+`uap worktree ensure --strict` is the gate used by CI and by the per-edit
+hook. It checks whether the current working directory is inside a
+`.worktrees/` path and exits non-zero if it is not:
+
+```bash
+uap worktree ensure --strict   # exit 0 inside a worktree, exit 1 otherwise
+```
+
+In strict mode, when you are *not* in a worktree, it prints the remediation and
+fails hard:
+
+```
+NOT in a worktree. All file edits are prohibited.
+  Run: uap worktree create <slug>
+  Then: cd .worktrees/<id>-<slug>/
+```
+
+Without `--strict`, `ensure` is advisory: it lists active worktrees (flagging
+any sitting on `master`/`main`) and suggests next steps instead of exiting
+non-zero. The strict variant is what you wire into a CI step or a pre-edit
+check; the advisory variant is for interactive orientation.
+
+The same `.worktrees/` containment is enforced at edit time by the
+`worktree-required` policy enforcer — see [POLICIES.md](./POLICIES.md).
+
+## Parallel-agent safety
+
+The numeric ID is allocated from the SQLite registry, not from a directory
+scan, so two agents calling `create` at the same moment get distinct IDs and
+distinct branches. Because each agent operates in its own worktree directory on
+its own branch, their edits, builds, and commits are fully isolated — the only
+shared point is `origin/master`, which each branch syncs against at `pr`/`finish`
+time. This is what makes conflict-free parallel agent execution possible.
+
+## Command reference
+
+All commands are subcommands of `uap worktree`, registered in
+[`src/bin/cli.ts`](../../src/bin/cli.ts) and implemented in
+[`src/cli/worktree.ts`](../../src/cli/worktree.ts).
+
+### `create <slug>`
+
+Create a new worktree and feature branch for `<slug>`.
+
+| Flag | Description |
+|------|-------------|
+| `-f, --from <branch>` | Base branch (defaults to the current branch) |
+| `-d, --description <description>` | Optional worktree description |
+
+```bash
+uap worktree create add-user-auth
+uap worktree create fix-login-bug --from master
+```
+
+Produces a branch `feature/NNN-add-user-auth` and a checkout at
+`.worktrees/NNN-add-user-auth/`, where `NNN` is the next zero-padded ID.
+
+### `list`
+
+List all git worktrees under `.worktrees/`, with their ID, name, branch, and
+path.
+
+```bash
+uap worktree list
+```
+
+### `pr <id>`
+
+Create a pull request from the worktree identified by `<id>`. Syncs the branch
+with `origin/master`, pushes it, then runs `gh pr create --fill`.
+
+| Flag | Description |
+|------|-------------|
+| `--draft` | Create the PR as a draft |
+
+```bash
+uap worktree pr 7
+uap worktree pr 7 --draft
+```
+
+### `finish <id>`
+
+End-to-end landing: sync with `origin/master`, push, ensure a PR exists, merge
+it (`gh pr merge --merge`), delete the remote branch, and then clean up the
+worktree.
+
+```bash
+uap worktree finish 7
+```
+
+### `cleanup <id>`
+
+Remove the worktree directory, delete the local and remote branch, and mark the
+registry entry as `cleaned`. Use this to tear down a worktree without merging.
+
+```bash
+uap worktree cleanup 7
+```
+
+### `ensure`
+
+Check whether you are working inside a worktree.
+
+| Flag | Description |
+|------|-------------|
+| `--strict` | Exit with code 1 if not in a worktree (for use as a gate) |
+
+```bash
+uap worktree ensure            # advisory: list options
+uap worktree ensure --strict   # gate: exit non-zero if not in a worktree
+```
+
+### `prune`
+
+Prune stale worktrees from the registry and disk.
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-o, --older-than <days>` | Only prune worktrees older than N days | `30` |
+| `-f, --force` | Skip the confirmation prompt | off |
+| `-n, --dry-run` | Preview without making changes | off |
+
+```bash
+uap worktree prune --dry-run
+uap worktree prune --older-than 14 --force
+```
+
+Stale worktrees are selected by age from the registry; pruning deletes the
+worktree directory and removes the registry row.