@nanobpm/nano-workforce 0.203.0 → 0.204.0

package/docs/agent-guide.md

@@ -1,355 +1,161 @@
 # Nano Workforce — agent operator guide
 
-You are an AI assistant helping a human operate a running **Nano Workforce**
-instance. Nano Workforce is a durable orchestration app (a [Nano](https://nanobpm.io)
-Urban app) that drives pull requests to **review convergence** against an automated
-reviewer, then **merges** them, and can take a whole issue and **plan → implement →
-converge** it across a fleet of coding agents.
-
-This document is served live by the running app so you always match the deployed
-version. Use it to **drive** the workforce (submit work, answer escalations) and to
-**debug** it (find stuck instances, relate them to PRs, inspect the models/prompts,
-and unstick or report problems).
+You are helping a human operate a running **Nano Workforce** instance: a durable
+orchestration app that drives pull requests to **review convergence** and **merges** them,
+takes whole issues through **plan → implement → converge** across a fleet of coding agents,
+and runs agent-authored **delivery graphs**.
 
 - **App control API base:** `__BASE__`
-- **Engine (Nano/Camunda-8 v2 REST) base:** `__ENGINE__`
+- **Engine (Camunda-8 v2 REST) base:** `__ENGINE__`
 - **Source repository:** `nanobpm/nano-workforce`
 
-Everything below assumes the app control API is reachable at `__BASE__`. Most app
-endpoints are mounted under that base (ADR 0059), but a few siblings sit outside it —
-notably the interactive docs (Swagger UI) at `__BASE__/../api-docs` and the action
-endpoints (e.g. the cancel action at `/app/actions/cancel`). Paths below are written
-in full so you can tell which are under the control-API base and which are not.
+**Tools first, curl as fallback.** Over MCP, call the projected tool named in each
+recipe. Without MCP, use the curl door in the §10 crosswalk. If the deployment sets
+`NANO_PR_WEBHOOK_SECRET`, add `-H "x-hook-secret: <secret>"` to **every** request — the
+read endpoints (`/version`, `/status`, `/escalations`, `/agent`, `/agent/guide`, …) are
+guarded too, not only the POSTs.
 
 ---
 
 ## 0. Orient yourself first
 
-Before acting, confirm what is running and what is in flight. **Prefer the projected
-tools** (`getVersion`, `listActivePrs`); curl is the no-MCP fallback only. Every step in
-this guide that has a tool is mapped in the **tool↔curl crosswalk (§10)** — reach for the
-tool first and drop to curl only when you are not driving this instance over MCP.
-
-```text
-# Which code is live (app version, urban version, git sha/branch, uptime):
-tool: getVersion            # GET /version
-
-# Every PR currently in flight (not converged/abandoned), with its engine
-# process key, status, round, and any open escalation:
-tool: listActivePrs         # GET /status
-```
+Confirm what is running and what is in flight before you act.
 
 ```bash
-# No-MCP fallback (agent without the projected tools):
-curl -sS __BASE__/version | jq
-curl -sS __BASE__/status | jq
+curl -sS __BASE__/version | jq   # tool: getVersion: app/urban version, git sha, uptime
+curl -sS __BASE__/status  | jq   # tool: listActivePrs: every PR in flight
 ```
 
-`listActivePrs` (the `/status` endpoint) is your primary situational-awareness surface.
-Each entry carries:
-`prKey` (`owner/repo#123`), `status`, `round`, `processKey` (the **engine process
-instance key** — the bridge to the engine REST API, §5), `openEscalation`,
-`activeWorker`/`leaseUntil` (is an agent actually working the round, or is the job
-just queued), and `updatedAt`.
+Each `/status` entry carries `prKey` (`owner/repo#123`), `status`, `round`, `processKey`
+(the **engine process-instance key**, the bridge to §5), `openEscalation`,
+`activeWorker`/`leaseUntil` (an agent holds the round, or the job is just queued), and
+`updatedAt`.
 
 ---
 
 ## 1. Submit a PR for review convergence
 
-One PR → one durable `convergence-loop`. Each round dispatches a `senior:pr-review`
-agent; between rounds the process parks on a durable message-catch, so review latency
-never holds an agent slot. The app's poller watches GitHub and republishes
-`review-ready` when a new review lands.
+One PR → one durable `convergence-loop`. Each round runs a `senior:pr-review` agent. Between
+rounds the process waits durably for the next review (the poller republishes `review-ready`),
+so review latency never holds an agent slot.
 
 ```bash
-# Minimal: converge, then merge (if NANO_PR_AUTO_MERGE is on — the default).
+# tool: startConvergenceLoop
 curl -sS -X POST __BASE__/actions/start/convergence-loop \
   -H 'content-type: application/json' \
-  -d '{ "pr": "owner/repo#123" }'
+  -d '{ "pr": "owner/repo#42", "autoMerge": true, "maxRounds": 8, "dependsOn": ["owner/repo#40"] }'
 ```
 
-The body is flat. Fields:
-
 | field | type | meaning |
 |---|---|---|
-| `pr` (or `url`) | string | the PR — `owner/repo#123` or a full PR URL. Required. |
-| `autoMerge` | boolean | **Positive per-request setting.** `false` = review only, stopping at `converged`, regardless of the global default; `true` = converge **then merge** when `NANO_PR_AUTO_MERGE` is enabled. |
-| `maxRounds` | integer | per-submit cap before escalating (clamped 1–100; default from `NANO_PR_MAX_ROUNDS`, 20). |
-| `dependsOn` | string[] | other `prKey`s that must land before this one merges (merge-loop barrier). |
-| `autoResolveEscalations` | boolean | **Opt in to the escalation steward** (issue #889). When `true`, this loop's open escalations become eligible for the steward to review and auto-resolve every 30 min (recorded reviewably in **Auto-resolutions**, §3). Default `false` — escalations stay human-only. |
+| `pr` (or `url`) | string | `owner/repo#123` or a PR URL. Required. |
+| `autoMerge` | boolean | `false` = review only, stop at `converged`. `true` = converge **then merge**. **Omitted = merge** (the merge path is the default). Merging also requires `NANO_PR_AUTO_MERGE` on (the default); a per-request value only ever narrows to review-only, it never forces a merge when the global switch is off. Choose deliberately — to guarantee review-only, set `autoMerge: false` explicitly. |
+| `maxRounds` | integer | round cap before escalating (1–100; default `NANO_PR_MAX_ROUNDS`, 20). |
+| `dependsOn` | string[] | `prKey`s that must land before this one merges. |
+| `autoResolveEscalations` | boolean | opt in to the escalation steward (§3). Default `false`. |
 
-**Converge-only vs. converge-and-merge — choose deliberately:**
-
-```bash
-# Review only — do NOT merge (use when the human wants to merge by hand,
-# or is only after a review pass):
-curl -sS -X POST __BASE__/actions/start/convergence-loop \
-  -H 'content-type: application/json' \
-  -d '{ "pr": "owner/repo#123", "autoMerge": false }'
-
-# Converge then merge, with a dependency barrier and a tighter round cap:
-curl -sS -X POST __BASE__/actions/start/convergence-loop \
-  -H 'content-type: application/json' \
-  -d '{ "pr": "owner/repo#42", "autoMerge": true, "maxRounds": 8, "dependsOn": ["owner/repo#40"] }'
-```
-
-Submitting is **idempotent on the PR key** — re-POSTing the same PR refreshes the
-aggregate rather than starting a duplicate loop. The response (202) echoes the
-`prKey` and the engine `processKey`.
+Idempotent on the PR key: re-POSTing refreshes the record instead of starting a second
+loop. The 202 response echoes `prKey` and `processKey`.
 
 ---
 
 ## 2. Submit an epic (plan → implement → converge)
 
-Hand the fleet a whole issue. A planning agent decomposes it into levelized tasks; a
-parallel fan-out drives one implementation agent per task (one PR each); every opened
-PR is then enrolled into its own convergence loop (§1).
+A planning agent splits an issue into levelled tasks. One implementation agent per task
+opens a PR, and every PR is enrolled in its own convergence loop (§1).
 
 ```bash
+# tool: startPlanFanout
 curl -sS -X POST __BASE__/actions/start/plan-fanout \
   -H 'content-type: application/json' \
   -d '{ "issue": "owner/repo#123", "baseBranch": "epic/agent-protocol" }'
-```
-
-The body is flat: `issue` (or `url`) — `owner/repo#123` or an issue URL — plus a REQUIRED
-`baseBranch` (ADR 0003), the branch the fleet branches off and opens every PR against; a
-blank/absent base is rejected with a 400. Starting a
-plan is idempotent on the plan key; an already-running plan short-circuits. The
-response (202) echoes the `planKey` and engine `processKey`.
 
-Both epic (`startPlanFanout`) and feature (`startFeature`) accept the optional
-**`autoResolveEscalations`** boolean (issue #889, default `false`). When `true`, the run opts in to
-the escalation steward, and the opt-in **propagates to every child it spawns** — an epic's
-implementation tasks and each enrolled convergence/merge loop, a feature run's handed-off PR. Only
-escalations raised under opted-in work are eligible for the steward (§3).
-
-**Single issue, one PR (feature run, `startFeature`)** — no planning or fan-out. Same body and
-base-branch admission, plus `converge` (enrol the PR in §1) and `autoMerge`:
-
-```bash
+# Single issue → one PR, no planning (tool: startFeature). Adds `converge` and `autoMerge`.
 curl -sS -X POST __BASE__/actions/start/feature \
   -H 'content-type: application/json' \
   -d '{ "issue": "owner/repo#123", "baseBranch": "main", "confirmDefaultBase": true, "converge": true, "autoMerge": true }'
 ```
 
-### Base-branch admission (ADR 0003)
-
-`startPlanFanout` admits the base through one fail-fast gate before any task fans out.
-Four ordered rules govern which base is accepted:
-
-1. **Required + explicit.** `baseBranch` is mandatory — a blank/absent value is a `400`
-   (`MissingBaseBranchError`), and an implausible name is a `400` (`InvalidBaseBranchError`).
-   There is no silent "land on the default branch" fallback.
-2. **Create-if-missing, `epic/*` only.** A missing `epic/*` base is **auto-created** off the
-   repository default branch's HEAD (idempotently — an existing branch is never reset). A
-   missing base that is **not** `epic/*` is a clean `400` (`BaseBranchMustExistError`): a typo
-   can't silently spawn a wrong-rooted branch, so any non-`epic/*` base must already exist.
-3. **Confirm-default.** Naming the repository **default branch** as the base requires
-   `confirmDefaultBase: true`, else `400` (`DefaultBaseNotConfirmedError`). This is a
-   deliberate acknowledgement that every task lands directly on the default branch with no
-   integration buffer, and any merge-to-default side effect fires per task.
-4. **Shared-base guard.** If another **active** epic (status not `done`/`failed`/`abandoned`)
-   already targets the **same repo + same custom base**, admission is a `409` (`SharedBaseError`)
-   unless you pass `allowSharedBase: true`. The default branch is exempt — many epics target it
-   concurrently without colliding.
-
-So the body may also carry two optional booleans — `confirmDefaultBase` and `allowSharedBase` —
-each a "warn you can't skip" for its rule:
+Idempotent on the plan key. The 202 response echoes `planKey` and `processKey`, and the
+plan's PRs appear in `/status` as ordinary convergence loops. Both doors accept
+`autoResolveEscalations` (default `false`), and it propagates to every child the run spawns.
 
-```bash
-curl -sS -X POST __BASE__/actions/start/plan-fanout \
-  -H 'content-type: application/json' \
-  -d '{ "issue": "owner/repo#123", "baseBranch": "main", "confirmDefaultBase": true }'
-```
+**Base-branch admission.** `baseBranch` is checked before anything fans out:
+
+1. **Required.** Blank or absent → `400 MissingBaseBranchError`. An implausible name →
+   `400 InvalidBaseBranchError`. There is no silent default.
+2. **Only `epic/*` is created if missing** (off the default branch's HEAD; an existing branch
+   is never reset). Any other missing base → `400 BaseBranchMustExistError`.
+3. **The repo default branch needs `confirmDefaultBase: true`**, else
+   `400 DefaultBaseNotConfirmedError`, because every task then lands straight on it.
+4. **Shared base.** Another active epic on the same repo and custom base →
+   `409 SharedBaseError`, unless you pass `allowSharedBase: true`. The default branch is exempt.
 
-Grandfathered: in-flight plans launched before this admission gate (with a `null` base branch)
-keep running unchanged — the requirement is enforced at admission of **new** launches, not by a
-database constraint.
-
-Track a plan the same way you track PRs — its `process_key` is an engine instance you
-can inspect in §5, and the PRs it opens show up in `/status` as ordinary convergence
-loops.
-
-### Build hygiene — implementation agents warm up once, then build module-scoped
-
-Implementation and CI-fix agents run on **stateless / ephemeral workers**: the
-workspace, including its build outputs, is thrown away between runs, so each worker pays any
-cold whole-reactor build tax independently. To keep iterations fast, the implementation
-prompts (`resources/prompts/feature.md`, `resources/prompts/fix-ci.md`) instruct every
-agent to, **before iterating on a build in the target repo**:
-
-1. **Read the target repo's own `AGENTS.md` / `CONTRIBUTING.md` build section** — the
-   recipe is authored there, never duplicated into nano-workforce (a per-repo copy here
-   would rot as the target's build changes).
-2. **Run the prescribed dependency warm-up once**, right after checkout. For a Maven
-   monorepo that ships the fast path (e.g. camunda), that is
-   `./mvnw install -Dquickly -T1C` — it installs every reactor SNAPSHOT into `~/.m2`.
-3. **Then build only the changed module, offline, without `-am`** —
-   `./mvnw -Dquickly -o -pl <module> <goals>`. Never run a cold `-am` reactor build per
-   iteration.
-
-The repo-agnostic infra levers behind this — a host-persisted `~/.m2` and a shared
-remote Maven build cache for JVM-capable worker hosts — live in worker-host config, not
-in per-repo files here. The retro loop (`resources/prompts/retro.md`) promotes any
-durable "warm the cache, then build module-scoped" lesson into the *target repo's*
-`AGENTS.md`, keeping each target's recipe sharp without nano-workforce owning it.
+**Build hygiene.** Workers are ephemeral, so implementation prompts (`feature.md`,
+`fix-ci.md`) tell agents to read the target repo's `AGENTS.md`/`CONTRIBUTING.md` build
+recipe, run its dependency warm-up once (e.g. camunda: `./mvnw install -Dquickly -T1C`),
+then build only the changed module offline (`./mvnw -Dquickly -o -pl <module> <goals>`),
+never a cold `-am` reactor build per iteration. The recipe lives in the target repo, not here.
 
 ---
 
 ## 3. Answer escalations (unblock a human-in-the-loop wait)
 
-A loop escalates only when an agent returns `needs_input`/`blocked`, or a safety net
-fires (round cap, a review that never arrives, a merge conflict, an unfixable CI
-failure). The parked process waits for a human answer.
-
-Find the open escalations, then answer them. **Prefer the `listEscalations` tool**
-(the projected read tool that lists every open escalation with the `userTaskKey` and form —
-tracked by sibling #666; on a deployment that predates it, use the `/status` / task-inbox
-curl fallback below —
-you need to answer it); curl is the no-MCP fallback.
-
-```text
-# Every open escalation waiting for a human, across all four kinds — each with its
-# userTaskKey, prKey, kind (elementId), question/findings/task, and formVariables:
-tool: listEscalations
-```
+A loop escalates when an agent returns `needs_input`/`blocked`, or when a safety net fires
+(round cap, a review that never arrives, a merge conflict, unfixable CI). The process parks
+on a native BPMN user task until someone answers.
 
 ```bash
-# No-MCP fallback: read the open escalations off /status …
-curl -sS __BASE__/status | jq '.prs[] | select(.openEscalation != null)
-  | { prKey, status, round, openEscalation }'
+# tool: listEscalations: every open escalation with userTaskKey, kind, subject, question
+curl -sS __BASE__/escalations | jq
 ```
 
-The four decision-required escalation kinds — **PR review-loop**, **implementation
-(feature) task**, **plan-review**, and **trial-merge** — are now native BPMN
-`userTask`s bearing a linked `.form`, all answered the same way through the
-`completeUserTask` tool (a human uses the same **task inbox** surface underneath).
-There is no bespoke per-kind webhook or answer page any more.
+`/status` also carries a structured `openEscalation` pointer — `{ userTaskKey, kind, summary }`
+(or `null`) — so you can answer straight from it. `listEscalations` remains the fuller
+task-context surface (subject, question, findings). The raw task inbox is
+`__BASE__/../../tasks/api/tasks`, and its UI for humans is at `__BASE__/../../tasks`.
 
-**List the open escalation tasks.** `listEscalations` returns each open task with its
-context (`prKey` / `question` / `findings` / `task`) and its kind in `elementId` /
-`kind`, so you do **not** need to reach for the raw Tasks inbox. No-MCP fallback only:
+**Answer** through the one door, `completeUserTask`, with the variables the task's kind
+expects. Answering as an agent assignee? Use `agentCompleteEscalation` instead: it records
+agent identity for attribution.
 
-```bash
-# No-MCP fallback — the un-projected engine task inbox (prefer `listEscalations`):
-curl -sS __BASE__/../../tasks/api/tasks | jq '.[] | { userTaskKey, elementId, variables }'
-
-# Filter to one kind (e.g. plan-review decisions) by elementId:
-curl -sS __BASE__/../../tasks/api/tasks \
-  | jq '[.[] | select(.elementId == "plan-review-decision")]'
-```
-
-The inbox UI is also served at `__BASE__/../../tasks` for a human to browse, filter, and
-answer (assignee/candidate-group and age surface on each task once assignment lands).
-
-> **`wait`-gate escalations are different — completing one does NOT re-arm the gate.** The
-> escalation kinds above resume a loop with your answer. A **delivery-graph `wait` node**
-> (§9) that elapses its bound also parks a task, but completing *that* one releases the token
-> **as not-ready** and the graph proceeds **past the gate** — the downstream side-effecting
-> node then runs against the unmet dependency. See §9.2 before clearing one.
-
-**Answer a task** by completing it with the typed variables its form expects — the
-completion resumes the parked process. **Prefer the `completeUserTask` tool** (or
-`agentCompleteEscalation` when you answer as an agent assignee, ADR 0046); the
-`curl … /actions/complete-user-task` app-owned door is the no-MCP fallback.
-
-```text
-# PR review-loop (elementId `wait-answer`, pr-escalation form):
-tool: completeUserTask { "userTaskKey": "<key>",
-                         "variables": { "answer": "Cap retries at 5 and proceed." } }
-
-# Implementation (feature) task (elementId `feature-escalation`):
-#   { "resolution": "answer", "answer": "…" }  to resume, or  { "resolution": "abandon" }
-tool: completeUserTask { "userTaskKey": "<key>",
-                         "variables": { "resolution": "answer", "answer": "Use v2." } }
-
-# Plan-review (elementId `plan-review-decision`):
-#   { "directive": "revise", "notes": "…" }  (fresh review budget)  or  { "directive": "proceed" }
-tool: completeUserTask { "userTaskKey": "<key>",
-                         "variables": { "directive": "revise", "notes": "Make issue-7 the seam." } }
-
-# Trial-merge (elementId `trial-merge-decision`):
-#   { "action": "proceed" | "rebase" | "abandon", "notes"?: "…" }
-tool: completeUserTask { "userTaskKey": "<key>",
-                         "variables": { "action": "rebase", "notes": "Re-run after the fix." } }
-```
+| kind (`elementId`) | `variables` |
+|---|---|
+| PR review loop (`wait-answer`) and merge loop (`wait-merge-answer`) | `{ "answer": "…" }` |
+| Implementation task (`feature-escalation`) | `{ "resolution": "answer", "answer": "…" }` or `{ "resolution": "abandon" }` |
+| Plan review (`plan-review-decision`) | `{ "directive": "revise", "notes": "…" }` (fresh review budget) or `{ "directive": "proceed" }` |
+| Trial merge (`trial-merge-decision`) | `{ "action": "rebase", "notes": "…" }`; `action` is `proceed`, `rebase` or `abandon` (`notes` optional) |
 
 ```bash
-# No-MCP fallback — the app-owned complete-user-task door (prefer the tool).
-# `variables` must carry the shape THIS task's escalation kind expects (see the per-kind
-# tool forms above): `{ answer }` here is the PR review-loop form — a feature task wants
-# `{ resolution, answer }`, plan-review `{ directive, notes }`, trial-merge `{ action, notes? }`.
+# tool: completeUserTask
 curl -sS -X POST __BASE__/actions/complete-user-task -H 'content-type: application/json' \
   -d '{ "userTaskKey": "<key>", "variables": { "answer": "Cap retries at 5 and proceed." } }'
 ```
 
-**Answer a PR escalation** (both the review-loop `wait-answer` and the merge-loop
-`wait-merge-answer` — both are now native user tasks answered the same way, #256).
-Use the PR key's parked user task and submit the `pr-escalation` form's `{ answer }`
-through the `completeUserTask` tool; curl is the no-MCP fallback:
+The answer becomes the agent's next-round context and the loop resumes. Read the
+`question`/`findings` first and give the smallest answer that unblocks it. The history is
+durable: completed user tasks, plus the `escalations` table shown per PR on the Convergence page.
 
-```text
-tool: completeUserTask { "userTaskKey": "<key>",
-                         "variables": { "answer": "Yes — cap the retries at 5 and proceed." } }
-```
+> **A delivery-graph `wait` escalation is different.** Completing it releases the gate
+> **as not-ready**, so the downstream work runs against the unmet dependency. Read §9.2
+> before clearing one.
 
-```bash
-# No-MCP fallback:
-curl -sS -X POST __BASE__/actions/complete-user-task \
-  -H 'content-type: application/json' \
-  -d '{
-        "userTaskKey": "<key>",
-        "variables": { "answer": "Yes — cap the retries at 5 and proceed." }
-      }'
-```
+### The escalation steward (opt-in auto-resolution)
+
+Work submitted with `autoResolveEscalations: true` has its open escalations reviewed by the
+**steward** every 30 minutes (`NANO_ESCALATION_STEWARD_INTERVAL`; `NANO_ESCALATION_STEWARD=off`
+disables it). The steward submits the recommended choice through `completeUserTask` with
+**agent** attribution. It is conservative:
+
+- It waits a minimum age, so a human already answering wins.
+- It never touches human-only kinds: merge approval, permission prompts, readiness gates,
+  blocked/conformance acks, abandon.
+- It **abstains** when the right choice is unclear, or when a subject has already been
+  auto-resolved twice and escalated again.
 
-The `userTaskKey` comes from `listEscalations` (or `GET /status`/the Tasks inbox). This
-is the ONE canonical answer door (`completeUserTask`) for every escalation kind — with
-`agentCompleteEscalation` the agent-assignee variant that records identity for
-attribution (ADR 0046); the merge loop no longer uses a durable `escalation-answered`
-message catch.
-
-If `NANO_PR_WEBHOOK_SECRET` is set on the deployment, add `-H "x-hook-secret: <secret>"`.
-
-The answer is delivered to the agent as its next-round context (e.g. the `answer`,
-`directive`, or `action` variable), and the loop resumes. **Audit** is durable: the
-completed user tasks form the escalation history, and the review/merge loops' rows
-live in the `escalations` table (surfaced read-only per PR on the Convergence page).
-
-Guidance for the human you assist: read the escalation `question` or plan-review
-`findings` first, decide the smallest unblocking answer, and answer it precisely —
-the answer becomes the agent's next-round context.
-
-### The escalation steward (opt-in auto-resolution, issue #889)
-
-Escalations are **still for humans** — unless the work opted in. Each initiation
-pathway (§1, §2, §9) accepts `autoResolveEscalations` (default off). When a piece of
-work opts in, the **escalation steward** reviews its open escalations every 30 minutes
-(configurable via `NANO_ESCALATION_STEWARD_INTERVAL`; `NANO_ESCALATION_STEWARD=off`
-disables the loop entirely) and submits a recommended choice for each — keeping the
-fleet moving instead of parking for hours on a decision with a clear best option.
-
-The steward is deliberately conservative:
-
-- It only touches escalations on **opted-in** work, past a short minimum age (so a
-  human already answering wins), and never a human-only / irreversible / credential
-  kind (merge approval, a permission prompt, a readiness gate, a blocked/conformance
-  ack, an *abandon*).
-- It **abstains** — leaving the escalation for a human — when the right choice is
-  unclear, and a **loop guard** abstains once a subject has been auto-resolved twice
-  and escalates again (the automatic answer isn't working).
-- Every resolution goes through the canonical `completeUserTask` door with **agent**
-  attribution (ADR 0046) — never recorded as a human decision.
-
-**Reviewing auto-resolutions.** Every resolution *and* abstention is written to a
-durable record and shown in the **Auto-resolutions** view (a pending-count badge sits
-in the nav). The default list shows `pending` records, newest first; open one to see
-the full question, the options offered, the submitted variables, the rationale and the
-evidence checked, plus links to the subject and the steward's transcript. From there
-you can **Dismiss** it (reviewed, no action) or **Intervene** (mark the record and
-record guidance for stepping in after the fact — reopening the completed user task is
-not required). Over MCP / curl, `listAutoResolutions` reads the records and
-`reviewAutoResolution` (`{ id, action: "dismiss" | "intervene", note? }`) reviews one.
+Every resolution and abstention is recorded for review in **Auto-resolutions** (nav badge =
+pending count). Read with `listAutoResolutions` (`GET __BASE__/auto-resolutions`), review with
+`reviewAutoResolution` (`{ id, action: "dismiss" | "intervene", note? }`).
 
 ---
 
@@ -364,178 +170,89 @@ not required). Over MCP / curl, `listAutoResolutions` reads the records and
              blocked (CI red) ─► senior:fix-ci ─► retry     conflict ─► senior:rebase ─► retry
 ```
 
-PR `status` values you will see in `/status`:
-`converging` (a review round is live), `waiting_review` (parked for a fresh review),
-`escalated` (waiting on a human answer), `converged`, `waiting_deps` / `waiting_merge`
-/ `queued` / `merging` (merge stage), `merged`, `abandoned`. A separate
-`incident` signal (§5) can overlay any live status when the engine parks the token on
-a technical fault.
+PR `status` values: `converging` (round live), `waiting_review`, `escalated`, `converged`,
+`waiting_deps` / `waiting_merge` / `queued` / `merging`, `merged`, `abandoned`. An
+**incident** (§5) can overlay any live status when the engine parks the token on a fault.
 
 ---
 
 ## 5. Debug: find engine instances and relate them to PRs
 
-The app stores each PR/plan's engine **process instance key** in its `process_key`
-column and surfaces it as `processKey` in `/status`. That key is the join between the
-app's business view and the engine's execution view.
-
-**Find the instance for a PR:** take `processKey` from `listActivePrs` (`/status`), then
-query engine truth. **Prefer the framework `urban_debug_*` engine-debug tools** (owned by
-the nano-ide urban runtime — see the crosswalk in §10); the `curl __ENGINE__/…` engine
-REST calls are the no-MCP fallback:
-
-```text
-PK = <processKey from listActivePrs>
-
-# The instance itself (state, the BPMN process it is running, start time):
-tool: urban_debug_search_process_instances   { "filter": { "processInstanceKey": PK } }
-
-# Where is it parked? — active jobs on the instance (a CREATED senior:pr-review job
-# with a `worker` set means an agent has leased the round; none means it is queued).
-# `urban_debug_search_jobs`/`_search_variables` are projected only where the framework
-# offers them (sibling nano-ide epic); else drop to the curl door (see §10 crosswalk):
-tool: urban_debug_search_jobs                 { "filter": { "processInstanceKey": PK, "state": "CREATED" } }   # where projected
-
-# Its variables (the aggregate/job payload the engine holds):
-tool: urban_debug_search_variables           { "filter": { "processInstanceKey": PK } }   # where projected
-
-# Is it dead-in-the-water on a technical fault? — active incidents:
-tool: urban_debug_search_incidents           { "filter": { "processInstanceKey": PK, "state": "ACTIVE" } }
-
-# Which BPMN element/wait-state is it sitting on?
-tool: urban_debug_search_element_instance_wait_states { "filter": { "processInstanceKey": PK } }
-```
+`processKey` (DB column `process_key`) joins the app's record to the engine instance. Take it
+from `/status`, then query the engine. Over MCP, the framework `urban_debug_*` tools front
+these same searches (§10).
 
 ```bash
-# No-MCP fallback — the raw engine Camunda-8 v2 REST API:
-PK=<processKey-from-status>
-
-# The instance itself (state, the BPMN process it is running, start time):
-curl -sS -X POST __ENGINE__/process-instances/search \
-  -H 'content-type: application/json' \
-  -d "{ \"filter\": { \"processInstanceKey\": \"$PK\" } }" | jq
-
-# Where is it parked? — active jobs on the instance:
-curl -sS -X POST __ENGINE__/jobs/search \
-  -H 'content-type: application/json' \
-  -d "{ \"filter\": { \"processInstanceKey\": \"$PK\", \"state\": \"CREATED\" } }" | jq
-
-# Is it dead-in-the-water on a technical fault? — active incidents:
-curl -sS -X POST __ENGINE__/incidents/search \
-  -H 'content-type: application/json' \
-  -d "{ \"filter\": { \"processInstanceKey\": \"$PK\", \"state\": \"ACTIVE\" } }" | jq
-
-# What are the element/flow-node instances (which BPMN element is it sitting on)?
-curl -sS -X POST __ENGINE__/element-instances/search \
-  -H 'content-type: application/json' \
-  -d "{ \"filter\": { \"processInstanceKey\": \"$PK\" } }" | jq
+PK=<processKey>
+H='content-type: application/json'
+# State, BPMN process, start time:
+curl -sS -X POST __ENGINE__/process-instances/search -H "$H" -d "{\"filter\":{\"processInstanceKey\":\"$PK\"}}" | jq
+# Where it is parked (a job with a `worker` set is leased by an agent; none = queued):
+curl -sS -X POST __ENGINE__/jobs/search -H "$H" -d "{\"filter\":{\"processInstanceKey\":\"$PK\",\"state\":\"CREATED\"}}" | jq
+# Technical fault?
+curl -sS -X POST __ENGINE__/incidents/search -H "$H" -d "{\"filter\":{\"processInstanceKey\":\"$PK\",\"state\":\"ACTIVE\"}}" | jq
+# Which BPMN element it sits on:
+curl -sS -X POST __ENGINE__/element-instances/search -H "$H" -d "{\"filter\":{\"processInstanceKey\":\"$PK\"}}" | jq
+# The variables the engine holds:
+curl -sS -X POST __ENGINE__/variables/search -H "$H" -d "{\"filter\":{\"processInstanceKey\":\"$PK\"}}" | jq
 ```
 
-> The `urban_debug_search_jobs`, `urban_debug_search_variables` and
-> `urban_debug_get_process_definition_xml` reads are owned by the sibling nano-ide urban
-> epic; where a deployment's framework has not yet projected them, use the curl fallback
-> for that row. The three always-present engine reads are
-> `urban_debug_search_process_instances`, `urban_debug_search_element_instance_wait_states`
-> and `urban_debug_search_incidents`.
+An active incident is mirrored onto the PR row, so a PR showing an incident in the UI is
+parked on an engine fault. The engine base comes from `NANOBPMN_BASE_URL` or
+`CAMUNDA_REST_ADDRESS`.
 
-The app already mirrors an ACTIVE incident onto the PR row (`incident`/incident
-message), so a PR that shows an incident in the UI is parked on an engine fault —
-inspect it with `urban_debug_search_incidents` (or `incidents/search`) above. If the
-engine is not at the default, the deployment's engine base is `__ENGINE__` (set via
-`NANOBPMN_BASE_URL` or `CAMUNDA_REST_ADDRESS`).
-
-**Relate an instance back to a PR:** if you have a `processKey` but not the PR, match
-it against `listActivePrs`/`/status` (`.prs[] | select(.processKey == "<PK>")`). A
-terminal PR is no longer in `/status`; its instance has already completed or been
-cancelled.
+Have a `processKey` but not the PR? Use `/status | jq '.prs[] | select(.processKey == "<PK>")'`.
+A terminal PR has left `/status`.
 
 ---
 
 ## 6. Debug the models and the prompts
 
-The behaviour is defined by durable BPMN processes and model-authored agent prompts —
-both live in the source repo, not in the job payload.
-
-- **Processes:** to inspect the model an instance is **actually running**, prefer the
-  framework tool **`urban_debug_get_process_definition_xml`** (owned by the sibling
-  nano-ide urban epic — see §10), which returns the deployed BPMN XML for a process
-  definition; that is engine truth and cannot drift from what is live. The repo copies
-  `resources/processes/*.bpmn` — `convergence-loop.bpmn` (review), `merge-loop.bpmn`
-  (merge/CI-fix/rebase), `plan-fanout.bpmn` (planning), `retro.bpmn` — are the
-  **source of truth in git** for routing, read them from the checkout when you want the
-  authored form (or have no MCP). They can lag a running deployment, so confirm against
-  the deployed XML when *why did this instance route here* matters. To understand *why* an
-  instance went where it did, read the gateway conditions (FEEL expressions on the
-  sequence flows) for the element it is parked on (§5).
-- **Prompts (agent base instructions):** `resources/prompts/*.md` — `review-round.md`,
-  `plan.md`, `feature.md`, `fix-ci.md`, `rebase.md`, `trial-merge.md`, etc. They live
-  under `resources/` so they deploy by convention (ADR 0062 — the app declares no
-  `models`; every file under `resources/` is deployed, one `.md` per task under
-  `resources/prompts/`). An agent's base prompt is **not** a job variable and is **not**
-  a deploy-time `{{token}}` substitution (that templating is removed — there is no
-  back-compat): it is delivered as a **linked resource**, the blessed **and only**
-  prompt-modularity path:
+- **Processes.** Engine truth is the deployed XML (`urban_debug_get_process_definition_xml`).
+  The source in git is `resources/processes/*.bpmn`: `convergence-loop.bpmn` (review),
+  `merge-loop.bpmn` (merge/CI-fix/rebase), `plan-fanout.bpmn`, `retro.bpmn`. The repo copy can
+  lag a running deployment. To see *why* an instance routed somewhere, read the FEEL
+  conditions on the outgoing sequence flows of the element it is parked on (§5).
+- **Prompts.** `resources/prompts/*.md` (`review-round.md`, `plan.md`, `feature.md`,
+  `fix-ci.md`, `rebase.md`, `trial-merge.md`, …) deploy by convention. Each agent task links its
+  base prompt as a linked resource that the engine resolves at job activation:
 
   ```xml
   <zeebe:linkedResource resourceId="prompts/review-round.md" bindingType="latest" resourceType="GenericScript" linkName="prompt"/>
   ```
 
-  that the engine
-  resolves to the latest deployed prompt at job activation, combined at runtime with the
-  per-task `appendPrompt` FEEL (the task-specific slice appended to this base). Because
-  the binding is `latest`, redeploying one of these files updates the prompt mid-epic
-  without a process redeploy. If an agent misbehaves systematically, the prompt is the
-  first thing to inspect/fix.
-
-  > **Value-injection caveat:** never bake a per-run value (a URL, a flag) into a prompt
-  > at deploy time — that path is gone. Pass it as a runtime job variable / `appendPrompt`
-  > FEEL instead; deploy-time string substitution is not available.
-- **Job contract:** `senior:pr-review` receives `{ prUrl, repo, prNumber, round,
-  answer? }` and must return a flat result `{ status, summary, question? }` with
-  `status ∈ { converged, addressed, waiting, needs_input, blocked }`. A round that
-  pushes anything (including a rebase/force-push) is `addressed`; a round with an
-  unknown/empty result is treated as a safe `addressed` and re-enters the review wait
-  rather than escalating.
-
-To validate a model/prompt change locally: `npm run layout:check` (BPMN diagram
-freshness), `npm run check:prompts` (every prompt link resolves), `npm run check`
-(manifest), `npm run typecheck`, `npm run lint`, `npm test`.
+  It is combined with the task's runtime `appendPrompt` FEEL. Because of `latest`, redeploying a
+  prompt changes it mid-epic with no process redeploy. A systematically misbehaving agent
+  usually means a prompt problem. There is no deploy-time `{{token}}` templating: pass per-run
+  values as job variables / `appendPrompt`.
+- **Job contract.** `senior:pr-review` receives `{ prUrl, repo, prNumber, round, answer? }` and
+  returns `{ status, summary, question? }`, with `status ∈ { converged, addressed, waiting,
+  needs_input, blocked }`. Any push (including a rebase) is `addressed`. An empty or unknown
+  result is treated as `addressed` and re-enters the review wait.
+
+Validate a model or prompt change with `npm run layout:check`, `check:prompts`, `check`,
+`typecheck`, `lint` and `test`.
 
 ---
 
 ## 7. Unstick a stuck process
 
-Work through this order:
-
-1. **Confirm it is actually stuck.** From `/status`, a PR `converging` with an
-   `activeWorker` set is *working*, not stuck — an agent holds the round. No worker
-   for a long time means the job is queued: is a fleet `c8ctl nano work` daemon
-   running and subscribed to the `senior:*` task types?
-2. **Check for an incident** (§5). An ACTIVE incident parks the token; the underlying
-   fault must be resolved (or the instance cancelled and the work resubmitted). The
-   app surfaces the incident message on the PR row.
-3. **Check for an open escalation** (§3) — the process may simply be waiting for a
-   human answer. Answer it.
-4. **A review that never arrives** escalates on its own after
-   `NANO_PR_REVIEW_WAIT_TIMEOUT` (default `PT30M`); the poller also re-nudges the
-   reviewer periodically. If the reviewer bot is not provisioned on the repo, no
-   review will ever land — that is a repo-config problem, not an app bug.
-5. **Cancel + resubmit** as a last resort. Cancel through the **app-owned** door —
-   **prefer the `cancelInstance` tool** (projected by sibling #667; the same
-   record-consistent path as the UI's per-row Cancel, `POST /app/actions/cancel
-   { "processInstanceKey": "<PK>" }`), which cancels
-   the engine instance **and** marks the PR `abandoned` so it drops out of
-   `listActivePrs`. Then re-submit the PR (§1) to start a fresh loop. **Do not** cancel a
-   raw engine instance out from under the app with the engine-level
-   `urban_debug_cancel_instance` tool (or a direct engine REST cancel) — that cancels the
-   token but leaves the PR row inconsistent. Always go through `cancelInstance` /
-   `POST /app/actions/cancel` so the app's record state stays consistent. Note the door
-   sits at `/app/actions/cancel`, **outside** the `__BASE__` control-API base (ADR 0059) —
-   until #667 projects `cancelInstance`, that curl door is the only cancel path. No-MCP
-   fallback:
+1. **Is it actually stuck?** `converging` with an `activeWorker` means an agent is working.
+   No worker for a long time means the job is queued: check that a fleet `c8ctl nano work`
+   daemon is running and subscribed to the `senior:*` types.
+2. **Incident?** (§5) It parks the token until the fault is resolved, or until you cancel and
+   resubmit.
+3. **Open escalation?** (§3) Answer it.
+4. **Review never arrives?** It escalates after `NANO_PR_REVIEW_WAIT_TIMEOUT` (default `PT30M`),
+   and the poller re-nudges the reviewer. If no reviewer bot is provisioned on the repo, that
+   is a repo-config problem.
+5. **Last resort: cancel and resubmit** through the app-owned door, `cancelInstance`. It cancels
+   the engine instance **and** marks the record `abandoned`. Then resubmit (§1). Never use the
+   engine-level `urban_debug_cancel_instance` or a raw engine cancel: it leaves the PR row
+   inconsistent.
 
    ```bash
-   curl -sS -X POST __BASE__/../actions/cancel -H 'content-type: application/json' \
+   curl -sS -X POST __BASE__/actions/cancel -H 'content-type: application/json' \
      -d '{ "processInstanceKey": "<PK>" }'
    ```
 
@@ -543,252 +260,109 @@ Work through this order:
 
 ## 8. Raise an issue or a PR against nano-workforce
 
-When you find a genuine bug or a missing capability in the orchestration itself
-(not a transient repo/agent problem), help the human file it against
-`nanobpm/nano-workforce`:
-
-- **Every change needs a tracked issue or PR** — no silent fixes. Open an issue
-  first if one does not exist.
-- **DCO is enforced:** every commit needs a `Signed-off-by` trailer — commit with
-  `git commit -s` (or `git rebase --signoff`).
-- **Work in a git worktree** off `origin/main`, on a `feat/*` or `fix/*` branch.
-- **Author the BPMN semantics, generate the diagram.** Never hand-edit the
-  `bpmndi:BPMNDiagram`; run `npm run layout <file.bpmn>` and commit the result. CI
-  fails on stale DI.
-- **Match the CI gates locally before pushing:** `npm run lint`, `npm run typecheck`,
-  `npm run check`, `npm run layout:check`, `npm run check:prompts`, `npm test`.
-- **Copilot code review is provisioned** — drive the PR to convergence against it.
-- Read `AGENTS.md` (engineering principles + gates) and `SPEC.md` (behavioural source
-  of truth) before proposing a change to a process.
-
-When describing the bug, include the concrete evidence you gathered here: the
-`prKey`, the engine `processKey`, the parked element / incident message (§5), and the
-BPMN/prompt file you believe is responsible (§6).
+For a genuine orchestration bug or gap (not a transient repo/agent problem), file it against
+`nanobpm/nano-workforce`. Include the evidence: `prKey`, `processKey`, the parked element or
+incident message (§5), and the BPMN or prompt file you suspect (§6).
+
+If you change code: open or claim an issue first, work in a worktree off `origin/main`, and
+sign off every commit (`git commit -s`, DCO). Never hand-edit `bpmndi` (run
+`npm run layout <file.bpmn>`). Run the CI gates locally (§6 list). Drive the PR to convergence
+against Copilot review. Read `AGENTS.md` and `SPEC.md` before changing a process.
 
 ---
 
 ## 9. Author and run a delivery graph (ADR 0005)
 
-The two workflows above (§1 convergence-loop, §2 plan-fanout) are each specialised to
-**one** node shape ("an agent implements a slice → opens a PR"). Real delivery is often a
-**heterogeneous, cross-repo, partly-human graph** — e.g. *merge PR #101 → un-draft+merge
-PR #202 → a human does a manual OTP publish → PR #303 consumes the just-published version*. A
-**delivery graph** ([ADR 0005](https://github.com/nanobpm/nano-workforce/blob/main/docs/adr/0005-agent-authored-delivery-graphs.md))
-lets you compose exactly that as **data** and hand it to a generic runner.
-
-> **Discover the vocabulary from the surface.** Everything this section describes — the four
-> node kinds and their body contracts, every `wait` probe kind and **what it observes**, the
-> real-vs-stub connector targets, the `onTimeout` options, the poll-budget trap, and the
-> fact-threading rules — is also available as **structured JSON** from the read tool
-> **`getDeliveryGraphVocabulary`** (`GET __BASE__/delivery-graph/vocabulary`). It is derived
-> from the implementing code (a drift test fails the build if the two disagree), so prose and
-> data can never drift. Fetch it to author against the live vocabulary; this section is the
-> narrative companion.
-
-You author the graph as **JSON — never BPMN or code** (Decision 1: the agent must never
-author the executable artifact; the closed node vocabulary is the trust boundary). Your
-surface ends at **propose → compile → stage**: a single `compile` door validates the JSON,
-renders a preview, and — when valid — **stages the compiled graph as a proposal** for a
-human. **Dispatch is an operator action in the cockpit, not an agent endpoint** (issue #460):
-there is deliberately no `start` door on the agent surface, so there is nothing an agent can
-call — or replay — to launch a run. A human previews the staged proposal and dispatches it.
+A delivery graph composes heterogeneous, cross-repo, partly-human work as **data**, for example:
+*merge PR #101 → un-draft and merge PR #202 → a human does a manual OTP publish → PR #303
+consumes that version.* You author **JSON only, never BPMN or code**.
 
-### 9.1 The `DeliveryGraph` shape
+Your surface is **propose → compile → stage**. **Dispatch is an operator action** in the
+cockpit. There is no agent start door, so nothing an agent can call or replay launches a run.
 
-A `DeliveryGraph` is a JSON **DAG**: `{ name?, nodes[], edges[] }`.
-
-- **`nodes[]`** — each node has a unique `id`, a `kind` from the **closed allowlist**
-  (`agent` | `wait` | `human` | `connector`), the matching per-kind config, and an
-  optional typed `emits[]` declaration (the facts it hands forward).
-- **`edges[]`** — each edge is `{ from, to }` meaning *"`to` proceeds once fact `from` is
-  observable"* (Decision 3 — edges are **discovered facts**, not declared values). `from`
-  is either a bare **`<nodeId>`** (the degenerate "wait for the upstream node's
-  completion" fact) or a **qualified `<nodeId>.<fact>`** referencing one of that node's
-  declared `emits`. The whole edge set must be a DAG. Omit / `[]` for independent roots.
-
-**The four node kinds** (each delegates to an existing engine-native body — the graph
-layer schedules, it does not re-implement execution):
-
-| kind | config | what it does | may `emits`? |
-|---|---|---|---|
-| `agent` | `agent: { jobType, repository?, baseBranch?, prompt?, converge?, merge?, timeout? }` | a worker runs an agent job type (the fan-out body) in a fresh checkout of its `repository` (see *Provision every agent node* below). **Side-effecting.** First-class **`converge?` / `merge?`** cell policy (§9.4) — a **declared, compiler-validated** completion-policy flag that *declares* review-convergence / landing intent (`merge` requires `converge`); a raw `senior:converge`/`senior:merge` job is rejected. This slice adds + validates the flags; the delivery-graph execution wiring that consumes them lands in a follow-up slice. **`timeout?`** is an OPTIONAL per-node ISO-8601 SLA (#505) that overrides the run-level `nodeTimeout` (and the `PT1H` default) for this node's bounded-timeout → escalate boundary, so a legitimately-long node outlasts a quick gate without a spurious escalation. | yes |
-| `wait` | `wait: <ReadinessProbe>` | a durable, bounded readiness probe — kind ∈ `http`, `command`, `npm`, `github-check`, `capability`, `pr`, `epic`. Read-only. | yes (binds observed facts) |
-| `human` | `human?: { formKey?, prompt? }` | a scheduled user task + form (the Tasks inbox, §3). Blocks dependents, SLA-bounded, answerable by a human **or** an agent. | yes |
-| `connector` | `connector: { target, dedupeKey?, payload?, timeout? }` | an automated, side-effecting outbound action. Carries a `dedupeKey` (at-least-once safe). Three **real targets** ship today — **`converge`**, **`converge-merge`** (unit → base branch) and **`merge-main`** (graph → `main`, the two-level top-level land) (§9.4); other targets are a forward-declared stub. **`timeout?`** — a per-node ISO-8601 SLA (#505), same semantics as the `agent` row. | yes |
-
-> **Provision every `agent` node with a repository — compile will NOT catch it.** Each `agent` cell
-> runs in an isolated checkout: the harness clones the node's **`repository`** (`owner/repo`, no
-> `.git`/URL) at **`baseBranch`** and cuts `feat/<node.id>` off it (#739/#776). `baseBranch` resolves
-> **per field** — the node's own, else the **run-level dispatch `baseBranch`**, else the repo default
-> (an id yielding an ill-formed ref like `a..b`/`a.lock` makes the harness skip `branch.create`, so
-> the agent cuts its own branch). A node with **no `repository`** is staged by compile **without a
-> warning**, then — absent a **run-level fallback** supplied *at dispatch* — Dispatch fails with
-> `N agent node(s) resolve to no repository (…)`. So:
->
-> - **Declare `repository` on EVERY `agent` node** (and `baseBranch` when it is neither the run-level
->   base nor the default): a single-repo graph repeats one value; a cross-repo graph names each node's
->   own repo. Every repo a node's prompt changes must be that node's `repository`.
-> - **`repoless` is a RUN-WIDE mode, not a per-node escape hatch** — it strips isolation from *every*
->   node. Use it only when **every** `agent` node is checkout-less (pure research/comment work); if
->   even one needs a checkout, provision repositories instead.
-> - **Self-check before handing over the digest:** every `"kind": "agent"` node has a `repository`;
->   if you leave some unset, tell the operator which, and that they must pick the run-level
->   **repository + base-branch fallback** in the Dispatch form (the default mode rejects the graph).
->
-> A **present** `repository`/`baseBranch` is validated at compile (`invalid-node-repository` /
-> `invalid-node-base-branch`); an **absent `repository`** defers to dispatch (and can fail there); an
-> **absent `baseBranch` is always valid** — it inherits the run-level base, else the repo default.
-
-A **`wait` node's `wait` is a `ReadinessProbe` verbatim** (the same shape feature-run
-intake uses): `{ kind, target, onTimeout?, match?, poll? }`, where `poll` is
-`{ everyMs?, timeoutMs?, backoff? }` — `everyMs` is the re-probe cadence, `timeoutMs` the
-total bounded budget, and `backoff ∈ fixed|exponential`.
-
-> **The bound is invisible unless you set it.** When `poll` (or `poll.timeoutMs`) is
-> **omitted**, the gate inherits the built-in default budget of **`PT30M` (30 minutes),
-> re-probing every 15s** (`DEFAULT_READINESS_TIMEOUT` / `DEFAULT_EVERY_MS`,
-> `app/readiness.ts`). That default is right for *"is the package published yet"* and badly
-> wrong for `wait[pr, merged]` / `wait[epic]`, which routinely wait **hours or days** — an
-> unpopulated `poll` on such a gate escalates after 30 minutes for no visible reason. Neither
-> `compile` nor `preview` surfaces the effective bound, so **set `poll.timeoutMs` explicitly**
-> on any gate that waits on a merge or an epic (see §9.4 / §9.5).
-
-The **`pr` kind** watches an
-in-flight PR — `target: "owner/repo#123"`, `match.prState ∈ ready|merged|mergeable|checks-green`
-(default `merged`) — and on a merged match binds `mergedSha` as an output fact. The **`epic`
-kind** (issue #568) gates on an **nwf plan-fanout epic reaching "fully merged"** — `target:
-"owner/repo#NN"` is the epic's durable **`planKey`** (the epic issue, *not* the engine
-`processInstanceKey`, so a resubmit/replay still resolves), `match.epicState ∈ merged|done`
-(default `merged`, both mean "every opened slice landed"). It observes the app's own aggregate
-(the lineage read-model), so a **failed/abandoned/mixed** epic never reports merged and the
-bounded wait routes to **`onTimeout`** rather than hanging; on a fully-merged match it binds
-`prCount` (how many slice PRs landed) as an output fact. Both `pr` and `epic` targets may also
-be a **`<nodeId>.<fact>` late-binding reference** the compiler resolves at dispatch (§9.4),
-rather than a literal handle.
-
-A **typed fact** (`emits[]` entry) is `{ name, type, description? }` where
-`type ∈ string|number|boolean|artifact|version|url|pr` (`artifact` = a `pkg@version` handle,
-`version` = a bare version, `pr` = a PR reference `owner/repo#N` an `agent` node emits for the
-PR it opened, late-bound by a downstream `wait[pr]`/`connector[converge*]` target — issue #548).
-`name` matches `^[A-Za-z_][A-Za-z0-9_]*$` and is referenced
-downstream as `<nodeId>.<name>`. A "click done" human node or a pass-through node declares
-no facts.
-
-**Guarded routing + the agent classifier-emit contract.** An edge may carry a **guard** —
-`when: "<nodeId>.<fact>"` + `equals: <scalar>` — or be the split's single `default: true`
-else-branch (S7). A node whose out-edges are guarded is a **data-based exclusive split**: at
-runtime exactly one branch fires, chosen by the producer's emitted fact. For an **`agent`**
-node the fact is late-bound from the servicing job's completion: the delivery output-mapping
-publishes the engine variable named **exactly after the fact** (e.g. a fact `result` reads the
-completion variable `result`). A real `senior:*` fleet agent completes with its **Output
-contract** envelope (`{ status, summary, pr, question, delta }`), so — to make a guarded split
-fire — an agent node that declares `emits` has a **classifier emit contract** automatically
-appended to its prompt at dispatch: the agent MUST return each declared fact as an **extra
-top-level field of the same result JSON** (the `AGENT_RESULT_FILE` it already writes
-`status`/`summary`/`pr` to). Author side, this means: declare `emits: [{ name, type }]` on the
-agent node and guard the downstream edge on `<node>.<name>`; a contract-following agent returns
-`{ …, <name>: <value> }` and the split routes on it. If the agent cannot decide the fact it
-**omits** it, and the split takes its `default` (else) branch — the deadlock-safe fallback. A
-node that declares no `emits` gets no contract text and behaves exactly as before.
-
-**Producer completion contract (auto-injected — do NOT hand-encode it).** Every `agent` node
-*also* has a **producer completion contract** appended to its prompt at dispatch, alongside the
-idempotency preflight and — only for a node that declares `emits` — the classifier emit contract.
-It hands the agent the terminal-status vocabulary
-the `#731` producer gate enforces: the injected text tells the agent it MUST end its result with
-one of `AGENT_TERMINAL_SUCCESS_STATUSES` (`done` / `opened` / `skipped`) — never omit `status` or
-invent one. The gate routes a completion onward only when its self-reported `status` is one of that
-allowlist **and** every required emit is non-null; any *explicitly non-terminal* status parks the
-run on a human `__contract` escalation (fail-closed). (As a backward-compat concession the gate
-*also* routes onward an **absent/null** status — for legacy workers / stubs that report none — but
-the injected contract never invites a real agent to lean on that: always return an allowlisted
-status.) The wording is **derived from that single allowlist** (changing the
-list changes the prompt — no second copy), so **authors must not hand-encode status vocabulary
-in a node's prompt.** Unlike the emit contract, a no-emit node still receives the status block
-(the gate applies to it too).
+> **The structured vocabulary is authoritative:** `getDeliveryGraphVocabulary`
+> (`GET __BASE__/delivery-graph/vocabulary`) returns the node kinds and fields, every `wait`
+> probe kind and what it observes, connector targets, `onTimeout` options, poll defaults and
+> fact-threading rules. It is derived from the code, so read it before authoring. This section
+> covers the workflow and the traps.
 
-### 9.2 The agent loop: draft → compile → stage → ask an operator to dispatch
+### 9.1 The `DeliveryGraph` shape
 
-```
-GET __BASE__/agent           # ← you are reading it; learn the vocabulary + endpoints
-   └─ draft a DeliveryGraph JSON
-        └─ POST __BASE__/actions/compile-delivery-graph   # validate + preview + STAGE
-             ├─ 400 { ok:false, errors:[{path,message}] } → fix the exact offending input, recompile
-             └─ 200 { status:"ready", message, digest, preview, reviewUrl }
-                  └─ ask the operator to preview + dispatch it in the cockpit (there is no start door)
-```
+`{ name?, nodes[], edges[] }`, a DAG. Each node has a unique `id`, a `kind`, that kind's
+config, and optional `emits[]` (typed facts `{ name, type, description? }`, with
+`type ∈ string|number|boolean|artifact|version|url|pr`). For edges, each edge is `{ from, to }`:
+`to` proceeds once `from` is observable. `from` is a bare `<nodeId>` (completion) or a
+qualified `<nodeId>.<fact>` naming one of that node's `emits`.
 
-**Compile (validate + preview + stage).** The compile door runs the semantic validator and
-the deterministic compiler and, on success, **stages** the compiled graph as a proposal a
-human can dispatch — it does **not** deploy or run anything. Recompiling a graph you are
-still drafting is safe: a re-compile of the same graph is idempotent, and a changed graph
-with the same `name` supersedes the prior staged proposal, so the cockpit shows exactly one
-live proposal per graph.
+| kind | config | does |
+|---|---|---|
+| `agent` | `agent: { jobType, repository?, baseBranch?, prompt?, converge?, merge?, timeout? }` | runs an agent job in a fresh checkout of `repository`. Side-effecting. `converge`/`merge` (merge requires converge) declare land intent; a raw `senior:converge`/`senior:merge` job is rejected. `timeout` is an ISO-8601 per-node SLA overriding the run's `nodeTimeout` (default `PT1H`). |
+| `wait` | `wait: <ReadinessProbe>` | a durable, bounded, read-only readiness probe `{ kind, target, match?, poll?, onTimeout? }`. Kinds: `http`, `command`, `npm`, `github-check`, `capability`, `pr`, `epic`. |
+| `human` | `human?: { formKey?, prompt? }` | a user task on the Tasks inbox (§3), answerable by a human or an agent. |
+| `connector` | `connector: { target, dedupeKey?, payload?, timeout? }` | an at-least-once, deduped outbound action. Real targets: `converge`, `converge-merge`, `merge-main` (§9.4). |
+
+> **Provision every `agent` node with a repository — compile will NOT catch it.** Each agent
+> clones its node's `repository` (`owner/repo`) at `baseBranch` (node value, else the run-level
+> dispatch base, else the repo default) and cuts `feat/<node.id>`. A node with no `repository`
+> compiles cleanly, then Dispatch fails with `N agent node(s) resolve to no repository (…)`
+> unless the operator supplies a run-level fallback. So set `repository` on **every** agent node.
+> If you leave one unset, tell the operator. `repoless` is a run-wide mode for graphs where
+> **no** node needs a checkout.
+
+> **Set `poll.timeoutMs` on every merge or epic gate.** If `poll` is omitted, a `wait` inherits
+> **30 minutes** (re-probing every 15 s). That suits "is the package published?", but a
+> `wait[pr, merged]` or `wait[epic]` then escalates mid-review. Use e.g.
+> `"poll": { "everyMs": 300000, "timeoutMs": 259200000 }` (5 min / 3 days).
+
+**Guarded routing.** An edge may carry `when: "<nodeId>.<fact>"` + `equals: <scalar>`, or be the
+split's single `default: true` branch. Exactly one branch fires. For an `agent` node, the fact
+is read from a same-named top-level field in the agent's result JSON. The system adds that
+instruction to the agent's prompt automatically when the node declares `emits`. If the agent
+omits the fact, the `default` branch is taken.
+
+**Result statuses are added automatically. Don't write them into your prompt.** Every agent
+node's prompt gets the allowed terminal statuses (`done` / `opened` / `skipped`). A completion
+moves on only with one of those statuses and every required emit present. Anything else parks
+the run on a human `__contract` escalation — **except** an absent/null `status`, which a legacy
+worker that populates its required emits may still advance with (the status contract binds only
+when a status is actually reported).
+
+### 9.2 The agent loop: draft → compile → stage → ask an operator to dispatch
 
 ```bash
+# tool: compileDeliveryGraph: validate + preview + STAGE (never deploys or runs)
 curl -sS -X POST __BASE__/actions/compile-delivery-graph \
-  -H 'content-type: application/json' \
-  -d @graph.json | jq
+  -H 'content-type: application/json' -d @graph.json | jq
 ```
 
-- `200 { status:"ready", message, digest, preview, reviewUrl }` — the graph compiled and is
-  **staged for operator review**. `digest` is the content-address that NAMES the proposal (tell the
-  operator exactly which one to dispatch); `preview` is `{ diagram, sideEffects, humanNodes }` —
-  `diagram` is a mermaid `flowchart` of the resolved graph, `humanNodes[]` are the stop-points where
-  it waits for a person, and `sideEffects[]` are the `agent`/`connector` actions it **will** perform
-  once dispatched; `reviewUrl` is a **navigational** cockpit deep-link (a pointer only — **not** a
-  dispatch handle). The response carries **no run key, token, or process-instance key**: nothing you
-  can replay to start a run. Hand the operator the `digest` (or `reviewUrl`) and ask them to dispatch.
-- `400 { ok:false, errors:[{ path, message }] }` — every error path-qualified
-  (`nodes[2].kind`, `edges[1].from`, …) for unknown kind, dangling edge, a cycle, or an
-  unresolvable `from` fact. Fix and recompile; nothing is staged.
-
-**Dispatch (operator-only — NOT on the agent surface).** There is deliberately no agent
-`start` endpoint (Decision 5/7, issue #460). Dispatch is a human action: an operator opens
-the **Delivery Graphs** page in the cockpit, reviews the staged proposal's rendered preview
-(its diagram, the human stop-points, and the side effects a dispatch authorises), and clicks
-**Dispatch** on the one they approve. That click **is** the approval — content-addressed to the
-exact digest previewed, so it cannot replay some other graph. Once dispatched, the graph deploys +
-runs engine-natively and registers as a run aggregate, so its current phase / parked node shows in
-the cockpit's **Active Delivery Graphs** grid (e.g. *"parked on human node: manual OTP publish"*).
-A `human` node parks on the **Tasks** inbox and is answered exactly as an escalation is (§3) — its
-completion emits any declared facts, which downstream edges bind.
-
-The dispatch body accepts the optional **`autoResolveEscalations`** boolean (issue #889, default
-`false`): when `true`, the run opts in to the escalation steward (§3) — its `human` nodes, service-node
-escalation twins, and any `converge` connector's enrolled PR become eligible for auto-resolution.
-
-> **Completing a `wait` escalation proceeds *as not-ready* — it does NOT re-arm the gate.**
-> A `wait` node with `onTimeout: "escalate"` (the default) that elapses its bound parks a
-> human-completable escalation task on the Tasks inbox. **Completing that task does not retry
-> the probe or wait for readiness** — it releases the token **as not-ready** and the graph
-> proceeds **past the gate**, so the downstream side-effecting node then runs *against the
-> unmet dependency* (`waitBodyLines`, `app/deliveryGraphCompiler.ts`). An operator clearing
-> what looks like a stuck task therefore *launches the very work the gate was holding back*.
-> If the dependency genuinely is not ready, do **not** complete the escalation to "unstick"
-> it — extend the gate's `poll.timeoutMs` and re-dispatch, or abandon the run. (Same for
-> `onTimeout: "continue"`, which proceeds past the gate as not-ready with **no** human stop
-> at all.)
->
-> **Exception (#872):** a `wait` that declares `emits` **validates** its resume value — an
-> omitted/invalid value **re-parks** the task rather than releasing not-ready.
-
-> **Why the split?** Making the compile door the end of the agent surface closes a
-> self-approval hole: the old flow handed the same caller an approval token to re-submit with,
-> so any holder of the API credential approved its own graph. With no dispatch affordance on the
-> agent surface (capability by absence), the human in the cockpit is the only actor who can
-> launch side effects.
+- **`200 { status:"ready", message, digest, preview, reviewUrl }`**: staged.
+  `preview` is `{ diagram (mermaid), sideEffects[], humanNodes[] }`. `digest` names the proposal,
+  and `reviewUrl` is a cockpit link (navigation only, not a dispatch handle). Give the operator
+  the `digest`/`reviewUrl` and ask them to dispatch.
+- **`400 { ok:false, errors:[{ path, message }] }`**: path-qualified errors (unknown kind,
+  dangling edge, cycle, unbound fact). Fix and recompile; nothing is staged.
+
+Recompiling is safe: the same graph is idempotent, and a changed graph with the same `name`
+replaces the staged proposal. The operator previews it on the **Delivery Graphs** page and
+clicks **Dispatch**. That click is the approval, bound to the previewed digest. Dispatch also
+accepts `autoResolveEscalations` (§3). The running graph shows in **Active Delivery Graphs**,
+and `human` nodes are answered like escalations (§3), emitting their declared facts.
+
+> **Completing a `wait` escalation proceeds *as not-ready*. It does NOT re-arm the gate.** With
+> `onTimeout: "escalate"` (default), an elapsed bound parks a task. Completing it releases the
+> token past the gate, so the downstream side-effecting node runs against the unmet dependency.
+> If the dependency isn't ready, don't complete it: raise `poll.timeoutMs` and re-dispatch, or
+> abandon. (`onTimeout: "continue"` proceeds the same way with no human stop.) **Exception:** a
+> `wait` that declares `emits` validates the resume value and re-parks on a missing or invalid one.
 
 ### 9.3 Worked example — the cross-repo human-in-the-loop release
 
-*Merge PR #101 (repo 1) → un-draft+merge PR #202 (repo 2) → a **human** runs the manual OTP
-publish and records the version → open+merge PR #303 (repo 3) consuming that version.* The
-`human` node **emits** a typed `version` fact, and the downstream `from:
-"manual-publish.publishedVersion"` edge binds it into the PR-#303 path:
+The `human` node emits a `version` fact that the edge `manual-publish.publishedVersion` binds
+into the next agent:
 
 ```json
 {
-  "name": "cross-repo release: merge #101 → un-draft+merge #202 → manual OTP publish → consume in #303",
+  "name": "cross-repo release: merge #101 → un-draft+merge #202 → manual OTP publish → consume in repo-3",
   "nodes": [
     { "id": "merge-a", "kind": "wait",
       "wait": { "kind": "pr", "target": "acme/repo-1#101", "match": { "prState": "merged" },
@@ -796,244 +370,97 @@ publish and records the version → open+merge PR #303 (repo 3) consuming that v
     { "id": "undraft-merge-b", "kind": "agent",
       "agent": { "jobType": "senior:feature", "repository": "acme/repo-2", "converge": true, "merge": true, "prompt": "Take draft PR acme/repo-2#202 out of draft; converge it to green and land it." } },
     { "id": "manual-publish", "kind": "human",
-      "human": { "prompt": "Run the manual OTP-authenticated `npm publish` for @acme/widget and set up OIDC trusted publishing. Record the exact published version." },
-      "emits": [ { "name": "publishedVersion", "type": "version", "description": "The version just published to npm." } ] },
+      "human": { "prompt": "Run the manual OTP-authenticated `npm publish` for @acme/widget. Record the exact published version." },
+      "emits": [ { "name": "publishedVersion", "type": "version" } ] },
     { "id": "open-pr-c", "kind": "agent",
-      "agent": { "jobType": "senior:feature", "repository": "acme/repo-3", "prompt": "Bump @acme/widget to the published version in acme/repo-3 and open PR #303." } },
+      "agent": { "jobType": "senior:feature", "repository": "acme/repo-3", "prompt": "Bump @acme/widget to the published version in acme/repo-3 and open a PR." },
+      "emits": [ { "name": "pr", "type": "pr" } ] },
     { "id": "merge-c", "kind": "wait",
-      "wait": { "kind": "pr", "target": "acme/repo-3#303", "match": { "prState": "merged" },
+      "wait": { "kind": "pr", "target": "open-pr-c.pr", "match": { "prState": "merged" },
                 "poll": { "everyMs": 300000, "timeoutMs": 259200000 }, "onTimeout": "escalate" } }
   ],
   "edges": [
     { "from": "merge-a", "to": "undraft-merge-b" },
     { "from": "undraft-merge-b", "to": "manual-publish" },
     { "from": "manual-publish.publishedVersion", "to": "open-pr-c" },
-    { "from": "open-pr-c", "to": "merge-c" }
+    { "from": "open-pr-c.pr", "to": "merge-c" }
   ]
 }
 ```
 
-`compile` returns this preview (abridged):
-
-```
-diagram (mermaid flowchart):
-  n4["agent: undraft-merge-b"] --> n0["human: manual-publish"]
-  n0 -- "publishedVersion" --> n3["agent: open-pr-c"]
-  n1["wait: merge-a"] --> n4
-  n3 --> n2["wait: merge-c"]
-
-humanNodes: [ { nodeId: "manual-publish", emits: [ { name: "publishedVersion", type: "version" } ], … } ]
-sideEffects: [ { nodeId: "open-pr-c", kind: "agent", … }, { nodeId: "undraft-merge-b", kind: "agent", … } ]
-```
-
-Two side-effecting `agent` nodes ⇒ the compile door **stages** the proposal and hands you a
-`digest` + `reviewUrl`; ask an operator to preview and **Dispatch** it in the cockpit. Once
-they do, the graph runs to `manual-publish`, parks it on the Tasks inbox (`now do X`), and —
-once a human (or agent) completes it with the `publishedVersion` — binds that fact into
-`open-pr-c` and carries on to `merge-c`.
+### 9.4 Connector targets — drive a PR to convergence + merge (`converge` / `converge-merge` / `merge-main`)
 
-To swap the manual PR-#303 path for a **capability** edge instead of a raw `pr` watch, make
-the consumer a `wait` node with `kind: "capability"` (resolving *which published
-`pkg@version` first carries the change*) fed by the same `manual-publish.publishedVersion`
-fact — the fact-edge syntax is identical.
+A connector with one of these targets enrolls a PR in the same convergence loop as §1
+(idempotent; never double-enrolls). Payload: `{ pr, autoMerge?, dependsOn? }`.
 
-### 9.4 Connector targets — drive a PR to convergence + merge (`converge` / `converge-merge` / `merge-main`)
+- **`converge`**: review only, stop at `converged`.
+- **`converge-merge`**: converge, then merge onto the PR's own base (inside an epic, that is the
+  integration branch).
+- **`merge-main`**: same mechanics, for landing the graph's integration PR on `main`.
 
-A `connector` node with **`target: "converge-merge"`** (or **`"converge"`** / **`"merge-main"`**)
-enrolls an agent-opened PR into the app's **shared convergence loop** — the *same* enrollment §1 (a
-standalone submit) and a feature run use (`submitPr`), no duplicated machinery. This replaces
-the old habit of bridging an `agent`-opened PR to review with a **human `land-*` gate** whose
-only job was "go run convergence yourself".
-
-- **`converge-merge`** — the **unit-level** land: drive review convergence **and then the merge
-  loop**, landing the PR onto **its own base branch** (for a unit inside an epic that base is the
-  epic integration branch, never `main` directly — ADR 0003 base-branch admission). Equivalent to a
-  submit with `autoMerge: true`.
-- **`merge-main`** — the **graph-level** top-level land: the second level of the two-level merge
-  (ADR 0006 §3), landing the graph/epic **integration** PR onto **`main`**. Dispatch-identical to
-  `converge-merge` (both enroll + merge); the distinction is the *level*, kept a first-class literal
-  so the two levels are authored explicitly rather than left emergent.
-- **`converge`** — **converge-only**: drive review convergence and stop at `converged`, never
-  handing off to the merge loop (equivalent to `autoMerge: false`).
-
-> **converge/merge are cell POLICY, not raw nodes.** A raw `senior:converge` / `senior:merge`
-> **agent** job is **not expressible** — the compiler rejects it (`raw-converge-node`). Express
-> "get to green, then land" via a cell node's first-class **`agent.converge` / `agent.merge`**
-> policy flags (`merge` requires `converge`), or, for enrolling an already-open PR, the
-> `connector` targets above (ADR 0006 §3 / S5).
-
-**Payload:** `{ pr: "owner/repo#123", autoMerge?: boolean, dependsOn?: string[] }`. `pr` is
-required (a literal `owner/repo#N`, identical to how a `wait: pr` node targets a known PR).
-`autoMerge` defaults from the target and may be overridden per-node; `dependsOn` is unioned into
-the PR's merge-stage dependency set. The enrollment is idempotent (the connector's
-at-least-once dedupe fence **plus** `submitPr`'s own `prKey` idempotency), so a graph resume /
-redelivery never double-enrolls.
-
-**Canonical shape** — the agent opens the PR, emits it as a typed **`pr` fact**, and the connector
-and `wait[pr, merged]` gate **late-bind** that fact (no hardcoded PR number, no human node). The
-author never knows the PR number at compose time, so reference it by fact:
+The PR number is unknown when you write the graph, so have the agent **emit a `pr` fact** and
+reference it as `"<node>.pr"`. The reference needs a threading edge from that fact, otherwise
+compile rejects it (`unbound-pr`). A connector with no `payload.pr` binds the single incoming
+`pr` fact, and a literal `owner/repo#N` also works.
 
 ```json
 {
   "name": "open → converge+merge → wait merged",
   "nodes": [
     { "id": "open", "kind": "agent",
-      "agent": { "jobType": "senior:feature", "repository": "acme/repo", "prompt": "Implement the change in acme/repo and open a PR." },
+      "agent": { "jobType": "senior:feature", "repository": "acme/repo", "prompt": "Implement the change and open a PR." },
       "emits": [ { "name": "pr", "type": "pr" } ] },
-    { "id": "land", "kind": "connector",
-      "connector": { "target": "converge-merge", "payload": { "pr": "open.pr" } } },
+    { "id": "land", "kind": "connector", "connector": { "target": "converge-merge", "payload": { "pr": "open.pr" } } },
     { "id": "merged", "kind": "wait",
       "wait": { "kind": "pr", "target": "open.pr", "match": { "prState": "merged" },
                 "poll": { "everyMs": 300000, "timeoutMs": 259200000 }, "onTimeout": "escalate" } }
   ],
-  "edges": [
-    { "from": "open.pr", "to": "land" },
-    { "from": "open.pr", "to": "merged" }
-  ]
+  "edges": [ { "from": "open.pr", "to": "land" }, { "from": "open.pr", "to": "merged" } ]
 }
 ```
 
-The `merged` gate carries an explicit **`poll`** (re-probe every 5 minutes, budget 3 days:
-`timeoutMs: 259200000`) because a `wait[pr, merged]` waits on a human-paced merge — **omitting
-`poll` inherits the 30-minute default** (§9.1) and escalates mid-review. Set `poll.timeoutMs`
-to a realistic budget on any merge/epic gate.
-
-The `pr` fact is threaded along the **fact-qualified edges** (`open.pr → land`, `open.pr → merged`) —
-those edges are what carry the observed PR into each consumer, so they are **required** when you
-reference `open.pr` (the validator rejects a reference with no threading edge, `unbound-pr`). Three
-ways to name the target PR:
-
-- **fact reference** `"<node>.pr"` — late-bound from the upstream `agent`'s emitted `pr` fact (the
-  shape above). The referenced fact must be declared **`pr`-typed** and threaded on an incoming edge.
-- **omitted** (connector only) — `payload` without a `pr` auto-binds the **single** incoming `pr`
-  fact, so `"connector": { "target": "converge-merge" }` works when exactly one `pr` fact flows in.
-- **literal** `"owner/repo#N"` — still accepted for a PR you already know (a real ref is never
-  `<node>.pr`-shaped, so it never collides with a reference).
-
-`senior:feature` already returns the PR it opened, so declaring `emits: [{ "name": "pr", "type": "pr" }]`
-on the agent node is all it takes to publish it (issue #548).
-
-> **Don't hand-author this shape — generate it.** When your intent is simply "sequence these
-> issues, each implemented → converged → merged (optionally behind a gate)", call the
-> **`sequenceIssues`** door instead of assembling the nodes/edges by hand. Its body is the intent
-> `{ "issues": ["owner/repo#A", "owner/repo#B", …] }` with an optional leading `"behind": "owner/repo#NN"`
-> gate, and it GENERATES
-> exactly the canonical chain above — for each issue `agent` (`senior:feature`, emits `pr`) →
-> `connector[converge-merge]` → `wait[pr, merged]` with a realistic `poll.timeoutMs`, threading the
-> `pr` fact, plus an optional leading `wait[epic]` gate (§9.5) when `behind` is given — then STAGES it
-> through the same compile+stage path as `compileDeliveryGraph` (it never dispatches). The issues run
-> in **sequence**: each issue's implementation starts once the prior issue has merged.
+> **Don't hand-write that chain. Generate it.** To run issues one after another (each
+> implemented, converged, then merged), call **`sequenceIssues`**
+> (`POST __BASE__/actions/start/sequence-issues`, body
+> `{ "issues": ["owner/repo#A", "owner/repo#B"], "behind"?: "owner/repo#NN" }`). It builds the
+> chain above for each issue, with an optional leading `wait[epic]` gate, and stages it through
+> compile (it never dispatches).
 
 ### 9.5 Gate a graph on an epic reaching "fully merged" (`wait[epic]`)
 
-Sometimes the thing you must wait for is not one PR but a **whole epic** — an nwf
-`plan-fanout` that fans many slice PRs across waves whose numbers are unknown at compose
-time. The **`wait` kind `epic`** (issue #568) gates on that epic reaching **"fully merged"**
-(every opened slice landed), keyed by its durable **`planKey`** (`owner/repo#NN` — the epic
-issue), so *"start feature B once epic A has fully landed"* is an automated edge, not a human
-babysitting a gate.
+`kind: "epic"` waits until every slice PR of an epic (or the PR of a feature run) has landed.
+`target` is the **`planKey`** (`owner/repo#NN`, the root issue), not an engine key, so it
+survives a resubmit. `match.epicState` is `merged` (default) or `done`. A failed or abandoned
+epic never reports merged, so the bounded wait routes via `onTimeout`. On a match it binds
+`prCount`.
 
 ```json
-{
-  "name": "start #567 once epic #488 has fully merged",
-  "nodes": [
-    { "id": "gate-epic", "kind": "wait",
-      "wait": { "kind": "epic", "target": "nanobpm/nano-ide#488",
-                "match": { "epicState": "merged" },
-                "poll": { "everyMs": 300000, "timeoutMs": 259200000 },
-                "onTimeout": "escalate" },
-      "emits": [ { "name": "prCount", "type": "number" } ] },
-    { "id": "start-b", "kind": "agent",
-      "agent": { "jobType": "senior:feature", "repository": "nanobpm/nano-workforce", "prompt": "Implement nanobpm/nano-workforce#567 and open a PR." } }
-  ],
-  "edges": [ { "from": "gate-epic", "to": "start-b" } ]
-}
+{ "id": "gate-epic", "kind": "wait",
+  "wait": { "kind": "epic", "target": "nanobpm/nano-ide#488", "match": { "epicState": "merged" },
+            "poll": { "everyMs": 300000, "timeoutMs": 259200000 }, "onTimeout": "escalate" },
+  "emits": [ { "name": "prCount", "type": "number" } ] }
 ```
 
-Semantics:
-
-- **`target` is the `planKey`** (`owner/repo#NN`, the epic issue) — the *stable business id*,
-  not the engine `processInstanceKey` (`64200`), so a resubmit/replay still resolves.
-- **`match.epicState`** is `merged` (default) or `done` — "every opened slice landed". The gate reads
-  the app's own **aggregate** (the lineage read-model over `NANO_WORKFORCE_BASE_URL`), so it is
-  level-triggered like `pr` (no missed edge). A failed/abandoned/mixed epic never reports merged, so
-  it never falsely releases the gate — the **bounded** wait routes via **`onTimeout`**, never hanging.
-- **Set `poll.timeoutMs` to a realistic budget.** An epic reaching "fully merged" is a
-  multi-day, human-paced event, so the example budgets 3 days (`poll: { everyMs: 300000, timeoutMs:
-  259200000 }`). **Omitting `poll` inherits the 30-minute default** (§9.1) — the gate would escalate
-  long before the epic lands. Because this gate binds `prCount`, that escalation is **validated**
-  (§9.2): it **re-parks** unless the operator supplies a valid `prCount`, rather than silently
-  releasing `start-b` as not-ready.
-- On a fully-merged match it binds **`prCount`** (how many slice PRs the epic landed) as an
-  output fact, so a downstream node can consume it (parity with the `pr` kind's `mergedSha`).
-- **It also gates a single-PR *feature run*, not just a plan-fanout epic.** The gate resolves the
-  lineage thread whose **`rootRequestKey`** matches `target` **regardless of the thread's `kind`**
-  (`feature` | `epic` | `pr` | `delivery`), and `app/lineage.ts` lands a *feature* thread on
-  `stage:"merged"` once its PR merges. So `wait[epic]` targeting a feature/epic **root issue**
-  releases on `stage:"merged" && active:false` either way — see `getDeliveryGraphVocabulary` (the
-  `epic` probe entry) for the structured contract.
-
 ---
 
 ## 10. Tool ↔ curl crosswalk (MCP-first, curl is the no-MCP fallback)
 
-When you drive this instance over MCP, **call the projected tool** — every recipe above
-leads with it. `curl __BASE__/…`/`curl __ENGINE__/…` is only the **no-MCP fallback** for an
-agent that has no tools (see the runbook, `docs/mcp-runbook.md` §2/§3, and [§5
-Fallback](mcp-runbook.md#5-fallback)). This table maps every guide action to its projected
-tool name and its no-MCP fallback underneath (usually a curl door; a few rows fall back to reading a repo file instead).
-
-App-owned operations (projected from this app's `openapi.yaml`; the `__BASE__` control API).
-Rows tagged *(projected by sibling #NNN)* name a tool that lands with that sibling task —
-until it does, only the curl door in the third column exists on the deployment:
-
-| Guide action | Projected tool | No-MCP fallback |
-|---|---|---|
-| Which code is live (§0) | `getVersion` | `curl __BASE__/version` |
-| Every PR in flight (§0/§5) | `listActivePrs` | `curl __BASE__/status` |
-| List open escalations (§3) | `listEscalations` *(projected by sibling #666; curl door until then)* | `curl __BASE__/../../tasks/api/tasks` (the answerable list — carries each `userTaskKey`); `/status` filtered with the jq recipe just below this table is only a quick *indicator* (it surfaces `openEscalation` as a question string, **no `userTaskKey`**, so you can't answer from it) |
-| Answer an escalation (§3) | `completeUserTask` (agent-assignee: `agentCompleteEscalation`) | `curl -X POST __BASE__/actions/complete-user-task` |
-| List auto-resolutions (§3) | `listAutoResolutions` | `curl __BASE__/auto-resolutions` |
-| Review an auto-resolution (dismiss / intervene) (§3) | `reviewAutoResolution` | `curl -X POST __BASE__/auto-resolutions/review` |
-| Cancel an instance (record-consistent) (§7) | `cancelInstance` *(projected by sibling #667; curl door until then)* | `curl -X POST __BASE__/../actions/cancel` *(the `/app/actions/cancel` door, outside `__BASE__`)* |
-| Publish a BPMN message (§7) | `postMessage` | `curl -X POST __BASE__/actions/message` |
-| The operator guide itself | `getAgentInstructions` (full) / `getAgentGuide(section?)` (addressable) | `curl __BASE__/agent` / `curl __BASE__/agent/guide` |
-
-The `listEscalations` no-MCP fallback that filters `/status` with `jq` lives here, not inside the
-table cell above: a literal `|` can't be written in a GFM table cell without escaping it as `\|`,
-and this guide is served **raw** (byte-for-byte, `__BASE__`/`__ENGINE__` aside) to no-MCP agents, so
-the escaped form would be copied verbatim and the shell would treat `\|` as a literal argument
-rather than a pipe. It's only a **quick indicator** — `/status` surfaces `openEscalation` as a
-question string with **no `userTaskKey`**, so to actually *answer* one you still need the tasks
-inbox (`curl __BASE__/../../tasks/api/tasks`) or the `listEscalations` tool for its `userTaskKey`
-(§3). It selects the same `{ prKey, status, round, openEscalation }` fields as the §3 fallback for
-consistency. Copy it from here:
-
-```sh
-curl __BASE__/status | jq '.prs[] | select(.openEscalation != null)
-  | { prKey, status, round, openEscalation }'
-```
-
-
-Framework engine-debug tools (owned by the nano-ide urban runtime, not this app; they front
-the engine's Camunda-8 v2 REST API at `__ENGINE__`). The first three are always projected;
-`urban_debug_search_jobs` / `urban_debug_search_variables` /
-`urban_debug_get_process_definition_xml` are owned by the sibling nano-ide urban epic — use
-them by name where the framework projects them, else drop to the curl door:
-
-| Guide action | Projected tool | No-MCP fallback |
+| Action | Tool | No-MCP fallback |
 |---|---|---|
-| Search process instances (§5) | `urban_debug_search_process_instances` | `curl -X POST __ENGINE__/process-instances/search` |
-| Inspect element/wait states (§5) | `urban_debug_search_element_instance_wait_states` | `curl -X POST __ENGINE__/element-instances/search` |
-| Active incidents (§5) | `urban_debug_search_incidents` | `curl -X POST __ENGINE__/incidents/search` |
-| Jobs on an instance (§5) | `urban_debug_search_jobs` | `curl -X POST __ENGINE__/jobs/search` |
-| Instance variables (§5) | `urban_debug_search_variables` | `curl -X POST __ENGINE__/variables/search` |
-| Deployed BPMN model XML (§6) | `urban_debug_get_process_definition_xml` | read the source copy `resources/processes/*.bpmn` from the checkout |
-| Engine-level cancel — **avoid** (§7) | `urban_debug_cancel_instance` | *(use the app-owned `cancelInstance` instead — engine cancel leaves the PR row inconsistent)* |
-
-**Rule of thumb (agent-guide §5 fallback discipline):** if a row has a projected tool, use
-it; reach for its curl door only when you are genuinely not on MCP (or the tool's sibling
-task has not yet landed — see the *(projected by sibling #NNN)* tags above). The app-owned
-cancel door (`cancelInstance`, #667) is always preferred over the engine-level
-`urban_debug_cancel_instance`,
-because only the app door transitions the PR/plan record to `abandoned`.
+| Live version (§0) | `getVersion` | `GET __BASE__/version` |
+| PRs in flight (§0) | `listActivePrs` | `GET __BASE__/status` |
+| Submit a PR / epic / feature (§1–2) | `startConvergenceLoop` / `startPlanFanout` / `startFeature` | `POST __BASE__/actions/start/{convergence-loop,plan-fanout,feature}` |
+| List escalations (§3) | `listEscalations` | `GET __BASE__/escalations` |
+| Answer an escalation (§3) | `completeUserTask` (as agent: `agentCompleteEscalation`) | `POST __BASE__/actions/complete-user-task` (as agent: `POST __BASE__/hooks/agent-complete` with `agentId` required) |
+| Auto-resolutions (§3) | `listAutoResolutions` / `reviewAutoResolution` | `GET __BASE__/auto-resolutions` / `POST __BASE__/auto-resolutions/review` |
+| Cancel a run (§7) | `cancelInstance` | `POST __BASE__/actions/cancel` |
+| Publish a BPMN message | `postMessage` | `POST __BASE__/actions/message` |
+| Delivery graphs (§9) | `getDeliveryGraphVocabulary` / `compileDeliveryGraph` / `sequenceIssues` | `GET __BASE__/delivery-graph/vocabulary`, `POST __BASE__/actions/{compile-delivery-graph,start/sequence-issues}` |
+| This guide | `getAgentInstructions` (full) / `getAgentGuide(section?)` | `GET __BASE__/agent` / `GET __BASE__/agent/guide` |
+
+The engine-debug tools come from the urban framework and front `__ENGINE__` (§5).
+`urban_debug_search_process_instances`, `urban_debug_search_element_instance_wait_states` and
+`urban_debug_search_incidents` are always available. `urban_debug_search_jobs`,
+`urban_debug_search_variables` and `urban_debug_get_process_definition_xml` exist where the
+framework provides them; otherwise use the §5 curl searches or read `resources/processes/` from
+the checkout. **Never use `urban_debug_cancel_instance`**: use `cancelInstance` (§7).