@miller-tech/uap 2.36.4 → 2.39.0

package/docs/architecture/adr/0014-loop-steps-and-team-solve-deliver.md

@@ -0,0 +1,142 @@
+# ADR 0014: Loop step kind + team-solve-deliver — the team directs the convergence loop
+
+- Status: Accepted
+- Date: 2026-11-03
+- Spec: `uap deliver --team-solve` (src/cli/deliver.ts), the `loop` step kind
+  (src/workflow/), examples/workflows/team-solve-deliver/,
+  docs/guides/DELIVER.md, docs/guides/WORKFLOWS.md.
+- Extends: ADR 0013 (the declarative workflow layer). Amends its decision #2
+  (three step kinds → four) and #7 (O7 now measures the shipped posture).
+
+## Context
+
+UAP has two engines that had never been combined:
+
+1. **team-solve** (ADR 0013): a static role DAG — planner, parallel
+   ideators, solver, reviewer, repairer — fresh contexts, files as the only
+   channel, deterministic verdict. Measured shape (GVS5H/Memdoor prior:
+   9.8/10 LiveCodeBench Hard with a 27B local model). But its bundled form
+   is contest-shaped: everything happens in the run directory and a command
+   step is the verdict. A REPO mission needs tools and the project's real
+   gates, which the workflow engine did not have.
+2. **deliver**: the convergence loop — a tool-using executor iterating
+   against the project's real completion gates (tiered ladder), with
+   posture escalation (single → phased → orchestrated → epics). But its
+   planning is a single model's inline reasoning; there is no role
+   structure, no parallel ideation, no fresh-context review.
+
+The request: combine them — the convergence loop DIRECTED BY team-solve for
+superior results — and make the behavior automatic in UAP, not a manual
+incantation.
+
+## Decision
+
+1. **A fourth step kind: `loop`.** The engine stays the graph authority and
+   gains a convergence-loop seam: it assembles the instruction (role prompt
+   or `goal:`, direct-dependency summaries, inlined `reads:`) and hands it
+   to a caller-injected `LoopStepExecutor` which owns the iteration and
+   reports `{ success, summary, turns }`. A loop step declares no
+   `writes:` — it works the PROJECT tree; its DeliveryResult is the record.
+   Loop-only fields: `turns:` (bound, passed through) and `verifyOnly:`
+   (gates with no executor turns — a verdict, not a builder). A standalone
+   `uap workflow run` fails closed at run start: no provider is injected.
+   The loader enforces kind/field separation exactly as for the other kinds.
+2. **Role steps ride the caller's executor rails.** `RunWorkflowOptions`
+   gains `completeStep` (per-step role-call seam) which takes precedence
+   over the raw `client`, and `client` becomes optional when it covers
+   every agent step. This is what lets deliver drive the roles through its
+   judge/generator rails (plan + review on the cool deterministic judge;
+   ideation on the generator) instead of re-implementing model choice.
+3. **The bundled `team-solve-deliver` workflow** composes the two engines:
+   plan → ideate-a/ideate-b (parallel, different engineering families) →
+   solve (loop) → review (fresh-context judge) → repair (loop, review-
+   seeded) → verify (loop, verifyOnly). The run directory is the role
+   ledger; the project tree is the work surface.
+4. **`uap deliver` injects itself as the seams** (src/delivery/
+   team-solve-deliver.ts — deps-injected and unit-tested, the epic/phased/
+   orchestrated extraction precedent). solve = the mission dispatch itself —
+   the SAME posture decision as any other mission (epics → orchestrated →
+   phased → single, verbatim extraction) with the team's approach enriching
+   the instruction; repair = a bounded ConvergenceLoop with the reviewer's
+   brief as instruction, fresh checkpoint state, and a declared `turns:`
+   bound honored as its cap (a NO REPAIR NEEDED verdict collapses to the
+   loop's own baseline check — zero turns, tree untouched); verify = the
+   tiered ladder with no executor turns, checked BEFORE any step-id
+   dispatch so a gates-only verdict can never run executor turns whatever
+   the id says. The final DeliveryResult aggregates honestly: verify pass
+   AND workflow status decide success; histories concatenate; the role
+   ledger path lands in finalFeedback. The role ledger's source directory
+   is surfaced at engagement (a project `.uap/workflows/` copy shadows the
+   bundled one — the operator must see which ran).
+5. **Engagement is a posture, tier-gated AUTO by default.**
+   `resolveTeamSolveWanted` (pure, tested): explicit flag
+   (`--team-solve`/`--no-team-solve`) > env kill (`UAP_DELIVER_TEAM_SOLVE=0`)
+   > persistent config (`.uap.json` `deliver.teamSolve` on/off) > AUTO,
+   which engages for high/critical complexity AND a non-single-file scope
+   (`looksSingleFileScoped`: exactly one named file + short instruction
+   stands down — the classifier's keyword ladder promotes "optimize"/
+   "refactor" regardless of scope, which is right for cheap model routing
+   and wrong for a 4-6× pipeline multiplier; an operator who names one file
+   has already disambiguated the scope) — the reliability ladder's "hardest
+   tier → full loop + escalation" row now resolves to this shape.
+   Stand-downs: self-gate and acceptance-primary (no objective ladder for
+   the roles to converge against — the verify pass would be vacuous),
+   lazy-solved (nothing left to direct), and resumes under AUTO (the
+   interrupted run continues on its recorded posture; an explicit
+   `--team-solve` resume re-runs the team wrapper over the resumed mission).
+   If the workflow is missing or its step shape has drifted from what the
+   seam mapping is keyed to, the run falls back to the standard dispatch
+   with a warning — auto engagement must never make deliver worse.
+6. **Composition, not replacement.** team-solve composes with epics and
+   orchestration rather than competing with them: the solve step dispatches
+   through the same chain, so a massive mission still sequences as epics —
+   each epic's loop now directed by the team's approach. One nuance: for
+   PHASED/ORCHESTRATED missions the phase plan is produced from the
+   un-enriched instruction BEFORE the solve step runs, so the team directs
+   per-phase execution but not the decomposition itself; epics are the
+   exception (their planning happens inside the solve dispatch, after the
+   enrichment).
+7. **The solve step is not engine-retried.** The bundled workflow sets
+   `maxRepairsPerStep: 0`: the solve loop already converges internally
+   (until-delivered + escalation inside the mission dispatch), and a
+   workflow-level retry would re-run the ENTIRE dispatch after it burned
+   its turn budget — doubling the hardest-tier spend and bypassing this
+   workflow's own review→repair discipline. The repair loop is the retry.
+
+## Alternatives considered
+
+- **Make deliver read workflow.yaml directly (no loop kind)** — rejected:
+  the engine would need to know about convergence loops, gates, and
+  DeliveryResult; the seam keeps the workflow layer generic and testable
+  with stub loops.
+- **A second engine (a "team deliver" runner beside ConvergenceLoop)** —
+  rejected: duplicates gate logic, posture routing, resume bookkeeping;
+  the wrapper composes the existing, already-tested machinery.
+- **Auto-engage on every mission** — rejected: role overhead is real tokens
+  (4+ completions before the first tool call); the ladder escalates with
+  MEASURED difficulty, not anxiety. Simple/moderate missions keep the
+  cheap posture.
+- **Team-solve replaces the epics/orchestration postures** — rejected:
+  they answer different questions (context scaling vs approach quality);
+  the composition answers both.
+
+## Consequences
+
+- `runState.runnerKind` gains `'teamsolve'` (transient: the solve step's
+  dispatch records the inner posture, which is what a resume re-enters; a
+  crash mid-roles records 'teamsolve' and the resume warns + falls to the
+  inner path).
+- Review visibility is v1-honest and PROMPT-MATCHED: the reviewer receives
+  the plan file plus a one-line solve report (gate status, turns,
+  changed-tree flag, feedback tail) and `steps/review.md` is written to
+  judge exactly on that — no file list, no diff. A richer review surface
+  (diff inlining) is a tracked follow-up.
+- Loader tightening (fail-closed by design): stray `turns:`/`verifyOnly:`
+  on a non-loop step previously zod-stripped silently; it now exits 3.
+- O7's arm C is now the shipped auto posture (`--no-team-solve` vs
+  `--team-solve` on the same tasks) — the experiment validates the
+  product, not a bespoke rig.
+- Known follow-ups (tracked, deliberate): diff-surface for the reviewer;
+  role-pin awareness inside completeStep (rails own model choice today);
+  ledger-aware resume for an explicitly `--team-solve` resumed run (roles
+  re-run; the ledger files persist for inspection).

