@nanobpm/nano-workforce 0.40.2 → 0.41.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.41.0](https://github.com/nanobpm/nano-workforce/compare/v0.40.2...v0.41.0) (2026-08-11)
+
+
+### Features
+
+* **api:** serve an agent operator guide at GET /app/api/agent ([#118](https://github.com/nanobpm/nano-workforce/issues/118)) ([6768407](https://github.com/nanobpm/nano-workforce/commit/67684075cfe4706db7dfc63f8c536990254a7480))
+
 ## [0.40.2](https://github.com/nanobpm/nano-workforce/compare/v0.40.1...v0.40.2) (2026-08-11)
 
 

package/README.md

@@ -279,6 +279,26 @@ per-instance context (e.g. a human's escalation answer) is appended by the harne
 
 ---
 
+## Point an agent at it (self-serve guide)
+
+The running app serves a live **agent operator guide** at
+`GET /app/api/agent` — how to submit PRs (review-only vs. merge), hand over an epic,
+answer escalations, and **debug** the system (find engine instances, relate them to
+PRs, inspect the models/prompts, unstick stuck processes, and raise issues/PRs). Its
+examples are keyed to the instance you fetched it from, so a coding agent can drive
+**and** debug the workforce with no extra context:
+
+```bash
+curl -sS http://localhost:3000/app/api/agent | jq -r .instructions
+```
+
+Like `/version` and `/status`, this endpoint honours the optional
+`NANO_PR_WEBHOOK_SECRET` guard (`X-Hook-Secret` header): when that secret is set it
+returns `401` without the matching header; unset = open. The source lives in
+`resources/agent-guide.md`.
+
+---
+
 ## Architecture & contributing
 
 - **[SPEC.md](SPEC.md)** — the behavioural source of truth for the processes.

package/app/agentGuide.ts

@@ -0,0 +1,64 @@
+// The agent operator guide served by GET /app/api/agent (operationId `getAgentInstructions`).
+//
+// The guide itself is authored as plain markdown in `resources/agent-guide.md` (kept out of
+// `prompts/` so it is NOT treated as a deployable agent template) and read from the checkout at
+// module load — same "run the .ts sources directly, inspect the working tree at runtime" approach
+// as version.ts. Two placeholders are substituted per request/deployment so the embedded examples
+// are copy-pasteable against THIS instance:
+//   • __BASE__   → the app control-API base the caller reached us on (e.g. https://host/app/api)
+//   • __ENGINE__ → the engine's Camunda-8 v2 REST base this app is configured to talk to
+//
+// Reading is best-effort: a missing file yields a short built-in fallback rather than throwing, so
+// the endpoint never 500s just because the doc is absent from a stripped-down deploy.
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const REPO_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const GUIDE_PATH = join(REPO_ROOT, "resources", "agent-guide.md");
+
+// Read the raw guide once, at module load. Frozen for the life of the process.
+const RAW_GUIDE: string = (() => {
+  try {
+    return readFileSync(GUIDE_PATH, "utf8");
+  } catch {
+    return [
+      "# Nano Workforce — agent operator guide",
+      "",
+      "The full guide document could not be read from this deployment.",
+      "",
+      "Key endpoints (under the app control-API base `__BASE__`):",
+      "- `GET /status` — every PR in flight, with its engine `processKey` and any open escalation.",
+      "- `GET /version` — which code is live.",
+      "- `POST /actions/start/convergence-loop` — submit a PR (`{ pr, convergeOnly?, maxRounds?, dependsOn? }`).",
+      "- `POST /actions/start/plan-fanout` — submit an epic (`{ issue }`).",
+      "- `POST /actions/message` — answer an escalation (`escalation-answered`, correlate by PR key).",
+      "",
+      "Engine (Camunda-8 v2 REST) base for debugging: `__ENGINE__`.",
+      "Source repository: `nanobpm/nano-workforce`.",
+      "",
+    ].join("\n");
+  }
+})();
+
+/**
+ * The engine's Camunda-8 v2 REST base this app talks to, resolved exactly as `main.ts` does:
+ * an explicit `CAMUNDA_REST_ADDRESS` wins, else `${NANOBPMN_BASE_URL}/v2` (default localhost:8080).
+ * Trailing slashes are trimmed so the guide's `__ENGINE__/jobs/search` examples are well-formed.
+ */
+export function resolveEngineBase(): string {
+  const explicit = process.env.CAMUNDA_REST_ADDRESS;
+  const base = explicit?.trim()
+    ? explicit.trim()
+    : `${(process.env.NANOBPMN_BASE_URL ?? "http://localhost:8080").replace(/\/+$/, "")}/v2`;
+  return base.replace(/\/+$/, "");
+}
+
+/**
+ * Render the guide for a given app control-API base (e.g. "https://host/app/api"). The engine base
+ * is resolved from the environment. Substitutes every `__BASE__`/`__ENGINE__` occurrence.
+ */
+export function renderAgentGuide(apiBase: string): string {
+  const base = apiBase.replace(/\/+$/, "");
+  return RAW_GUIDE.replaceAll("__BASE__", base).replaceAll("__ENGINE__", resolveEngineBase());
+}

package/openapi.yaml

@@ -137,6 +137,42 @@ components:
           type: string
         uptimeSeconds:
           type: integer
+    AgentInstructions:
+      type: object
+      description: The agent operator guide — how to drive (submit PRs/epics, answer escalations)
+        and debug (find engine instances, relate them to PRs, inspect models/prompts, unstick stuck
+        processes, raise issues/PRs) this Nano Workforce instance. The `instructions` markdown has
+        its example commands keyed to this instance's `baseUrl`/`engineBase`.
+      additionalProperties: false
+      required:
+        - format
+        - appVersion
+        - generatedAt
+        - baseUrl
+        - engineBase
+        - instructions
+      properties:
+        format:
+          type: string
+          description: The `instructions` media format. Always "markdown".
+          enum:
+            - markdown
+        appVersion:
+          type: string
+          nullable: true
+          description: The running app version this guide matches (null when unreadable).
+        generatedAt:
+          type: string
+          description: When this response was rendered (ISO-8601).
+        baseUrl:
+          type: string
+          description: The app control-API base the examples target (e.g. https://host/app/api).
+        engineBase:
+          type: string
+          description: The engine's Camunda-8 v2 REST base this app talks to, for debugging queries.
+        instructions:
+          type: string
+          description: The full operator guide as markdown.
     SubmitResult:
       type: object
       required:
@@ -387,6 +423,27 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /agent:
+    get:
+      operationId: getAgentInstructions
+      summary: The agent operator guide (markdown) — how to submit PRs/epics, answer escalations, and
+        debug this instance. Point a coding agent at this URL to drive and debug the workforce.
+      security:
+        - hookSecret: []
+        - {}
+      responses:
+        "200":
+          description: The operator guide, with examples keyed to this instance.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AgentInstructions"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /actions/start/convergence-loop:
     post:
       operationId: startConvergenceLoop

package/operations/getAgentInstructions.test.ts

@@ -0,0 +1,100 @@
+// Tests for GET /app/api/agent → operation `getAgentInstructions` (ADR 0058 OpenAPI surface).
+// The guide markdown is served as the `instructions` field with its examples keyed to the request's
+// control-API base + the configured engine base. Mirrors the getVersion test's request shape and
+// shared-secret guard pattern.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import handler from "./getAgentInstructions.ts";
+
+const app = {} as any as AppApi;
+
+function input(headers: Record<string, string> = {}, path = "/app/api/agent") {
+  return {
+    req: {
+      method: "GET",
+      path,
+      query: new URLSearchParams(),
+      headers: new Headers(headers),
+      text: async () => "",
+    } as any,
+    params: {},
+    query: {},
+    body: undefined,
+  };
+}
+
+test("returns 200 with the markdown guide and metadata", async () => {
+  const r = (await handler(input(), app)) as any;
+  assertEquals(r.status, 200);
+  assertEquals(r.body.format, "markdown");
+  assert("appVersion" in r.body); // nullable, but always present
+  assert(typeof r.body.generatedAt === "string" && r.body.generatedAt.length > 0);
+  assert(typeof r.body.baseUrl === "string" && r.body.baseUrl.length > 0);
+  assert(typeof r.body.engineBase === "string" && r.body.engineBase.length > 0);
+  assert(typeof r.body.instructions === "string" && r.body.instructions.length > 200);
+});
+
+test("the guide covers every capability the endpoint promises", async () => {
+  const md = ((await handler(input(), app)) as any).body.instructions as string;
+  // Submit a PR (converge vs. merge), submit an epic, answer escalations…
+  assert(md.includes("start/convergence-loop"), "covers submitting a PR for convergence");
+  assert(md.includes("convergeOnly"), "documents review-only vs. merge");
+  assert(md.includes("start/plan-fanout"), "covers submitting an epic");
+  assert(md.includes("escalation-answered"), "covers answering escalations");
+  // …debug the system.
+  assert(md.includes("/jobs/search") && md.includes("/incidents/search"), "covers engine REST debugging");
+  assert(md.includes("processKey") || md.includes("process_key"), "relates instances to PRs");
+  assert(md.includes("resources/processes") && md.includes("prompts/"), "covers debugging models + prompts");
+  assert(md.includes("nanobpm/nano-workforce"), "covers raising issues/PRs against the repo");
+});
+
+test("examples are keyed to the request's control-API base and leave no placeholders", async () => {
+  const forwarded = input({ host: "wf.example.com", "x-forwarded-proto": "https" });
+  const md = ((await handler(forwarded, app)) as any).body.instructions as string;
+  const body = (await handler(forwarded, app)) as any;
+  assertEquals(body.body.baseUrl, "https://wf.example.com/app/api");
+  assert(md.includes("https://wf.example.com/app/api/version"), "base URL substituted into examples");
+  assert(!md.includes("__BASE__"), "no unsubstituted __BASE__ placeholder");
+  assert(!md.includes("__ENGINE__"), "no unsubstituted __ENGINE__ placeholder");
+});
+
+test("x-forwarded-proto is restricted to http/https", async () => {
+  const spoofed = input({ host: "wf.example.com", "x-forwarded-proto": "javascript" });
+  const body = (await handler(spoofed, app)) as any;
+  assertEquals(body.body.baseUrl, "http://wf.example.com/app/api", "unsafe scheme falls back to http");
+});
+
+test("engine base follows CAMUNDA_REST_ADDRESS / NANOBPMN_BASE_URL", async () => {
+  const prevCamunda = process.env["CAMUNDA_REST_ADDRESS"];
+  const prevBase = process.env["NANOBPMN_BASE_URL"];
+  try {
+    delete process.env["CAMUNDA_REST_ADDRESS"];
+    process.env["NANOBPMN_BASE_URL"] = "http://engine.internal:8080";
+    const r = (await handler(input(), app)) as any;
+    assertEquals(r.body.engineBase, "http://engine.internal:8080/v2");
+    assert(r.body.instructions.includes("http://engine.internal:8080/v2/jobs/search"));
+  } finally {
+    if (prevCamunda === undefined) delete process.env["CAMUNDA_REST_ADDRESS"];
+    else process.env["CAMUNDA_REST_ADDRESS"] = prevCamunda;
+    if (prevBase === undefined) delete process.env["NANOBPMN_BASE_URL"];
+    else process.env["NANOBPMN_BASE_URL"] = prevBase;
+  }
+});
+
+test("shared-secret guard rejects a missing/wrong secret when configured", async () => {
+  const prev = process.env["NANO_PR_WEBHOOK_SECRET"];
+  process.env["NANO_PR_WEBHOOK_SECRET"] = "s3cr3t";
+  try {
+    // SECRET is bound at import time, so import a cache-busted copy to observe the guard.
+    const mod = await import(`./getAgentInstructions.ts?guard=${Date.now()}`);
+    const guarded = mod.default as typeof handler;
+    const bad = (await guarded(input(), app)) as any;
+    assertEquals(bad.status, 401);
+    const ok = (await guarded(input({ "x-hook-secret": "s3cr3t" }), app)) as any;
+    assertEquals(ok.status, 200);
+  } finally {
+    if (prev === undefined) delete process.env["NANO_PR_WEBHOOK_SECRET"];
+    else process.env["NANO_PR_WEBHOOK_SECRET"] = prev;
+  }
+});

package/operations/getAgentInstructions.ts

@@ -0,0 +1,52 @@
+// GET /app/api/agent → operationId `getAgentInstructions` (ADR 0058/0059 OpenAPI surface, base
+// /app/api). Serves the agent operator guide: how to submit a PR for convergence (review-only vs.
+// merge), submit an epic, answer escalations, and debug the system (find engine instances, relate
+// them to PRs, inspect the models/prompts, unstick stuck processes, and raise issues/PRs). A user
+// can point their coding agent at this URL and it can drive AND debug the workforce.
+//
+// The runtime serializes an operation body as JSON, so the markdown guide is returned as the
+// `instructions` string field (alongside the app version + the base URLs the examples are keyed
+// to), rather than as a raw text/markdown body. The embedded examples are rewritten to THIS
+// instance's control-API base (derived from the request) and engine base (from the environment).
+//
+// Read-only. The optional shared-secret guard mirrors /version: enforced HERE only when
+// NANO_PR_WEBHOOK_SECRET is set (the runtime does not enforce OpenAPI `security`).
+
+import { renderAgentGuide, resolveEngineBase } from "../app/agentGuide.ts";
+import { buildVersionInfo, envVar } from "../app/version.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+/**
+ * Reconstruct the app control-API base the caller reached us on (e.g. "https://host/app/api"), so
+ * the guide's example commands are copy-pasteable. Honour reverse-proxy forwarding headers; fall
+ * back to a localhost default when the Host header is absent (e.g. a raw unit-test request).
+ */
+function resolveApiBase(req: { path: string; headers: Headers }): string {
+  const rawProto = (req.headers.get("x-forwarded-proto") ?? "http").split(",")[0].trim().toLowerCase();
+  // x-forwarded-proto is user-controlled behind some proxies; only trust http/https.
+  const proto = rawProto === "http" || rawProto === "https" ? rawProto : "http";
+  const host = (req.headers.get("x-forwarded-host") ?? req.headers.get("host") ?? "").split(",")[0].trim();
+  // The op is mounted at "<base>/agent"; strip the trailing segment to recover the base path.
+  const basePath = req.path.replace(/\/agent\/?$/, "") || "/app/api";
+  return host ? `${proto}://${host}${basePath}` : `http://localhost:3000${basePath}`;
+}
+
+export default defineOperation("getAgentInstructions", ({ req }) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+  const baseUrl = resolveApiBase(req);
+  return {
+    status: 200,
+    body: {
+      format: "markdown",
+      appVersion: buildVersionInfo().version,
+      generatedAt: new Date().toISOString(),
+      baseUrl,
+      engineBase: resolveEngineBase(),
+      instructions: renderAgentGuide(baseUrl),
+    },
+  };
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.40.2",
+  "version": "0.41.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/resources/agent-guide.md

@@ -0,0 +1,302 @@
+# 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).
+
+- **App control API base:** `__BASE__`
+- **Engine (Nano/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.
+
+---
+
+## 0. Orient yourself first
+
+Before acting, confirm what is running and what is in flight:
+
+```bash
+# Which code is live (app version, urban version, git sha/branch, uptime):
+curl -sS __BASE__/version | jq
+
+# Every PR currently in flight (not converged/abandoned), with its engine
+# process key, status, round, and any open escalation:
+curl -sS __BASE__/status | jq
+```
+
+`/status` is your primary situational-awareness endpoint. 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`.
+
+---
+
+## 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.
+
+```bash
+# Minimal: converge, then merge (if NANO_PR_AUTO_MERGE is on — the default).
+curl -sS -X POST __BASE__/actions/start/convergence-loop \
+  -H 'content-type: application/json' \
+  -d '{ "pr": "owner/repo#123" }'
+```
+
+The body is flat. Fields:
+
+| field | type | meaning |
+|---|---|---|
+| `pr` (or `url`) | string | the PR — `owner/repo#123` or a full PR URL. Required. |
+| `convergeOnly` | boolean | **`true` = review only.** The PR stops at `converged` and is **never** handed to the merge loop, even when `NANO_PR_AUTO_MERGE` is on. Omit / `false` = converge **then merge**. |
+| `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). |
+
+**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", "convergeOnly": true }'
+
+# 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", "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`.
+
+---
+
+## 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).
+
+```bash
+curl -sS -X POST __BASE__/actions/start/plan-fanout \
+  -H 'content-type: application/json' \
+  -d '{ "issue": "owner/repo#123" }'
+```
+
+The body is flat: `issue` (or `url`) — `owner/repo#123` or an issue URL. Starting a
+plan is idempotent on the plan key; an already-running plan short-circuits. The
+response (202) echoes the `planKey` and engine `processKey`.
+
+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.
+
+---
+
+## 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:
+
+```bash
+# Which in-flight PRs have an open escalation waiting for a human?
+curl -sS __BASE__/status | jq '.prs[] | select(.openEscalation != null)
+  | { prKey, status, round, openEscalation }'
+```
+
+**Answer a PR/merge escalation** (convergence-loop or merge-loop). Use the message
+name `escalation-answered`; correlate by the PR key:
+
+```bash
+curl -sS -X POST __BASE__/actions/message \
+  -H 'content-type: application/json' \
+  -d '{
+        "name": "escalation-answered",
+        "correlationKey": "owner/repo#123",
+        "variables": { "answer": "Yes — cap the retries at 5 and proceed." }
+      }'
+```
+
+The answer is delivered to the agent as the `answer` variable on its next round, and
+the loop resumes.
+
+**Answer an implementation-phase (feature) task escalation** raised during a
+plan fan-out — a dedicated webhook operation:
+
+```bash
+curl -sS -X POST __BASE__/hooks/feature-answer \
+  -H 'content-type: application/json' \
+  -d '{ "correlationKey": "<task-or-pr-key>", "answer": "…" }'
+```
+
+If `NANO_PR_WEBHOOK_SECRET` is set on the deployment, add `-H "x-hook-secret: <secret>"`.
+
+Guidance for the human you assist: read the escalation `question` first (it is the
+exact blocker text the agent surfaced), decide the smallest unblocking answer, and
+answer it precisely — the answer becomes the agent's next-round context.
+
+---
+
+## 4. The lifecycle & statuses (so you can reason about state)
+
+```
+ submit ──► convergence-loop
+   round (senior:pr-review) ──► addressed ──► wait review-ready ─┐
+                             ├─ converged  ──► finalize ──► merge-loop (unless convergeOnly)
+                             └─ needs_input/blocked ──► escalate ──► wait escalation-answered
+ merge-loop: wait deps ─► arm merge ─► (queue-aware) merge / land
+             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.
+
+---
+
+## 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 `/status`, then query the
+engine's Camunda-8 v2 REST API:
+
+```bash
+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 (a CREATED senior:pr-review job
+# with a `worker` set means an agent has leased the round; none means it is queued):
+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
+```
+
+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 `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 `/status` (`.prs[] | select(.processKey == "<PK>")`). A terminal PR is no
+longer in `/status`; its instance has already completed or been cancelled.
+
+---
+
+## 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:** `resources/processes/*.bpmn` — `convergence-loop.bpmn` (review),
+  `merge-loop.bpmn` (merge/CI-fix/rebase), `plan-fanout.bpmn` (planning),
+  `retro.bpmn`. These are the source of truth for routing. 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):** `prompts/*.md` — `review-round.md`,
+  `plan.md`, `feature.md`, `fix-ci.md`, `rebase.md`, `trial-merge.md`, etc. An
+  agent's base prompt is **not** a job variable: it is delivered as a model
+  **template header** (`{{review-round}}`, `{{plan}}`, …) substituted from these files
+  at deploy time. If an agent misbehaves systematically, the prompt is the first thing
+  to inspect/fix.
+- **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 template resolves), `npm run check`
+(manifest), `npm run typecheck`, `npm run lint`, `npm 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 `PT20M`); 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 the instance via the app (the UI's
+   per-row Cancel, `POST /app/actions/cancel { "processInstanceKey": "<PK>" }`), which
+   marks the PR `abandoned`, then re-submit the PR (§1) to start a fresh loop. Do not
+   cancel a raw engine instance out from under the app — go through the app so its
+   record state stays consistent.
+
+---
+
+## 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).