@miller-tech/uap 2.1.7 → 2.11.0

package/dist/supervise/policy.js

@@ -0,0 +1,147 @@
+/**
+ * The deterministic supervisor policy. PURE — same inputs, same decision.
+ *
+ * Priority is safety-first and FIXED (do not reorder without review):
+ *   0. terminal status     → FINISH when delivered, else CONTINUE (a run that
+ *                            is no longer running is never STOPped/ESCALATEd)
+ *   1. iteration bounds    → STOP — outranks even human-need: a run past its
+ *      budget stops regardless; a human-needed signal riding along is carried
+ *      in evidence.alsoEscalate instead of becoming the action
+ *   2. human-needed        → ESCALATE  (a blocked mission burns budget silently)
+ *   3. off-track/stuck     → RETRY while retries remain, else ESCALATE
+ *   4. completion-signaled → FINISH, ONLY on authoritative state
+ *      (status === 'delivered'); the log-tail success regex alone never
+ *      detaches supervision — a stuck mission whose model prints "mission
+ *      complete" keeps being watched
+ *   5. verification-pending → VERIFY, NEVER twice consecutively (oscillation
+ *      guard), and bounded by maxVerify: an unanswered verification falls
+ *      into the stuck path (RETRY/ESCALATE)
+ *   6. otherwise           → CONTINUE
+ *
+ * Every decision carries its reason and the evidence that fired it — the
+ * event ledger must be able to explain every action without re-running.
+ */
+import { runBudgetMinutes } from '../delivery/run-state.js';
+function dim(dims, name) {
+    return dims.find((d) => d.name === name);
+}
+function fired(dims, name) {
+    return dim(dims, name)?.value === true;
+}
+function scoreOf(dims, name) {
+    const v = dim(dims, name)?.value;
+    return typeof v === 'number' ? v : undefined;
+}
+/**
+ * The budget the STOP branch enforces: the LARGER of the supervisor policy
+ * and the deliver run's own budget (`UAP_DELIVER_MAX_MINUTES` /
+ * `.uap.json delivery.maxRunMinutes` / the calibrated default). An
+ * operator-raised deliver budget must not be overruled by the supervisor's
+ * static policy number; a LOWER operator budget makes the deliver loop stop
+ * itself first anyway, so taking the max never extends a mission past what
+ * its owner granted. Impure (reads env/config) — callers pass the result in
+ * via an adjusted cfg so decide() itself stays pure.
+ */
+export function effectiveMaxMinutes(cfg, projectRoot) {
+    return Math.max(cfg.maxMinutes, runBudgetMinutes(projectRoot));
+}
+/** RETRY while the budget remains, ESCALATE when it is spent. */
+function retryOrEscalate(reasonKind, state, cfg, evidence) {
+    const withBudget = { ...evidence, retries: state.retries, maxRetries: cfg.maxRetries };
+    if (state.retries < cfg.maxRetries) {
+        return { action: 'RETRY', reason: `${reasonKind} — retry budget remains`, evidence: withBudget };
+    }
+    return { action: 'ESCALATE', reason: `${reasonKind} — retries exhausted`, evidence: withBudget };
+}
+export function decide(obs, dims, state, cfg) {
+    // (0) Terminal runs: nothing left to supervise. NEVER STOP/ESCALATE them —
+    // a delivered run's log may still contain scary text from earlier turns.
+    if (obs.status !== 'running') {
+        if (obs.status === 'delivered') {
+            return {
+                action: 'FINISH',
+                reason: 'run delivered',
+                evidence: { status: obs.status, turnsCompleted: obs.turnsCompleted },
+            };
+        }
+        return {
+            action: 'CONTINUE',
+            reason: `run is ${obs.status} — nothing to supervise`,
+            evidence: { status: obs.status },
+        };
+    }
+    const humanNeeded = fired(dims, 'human-needed');
+    // (1) Iteration bounds. STOP outranks ESCALATE: an over-budget mission that
+    // is ALSO waiting on a human still stops — the human-need is recorded as an
+    // alsoEscalate note, not acted on as the decision.
+    if (obs.turnsCompleted > cfg.maxTurns || obs.elapsedMinutes > cfg.maxMinutes) {
+        return {
+            action: 'STOP',
+            reason: 'iteration bounds exceeded',
+            evidence: {
+                turnsCompleted: obs.turnsCompleted,
+                maxTurns: cfg.maxTurns,
+                elapsedMinutes: Math.round(obs.elapsedMinutes * 10) / 10,
+                maxMinutes: cfg.maxMinutes,
+                ...(humanNeeded ? { alsoEscalate: 'human input required' } : {}),
+            },
+        };
+    }
+    // (2) Human need: a blocked mission burns its whole budget silently.
+    if (humanNeeded) {
+        return {
+            action: 'ESCALATE',
+            reason: 'human input required',
+            evidence: { humanNeeded: true, tail: obs.recentLogTail.slice(-200) },
+        };
+    }
+    // (3) Off-track or stuck: retry while the budget remains, then escalate.
+    const offTrack = fired(dims, 'off-track');
+    const stuck = fired(dims, 'stuck-loop');
+    if (offTrack || stuck) {
+        return retryOrEscalate('off-track/stuck', state, cfg, {
+            offTrack,
+            stuckLoop: stuck,
+            progressStalled: fired(dims, 'progress-stalled'),
+            failures: obs.failures,
+        });
+    }
+    // (4) Completion: FINISH happens ONLY on authoritative state — branch (0)
+    // returns FINISH for status 'delivered'. A completion-signaled dimension
+    // firing from the log tail alone (a stuck model printing "mission
+    // complete") is deliberately ignored here: supervision stays attached.
+    // (5) Verification, oscillation-guarded AND budgeted. VERIFY never fires
+    // twice consecutively; once the verify budget is spent without test
+    // evidence appearing, the run is treated as stuck.
+    if (fired(dims, 'verification-pending')) {
+        if (state.lastAction !== 'VERIFY') {
+            return {
+                action: 'VERIFY',
+                reason: 'checkpoint exists without test evidence in the log tail',
+                evidence: { hasCheckpoint: obs.hasCheckpoint, lastAction: state.lastAction, verifyCount: state.verifyCount },
+            };
+        }
+        if (state.verifyCount >= cfg.maxVerify) {
+            return retryOrEscalate('verification unanswered', state, cfg, {
+                verifyCount: state.verifyCount,
+                maxVerify: cfg.maxVerify,
+            });
+        }
+        return {
+            action: 'CONTINUE',
+            reason: 'verify already requested, awaiting result',
+            evidence: { verifyCount: state.verifyCount, maxVerify: cfg.maxVerify },
+        };
+    }
+    // (6) Healthy.
+    return {
+        action: 'CONTINUE',
+        reason: 'within bounds',
+        evidence: {
+            errorDensity: scoreOf(dims, 'error-density'),
+            iterationPressure: scoreOf(dims, 'iteration-pressure'),
+            risk: scoreOf(dims, 'risk'),
+        },
+    };
+}
+//# sourceMappingURL=policy.js.map

