@miller-tech/uap 1.108.0 → 1.109.0

package/docs/INDEX.md

@@ -41,6 +41,7 @@ Full map: **[The UAP Delivery Pipeline](guides/DELIVERY_PIPELINE.md)**.
 | [**The Delivery Pipeline**](guides/DELIVERY_PIPELINE.md) | The station-by-station tour — the big-picture map of the whole floor ⭐ |
 | [**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 Build+QC harness — convergence loop to verified completion, tiered gates, CI/deploy feedback loop ⭐ |
+| [**Orchestrator & Hands-Free**](guides/ORCHESTRATOR.md) | The long-task autonomy layer — blackboard orchestrator, epic controller, completion ledger, auto-seed/resume; any model runs a huge build to 100% hands-free ⭐ |
 | [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/design/SELF_HARNESS.md

@@ -60,9 +60,10 @@ mine→propose→validate→accept and persists results. Humans do both today.
                                    key=(model_family, failure_sig)        (env + scaffold snapshot)
 ```
 
-New code lives under `src/self-harness/`: `orchestrator.ts`, `mine.ts`, `propose.ts`, `mods.ts` (the
-DSL), `apply.ts`, `transfer.ts`, plus `uap self-harness` CLI. It **reuses** `benchmarks/paired/` for
-validation and the HALO exporter for mining — no reimplementation.
+New code lives under `src/self-harness/`: `orchestrator.ts` (one iteration), `validate.ts` (the real
+paired-bench validator), `run.ts` (the committing loop + versioned snapshot), `mine.ts`, `propose.ts`,
+`mods.ts` (the DSL), `transfer.ts`, plus the `uap self-harness` CLI. It **reuses** `benchmarks/paired/`
+for validation and the HALO exporter for mining — no reimplementation.
 
 ## 4. The Modification DSL — bounded, typed, reversible
 
@@ -171,9 +172,15 @@ Controls:
 - **P0 — Plumbing (small).** Promote the failure-mode logs to structured HALO spans; add the held-out
   regression suite; pin a stable `signature` hashing. *Exit:* `uap harness analyze` emits a typed
   `WeaknessReport`.
-- **P1 — Closed loop, env+scaffold DSL (Option A).** `uap self-harness run` orchestrating
-  mine→propose→validate→accept over `env`+`scaffold` Mods, reusing `benchmarks/paired/`. *Exit:* one
-  autonomous iteration that accepts a real Mod (e.g. re-discovers `LLAMA_N_PREDICT=4096`) with stats.
+- **P1 — Closed loop, env DSL (Option A). [BUILT]** `uap self-harness run` orchestrates
+  mine→propose→validate→decide over `env` Mods, reusing `benchmarks/paired/`. The real validator
+  (`validate.ts`) runs a baseline arm, physically toggles the env knob + restarts the server, runs a
+  candidate arm, reverts, and pairs the two into a `Comparison`; held-out runs the same way. `--apply`
+  commits accepted Mods to the env file, restarts once, and writes a **versioned profile snapshot**
+  (`run.ts`, `profile.ts`) + append-only history; without it the run is a pure dry-run that touches
+  nothing. *Exit met:* one autonomous iteration accepts a real env Mod (e.g. re-discovers
+  `LLAMA_N_PREDICT=4096`) with paired stats. `scaffold`/`middleware` Mods are not auto-validated here —
+  they route through the human-gated pending queue (§9).
 - **P2 — Middleware Mods (Option B).** Add the `middleware` Mod class + the `toolcall-path-normalizer`.
   *Exit:* the loop proposes+validates the normalizer and measurably cuts path-garbling on the medium
   suite (the ceiling manual fixes couldn't crack).

package/docs/guides/AUTOMATIC_FEATURES.md

@@ -126,6 +126,65 @@ Install UAP (`npm i -g universal-agent-protocol`) and every feature below activa
 
 ---
 
+## Long-Task Autonomy (Hands-Free) ✨
+
+*The Fable-parity layer: any model runs a huge build to 100% without a human in
+the loop. Full guide: [The Orchestrator & Hands-Free Persistence](ORCHESTRATOR.md).*
+
+### Orchestrator (blackboard, minimal context)
+**What it does:** Decomposes a complex mission into a task DAG and runs each task
+in a **fresh, minimal context** — its own goal + the verified interface
+contracts of its direct dependencies + a small memory pull — instead of one
+giant prompt. Publishes each task's contract back for dependents and future
+sessions; can adaptively add discovered tasks (`NEW_TASKS`).
+
+**When it kicks in:** Automatically for any decomposed mission (auto-on). Turn
+off with `uap orchestrator off` / `--no-orchestrate`.
+
+**Why it matters:** A small-context local model (Qwen3.6) can multi-step through
+a build far larger than its window, because it never has to hold the whole thing.
+
+### Epic Controller (loop epics as fresh sessions)
+**What it does:** For a *massive* mission (design → build → operational
+readiness), runs it as a **sequence of epics**, each a fresh mission that sees
+only prior epics' summaries. An epic that fails its gates is retried with a
+fresh session fed the last failure — looped until accepted.
+
+**When it kicks in:** Auto for genuinely epic-scale missions (complex *and*
+≥ 1200 chars); force with `--epics`.
+
+**Why it matters:** "Start a new session per task, inject only what's needed,
+loop until complete" — without you orchestrating it by hand.
+
+### Hands-Free Persistence (can't stop until done)
+**What it does:** A **completion ledger** (`.uap/completion-ledger.json`) is the
+objective definition of done for the whole build. The Stop hook **blocks
+session-end** while any item remains, handing the model a *"NOT DONE —
+REMAINING: …"* message; the reactor injects a *"keep going"* directive each
+turn. Intensity is model-aware (trust Fable, nudge Opus/GPT, firmly drive
+local models), and it's bounded so it can never wedge.
+
+**When it kicks in:** Auto-on whenever an active ledger has remaining items.
+Casual sessions with no build in progress are untouched. Disable with
+`uap handsfree off` / `UAP_HANDSFREE=0`.
+
+**Why it matters:** Every model behaves like Fable on long tasks — persisting to
+objective completion instead of stopping at the first plausible finish.
+
+### Plan Auto-Seed & Auto-Resume
+**What it does:** When the model writes a plan (Claude Code `TodoWrite`), a hook
+**mirrors it into the ledger automatically** — no manual `init`. On session
+start, an unfinished build is **auto-resumed** (*"Resuming a build in progress —
+N/M done, REMAINING: …"*).
+
+**When it kicks in:** Any interactive session with a real multi-step plan
+(≥ 3 todos). `uap deliver` epic mode seeds the ledger directly.
+
+**Why it matters:** The whole loop is zero-touch — the model's own plan becomes
+the definition of done, and work resumes across sessions without being asked.
+
+---
+
 ## Developer Experience
 
 ### RTK (Rust Token Killer)
@@ -135,6 +194,18 @@ Install UAP (`npm i -g universal-agent-protocol`) and every feature below activa
 
 **Why it matters:** Token costs add up fast. RTK transparently optimizes every command without you thinking about it.
 
+### Dashboard — Savings & Orchestration Visibility
+**What it does:** `uap dash serve` shows **Token Savings by Influence** (real
+tokens/cost saved per mechanism — RTK, model routing, context compression — with
+honest *measured/estimated* labels) and an **Orchestrations & Hierarchy** tree
+(the live mission → epic → task tree with the agents on each node and the active
+build ledger's progress).
+
+**When it kicks in:** Whenever you run `uap dash serve` (open `http://localhost:3847`).
+
+**Why it matters:** See exactly where UAP is saving you tokens and how a
+long-running build is progressing — no guesswork.
+
 ### 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.
 

package/docs/guides/DELIVER.md

@@ -42,6 +42,13 @@ uap deliver "migrate the auth module to JWT" --guidance-file ./guidance.txt
 echo "prefer RS256 and keep the existing /login route" >> ./guidance.txt
 ```
 
+For **huge, multi-epic builds**, `deliver` goes further: it decomposes the
+mission into a task DAG (the **blackboard orchestrator**, minimal fresh context
+per task) and, for epic-scale work, loops whole **epics as fresh sessions**
+until each is accepted. Combined with **hands-free persistence**, any model —
+local or frontier — runs the build to 100% without stopping. See
+**[The Orchestrator & Hands-Free Persistence](ORCHESTRATOR.md)**.
+
 ---
 
 ## Auto-optimization

package/docs/guides/ORCHESTRATOR.md

@@ -0,0 +1,273 @@
+# The Orchestrator & Hands-Free Persistence
+
+> **🏭 Where this fits:** BUILD — the station that turns *"build this whole
+> thing"* into finished, verified work without a human babysitting the loop.
+> **What it delivers:** any model — local or frontier — runs a huge multi-epic
+> build hands-free, in fresh minimal context per task, and **cannot stop until
+> the whole thing is 100% done**. Install once; it self-applies. Automagic. ✨
+
+This is UAP's answer to the question *"why can Fable grind on a huge task for
+hours while other models stop after ten minutes?"* Fable's persistence is
+trained into the weights. UAP puts the same persistence in the **harness** —
+so **every** model gets it.
+
+- **[The orchestrator](#the-orchestrator)** runs a decomposed build as a task
+  DAG, each task in a fresh, minimal context.
+- **[The epic controller](#the-epic-controller)** loops whole epics as fresh
+  sessions, retrying until each is accepted.
+- **[Hands-free persistence](#hands-free-persistence)** is the outer loop: a
+  completion ledger defines "done", and the Stop hook + reactor refuse to let
+  the model stop until the ledger reads 100%.
+
+All of it is **auto-on**. You don't pass a flag. You describe a big build, and
+the machinery engages.
+
+---
+
+## TL;DR — install & go
+
+```bash
+npm install -g @miller-tech/uap
+uap setup                       # wires the hooks into your harness
+```
+
+That's it. From then on:
+
+- Ask for a big, multi-part build (in Claude Code, `uap deliver`, opencode, …).
+- The model writes a plan (a todo list, or `uap deliver` decomposes it).
+- UAP captures that plan as a **completion ledger** and drives the model
+  through it — fresh context per task, keep-going injected each turn, and the
+  session **blocked from ending** until every item is done.
+- A new session **auto-resumes** an unfinished build.
+
+Nothing to configure. To *turn things off* or tune them, see
+[Controls](#controls-toggles--env).
+
+---
+
+## The orchestrator
+
+When `uap deliver` (or an interactive session routed through it) gets a
+genuinely complex, multi-part mission, it **decomposes** the work into a task
+DAG and runs it on a **blackboard orchestrator** instead of one giant
+convergence loop.
+
+The key idea is **minimal fresh context per task**. Each leaf task runs in its
+own convergence loop that sees only:
+
+- a one-line orientation snippet of the overall mission,
+- its own goal, acceptance criteria, and the files it owns,
+- the **verified interface contracts** of its *direct* dependencies (a few
+  hundred tokens — "what already exists"), and
+- a small, relevant pull from memory.
+
+Not the full spec. Not every prior summary. This is what lets a small-context
+local model (e.g. Qwen3.6-35B-A3B) multi-step through a build far larger than
+its window.
+
+**What it does automatically:**
+
+| Capability | Behavior |
+|---|---|
+| **Auto-decompose** | Complex, long missions split into 2–8 phases along the `plan → design → implement → review → release` lifecycle. |
+| **Minimal context** | Each task's prompt is hard-capped by a context governor (default 6000 chars); furthest dependencies are elided first. |
+| **Memory in/out** | Each task pulls relevant design decisions from memory (`retrieveDesign`) and publishes its verified contract back (`publish`) for dependents and future sessions. |
+| **Adaptive re-planning** | A task that discovers missing work can emit `NEW_TASKS:[…]`; they're validated, de-duped, and folded into the DAG. |
+| **Dependency-correct** | A task runs only after every dependency has *succeeded*; a failed dependency blocks (never builds on a broken base). |
+
+It is **auto-on** for any decomposed mission — minimal-context orchestration is
+strictly better than a full-mission prompt for small models.
+
+---
+
+## The epic controller
+
+One `deliver` run drives one task DAG. A **massive** mission — *design → build
+→ operational readiness* — is more than one DAG: it's a **sequence of epics**,
+each itself a full mission. The epic controller is the loop above the
+orchestrator:
+
+```
+for each epic (dependency-ordered):
+    run it as a FRESH mission            ← fresh context; only prior epics'
+                                            compact summaries are injected
+    check acceptance (gates + judge)
+    if not accepted:
+        RETRY with a fresh session       ← fed the previous attempt's failure
+        …until accepted or the attempt budget is spent
+```
+
+- **Fresh session per epic/attempt** — exactly the "start new sessions per
+  task, inject only what's needed, loop until complete" pattern.
+- **Generator ≠ Evaluator** — an epic that "delivered" but fails the acceptance
+  judge is retried; a delivered-and-accepted epic is marked done.
+- **Never spins forever** — bounded per-epic attempts; stagnation gives up
+  gracefully.
+
+It **auto-engages** for genuinely epic-scale missions (complex *and* ≥ 1200
+characters). Smaller work uses the orchestrator or the plain loop.
+
+---
+
+## Hands-free persistence
+
+The orchestrator and epic controller run inside `uap deliver`. But most huge
+builds are driven **interactively** (Claude Code, opencode) where the model
+decides when it's "done". Hands-free persistence makes *that* Fable-like too —
+for any model — using four pieces that all ship **auto-on**.
+
+### B · The completion ledger — the objective definition of done
+
+`.uap/completion-ledger.json` is the persistent, whole-build checklist: the
+epic/task DAG with a status per item. Completion is judged against **this**,
+not the model's self-assessment, and it survives across turns *and* sessions.
+
+The ledger is populated automatically:
+
+- `uap deliver` epic mode writes it from the planned epics and marks items done
+  as epics are accepted.
+- **Interactive sessions**: whenever the model writes a plan with the built-in
+  todo tool (Claude Code `TodoWrite`), a PostToolUse hook **mirrors that plan
+  into the ledger** — statuses follow (`completed → done`, `in_progress`,
+  `pending`). No manual step. (Only a real multi-step plan seeds it — ≥ 3 todos
+  by default.)
+
+### A · The Stop-hook block — you can't stop early
+
+When the model tries to end its turn, the Stop hook checks the ledger. If the
+build is incomplete it **blocks the stop** and hands the model a
+*"NOT DONE — REMAINING: …"* message, so it keeps working. Fully guarded so it
+can never wedge:
+
+- honors the harness `stop_hook_active` flag (never re-blocks in a loop),
+- only blocks when there's an **active ledger with remaining items**,
+- bounded by per-build **block + stagnation counters** — progress resets the
+  counter; a genuine stall gives up. *"Never stop early"* and *"never spin
+  forever"* are the same feature.
+
+### C · Model-aware intensity — trust Fable, drive the local model
+
+The forcing scales **inversely** with a model's intrinsic persistence:
+
+| Family | Intensity | Behavior |
+|---|---|---|
+| **Fable** | light | Trust it; minimal safety net. |
+| **Opus / Sonnet / GPT** | moderate | Nudge past premature "done". |
+| **Qwen / local** | aggressive | Firmly drive; more blocks tolerated. |
+
+### D · Reactor injection — the standing "keep going" directive
+
+While a build is in progress, every prompt gets a
+*"keep going until 100% — REMAINING: …"* directive injected (via the reactor
+hook you already have). Casual sessions with no active build see nothing.
+
+### Auto-resume — pick up where you left off
+
+On session start, if a build was left unfinished, a resume banner surfaces it
+(*"Resuming a build in progress — N/M done, REMAINING: …"*) so a fresh session
+continues it **without being asked**.
+
+**The full loop, all automatic:**
+
+```
+model plans (todos)  →  ledger auto-seeds  →  reactor injects "keep going" each turn
+        →  Stop hook blocks until 100%  →  new session auto-resumes the remainder
+        →  done when every ledger item is complete
+```
+
+---
+
+## Seeing it: the dashboard
+
+`uap dash serve` (open `http://localhost:3847`) now includes two panels for
+this machinery:
+
+- **Orchestrations & Hierarchy** — the live `mission → epic → task` tree with
+  per-node status and the agents working each node, plus the active build
+  ledger's progress.
+- **Token Savings by Influence** — real tokens/cost saved, attributed per
+  mechanism (RTK, model routing, context compression), with honest
+  *measured / estimated* labels.
+
+---
+
+## Controls (toggles & env)
+
+Everything is on by default. These are for turning it **off** or tuning it.
+
+### Orchestrator
+
+```bash
+uap orchestrator status            # show effective setting
+uap orchestrator off               # sequential phase runner instead of the blackboard
+uap orchestrator on | auto         # re-enable (auto = default)
+uap deliver "…" --no-orchestrate   # disable for one run
+```
+
+| Knob | Effect |
+|---|---|
+| `UAP_DELIVER_ORCHESTRATE=0` | Disable the orchestrator. |
+| `.uap.json` `deliver.orchestrate: "off"` | Persistent disable. |
+| `UAP_DELIVER_CONTEXT_BUDGET` | Per-task context char cap (default 6000). |
+| `UAP_DELIVER_MAX_PHASES` | Phase ceiling (default 8, hard max 20). |
+| `UAP_DELIVER_MAX_TASKS` | Re-planning task cap (default 40). |
+
+### Epic controller
+
+```bash
+uap deliver "…" --epics            # force the epic controller
+uap deliver "…" --no-epics         # disable it for this run
+```
+
+| Knob | Effect |
+|---|---|
+| `UAP_DELIVER_EPICS=1` | Force epic mode. |
+| `UAP_DELIVER_EPIC_ATTEMPTS` | Fresh-session attempts per epic (default 2). |
+
+### Hands-free persistence
+
+```bash
+uap handsfree status               # master switch, model profile, ledger progress
+uap handsfree on | off             # toggle (persisted to .uap.json)
+uap handsfree remaining            # what's left in the current build
+uap handsfree init --mission "…" --items '[{"id":"e1","title":"…"}]'   # seed manually
+uap handsfree complete <id> | fail <id>                                # update an item
+```
+
+*(alias: `uap hf …`)*
+
+| Knob | Effect |
+|---|---|
+| `UAP_HANDSFREE=0` | Disable hands-free entirely. |
+| `.uap.json` `handsfree.enabled: false` | Persistent disable. |
+| `UAP_HANDSFREE_INTENSITY` | Force `light` / `moderate` / `aggressive`. |
+| `UAP_HANDSFREE_MIN_TODOS` | Min todos before a plan auto-seeds a ledger (default 3). |
+
+### Model routing
+
+```bash
+uap model routing status           # is routing on? which table + complexity tiers?
+uap model routing on | off         # toggle the whole multi-model table
+uap model routing use <preset>     # apply a preset (e.g. fable-local-opus)
+```
+
+---
+
+## How it maps to the code
+
+| Piece | Source |
+|---|---|
+| Blackboard orchestrator | `src/delivery/task-orchestrator.ts` |
+| Epic controller | `src/delivery/epic-controller.ts` |
+| Deliver wiring | `src/cli/deliver.ts` (`runOrchestratedMission`, `runEpicMission`) |
+| Completion ledger | `src/delivery/completion-ledger.ts` → `.uap/completion-ledger.json` |
+| Persistence profile | `src/delivery/persistence-profile.ts` |
+| Stop-hook block | `.factory/hooks/stop.sh` → `uap handsfree stop-check` |
+| Auto-seed / auto-resume | `templates/hooks/uap-todo-ledger.sh`, `session-start.sh` |
+| Reactor injection | `src/coordination/persistence-inject.ts` |
+
+---
+
+**See also:** [`uap deliver`](DELIVER.md) · [Multi-Model Routing](MULTI_MODEL.md)
+· [What UAP Does Automatically](AUTOMATIC_FEATURES.md) ·
+[Local Models](LOCAL_MODELS.md)

package/package.json

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

package/src/policies/enforcers/cluster_routing.py

@@ -6,7 +6,7 @@ import sys
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).parent))
-from _common import arg_str, emit, parse_cli, run  # noqa: E402
+from _common import emit, parse_cli, run  # noqa: E402
 
 DOMAINS = {
     "openobserve": re.compile(
@@ -31,7 +31,16 @@ def pick_domain(blob: str) -> str:
 
 def main() -> None:
     op, args = parse_cli()
-    blob = f"{op} {arg_str(args)}"
+    # Scope: only Bash invocations dispatch cluster commands. Other tools
+    # (Write/Edit/Read/etc.) may legitimately mention cluster product names
+    # in file content without that being a kubectl/helm call.
+    if op != "Bash":
+        emit(True, "non-Bash tool call")
+    # Strip heredoc bodies so file content written via cat <<MARK ... MARK
+    # does not pattern-match the trigger regex below.
+    cmd = args.get("command", "") if isinstance(args, dict) else ""
+    cmd = re.sub(r'<<\s*[\x27\x22]?(\w+)[\x27\x22]?[\s\S]*?\n\1\b', "", cmd)
+    blob = f"{op} {cmd}"
 
     if not re.search(r"\b(kubectl|helm)\b", blob):
         emit(True, "not a kubectl/helm call")