package/docs/benchmarks/LCB_DROID_SMOKE.md

@@ -0,0 +1,111 @@
+# LCB-Droid Smoke — 10 problems × 1 pass, arm 2 (UAP-in-Droid)
+
+**Result: 10/10 = 100% pass@1 on hidden tests. All 10 public gates green. All 10 scorer-control references green. 9/10 agents self-stopped; 1/10 hit the wall cap with a gate-green solution collected at cap.**
+
+Run: 2026-10-27, started ~01:21 local, 284 min serial wall time (~4.7 h).
+Model: `abliterated-iq3_s` (DavidAU Qwen3.8-Flash-Next IQ3_S abliterated)
+served by strata on `:8080`. Chain:
+`droid exec` → `uap-anthropic-proxy` `:4000` → strata. Arm 2 only: the
+UAP operating protocol (AGENTS.md) with restricted tools
+(`Read,Glob,Grep,LS,Create,Edit,Execute`), 60-min wall cap with
+collect-at-cap, concurrency 1. Scoring: the vendored LCB fork's
+`codegen_metrics` (hidden tests, k=1, `release_v6`), each attempt scored
+alongside the published passing reference as a per-problem control.
+
+## Caveats — read before comparing any number below
+
+1. **The abliteration delta is unmeasured and is the strongest confound.**
+   The local model is the *abliterated* IQ3_S quant, not the pristine
+   Flash Next the published numbers describe. Abliteration can move
+   code-generation reasoning in either direction; no local A/B measures it.
+2. **Local quant vs remote full precision.** GVS5H's published Flash Next
+   ran on a pinned remote backend (full-precision API model,
+   `reasoning=on`, 128k cap). The local arm is IQ3_S.
+3. **Different mechanism.** GVS5H's orchestrated arm is ledger-based
+   self-orchestration in their scaffold; arm 2 is the UAP protocol inside
+   the Droid harness (droid exec + gates + tool restrictions). Same
+   benchmark, different agent machinery.
+4. **This subset is published-solved.** The published orchestrated arm
+   scores 10/10 on pass 1 over these exact 10 problems (9 of them 5/5).
+   A local 10/10 therefore **validates the pipeline and reaches the subset
+   ceiling — it does not establish parity or superiority on the full 100**,
+   where the published orchestrated mean is 93.0 and single-call is 84.2.
+5. **n = 1 pass.** No variance measured. Published per-pass spread on the
+   full 100 is 92–94 (orchestrated) and 82–86 (single).
+6. **One wall-capped problem.** `abc399_e` ran to the 60-min cap; its
+   collected-at-cap solution passes both public and hidden tests, but the
+   session never self-terminated (result doc killed before emission, so
+   whether it kept working past a green gate is unobservable).
+7. **Token usage is unmeasurable on this chain** — the local proxy reports
+   zero usage counters, so no cost/efficiency comparison is possible.
+
+## Per-problem results
+
+| Problem | Style | Wall | Turns | Stop | Public gate | Hidden | Pub. orchestrated p1 | Pub. single p1 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| arc196_b | stdin | 19.1 min | 60 | done | PASS | **PASS** | True (5/5) | True |
+| arc196_c | stdin | 56.4 min | 81 | done | PASS | **PASS** | True (5/5) | True |
+| arc196_a | stdin | 15.3 min | 53 | done | PASS | **PASS** | True (5/5) | True |
+| arc196_d | stdin | 57.3 min | 43 | done | PASS | **PASS** | True (5/5) | True |
+| 3777 | leetcode | 8.9 min | 81 | done | PASS | **PASS** | True (4/5) | True |
+| abc400_e | stdin | 5.9 min | 43 | done | PASS | **PASS** | True (5/5) | True |
+| abc400_g | stdin | 48.5 min | 81 | done | PASS | **PASS** | True (5/5) | True |
+| 3717 | leetcode | 5.1 min | 43 | done | PASS | **PASS** | True (5/5) | **False** |
+| 3765 | leetcode | 7.6 min | 81 | done | PASS | **PASS** | True (5/5) | True |
+| abc399_e | stdin | 60 min (cap) | — | wall-cap | PASS | **PASS** | True (5/5) | True |
+
+Smoke pass@1: **10/10 (100%)** on this subset. Published orchestrated p1
+on the same subset: 10/10. Published single-call p1 on the same subset:
+9/10 (missed 3717, which the local arm solved).
+
+## Anchors (published, full 100-hardest, release_v6, pass@1)
+
+| Arm | Published pass@1 (full 100) |
+| --- | --- |
+| Qwen3.8 Flash Next single-call | 84.2 |
+| Qwen3.8 Flash Next orchestrated | **93.0** |
+| Claude Fable 5 single-call | 90.4 |
+| Qwen3.8-27B single / orchestrated | 66.8 / 92.4 |
+
+The local smoke subset (10 problems) is not comparable to these full-100
+means; it is listed here because these are the anchors any full run will
+be judged against.
+
+## Interpretation
+
+The smoke's purpose (per spec) was end-to-end pipeline validation, and
+that succeeded completely: rendering, verbatim prompt fidelity, public-test
+gates, UAP stop discipline (9/10 self-stops plus one collect-at-cap
+rescue), served-model snapshots, resumable records, and hidden-test
+scoring with per-problem reference controls all worked with zero
+infrastructure blockers.
+
+The 10/10 is at the subset ceiling — consistent with the published
+orchestrated arm, but this subset cannot discriminate arms. Any claim
+about local-vs-published performance requires the full 100 (or a
+randomly drawn, not published-solved, subset).
+
+Runtime scale for follow-on decisions (measured, serial, concurrency 1):
+mean 28.4 min/problem, total 284 min for 10. Extrapolations: 50×3 pilot
+≈ 71 h; full 100×5 ≈ 237 h (~10 days). Two problems ran near the 60-min
+cap, so a full run should expect some wall-caps and keep collect-at-cap.
+
+## Artifacts
+
+- `benchmarks/lcb-droid/results/smoke-10/` — `summary.json`,
+  `records.jsonl` (per-attempt records with served-model snapshots),
+  `smoke-scored.jsonl` (official verdicts + controls), `solutions/*.py`
+  (the 10 collected model outputs), `droid-results/*.json` (droid result
+  docs per completed session; abc399_e's was killed at cap).
+- `benchmarks/lcb-droid/render_tasks.py`, `run_smoke.py`, `score_smoke.py`
+  — reproduce with the recipe in `benchmarks/lcb-droid/README.md`.
+- `benchmarks/lcb-droid/anchors.json` — published anchors and per-problem
+  verdicts (GVS5H @ 707e2129).
+
+## Decision gate (requires explicit go)
+
+1. **Stop** — smoke goal met, archive as-is.
+2. **Pilot 50×3** — ~71 h serial; adds variance signal.
+3. **Full 100×5** — ~237 h serial; directly comparable to published means.
+4. **Add arm 1** (no AGENTS.md protocol) — isolates the protocol's
+   contribution on the same chain; any of the above can be combined with it.

package/docs/guides/DELIVER.md

@@ -58,6 +58,7 @@ For a mission too large to hold in one context, `deliver` scales down the contex
 - **`--decompose`** splits the mission into sequential phases, each converged by its own loop (auto for long, complex instructions; `--no-decompose` forbids it).
 - **`--orchestrate`** runs those phases through the **blackboard orchestrator** with *minimal* per-task context — each task sees only its goal + its direct-dependency outputs. Implies `--decompose`.
 - **`--epics`** runs a massive mission as a sequence of **epics, each a fresh session** — only prior epics' summaries are injected, never their full code — looped until each is accepted (auto for very long missions; `--no-epics` disables).
+- **`--team-solve`** runs the mission through the **team-solve-deliver workflow**: team roles direct the convergence loop. A planner and two parallel ideators (minimal-change vs structural) produce an approach; the **solve** step runs the SAME posture decision as any other mission (epics → orchestrated → phased → single) with that approach enriching the instruction; a **fresh-context reviewer** judges the outcome against the plan; a review-seeded **repair** loop applies only what the review named; and a **gates-only verify** pass — the tiered ladder with no executor turns — decides the mission. **AUTO by default**: engages for high/critical-complexity missions only (the reliability ladder's hardest-tier row), stands down on self-gate, lazy-solved, and resumed runs. `--no-team-solve`, `UAP_DELIVER_TEAM_SOLVE=0`, or `.uap.json` `deliver.teamSolve: "off"` disable; `deliver.teamSolve: "on"` always engages. The role ledger (plan, proposals, repair brief) lands in `.uap/workflow-runs/<runId>/`. See [Workflows](WORKFLOWS.md) for the workflow format.
 
 **Contracts-first** (on by default inside epic/decompose runs; `UAP_DELIVER_CONTRACTS=0` disables): the first epic plans the shared types, interfaces, and registry APIs the rest build against. Once accepted, its files are **locked read-only** so later epics build against frozen signatures and can't drift them. The public surface is *extracted and verified against emitted source* — only names proven present are recorded — which is what makes cross-module composition reliable without holding every module in context.
 
@@ -202,13 +203,14 @@ Long autonomous runs fail in predictable ways; `deliver` has a guard for each:
 | `--ci-passes <n>` | Max CI re-converge passes on failure (1–10, default `2`) |
 | `--ci-timeout <minutes>` | CI watch budget in minutes (1–120, default `20`) |
 
-**Big builds (decompose → orchestrate → epics)**
+**Big builds (decompose → orchestrate → epics → team-solve)**
 
 | Flag | Purpose |
 |---|---|
 | `--decompose` / `--no-decompose` | Split the mission into sequential phases, each converged by its own loop (auto for long complex tasks) |
 | `--orchestrate` / `--no-orchestrate` | Run decomposed tasks through the blackboard orchestrator with MINIMAL per-task context (implies `--decompose`) |
 | `--epics` / `--no-epics` | Run a massive mission as a sequence of fresh-session epics until each is accepted (auto for very long missions) |
+| `--team-solve` / `--no-team-solve` | Run the mission through the team-solve-deliver workflow: roles plan/ideate/review, solve+repair are gates-driven convergence loops, verify is gates-only (AUTO on high/critical complexity) |
 
 **Exploration & quality aids**
 

package/docs/guides/WORKFLOWS.md

@@ -0,0 +1,179 @@
+# Workflows — static step DAGs over the blackboard orchestrator
+
+A workflow is **data, not a plan**: one `workflow.yaml` plus role-prompt files
+that describe a step graph — agent roles, deterministic commands, approval
+gates. The runner executes it on the same machinery `uap deliver` uses
+(task-orchestrator: dependency-aware dispatch, bounded repair,
+resume-at-the-step-boundary), so the graph semantics are the validated
+delivery semantics.
+
+The shape this buys is the measured one from GVS5H/Memdoor: several small
+roles — planner, ideators, solver, reviewer, repairer — each in a FRESH
+context, communicating only through files, with a command step's exit code
+(rather than any model's claim) as the verdict. Five Qwen3.8-27B roles on
+this shape matched the authors' own harness on LiveCodeBench Hard (9.8/10
+vs 9.6, Fable 5 single-call at 8.0 — their runs, their caveats; see
+`examples/workflows/team-solve/README.md`).
+
+## Quickstart
+
+```bash
+uap workflow list                                        # what exists, from where
+uap workflow show team-solve                             # the validated plan + pins
+uap workflow run team-solve \
+  --input examples/workflows/team-solve/sample           # run the LIS smoke task
+uap workflow show team-solve-deliver                     # the loop-step variant (deliver-driven)
+uap workflow status                                      # every run + its verdict
+uap workflow resume <runId>                              # continue at the boundary
+```
+
+Exit codes: `0` success · `1` a step failed · `2` blocked at a gate
+(resumable) · `3` the workflow file is invalid. Cron-safe by construction.
+
+Two bundled workflows: **team-solve** (contest-shaped: everything happens in
+the run directory, a command step is the verdict — runs standalone) and
+**team-solve-deliver** (repo missions: solve/repair are convergence loops
+against the project's real gates, verify is gates-only — driven by
+`uap deliver --team-solve`, which injects the loop machinery; standalone
+runs fail closed). See
+[examples/workflows/team-solve-deliver/README.md](../../examples/workflows/team-solve-deliver/README.md).
+
+## Where workflows live
+
+Search order — first hit wins, so a project can override a bundled workflow
+without touching the install:
+
+1. `<project>/.uap/workflows/<name>/` — project-owned (committed)
+2. `~/.uap/workflows/<name>/` — operator-wide
+3. `<package>/examples/workflows/<name>/` — bundled (team-solve ships here)
+
+## The file format
+
+```yaml
+name: my-workflow
+description: One line, shown in `show`.
+defaultModel: qwen38-27b     # optional pin ladder default (see below)
+parallel: 2                  # max concurrent independent steps (default 1)
+maxRepairsPerStep: 1         # bounded re-execution of a failed step
+steps:
+  - id: plan                 # lowercase slug (repair chains use <id>.r0-…)
+    kind: agent              # agent | command | gate | loop
+    title: Planner           # optional label
+    prompt: steps/plan.md    # role-prompt file, relative to this directory
+    reads: [task.md]         # run-dir files inlined into the prompt
+    writes: [plan.md]        # writes[0] receives the reply (the ledger)
+    requires: []             # DAG edges: ids that must SUCCEED first
+  - id: verify
+    kind: command
+    command: bash check.sh --strict   # cwd = the run directory
+    writes: [verify.log]
+    requires: [plan]
+```
+
+### Step kinds
+
+- **agent** — one fresh completion: the role prompt (or inline `goal:`),
+  plus direct-dependency summaries and the inlined `reads:` files, sent to
+  the pinned model. The reply is written verbatim to `writes[0]`. There is
+  no chat: the run directory is the only memory. Agent steps take exactly
+  one of `prompt:` / `goal:`.
+- **command** — a shell line in the run directory. Exit 0 = success. With
+  `neverFails: true` the output is captured as evidence and the step never
+  fails the run (team-solve's `test` step); without it, a nonzero exit IS
+  the verdict (team-solve's `verify`). Output lands in `writes[0]` (or
+  `<id>.log`). `timeoutMs` bounds it (default 120000). The workflow's own
+  directory is exported as `$UAP_WORKFLOW_DIR` — reference harness scripts
+  there (`bash "$UAP_WORKFLOW_DIR/check.sh"`) instead of copying them into
+  the run.
+- **gate** — pauses the run for an operator decision. Default `waitMs: 0`
+  returns immediately as BLOCKED (exit 2); `uap workflow approve <runId>
+  <step>` records the approval, then `resume` re-runs the gate and passes.
+  Set `waitMs` if a run should hold a terminal open for approval instead.
+- **loop** — a convergence loop owned by the CALLER, not the engine: the
+  engine assembles the instruction (role prompt or `goal:`, plus
+  direct-dependency summaries and inlined `reads:`) and hands it to an
+  injected `runLoop` seam, which drives a tools-and-gates iteration to
+  completion and reports `{ success, summary, turns }`. The step outcome is
+  the seam's result — there is no `writes[0]` (a loop works the project
+  tree; its DeliveryResult is the record). Loop-only fields: `turns:` (a
+  turn bound passed through to the seam) and `verifyOnly:` (the loop runs
+  the gates with NO executor turns — a verdict, not a builder; this is what
+  `team-solve-deliver`'s final step is). A standalone `uap workflow run`
+  cannot execute loop steps — no provider is injected — and fails closed at
+  run start with that message; `uap deliver --team-solve` is the caller
+  that can.
+
+### Trust boundary
+
+Authoring a workflow is authoring shell + prompts for your own account:
+`command:` lines run through a shell as the invoking user (the same trust
+level as a `package.json` script or a CI step — this is the design, not a
+bug), and `--input` task directories are copied into the run directory
+where later steps may read them. Authored commands may EXECUTE files a
+model produced — team-solve's harness runs `python3 solution.py`, model
+code under your privileges, exactly like `uap deliver` gate scripts. Model
+replies are data on the way IN (prompts and files); whether they execute
+is a decision the workflow author made when writing the command step. For
+untrusted tasks: insert a `gate` before the first command step, or wrap
+the run — `uap sandbox [--net off] -- uap workflow run <name>`.
+
+Two consequences of the trust model worth knowing:
+
+- **Workflows are discovered from the current directory** (`.uap/workflows/`
+  first). Running `uap workflow run <name>` inside a cloned repository
+  executes that repo's command steps — the same act as running its npm
+  scripts. Read a repo's workflows before running them.
+- **`--endpoint <url>` receives your prompts.** Prompt assembly inlines
+  `reads:` file contents; a third-party endpoint sees them. Local pins
+  keep that traffic on the loopback.
+
+### Model pins
+
+Steps name no model — the pin ladder answers:
+
+```
+step.model → workflow.defaultModel → uap workflow run --model → fleet default
+```
+
+The fleet default is `qwen38-27b` (the strata arm through the proxy,
+`http://127.0.0.1:4000/v1`). `--endpoint <url>` overrides the endpoint for
+every arm, so the same workflow runs on any OpenAI-compatible server.
+
+### Authoring rules (enforced at load, exit 3 on violation)
+
+- Step ids are lowercase slugs; `requires:` must reference known ids; the
+  graph must be a DAG (cycles are authoring bugs, surfaced not survived).
+- Fields are kind-checked: `command` on an agent step, `reads` on a command
+  step, etc. are rejected.
+- Two steps that write the same file with no `requires:` path between them
+  are rejected — parallel siblings must not be able to clobber each other
+  (the graph-safety FALSE INDEPENDENCE invariant, checked at authoring
+  time instead of merge time).
+- `reads`/`writes` are run-directory relative; absolute paths and `..`
+  escapes are rejected.
+- Steps may not write `run-state.json` or `.gates/` — the runner's own files.
+
+## Runs, state, resume
+
+Every run gets `.uap/workflow-runs/<runId>/`: the step output files (the
+ledger), `run-state.json` (status + accepted steps + summaries), and gate
+approvals. `--input <dir>` copies a task directory (e.g. `task.md` +
+`tests/`) into the fresh run dir first.
+
+State persists after EVERY accepted step. An interrupted run resumes with
+`uap workflow resume <runId>` — accepted steps are seeded into the
+blackboard and never re-executed; the model is only paid for what remains.
+
+## What this is not
+
+- Not a replacement for `uap deliver`: deliver's convergence loop is for
+  repo-editing tasks judged by real gates; a workflow's agent steps are
+  single completions producing files. Use a workflow when the SHAPE is the
+  asset — when the same role graph should run on many inputs.
+- Not the Memdoor harness: the engine is UAP's orchestrator; the ported
+  team-solve keeps the method's structure and discipline, not its byte
+  parity. Its published numbers belong to the authors.
+- The validation claim (does role-DAG structure beat the gate loop on the
+  same local model?) is option O7 in
+  [model-performance-proof-options.md](../plans/model-performance-proof-options.md)
+  and starts only on an explicit go, like every option there.

package/docs/plans/model-performance-proof-options.md

@@ -153,12 +153,51 @@ comparator (K3's published 88.3, harness caveat attached).
 - **Discrimination status:** 89 tasks × 5 attempts is powered for the
   published convention's effect sizes; report Δ with bootstrap CI + McNemar.
 
+### O7 — Role-DAG structure vs the gate loop (free, GPU-local)
+
+**Claims:** C1 (its strongest form) · **Cost:** GPU-hours only ·
+**Prereqs:** `uap workflow` (shipped) + the bundled
+[team-solve](../../examples/workflows/team-solve/README.md) +
+[team-solve-deliver](../../examples/workflows/team-solve-deliver/README.md)
+(auto-applied by `uap deliver` on high/critical complexity) + a
+LiveCodeBench-Hard-style task set.
+
+The measured prior is external and published: five Qwen3.8-27B roles on a
+static relay-with-cross-correction graph matched the authors' own harness on
+LiveCodeBench Hard (9.8/10 vs 9.6 on their first ten; Fable 5 single-call at
+8.0) — structure, not model class, carried the result. UAP now has the
+capability to test that prior against ITS OWN baseline: the gate loop. The
+experiment now validates EXACTLY what ships — team-solve-deliver is the
+auto-applied posture for high/critical missions, so arm C is the product's
+default hardest-tier behavior, not a bespoke rig:
+
+| arm | treatment |
+|---|---|
+| A | single-shot (one completion per problem) |
+| B | `uap deliver --no-team-solve` gate loop (the pre-existing C1 baseline) |
+| C | `uap deliver --team-solve` (the shipped auto posture: roles direct the convergence loop; solve/repair are gates-driven loops; verify is gates-only) |
+
+- **Would prove:** whether role-DAG structure lifts a weak local model
+  BEYOND the gate loop alone — the C1 claim's strongest form, and the first
+  number that would justify the workflow layer (and its auto-engagement on
+  the hardest tier) on measured grounds rather than the GVS5H prior.
+- **Would NOT prove:** parity with the authors' harness (their numbers are
+  theirs — different prompts, OpenRouter host, their grader; UAP's port
+  keeps the method, not the bytes), anything about frontier models, or any
+  C2/C3 claim.
+- **Discrimination status:** pilot first (10 problems × 3 arms × 3 passes);
+  the paired format's bootstrap CI sizes the power-up. Contamination
+  caveats travel with the tasks exactly as they did for the authors.
+
 ## Suggested order
 
 1. **O1** (free, hours of analysis, no risk) → publishes the descriptive dataset and
    targets O2's strata.
 2. **O2 hardest-tier replication** (free, targeted) → upgrades the ladder's
    strongest row from underpowered to powered, or retires it honestly.
+   **O7** (also free, also C1) can ride the same task-set effort: pilot the
+   three arms once the task set exists, and only power up whichever arm
+   delta the pilot says is worth powering.
 3. **O4 + O5** (free, small) → the C3 throughput numbers, including the
    demote-if-null honesty.
 4. **O3** (the gap) → design review first (the sequence design is its own

package/docs/reference/CLI.md

@@ -53,6 +53,7 @@ runs, keeping `--help` fast.
 | [`proxy`](#proxy) | Reference-counted, session-scoped local inference proxy lifecycle |
 | [`orchestrator`](#orchestrator) | Toggle the long multi-turn deliver orchestrator |
 | [`handsfree`](#handsfree) (`hf`) | Hands-free persistence: loop any model to a 100% ledger |
+| [`workflow`](#workflow) | Static YAML step DAGs (agent/command/gate/loop) over the orchestrator |
 | [`challenge`](#challenge) | Open multi-agent challenge with a significance-gated leaderboard |
 | [`sandbox`](#sandbox) | Run a command with a kernel-enforced writable-dir boundary |
 | [`react`](#react) | Resolve dynamic experts/skills/patterns for a lifecycle event (JSON) |
@@ -762,6 +763,38 @@ See [Orchestrator & Hands-Free](../guides/ORCHESTRATOR.md).
 
 ---
 
+## `workflow`
+
+Declarative workflows: a static `workflow.yaml` step DAG (agent | command |
+gate | loop) executed on the blackboard orchestrator — role-specialized steps
+in fresh contexts talking through files, deterministic command verdicts,
+approval gates, resume at the step boundary. `loop` steps run through a
+caller-injected convergence loop (`uap deliver --team-solve` is the caller
+that can; a standalone run of a loop-bearing workflow fails closed).
+
+`uap workflow [list | show <name> | run <name> | status [runId] | resume <runId> | approve <runId> <step>]`
+
+| Flag | Purpose |
+|------|---------|
+| `--input <dir>` | Task directory copied into the run (what the steps read) |
+| `--model <preset>` | Model pin (ladder: step → workflow default → this → fleet default) |
+| `--endpoint <url>` | Override the model endpoint (OpenAI-compatible `/v1`) |
+| `--run-id <id>` | Name the run directory under `.uap/workflow-runs/` |
+| `--mission <text>` | One-line objective assembled into every step context |
+| `--dry-run` | Validate and print the execution plan; run nothing |
+
+Exit codes: `0` success · `1` step failed · `2` blocked at a gate (resumable) ·
+`3` invalid workflow.
+
+```bash
+uap workflow run team-solve --input examples/workflows/team-solve/sample
+uap workflow show team-solve-deliver     # the deliver-driven variant (loop steps)
+```
+
+See [Workflows](../guides/WORKFLOWS.md).
+
+---
+
 ## `challenge`
 
 Open multi-agent challenge: a shared goal, verified submissions, and a

package/docs/reference/CONFIGURATION.md

@@ -104,6 +104,7 @@ Top level: `version`, `project`, `memory`, `worktree`, `costOptimization`,
 |---|---|---|
 | `deliver.orchestrate` | Blackboard orchestration for decomposed missions (`"on"`/`"off"`) | `"on"` (preflight seeds it) |
 | `deliver.epics` | Epic controller outer loop (`"on"`/`"off"`) | `"on"` (preflight seeds it) |
+| `deliver.teamSolve` | Team-solve posture — roles direct the convergence loop (`"on"`/`"off"`; unset = AUTO: high/critical complexity only) | unset (auto) |
 | `deliver.parallelTasks` | Worktree-isolated parallel dispatch: independent READY orchestrator tasks run concurrently, each convergence loop + its gates in a detached git worktree seeded with the mission's current state; deltas merge back serially, and a merge conflict fails the task into the minimal-repair retry. Completion-triggered scheduling: a finished task's slot refills the moment it settles (no wave barrier — a fast sibling never idles behind a slow one), and a task whose dependencies all succeeded starts as soon as its slowest sibling-dependency settles. Settlement stays strictly sequential (one task at a time); which task settles next is timing-dependent. Clamped to 1–8. **Parallel is the default** — an unset key resolves to 4. Parallelism is conditional on worktree isolation: outside a git repo (or with an unborn HEAD) the run stays sequential and logs why. Set `1` (or `UAP_DELIVER_PARALLEL_TASKS=1`) to force sequential execution. | `4` (parallel, worktree-isolated) |
 | `deliver.adversarialGate` | Adversarial red-team gate before a converged run is accepted (`false`/`0`/`"off"` disables; a positive integer retunes the round budget, cap 4). Overridden by `UAP_DELIVER_ADVERSARIAL_GATE`. | on (≤2 rounds) |
 | `deliver.criteriaLint` | Plan-time lint of planner/split-emitted acceptance criteria; behavioral criteria gain an executable-evidence clause. Overridden by `UAP_DELIVER_CRITERIA_LINT`. | on |

package/docs/reference/FEATURES.md

@@ -189,6 +189,24 @@ you'd run by hand.
 | Sandbox grants + egress boundary (`sandbox-grants.ts`, `sandbox.ts`) | Recorded authority for the bubblewrap sandbox: extra writable holes are per-session GRANTS (`uap sandbox grant <path> --session <id> --reason "..."`, TTL 8h default / 7d cap, revocable) from a consent ledger at the main checkout root, audit-logged per run — the legacy `UAP_SANDBOX_ALLOW` env still works but is named UNRECORDED in the audit. The out-of-checkout trust anchor (`sandbox-anchor.ts`) records the sanitized-ledger hash after every recorded mutation; a ledger changed outside a consent operation is detected on load — new grants refused, the session resolves ZERO grant-derived holes (fail-closed), and the grants listing stamps every row unverified. The audit JSONL is seq-stamped and bounded (past 12,000 lines it compacts to the 10,000 newest event lines plus the triggering event and one recorded `audit-compaction` marker — 10,002 total). `uap dashboard` (session view) surfaces the active grants per session with the anchor verdict and a revoke command per grant. `--net off` is the kernel egress boundary: own network namespace with nothing up (no TCP, no DNS, not even loopback) for untrusted code, evals, and data-only work. The proxy's optional `PROXY_SOCKET` (0600 AF_UNIX) is the permission-gated model choke point; `uap proxy connect` re-serves it on local TCP for AF_UNIX-less clients. |
 | Integrity (`integrity.ts`) | Test-protection / integrity guard — stops the model from gutting the tests to "pass." |
 
+## Workflows (`src/workflow/`) — Build (structured)
+
+> **Stage: Build.** The declarative layer over the blackboard orchestrator: a
+> workflow is DATA — a static `workflow.yaml` step DAG with role prompts,
+> deterministic command steps, and approval gates — so the graph that five
+> small models execute is authored once, reviewed, and re-run, instead of
+> re-planned by a model every mission. The GVS5H/Memdoor team-solve shape:
+> role-specialized steps cross-correct each other through files, and a
+> command step's exit code — not a model's claim — is the verdict.
+
+| Feature | Description |
+|---------|-------------|
+| Workflow loader (`loader.ts`) | Fail-closed front door: zod schema + graph checks (unique ids, known `requires:`, cycle rejection, kind/field confusion, parallel write collision, run-dir path escapes, reserved paths) before any model is paid. Search roots: project `.uap/workflows/` → `~/.uap/workflows/` → bundled `examples/workflows/`. |
+| Workflow runner (`runner.ts`) | Four step kinds onto `orchestrate()` unchanged: `agent` (fresh single completion; `reads:` inlined into the prompt, the reply IS the file — the ledger discipline), `command` (exit-code verdict with `neverFails` evidence mode), `gate` (approval pause → `uap workflow approve`, exit 2, resumable), `loop` (a caller-injected convergence-loop seam — the engine assembles the instruction, the caller drives tools-and-gates iteration; `verifyOnly:` runs the gates with no executor turns). Run state persists after every accepted step; resume seeds `initialDone` so finished work is never redone. Exit contract 0/1/2/3 for CI/cron. |
+| Workflow CLI (`cli/workflow.ts`) | `uap workflow list | show | run | status | resume | approve`. Steps name no model: the pin ladder (step → workflow `defaultModel` → `--model` → the local fleet default, `qwen38-27b` on the strata arm) answers, so one workflow file is portable across arms and endpoints. |
+| Bundled team-solve (`examples/workflows/team-solve/`) | The flagship: plan → parallel ideate-a/ideate-b → solve → deterministic test → review → repair → verify, five roles, files only. The sample LIS task runs end-to-end on the local fleet; its provenance and caveats (the 9.8/10 LiveCodeBench Hard numbers are the authors', on OpenRouter) are documented in place. |
+| Bundled team-solve-deliver (`examples/workflows/team-solve-deliver/`) | The combined engine: team roles directing the deliver convergence loop. plan → parallel ideations → solve (loop, the mission dispatch with the team's approach enriching the instruction) → fresh-context review → repair (loop, review-seeded) → verify (loop, gates-only verdict). `uap deliver --team-solve` injects its machinery as the seams and AUTO-engages it for high/critical-complexity missions (`--no-team-solve` / `UAP_DELIVER_TEAM_SOLVE=0` / `.uap.json` `deliver.teamSolve` control it; ADR 0014). |
+
 ## MCP Router (`src/mcp-router/`) — Cross-cutting (lean context)
 
 > **Stage: Every station.** A stuffed context window slows and confuses the whole