package/dist/supervise/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../src/supervise/policy.ts"],"names":[],"mappings":"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"}

package/dist/supervise/types.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Semantic supervisor for `uap deliver` missions — shared types.
+ *
+ * The supervisor WATCHES a run; it does not drive it. Observations are bounded
+ * (log tails capped, diffs capped, git calls time-boxed), assessments are pure
+ * functions over those observations, and the policy is deterministic with
+ * reviewed thresholds (config/supervise-policy.json). Models may only ASSESS
+ * (via the injectable classifier); they never decide.
+ */
+export type SupervisorAction = 'CONTINUE' | 'STOP' | 'RETRY' | 'VERIFY' | 'FINISH' | 'ESCALATE';
+export type SupervisedRunStatus = 'running' | 'delivered' | 'failed' | 'interrupted';
+/**
+ * One bounded snapshot of a deliver run. Everything here is cheap to collect
+ * and safe to hand to a classifier: no unbounded file contents, no secrets.
+ *
+ * Beyond the minimal contract (runId/status/elapsed/turns/failures/tail/git)
+ * this carries three derived fields the PURE dimension functions need so
+ * observation stays the only impure step: `instruction` (off-track keyword
+ * matching), `minutesSinceUpdate` (stall detection), and `hasCheckpoint`
+ * (verification-pending).
+ */
+export interface Observation {
+    runId: string;
+    status: SupervisedRunStatus;
+    /** Mission instruction (already length-clamped by run-state on load). */
+    instruction: string;
+    /** Wall-clock minutes since the run was created. */
+    elapsedMinutes: number;
+    /** Minutes since the run state was last persisted (stall signal). */
+    minutesSinceUpdate: number;
+    /** Last completed loop turn (0 before the first checkpoint). */
+    turnsCompleted: number;
+    /** Turns recorded as not-passed in the checkpoint history. */
+    failures: number;
+    /** A loop checkpoint exists (the run has completed at least one turn). */
+    hasCheckpoint: boolean;
+    /** Tail of the newest matching deliver log, capped at 8KB. '' when absent. */
+    recentLogTail: string;
+    /** `git status --porcelain` line count; undefined when git is unavailable. */
+    gitDirtyFiles?: number;
+    /** `git diff --stat`, capped; undefined when git is unavailable. */
+    diffStat?: string;
+}
+export interface DimensionAssessment {
+    name: string;
+    /** boolean for flag dimensions, 1-5 for score dimensions. */
+    value: boolean | number;
+    /** Estimated probability the assessment is correct (0-1). */
+    probability: number;
+    /** Confidence in THIS answer (0-1); low confidence defers to the heuristic. */
+    confidence: number;
+    /** True when the assessor abstains (insufficient evidence). */
+    defer: boolean;
+    source: 'heuristic' | 'classifier';
+}
+export interface Decision {
+    action: SupervisorAction;
+    reason: string;
+    /** The dimension values and counters that fired, for the event ledger. */
+    evidence: Record<string, unknown>;
+}
+/**
+ * Reviewed policy thresholds (config/supervise-policy.json). Validated loudly
+ * at load — a missing or out-of-range policy REFUSES to run rather than
+ * silently supervising with invented numbers.
+ */
+export interface SupervisorConfig {
+    version: 1;
+    /** running + no state update for this long ⇒ progress-stalled. */
+    stallMinutes: number;
+    /** elapsed beyond this ⇒ STOP (mirrors the calibrated 120m deliver budget). */
+    maxMinutes: number;
+    /** turns beyond this ⇒ STOP. */
+    maxTurns: number;
+    /** RETRY budget before off-track/stuck escalates. */
+    maxRetries: number;
+    /** checkpoint failures at/above this ⇒ stuck-loop. */
+    maxFailures: number;
+    /** minimum gap between assessments (change-triggered). */
+    debounceMs: number;
+    /** maximum gap between assessments (periodic heartbeat). */
+    intervalMs: number;
+    /** classifier answers below this confidence are ignored (fail closed). */
+    classifierConfidenceMin: number;
+    /** escalation-risk answers below this probability are ignored. */
+    classifierTau: number;
+    /** VERIFY actions issued without test evidence before stuck-path takeover. */
+    maxVerify: number;
+}
+/** State persisted per supervised run at .uap/supervise/<runId>/state.json. */
+export interface SupervisorState {
+    version: 1;
+    runId: string;
+    startedAt: string;
+    updatedAt: string;
+    /** Assessment cycles completed. */
+    assessments: number;
+    /** RETRY actions issued so far (drives the retry→escalate boundary). */
+    retries: number;
+    /** VERIFY actions issued since test evidence was last seen. */
+    verifyCount: number;
+    /** Consecutive suppressed ESCALATE repeats (bounded by the loop). */
+    suppressedEscalations: number;
+    /** Last action taken — the oscillation guard's memory. */
+    lastAction: SupervisorAction | null;
+    lastActionAt: string | null;
+    lastDecision?: Decision;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/supervise/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/supervise/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEhG,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,aAAa,CAAC;AAErF;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,mBAAmB,CAAC;IAC5B,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,cAAc,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gEAAgE;IAChE,cAAc,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,aAAa,EAAE,OAAO,CAAC;IACvB,8EAA8E;IAC9E,aAAa,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;IACxB,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,WAAW,GAAG,YAAY,CAAC;CACpC;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,gBAAgB,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,CAAC,CAAC;IACX,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,UAAU,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,uBAAuB,EAAE,MAAM,CAAC;IAChC,kEAAkE;IAClE,aAAa,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,+EAA+E;AAC/E,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,CAAC,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,qBAAqB,EAAE,MAAM,CAAC;IAC9B,0DAA0D;IAC1D,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACpC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,CAAC,EAAE,QAAQ,CAAC;CACzB"}

package/dist/supervise/types.js

@@ -0,0 +1,11 @@
+/**
+ * Semantic supervisor for `uap deliver` missions — shared types.
+ *
+ * The supervisor WATCHES a run; it does not drive it. Observations are bounded
+ * (log tails capped, diffs capped, git calls time-boxed), assessments are pure
+ * functions over those observations, and the policy is deterministic with
+ * reviewed thresholds (config/supervise-policy.json). Models may only ASSESS
+ * (via the injectable classifier); they never decide.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/supervise/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/supervise/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/docs/INDEX.md

@@ -18,12 +18,13 @@ UAP is organized like a delivery line. If you know which part of the pipeline yo
 | Station | The break it prevents | Start with |
 |---|---|---|
 | **Intake** — understand the work | Amnesiac sessions, invented scope | [Memory](guides/MEMORY.md) · [Reactor](design/UAP_REACTOR.md) |
-| **Prep / routing** — right job, right station | Wrong approach or wrong-sized model | [Multi-Model Routing](guides/MULTI_MODEL.md) · [Patterns](reference/PATTERNS.md) · [Droids & Skills](guides/DROIDS_AND_SKILLS.md) |
+| **Prep / routing** — right job, right station | Wrong approach or wrong-sized model | [Multi-Model Routing](guides/MULTI_MODEL.md) · [Patterns](reference/PATTERNS.md) · [Droids & Skills](guides/DROIDS_AND_SKILLS.md) · [System-1 Classifier](reference/system1-classifier.md) (`uap classify`) |
 | **Isolation** — a bench per job | Editing `main`, clobbering files | [Worktree Workflow](guides/WORKTREE_WORKFLOW.md) |
 | **Build** — make the thing | Plausible-but-wrong code, stubs, empty output | [`uap deliver`](guides/DELIVER.md) · [Local Models](guides/LOCAL_MODELS.md) · [Inference Proxy](guides/PROXY.md) |
-| **QC / verify** — prove it runs | "Done" on code that never ran | [`uap deliver`](guides/DELIVER.md) · [Policies](guides/POLICIES.md) · [Quality gate](../CLAUDE.md) (`uap quality check`) |
-| **Coordination** — many workers, one floor | Parallel agents colliding, stale branches overwriting landed work | [Parallel Agents](guides/PARALLEL_AGENTS.md) · [Coordination](guides/COORDINATION.md) · [Deploy Batching](guides/DEPLOY_BATCHING.md) |
+| **QC / verify** — prove it runs | "Done" on code that never ran | [`uap deliver`](guides/DELIVER.md) · [Policies](guides/POLICIES.md) · [Quality gate](../CLAUDE.md) (`uap quality check`) · [AutoMode risk](reference/automode-risk.md) · [Evidence-bound ship](reference/evidence-bound-ship.md) |
+| **Coordination** — many workers, one floor | Parallel agents colliding, stale branches overwriting landed work | [Parallel Agents](guides/PARALLEL_AGENTS.md) · [Coordination](guides/COORDINATION.md) · [Deploy Batching](guides/DEPLOY_BATCHING.md) · [Semantic Supervisor](reference/semantic-supervisor.md) (`uap supervise`) |
 | **Shipping** — out the door safely | Regressions, red CI, skipped bumps | [Worktree Workflow](guides/WORKTREE_WORKFLOW.md) · [Policies](guides/POLICIES.md) |
+| **Capacity** — services inside their budgets | Silent OOMs, crash loops, headroom loss | [Capacity Policy](guides/CAPACITY_POLICY.md) (`uap doctor`) |
 | **Feedback** — the floor learns | The same mistake every session | [Memory](guides/MEMORY.md) · [Self-Harness](design/SELF_HARNESS.md) · [Self-Tuning](guides/SELF_TUNING.md) |
 | *Cross-cutting* — the whole line | Ignored rules, bloated context | [Policies](guides/POLICIES.md) · [MCP Router](guides/MCP_ROUTER.md) |
 
@@ -87,7 +88,10 @@ Full map: **[The UAP Delivery Pipeline](guides/DELIVERY_PIPELINE.md)**.
 | [API](reference/API.md) | Programmatic API surface |
 | [Features](reference/FEATURES.md) | Full feature catalog, mapped to the pipeline stages |
 | [Patterns](reference/PATTERNS.md) | The 23 Terminal-Bench patterns |
+| [Routing Evals](reference/routing-evals.md) | CI-enforced rank-1 routing evals over the pattern/droid/skill registries — planted traps, negative cases, 90% threshold |
 | [Platforms](reference/PLATFORMS.md) | The 9 supported harnesses + support matrix |
+| [Review Pre-Pass](reference/review-prepass.md) | Deterministic ruleset scanner (`uap review prepass`) that feeds line-anchored findings to the parallel review protocol |
+| [Visual Captures](reference/visual-captures.md) | Before/after capture binding for UI diffs (`uap review captures`) — ship-time gate 7 enforcement |
 | [Configuration](reference/CONFIGURATION.md) | All config files and env vars |
 | [**Configuration Reference**](reference/CONFIGURATION_REFERENCE.md) | Every setting `uap config` exposes — what it does, default, and a recommendation (generated from the registry); `uap config list/explain/set/doctor/wizard` ⭐ |
 | [Database Schema](reference/DATABASE_SCHEMA.md) | SQLite databases + Qdrant collections |
@@ -132,6 +136,7 @@ the decision record.
 | [Harness engineering uplift](plans/harness-engineering-uplift-2026-07-31.md) | Three-paper analysis of harness variance and what UAP does about it |
 | [K3 UAP uplift validation](plans/k3-uap-uplift-validation.md) | Plan to measure UAP's paired uplift on Kimi K3 by re-running Terminal-Bench 2.1 with Factory Droid as the harness, UAP on vs off |
 | [Qwen3.8 UAP re-test plan](plans/qwen38-uap-retest-plan.md) | Plan to re-run the paired benchmark matrix on the current local Qwen3.8-27B stack with UAP v1.224.x, replicating the +20pp gate-loop finding and checking the hardened deliver pipeline |
+| [System-1 uplift plan](plans/system1-uplift-2026-09-18.md) | Approved uplift from the 2026-09-18 ten-source analysis (Jev/Foreman/Fluent/CEK et al): Wave 0 quick wins + Wave 1 System-1 decision layer, local-only classifier trained from UAP telemetry |
 
 ## Specs & performance
 
@@ -140,6 +145,7 @@ the decision record.
 | [P0 anti-vacuous spec](specs/p0-anti-vacuous.md) | The verbatim-operations spec behind deliver's anti-stub hardening |
 | [Dashboard uplift spec](DASHBOARD_UPLIFT_SPEC.md) | Replacing the monolithic dashboard with the modular token-locked console |
 | [Performance baseline](performance/baseline-2026-03-27.json) | Machine-recorded perf baseline (heap, query latency) |
+| [Reliability ladder](performance/reliability-ladder.md) | Measured technique-selection table for the decision loop; `npm run bench:ladder` regenerates it from `benchmark-results/` |
 
 ## Contributing
 

package/docs/architecture/adr/0001-automode-risk-floor.md

@@ -0,0 +1,75 @@
+# ADR 0001: AutoMode risk classification ships as a Python heuristic floor ahead of the TS SYS1 head
+
+- Status: Accepted
+- Date: 2026-07-13 (uplift 1.3, branch `feature/304-automode-risk`)
+
+## Context
+
+AutoMode needs risk classification of tool calls **before dispatch** —
+ahead of the verb/regex heuristics in the client-side enforcer chain
+(`src/policies/enforcers/*.py`). The designed classifier is the TypeScript
+SYS1 head (`src/classify/`, PR #807, branch `feature/301-sys1-classifier`),
+but that branch is **unmerged and unreachable from Python**: the proxy
+(`tools/agents/scripts/anthropic_proxy.py`) and the enforcers are Python,
+and there is no TS→Python bridge in the serving path. Blocking AutoMode on
+the TS merge would leave the proxy/enforcer stack with no risk signal at
+all.
+
+Two further constraints shaped the decision:
+
+1. The deterministic enforcers are the blocking floor and must stay exactly
+   as strict — any classifier output is **advisory only**.
+2. A wrong signal is asymmetric: a *missed* destructive call is the
+   unacceptable error; a false positive costs one advisory log line.
+
+## Decision
+
+Ship a **Python-resident calibrated heuristic scorer**
+(`tools/agents/scripts/tool_risk.py`) behind a stable contract,
+`classify_tool_call(tool_name, tool_input) -> RiskAssessment`, wired
+advisory-only into the proxy's three outbound tool_use interception points
+(debug log per call; `dashboard_events` telemetry for score ≥ 4; never
+blocks, never mutates the stream; `PROXY_AUTOMODE_RISK=off` hatch).
+
+- **Vocabulary inspired by, not ported from, the TS baseline.** The SYS1
+  `baseline.ts` scores prose state descriptions; this scorer parses shell
+  structure (verbs, flags, redirects, launchers). The domains differ, so we
+  do not claim cross-stack parity.
+- **Deliberate duplication against `enforcement_self_protect.py`.** The
+  scorer re-implements launcher step-over, find-mutating flags, and the
+  sed `-i` conditional rather than importing the enforcer, because the
+  enforcer is a blocking gate with repo-root side effects and the scorer
+  must stay pure and importable from the proxy hot path. The mitigation for
+  the copy-divergence risk is a **drift-guard test**
+  (`EnforcerParityDriftGuardTest` in `test_tool_risk.py`) that imports both
+  modules and asserts the launcher sets, find-mutating semantics, and sed
+  `-i` semantics agree — divergence becomes a CI failure, not silent drift.
+- **Deferred consumption.** For now the classification is consumed only by
+  logs and telemetry. The follow-up that produces *production* calibration
+  data is enforcer consumption plus a shadow-disagreement signal: run the
+  scorer beside the enforcers, record where advisory and floor disagree,
+  and let that corpus — not hand-labeled fixtures alone — calibrate the
+  promoted head.
+- **Real promotion path.** The SYS1 head, when it lands, is a
+  Python-resident model (or a local sidecar) behind the same
+  `classify_tool_call` contract, gated by
+  `tools/agents/scripts/tool_risk_calibrate.py` at held-out destructive
+  recall 1.0 on a corpus that by then includes production disagreement
+  data. Wiring, harness, and doctrine do not change.
+
+## Consequences
+
+- The proxy/enforcer stack gets AutoMode risk classification now, with
+  measured latency (p95 ≈ 0.03 ms over 10k calls) far under the 50 ms
+  budget reserved for a future model call.
+- The advisory path fails **open** (classifier exception → warning +
+  pass-through) precisely because the enforcer floor fails **closed**; a
+  dead scorer degrades to today's behavior plus one startup warning if the
+  import itself failed.
+- The heuristic floor's perfect fixture numbers are a *contrast baseline*
+  on a small, hand-labeled probe (held-out n=4–10 per class), explicitly
+  caveated in `docs/performance/automode-risk-calibration.md`; they are not
+  evidence of model-grade generalization.
+- The duplication debt against `enforcement_self_protect.py` is real but
+  bounded and guarded; if the enforcer grows a new evasion shape, the
+  drift-guard test forces the scorer to follow.

package/docs/architecture/adr/0002-evidence-bound-ship.md

@@ -0,0 +1,81 @@
+# ADR-0002: Evidence-bound merge candidates (gate evidence)
+
+- **Status**: Accepted
+- **Date**: 2026-09-18
+- **Policy**: `evidence-bound-ship` (`src/policies/schemas/policies/evidence-bound-ship.md`)
+- **Enforcer**: `src/policies/enforcers/evidence_bound_ship.py`
+- **Writer**: `src/delivery/gate-evidence.ts` (emit seam: `src/cli/deliver.ts`)
+- **Reference**: `docs/reference/evidence-bound-ship.md`
+
+## Context
+
+Deliver missions claim "all gates pass", but nothing bound that claim to the
+commit a ship action actually publishes. An agent could run the gates on one
+tree, then amend, swap, or dirty the commit and ship code the gates never saw —
+the existing ship gates (`expert-review-required`) trusted a *review verdict*,
+not machine proof tied to a SHA. Uplift 1.4 requires merge candidates to carry
+their gate evidence.
+
+Two properties make such evidence worth anything, and both shaped the design:
+
+1. **The agent must not be able to write it.** A `.uap/evidence/<sha>.json`
+   the agent can forge is worse than none — it converts "no proof" into
+   "plausible proof". `.uap/evidence/` is therefore a self-protect
+   PROTECTED_TARGET with no carve-out, and the interpreter-write rule
+   (`python3 -c`, `node -e`, heredoc) covers the directory, because the
+   verb-based Bash scan cannot see an interpreter-mediated write.
+2. **The evidence must name the exact commit it proves.** Binding to "the
+   branch" or "whenever the gates ran" re-admits the swap. So the artifact
+   records `candidateSha = HEAD` and is only written against a **clean** tree —
+   with uncommitted changes the gates provably ran against HEAD-plus-delta,
+   and the claim would be unprovable.
+
+## Decision
+
+- The deliver CLI records `.uap/evidence/<head-sha>.json` at the single
+  completion seam all runner kinds converge on, from the **last passing**
+  iteration's rung results (or the baseline ladder run when the run
+  short-circuits as `alreadyDelivered` — otherwise the supported commit →
+  deliver → ship flow dead-ends on an already-green tree).
+- The ship enforcer **fails closed** on missing, oversized (>512KB),
+  malformed, wrong-version, SHA-mismatched, backdated, future-dated
+  (>5min skew), stale (default 24h), or gate-empty evidence; an unresolvable
+  commit time also blocks. The only fail-open is a tree that is not a git
+  repository.
+- Ship-action detection is **shared** with `expert-review-required` (imported
+  `is_ship_action`) so the two gates can never disagree on what a ship is.
+- Operator hatches are environment-only (`UAP_EVIDENCE_GATE_OFF=1`,
+  `UAP_EVIDENCE_MAX_AGE_HOURS`); the agent cannot set either inline or
+  persistently — enforcement-self-protect refuses the assignment text.
+
+### Fail-soft emit / fail-closed gate asymmetry
+
+Evidence **emission** never breaks a mission (a warning is the whole failure
+mode): a deliver run must not fail because bookkeeping failed. The **gate**
+fails closed: a ship without verifiable evidence is refused. The asymmetry has
+a real recovery cost — when emission silently fails (dirty tree, unborn HEAD),
+the operator's only feedback is a warning line, and the ship block arrives
+later, detached from its cause. We accept this because the block message names
+the fix (`commit, then re-run uap deliver`) and the escape hatch exists for
+genuinely blocked operators. The alternative (fail-hard emission) would wedge
+missions on a provenance feature; the other alternative (fail-open gate)
+deletes the control.
+
+## Consequences
+
+- The supported flow is **commit → `uap deliver` → ship**. A deliver run that
+  leaves the tree dirty emits no evidence (warns only); the subsequent ship is
+  blocked until the candidate is committed and deliver re-run.
+- **Local-only perimeter**: the gate fires only for ship actions routed
+  through this machine's policy chain. GitHub-web merges and machines without
+  the chain bypass it; squash/rebase merges mint a remote SHA no local
+  evidence can bind. Branch protection / required status checks remain the
+  remote-side complement (see the reference doc's Scope & limitations).
+- `gh pr merge <N>` binds the **local** HEAD (no network/`gh` in the policy
+  chain); shipping from a checkout diverged from the PR head validates the
+  wrong commit and is blocked by design.
+- Per-gate timestamps are reconstructed from rung durations, not measured —
+  honest ordering, approximate clock; documented in the schema.
+- The artifact carries a `hatches` audit field (which gate-affecting env vars
+  were set at deliver time) so a reviewer can see the gates ran with e.g. the
+  quality gate disabled; the enforcer deliberately does not act on it.

package/docs/guides/CAPACITY_POLICY.md

@@ -0,0 +1,98 @@
+# Capacity Policy as Code
+
+Uplift 0.5 of the [System-1 uplift plan](../plans/system1-uplift-2026-09-18.md):
+every UAP-managed service declares its resource budget, its headroom
+requirement, and its restart discipline; `uap doctor` probes each service and
+reports GREEN/RED/DARK health against the declaration.
+
+This generalizes the 2026-09-18 llama.cpp OOM fix: four SIGABRT crashes
+happened because a KV-cache budget was resolved against a GPU that also runs
+a desktop, and nothing declared that relationship. The fix held, but the
+*discipline* (declare budget + headroom + restart baseline, watch for
+violations) lived in a commit message. Now it is data.
+
+## Policy file
+
+Resolution order: `--policy <path>`, then `config/capacity-policy.json` in
+the project, then `~/.config/uap/capacity-policy.json`.
+
+```json
+{
+  "version": 1,
+  "services": [
+    {
+      "name": "gsq-rco-server",
+      "systemd": { "unit": "uap-gsq-rco-server.service", "scope": "user" },
+      "budget": { "vramMiB": 5120, "note": "--vbr-vram 5120M (OOM fix 2026-09-18)" },
+      "headroom": { "gpuMinFreeMiB": 600 },
+      "restartBudget": { "knownRestarts": 0, "allowedNew": 0 }
+    }
+  ]
+}
+```
+
+- **budget** — what the service is configured to stay inside (free-text
+  `note` records the provenance: which incident, which flag).
+  - `budget.vramMiB` declares the service's *own* allocator limit (e.g.
+    `--vbr-vram 5120M`), which the server enforces internally. The doctor
+    does **not** compare it against the process's total GPU footprint —
+    the host-side invariant it owns is `headroom.gpuMinFreeMiB`.
+  - `budget.rssMiB` **is** enforced: compared against the unit's
+    `MemoryCurrent`. Declaring it when systemd cannot report memory
+    (cgroup accounting off) is RED — a declared budget that cannot be
+    verified is not healthy.
+- **headroom.gpuMinFreeMiB** — free VRAM the *host* must keep; below it the
+  service is in OOM territory even while running.
+- **restartBudget** — `knownRestarts` is the accepted historical baseline
+  (e.g. crashes already fixed); `allowedNew` new crashes beyond that turn the
+  service RED. Zero is the right default after a fix lands.
+
+## Health semantics
+
+| Health | Meaning |
+| --- | --- |
+| GREEN | Unit active and serving, restarts within budget, headroom verified. |
+| RED | A budget is violated or unverifiable: new crashes since the baseline, GPU free below declared headroom, RSS over budget, headroom/RSS declared but not probeable. Also RED while `activating` (e.g. `SubState=auto-restart`) — a `Restart=always` crash loop is not yet serving, so it never reads GREEN, with or without a declared `restartBudget`. |
+| DARK | Unit failed/inactive/unresolvable — the service is *absent*, not degraded. |
+| UNKNOWN | systemd itself unavailable (container, macOS) — never a fabricated GREEN. |
+
+## Running it
+
+```bash
+uap doctor             # report, advisory (exit 0)
+uap doctor --json      # machine-readable
+uap doctor --strict    # exit 1 on RED/DARK — for CI and monitor loops
+```
+
+Reference implementation: `config/capacity-policy.json` in this repo is the
+**live policy of the gsq build host**, committed deliberately — the uplift
+requires the gsq-rco llama.cpp server and its watchdog monitor to be the
+reference implementations, and keeping the real file in-repo means `uap
+doctor` run from this checkout reports that host truthfully. Consumers
+elsewhere should ship their own `config/capacity-policy.json` (project) or
+`~/.config/uap/capacity-policy.json` (operator); the resolution order above
+makes the committed file the fallback only inside this repo.
+
+`uap doctor --strict` is the natural health source for the monitor service
+to consult before restarting anything, and for CI to refuse a deploy into a
+degraded host.
+
+## Decisions
+
+- **Restarts are budgeted against a baseline, not a rate.** `NRestarts` is a
+  monotonic counter; "crashes per day" windows go stale. The policy records
+  how many restarts are *explained* (pre-fix) and alerts on new ones.
+  Known hole: `systemctl restart` / `reset-failed` resets `NRestarts` to 0,
+  so bouncing a crash-looping unit produces a false GREEN until the next
+  crash. Re-baseline `knownRestarts` in the same commit as any legitimate
+  restart (deploy, config change) — a `uap doctor --rebaseline` verb is
+  planned as a follow-up; until it lands the edit is manual and deliberate.
+- **UNKNOWN instead of fail-open GREEN.** A doctor that cannot probe must say
+  so; a green report from a blind probe is the failure mode this tool exists
+  to prevent.
+- **One GPU probe per run** shared across services — nvidia-smi is not cheap.
+- **Probes fail soft on a 5s timeout.** A wedged driver or D-Bus makes the
+  doctor report UNKNOWN/RED-unverified instead of hanging the monitor loop
+  that called it.
+- **`uap doctor` vs `uap config doctor`:** the latter diagnoses *settings*
+  health; this diagnoses *running services* against declared capacity.