@miller-tech/uap 1.183.2 → 1.184.0

package/docs/reference/CONFIGURATION_REFERENCE.md

@@ -26,6 +26,7 @@ uap config wizard               # interactive expert configurator (also: uap set
 - [Orchestrator & hands-free](#orchestration) — Long-task autonomy: decompose, resume, and loop-to-100%.
 - [Reactor (auto-apply)](#reactor) — Per-prompt injection of the matching experts, skills, and patterns.
 - [Design system](#design) — DESIGN.md interrogation and the hard token gate for UI work.
+- [Engineering principles](#principles) — How code should be written, and the backward-compatibility stance.
 - [Worktree workflow](#worktree) — Branch-per-feature isolation and auto-cleanup.
 - [Inference proxy tuning](#proxy) — Guardrails and context limits for a local model behind the proxy.
 - [Dashboard](#dashboard) — The live analytics server and its mutation token.
@@ -60,6 +61,18 @@ How local-model sessions are routed through delivery. `deliver` runs builds thro
 
 **Recommendation:** `deliver` when a local model does the writing (routes it through the verified loop); `advisory` for exploratory work.
 
+### `deliver.escalateModel`
+
+| | |
+|---|---|
+| **Where** | `.uap.json` |
+| **Type** | string |
+| **Default** | `null` |
+
+Stronger model id for deliver escalation ladders: repair passes, the phase-5 escalation tier, and the evaluator fallback. Same role as $UAP_ESCALATE_MODEL but persisted in .uap.json (reproducible).
+
+**Recommendation:** Point at your strongest available preset/model (e.g. an Opus cloud id) when the executor is a local model — stuck epics then escalate instead of re-splitting into the same wall.
+
 ### `UAP_ENFORCE_DELIVERY`
 
 | | |
@@ -100,6 +113,30 @@ Installs the runtime-verify Stop-hook: at end of turn it actually runs the chang
 
 **Recommendation:** Enable for any project with a runnable artifact — it catches "declared done but never ran". Safe on empty projects (it skips when nothing is runnable).
 
+### `delivery.userValidation`
+
+| | |
+|---|---|
+| **Where** | `.uap.json` |
+| **Type** | string |
+| **Default** | `block` |
+
+User-path validation gate: deliver runs the .uap/user-paths.json critical journeys through the real client (headless browser / HTTP / built CLI) as the terminal gate rung. block = DELIVERED requires them green; advisory = report only; off = disabled.
+
+**Recommendation:** Leave on block — it is the only gate that proves the artifact works for a real user, not just that tests pass.
+
+### `UAP_USER_VALIDATION`
+
+| | |
+|---|---|
+| **Where** | shell env |
+| **Type** | boolean |
+| **Default** | `true` |
+
+Runtime downgrade for the user-validation gate: `0` demotes block to advisory for this run only. Persisting `0` is blocked by the self-protect enforcer.
+
+**Recommendation:** Leave unset. Use inline `UAP_USER_VALIDATION=0 uap deliver ...` only to unblock a run where the gate itself misfires.
+
 ### `UAP_VERIFY_ON_STOP`
 
 | | |
@@ -112,6 +149,78 @@ Master switch for the runtime execution gate in the Stop hook. `0` bypasses it.
 
 **Recommendation:** Leave on (default). Set `0` only to unblock a session where the runtime gate misfires.
 
+### `fidelity.mode`
+
+| | |
+|---|---|
+| **Where** | `.uap.json` |
+| **Type** | enum (standard \| max) |
+| **Default** | `standard` |
+
+Maximum-fidelity mode. `max` flips every verification default to its strongest: raised verifier floor (runtime+integration), acceptance judge required, blocking vision review, and a fail-CLOSED visual gate — a delivery is accepted only when it builds, runs, looks right, and matches the spec. (`UAP_FIDELITY` overrides at runtime.)
+
+**Recommendation:** `max` when correctness matters more than speed (UI work, releases, hands-free autonomy). `standard` for fast exploratory iteration.
+
+### `UAP_FIDELITY`
+
+| | |
+|---|---|
+| **Where** | shell env |
+| **Type** | enum (standard \| max) |
+| **Default** | `standard` |
+
+Runtime override of `fidelity.mode`, read from the shell env by verify/deliver and the Python enforcers. Takes precedence over the config value.
+
+**Recommendation:** Set inline (`UAP_FIDELITY=max <cmd>`) to force max fidelity for one command without editing config.
+
+### `fidelity.visionMinScore`
+
+| | |
+|---|---|
+| **Where** | `.uap.json` |
+| **Type** | number |
+| **Default** | `6` |
+
+Minimum aesthetic score (0–10) the vision judge must give a rendered UI before it passes under `max` fidelity.
+
+**Recommendation:** 6 is a reasonable "looks like a real, polished app" bar. Raise toward 8 for design-critical surfaces; lower to 4 to only catch broken/blank UIs.
+
+### `fidelity.visualBaselines`
+
+| | |
+|---|---|
+| **Where** | `.uap.json` |
+| **Type** | boolean |
+| **Default** | `true` |
+
+Keep approved UI screenshots as regression baselines under `.uap/visual/baseline/` and block on visual drift beyond threshold on later runs.
+
+**Recommendation:** Leave on so accepted UIs are pinned against regressions. Disable for throwaway prototypes where every render legitimately differs.
+
+### `UAP_VISION_ENDPOINT`
+
+| | |
+|---|---|
+| **Where** | `.uap/proxy.env` |
+| **Type** | string |
+| **Default** | `` |
+
+Base URL of an OpenAI-compatible, image_url-capable endpoint used for aesthetic screenshot review (e.g. http://127.0.0.1:8080/v1). Defaults to the local model when set by setup.
+
+**Recommendation:** Point at your local vision-capable model so aesthetic review runs offline with no per-image cost.
+
+### `UAP_VISION_MODEL`
+
+| | |
+|---|---|
+| **Where** | `.uap/proxy.env` |
+| **Type** | string |
+| **Default** | `` |
+
+Model id sent to the vision endpoint for aesthetic review (e.g. qwen36-35b-a3b-iq4xs).
+
+**Recommendation:** Set by `uap setup` to your local vision model. Required for blocking vision review under `max` fidelity.
+
 ## Model routing
 
 <a id="routing"></a>Which model handles planning, execution, and review.
@@ -482,6 +591,58 @@ Hard-blocks UI edits that hardcode off-token colors or off-scale spacing.
 
 **Recommendation:** Enable once your DESIGN.md tokens are stable — it keeps the UI on-system automatically.
 
+## Engineering principles
+
+<a id="principles"></a>How code should be written, and the backward-compatibility stance.
+
+### `principles.enabled`
+
+| | |
+|---|---|
+| **Where** | `.uap.json` |
+| **Type** | boolean |
+| **Default** | `true` |
+
+Applies the engineering principles (simplest sufficient implementation, reuse over reinvention, no stopgaps, prior art first) to generated code.
+
+**Recommendation:** Leave on. Turn it off only if your project has its own conflicting house style.
+
+### `principles.compat`
+
+| | |
+|---|---|
+| **Where** | `.uap.json` |
+| **Type** | enum (ask \| preserve \| remove) |
+| **Default** | `ask` |
+
+Backward-compatibility stance. `remove` deletes obsolete paths outright; `preserve` keeps them working and migrates callers; `ask` (default) prompts once per session instead of guessing.
+
+**Recommendation:** Leave on `ask` unless the project's answer is settled. `remove` is for side projects — on anything published it tells the agent to delete migration paths.
+
+### `principles.maturity`
+
+| | |
+|---|---|
+| **Where** | `.uap.json` |
+| **Type** | enum (ask \| greenfield \| production) |
+| **Default** | `ask` |
+
+What breaking a caller costs. `production` adds caveats about existing callers and dependency cost; `greenfield` states the rules absolutely.
+
+**Recommendation:** Set `production` for anything with real users; `greenfield` for a fresh side project.
+
+### `principles.injectDeliver`
+
+| | |
+|---|---|
+| **Where** | `.uap.json` |
+| **Type** | boolean |
+| **Default** | `true` |
+
+Injects the compact principles block into deliver prompts, so generated code follows them rather than only the agent preamble.
+
+**Recommendation:** Leave on. Disable only if you are tight on prompt budget with a small-context model.
+
 ## Worktree workflow
 
 <a id="worktree"></a>Branch-per-feature isolation and auto-cleanup.
@@ -651,6 +812,66 @@ Dashboard data refresh interval in milliseconds (floor 250).
 
 **Recommendation:** 2000 is fine; lower for a more live feel at higher CPU cost.
 
+### `proxy.dashboard`
+
+| | |
+|---|---|
+| **Where** | `.uap.json` |
+| **Type** | boolean |
+| **Default** | `true` |
+
+Ride-along dashboard: `uap proxy ensure|start` also starts (or adopts) `uap dashboard serve`, and release/stop tears it down under the same ownership rules — so a session gets monitoring without running a second command. Only takes effect where the proxy itself runs (hooks gate on proxy.autostart).
+
+**Recommendation:** Leave on. Turn off if you prefer to run `uap dash serve` yourself, or the port is spoken for.
+
+### `UAP_PROXY_DASHBOARD`
+
+| | |
+|---|---|
+| **Where** | shell env |
+| **Type** | boolean |
+| **Default** | `true` |
+
+Force the ride-along dashboard on (1/on/true) or off (0/off/false). Wins over .uap.json proxy.dashboard.
+
+**Recommendation:** Use for one-off overrides; prefer `uap proxy dashboard on|off` for a durable project setting.
+
+### `UAP_DASH_PORT`
+
+| | |
+|---|---|
+| **Where** | shell env |
+| **Type** | number |
+| **Default** | `3847` |
+
+Port the ride-along dashboard binds and is probed on (1-65535). Does not change `uap dash serve --port`.
+
+**Recommendation:** Change only on a port clash; keep it consistent across sessions so adoption works.
+
+### `UAP_DASH_HOST`
+
+| | |
+|---|---|
+| **Where** | shell env |
+| **Type** | string |
+| **Default** | `localhost` |
+
+Interface the ride-along dashboard binds. `0.0.0.0` exposes it beyond this machine.
+
+**Recommendation:** Keep localhost. Bind wider only behind a trusted network, and set UAP_DASHBOARD_TOKEN when you do.
+
+### `UAP_DASH_HEALTH_WAIT_MS`
+
+| | |
+|---|---|
+| **Where** | shell env |
+| **Type** | number |
+| **Default** | `10000` |
+
+How long `uap proxy ensure` waits for the ride-along dashboard to serve before giving up.
+
+**Recommendation:** Lower it if session start feels slow on a cold dashboard; the proxy is unaffected either way.
+
 ## Token & time optimization
 
 <a id="optimization"></a>Context budgets, caching, batching, and parallelism.

package/docs/reference/PLATFORMS.md

@@ -66,6 +66,7 @@ platform's lifecycle events:
 | `pre-tool-use-bash.sh` | PreToolUse (Bash) | Dangerous-command guard — **blocks** force push, `terraform apply`, etc. |
 | `uap-policy-gate.sh` | PreToolUse | DB-driven policy gate (`policies.db` + `.policy-tools/*.py`). |
 | `post-tool-use-edit-write.sh` | PostToolUse (Edit/Write) | Build gate + backup reminder after edits. |
+| `post-tool-use-read.sh` | PostToolUse (Read/Grep/Glob) | Writes `.uap/read_log.state` — the evidence `codebase-read-before-plan` gates on. |
 | `pre-compact.sh` | PreCompact | Flushes a compaction marker to memory. |
 | `post-compact.sh` | PostCompact | Re-injects policy awareness after compaction. |
 | `stop.sh` | Stop | Completion-gate checklist + session cleanup. |

package/package.json

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

package/src/policies/schemas/policies/engineering-principles.md

@@ -0,0 +1,93 @@
+# engineering-principles
+
+**Category**: quality
+**Level**: RECOMMENDED
+**Enforcement Stage**: pre-exec
+**Tags**: quality, simplicity, architecture, dependencies, prior-art
+
+## Rule
+
+Write code to these principles. Rules 2-8 always apply. Rule 1 depends on a
+stance resolved per project per session — run `uap principles show` to see the
+form in force, and `uap principles ask` to answer it.
+
+1. **Backward compatibility — stance-dependent.**
+   - `remove`: delete obsolete paths instead of adding compatibility layers,
+     fallbacks, or migrations.
+   - `preserve`: keep existing paths working and migrate callers before
+     removing anything.
+
+   Under `remove`, these surfaces are still preserved and migrated, never
+   deleted, because their callers are not yours to update:
+   - the public CLI surface — command names, flags, and their output contracts
+   - MCP tool names and input schemas
+   - database, config, and on-disk state schemas, including their migrations
+   - exported types and public module entry points
+
+2. **Choose the simplest implementation that fully meets the current
+   requirements.** Avoid speculative abstractions, configuration, and
+   indirection.
+
+3. **Grow the system in layers.** Start from the smallest version that works end
+   to end, and add each new capability on top of a product that already works.
+   Never trade a working product for unfinished complexity.
+
+4. **Keep components modular and concerns clearly separated.**
+
+5. **Prefer established, well-maintained libraries** when they reduce overall
+   complexity or improve reliability. Do not reimplement common functionality
+   without a clear reason.
+
+6. **Lean on the dependencies already in the project** before writing your own
+   implementation or adding packages. Do not assume a library lacks a capability
+   without checking its documentation and types.
+
+7. **Make architectural decisions for the long term.** Do not accept a stopgap
+   that only works for now and is meant to be replaced later.
+
+8. **Study how established products solve the problem before designing a
+   solution.** Adopt their proven patterns and conventions rather than inventing
+   an approach from scratch.
+
+## Why
+
+Adapted from an AGENTS.md distilled from roughly 60B tokens of agent-driven
+coding (x.com/MarcosHernanz/status/2083954734487212511). Its author scopes it to
+side projects — "don't use it in production if you don't want to destroy your
+codebase" — and rule 1 is why: deleting obsolete paths is right when you own
+every caller and destructive when you do not. Rather than adopt or drop rule 1
+wholesale, UAP resolves it per project per session and carves out the surfaces
+other people are bound to.
+
+The remaining rules are direction-of-travel guidance, not gates. They are
+RECOMMENDED because a machine cannot tell a speculative abstraction from a
+necessary one, and a blocking check that guesses would cost more than it saves.
+
+## Enforcement
+
+Advisory. There is no Python enforcer: these are judgment calls, and blocking
+gates in this repo have repeatedly cost more in false positives than they
+prevented. The principles reach the model three other ways:
+
+- **Deliver prompts** — the compact form is injected into every convergence-loop
+  and orchestrated task prompt, so generated code is held to them rather than
+  only the agent's preamble.
+- **Reactor** — while the rule-1 stance is unresolved, the agent is told to ask
+  the user once; after that it stays silent.
+- **Judge** — competing candidates are scored on reuse-over-reimplementation and
+  absence of stopgaps.
+
+Related: pattern P38 (Prior Art First) covers rules 5, 6 and 8 at plan time; the
+`/simplify` and `distill` skills cover rule 2 on existing code.
+
+```rules
+- title: "Simplest implementation that meets the requirement"
+  keywords: [implement, refactor, design, abstraction, config, indirection]
+  antiPatterns: [speculative-abstraction, premature-config, needless-indirection]
+- title: "Reuse before reimplementation"
+  keywords: [library, dependency, package, util, helper, from scratch]
+  antiPatterns: [reimplemented-common-functionality, unchecked-library-capability]
+- title: "No stopgaps"
+  keywords: [temporary, for now, placeholder, replace later, quick fix]
+  antiPatterns: [stopgap-architecture, deferred-rewrite]
+```

package/templates/hooks/post-tool-use-read.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# UAP Read Logger — INFORMATIONAL hook
+# Event: PostToolUse (matcher: Read|Grep|Glob)
+# Appends "<epoch>\t<path>" to .uap/read_log.state, which is the evidence the
+# codebase-read-before-plan enforcer checks before allowing a plan to be emitted.
+#
+# Without this hook that enforcer has no writer: the log goes stale, every entry
+# ages past its 30-minute window, and ExitPlanMode is blocked permanently with a
+# remedy ("read the codebase first") that can never be satisfied.
+#
+# Runs on EVERY Read/Grep/Glob — thousands of times a session, in the latency
+# path of each one — so it does its work in bash builtins and forks exactly once
+# (jq, which earns it: the payload shape differs per tool).
+#
+# Always exits 0 (never blocks).
+set -uo pipefail
+
+# Drain stdin without forking `cat`. `read -d ''` returns non-zero at EOF while
+# still populating INPUT, so the failure is expected, not an error.
+IFS= read -r -d '' INPUT || true
+[ -n "${INPUT:-}" ] || exit 0
+
+# Read passes file_path; Grep/Glob pass path (search root) and/or pattern.
+TARGET=$(jq -r '
+  .tool_input.file_path // .tool_input.filePath // .tool_input.path // .tool_input.pattern // empty
+' 2>/dev/null <<< "$INPUT" || true)
+[ -n "$TARGET" ] || exit 0
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+STATE_DIR="${UAP_STATE_DIR:-${PROJECT_DIR}/.uap}"
+LOG="${STATE_DIR}/read_log.state"
+
+[ -d "$STATE_DIR" ] || mkdir -p "$STATE_DIR" 2>/dev/null || exit 0
+
+# SECURITY: never append through a symlink. `>>` follows links, so a symlink
+# planted at read_log.state would turn every file read in the session into an
+# append to whatever it points at (~/.bashrc), with partly model-supplied
+# content — an arbitrary-file-write primitive that escapes workdir-scope
+# entirely. Writing the evidence is optional; this is not.
+[ -L "$LOG" ] && exit 0
+
+# Store project-relative where possible so entries stay readable across worktrees.
+REL="${TARGET#"$PROJECT_DIR"/}"
+# SECURITY: a record is "<epoch>\t<path>\n" and TARGET is model-supplied — a Grep
+# pattern may legally contain tabs and newlines. Strip the two characters that
+# frame a record so a crafted pattern cannot forge additional log entries (and
+# thereby forge the gate evidence this file exists to provide).
+REL="${REL//$'\t'/ }"
+REL="${REL//$'\n'/ }"
+REL="${REL//$'\r'/ }"
+
+printf -v NOW '%(%s)T' -1   # bash builtin; no `date` fork
+printf '%s\t%s\n' "$NOW" "$REL" >> "$LOG" 2>/dev/null || exit 0
+
+# Bound the file. The enforcer only ever looks at a 30-minute window, so old
+# lines are dead weight. Sampled rather than checked every call: reading the log
+# on every Read to decide whether to trim costs more than the occasional
+# overshoot, and the consumer filters by timestamp anyway.
+if (( RANDOM % 50 == 0 )); then
+  mapfile -t _lines < "$LOG" 2>/dev/null || exit 0
+  if (( ${#_lines[@]} > 400 )); then
+    # PID-unique temp: several agents share one project, and a shared temp name
+    # lets two concurrent trims interleave into one file and lose entries.
+    if printf '%s\n' "${_lines[@]: -200}" > "${LOG}.tmp.$$" 2>/dev/null; then
+      mv "${LOG}.tmp.$$" "$LOG" 2>/dev/null || rm -f "${LOG}.tmp.$$" 2>/dev/null
+    else
+      rm -f "${LOG}.tmp.$$" 2>/dev/null
+    fi
+  fi
+fi
+
+exit 0