@nanobpm/nano-workforce 0.29.0 → 0.31.0

package/resources/processes/retro.bpmn

@@ -0,0 +1,83 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI" xmlns:dc="http://www.omg.org/spec/DD/20100524/DC" xmlns:di="http://www.omg.org/spec/DD/20100524/DI" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:zeebe="http://camunda.org/schema/zeebe/1.0" xmlns:nano="https://nanobpm.io/schema/shapes/1.0" id="Definitions_nano_workforce_retro" targetNamespace="http://nanobpm.io/nano-workforce">
+  <bpmn:process id="retro" name="Epic Retrospective" isExecutable="true">
+    <bpmn:startEvent id="Start" name="Epic complete">
+      <bpmn:outgoing>f_start</bpmn:outgoing>
+    </bpmn:startEvent>
+    <bpmn:serviceTask id="gather" name="Gather learnings">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="pr.retro-gather" />
+      </bpmn:extensionElements>
+      <bpmn:incoming>f_start</bpmn:incoming>
+      <bpmn:outgoing>f_toSynthesize</bpmn:outgoing>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="synthesize" name="Synthesize &#38; promote (agent)">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:retro" />
+        <zeebe:taskHeaders>
+          <zeebe:header key="io.nanobpm.agentTask.task.prompt" value="{{retro}}" />
+        </zeebe:taskHeaders>
+        <zeebe:ioMapping>
+          <zeebe:input source="=retroDigest" target="appendPrompt" />
+        </zeebe:ioMapping>
+      </bpmn:extensionElements>
+      <bpmn:incoming>f_toSynthesize</bpmn:incoming>
+      <bpmn:outgoing>f_toRecord</bpmn:outgoing>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="record" name="Record retro">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="pr.retro-record" />
+      </bpmn:extensionElements>
+      <bpmn:incoming>f_toRecord</bpmn:incoming>
+      <bpmn:outgoing>f_toEnd</bpmn:outgoing>
+    </bpmn:serviceTask>
+    <bpmn:endEvent id="End" name="Retro filed">
+      <bpmn:incoming>f_toEnd</bpmn:incoming>
+    </bpmn:endEvent>
+    <bpmn:sequenceFlow id="f_start" sourceRef="Start" targetRef="gather" />
+    <bpmn:sequenceFlow id="f_toSynthesize" sourceRef="gather" targetRef="synthesize" />
+    <bpmn:sequenceFlow id="f_toRecord" sourceRef="synthesize" targetRef="record" />
+    <bpmn:sequenceFlow id="f_toEnd" sourceRef="record" targetRef="End" />
+  </bpmn:process>
+  <bpmndi:BPMNDiagram id="BPMNDiagram_retro">
+    <bpmndi:BPMNPlane id="BPMNPlane_retro" bpmnElement="retro">
+      <bpmndi:BPMNShape id="BPMNShape_Start" bpmnElement="Start">
+        <dc:Bounds x="80" y="102" width="36" height="36" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="67" y="143" width="63" height="28" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_gather" bpmnElement="gather">
+        <dc:Bounds x="216" y="80" width="100" height="80" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_synthesize" bpmnElement="synthesize">
+        <dc:Bounds x="416" y="80" width="100" height="80" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_record" bpmnElement="record">
+        <dc:Bounds x="616" y="80" width="100" height="80" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_End" bpmnElement="End">
+        <dc:Bounds x="816" y="102" width="36" height="36" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="794" y="143" width="80" height="14" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_start" bpmnElement="f_start">
+        <di:waypoint x="116" y="120" />
+        <di:waypoint x="216" y="120" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_toSynthesize" bpmnElement="f_toSynthesize">
+        <di:waypoint x="316" y="120" />
+        <di:waypoint x="416" y="120" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_toRecord" bpmnElement="f_toRecord">
+        <di:waypoint x="516" y="120" />
+        <di:waypoint x="616" y="120" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_toEnd" bpmnElement="f_toEnd">
+        <di:waypoint x="716" y="120" />
+        <di:waypoint x="816" y="120" />
+      </bpmndi:BPMNEdge>
+    </bpmndi:BPMNPlane>
+  </bpmndi:BPMNDiagram>
+</bpmn:definitions>

package/scripts/pages-contract.test.ts

@@ -0,0 +1,228 @@
+// Static contract guard between the declarative pages (`pages/*.page.json`) and the app schema
+// (`db/migrations/*.sql`).
+//
+// The Urban page runtime whitelists every datasource `table` and `column` against the LIVE schema
+// (`PRAGMA table_info`): a grid that binds to a table or column the migrations never created 400s
+// at request time — an invisible, runtime-only failure with no compile or `urban check` signal.
+// This test closes that drift surface: every table and column referenced by any page must be
+// derivable from the migrations, so a rename/typo/removed column fails CI instead of a live page.
+//
+// It also pins the issue #87 surfaces: the plan-review audit log (`plan_reviews`) — which is
+// persisted but was surfaced on no page — must appear on the epic page (flat grid) and inside the
+// home page's plan detail (child grid). Feature coverage so the trace can't silently regress out.
+import { assert } from "jsr:@std/assert@1";
+
+// Percent-decode the pathname: `new URL(..).pathname` can contain encoded characters (e.g. a space
+// as `%20`), which `Deno.readDir`/`readTextFile` would fail to resolve. Matches the repo convention
+// (see scripts/check-agent-prompts.test.ts).
+const ROOT = decodeURIComponent(new URL("../", import.meta.url).pathname);
+
+// ---- migrations -> { table -> Set<column> } -----------------------------------------------------
+
+function parseSchema(sql: string, schema: Map<string, Set<string>>): void {
+  // Strip SQL comments first: an inline `-- ...` trailing one column line would otherwise become
+  // the leading token of the NEXT comma-split fragment, hiding the real column name.
+  sql = sql.replace(/--[^\n]*/g, "").replace(/\/\*[\s\S]*?\*\//g, "");
+  // CREATE TABLE [IF NOT EXISTS] <name> ( <body> )
+  const createRe = /CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?["`]?(\w+)["`]?\s*\(/gi;
+  let m: RegExpExecArray | null;
+  while ((m = createRe.exec(sql)) !== null) {
+    const table = m[1];
+    const body = balancedBody(sql, createRe.lastIndex - 1); // start at the "("
+    if (body === null) continue;
+    const cols = schema.get(table) ?? new Set<string>();
+    for (const frag of splitTopLevel(body)) {
+      const first = frag.trim().split(/[\s(]/)[0];
+      if (!first) continue;
+      const upper = first.toUpperCase();
+      if (["PRIMARY", "FOREIGN", "UNIQUE", "CHECK", "CONSTRAINT"].includes(upper)) continue;
+      cols.add(first.replace(/["`]/g, ""));
+    }
+    schema.set(table, cols);
+  }
+  // ALTER TABLE <name> ADD [COLUMN] <col>
+  const alterRe = /ALTER\s+TABLE\s+["`]?(\w+)["`]?\s+ADD\s+(?:COLUMN\s+)?["`]?(\w+)["`]?/gi;
+  while ((m = alterRe.exec(sql)) !== null) {
+    const cols = schema.get(m[1]) ?? new Set<string>();
+    cols.add(m[2]);
+    schema.set(m[1], cols);
+  }
+}
+
+// Return the text inside the parentheses whose opener is at `openIdx`, honouring nesting.
+function balancedBody(s: string, openIdx: number): string | null {
+  let depth = 0;
+  for (let i = openIdx; i < s.length; i++) {
+    if (s[i] === "(") depth++;
+    else if (s[i] === ")") {
+      depth--;
+      if (depth === 0) return s.slice(openIdx + 1, i);
+    }
+  }
+  return null;
+}
+
+// Split a CREATE TABLE body on top-level commas (commas inside nested parens stay attached).
+function splitTopLevel(body: string): string[] {
+  const out: string[] = [];
+  let depth = 0, start = 0;
+  for (let i = 0; i < body.length; i++) {
+    const c = body[i];
+    if (c === "(") depth++;
+    else if (c === ")") depth--;
+    else if (c === "," && depth === 0) {
+      out.push(body.slice(start, i));
+      start = i + 1;
+    }
+  }
+  out.push(body.slice(start));
+  return out;
+}
+
+async function loadSchema(): Promise<Map<string, Set<string>>> {
+  const schema = new Map<string, Set<string>>();
+  const files: string[] = [];
+  for await (const e of Deno.readDir(`${ROOT}db/migrations`)) {
+    if (e.isFile && e.name.endsWith(".sql")) files.push(e.name);
+  }
+  files.sort(); // migration order doesn't matter for the union, but keep it deterministic
+  for (const f of files) {
+    parseSchema(await Deno.readTextFile(`${ROOT}db/migrations/${f}`), schema);
+  }
+  return schema;
+}
+
+// ---- pages -> datasource references -------------------------------------------------------------
+
+// deno-lint-ignore no-explicit-any
+type Json = any;
+
+interface Ref {
+  page: string;
+  table: string;
+  source: string;
+  fields: string[]; // every column that must exist on `table` (displayed columns + binding fields)
+  columns: string[]; // only the visibly displayed grid columns (`columns[].field`)
+}
+
+// Pull `field` names out of a `filter` array ([{ field, in/eq/... }, ...]).
+function filterFields(filter: Json): string[] {
+  if (!Array.isArray(filter)) return [];
+  return filter.map((f: Json) => f?.field).filter(Boolean);
+}
+
+function collectRefs(page: string, node: Json, out: Ref[]): void {
+  if (Array.isArray(node)) {
+    for (const v of node) collectRefs(page, v, out);
+    return;
+  }
+  if (!node || typeof node !== "object") return;
+
+  // Top-level datasource grid: the datasource lives at `node.data`, while `columns`, `rowKey`,
+  // `filter`/`tabs`, and `detail` are siblings on the same `node` (the grid props).
+  const data = node.data;
+  if (data && data.kind === "datasource" && typeof data.table === "string") {
+    const columns: string[] = (node.columns ?? []).map((c: Json) => c.field).filter(Boolean);
+    // Every reference that resolves to a column on this table — the runtime 400s on any of them if
+    // it names a column the migrations never created, so all must be guarded, not just displayed
+    // columns. `detail.fields`/`detail.linkField` render columns of the same top-level row.
+    const detail = node.detail ?? {};
+    const fields: string[] = [
+      ...columns,
+      ...(node.columns ?? []).map((c: Json) => c.linkField),
+      node.rowKey,
+      data.orderBy?.field,
+      ...filterFields(data.filter),
+      ...(node.tabs ?? []).flatMap((t: Json) => filterFields(t.filter)),
+      detail.linkField,
+      ...(detail.fields ?? []).flatMap((f: Json) => [f.field, f.linkField]),
+      // `detail.children[].parentField` joins each child grid back to a column on THIS (parent)
+      // table, so a rename/typo there 400s at request time — guard it against the parent schema.
+      ...(detail.children ?? []).map((c: Json) => c.parentField),
+    ].filter(Boolean);
+    out.push({ page, table: data.table, source: data.source ?? "app", fields, columns });
+  }
+
+  // Child grid inside a detail: { table, childField, parentField, orderBy, columns }
+  if (typeof node.table === "string" && typeof node.childField === "string") {
+    const columns: string[] = (node.columns ?? []).map((c: Json) => c.field).filter(Boolean);
+    out.push({
+      page,
+      table: node.table,
+      source: node.source ?? "app",
+      fields: [
+        ...columns,
+        ...(node.columns ?? []).map((c: Json) => c.linkField),
+        node.childField,
+        node.orderBy?.field,
+        node.lazyField?.field,
+      ].filter(Boolean),
+      columns,
+    });
+  }
+
+  for (const v of Object.values(node)) collectRefs(page, v, out);
+}
+
+async function loadRefs(): Promise<Ref[]> {
+  const refs: Ref[] = [];
+  for await (const e of Deno.readDir(`${ROOT}pages`)) {
+    if (!e.isFile || !e.name.endsWith(".page.json")) continue;
+    const page = JSON.parse(await Deno.readTextFile(`${ROOT}pages/${e.name}`));
+    collectRefs(e.name, page, refs);
+  }
+  return refs;
+}
+
+// ---- guards -------------------------------------------------------------------------------------
+
+Deno.test("every page datasource table exists in the migrations", async () => {
+  const schema = await loadSchema();
+  const refs = await loadRefs();
+  assert(refs.length > 0, "no datasource references found — collector or pages are broken");
+  for (const r of refs) {
+    // Only the default app SQLite source is schema-backed; other sources aren't migration-defined.
+    if (r.source !== "app") continue;
+    assert(
+      schema.has(r.table),
+      `${r.page}: datasource table "${r.table}" has no CREATE TABLE in db/migrations/*.sql`,
+    );
+  }
+});
+
+Deno.test("every page datasource column exists on its table", async () => {
+  const schema = await loadSchema();
+  const refs = await loadRefs();
+  for (const r of refs) {
+    if (r.source !== "app") continue;
+    const cols = schema.get(r.table);
+    if (!cols) continue; // table-existence is asserted by the sibling test
+    for (const f of r.fields) {
+      assert(
+        cols.has(f),
+        `${r.page}: column "${f}" referenced on table "${r.table}" is not defined by any migration`,
+      );
+    }
+  }
+});
+
+Deno.test("issue #87: plan_reviews is surfaced on the epic and home pages", async () => {
+  const refs = await loadRefs();
+  const onEpic = refs.some((r) => r.page === "epic.page.json" && r.table === "plan_reviews");
+  const onHome = refs.some((r) => r.page === "home.page.json" && r.table === "plan_reviews");
+  assert(onEpic, "epic.page.json must bind a grid to plan_reviews (plan-review trace)");
+  assert(onHome, "home.page.json plan detail must include a plan_reviews child grid");
+
+  // The trace is only useful with the verdict + critique columns, so pin them. Assert against the
+  // visibly displayed `columns` (not `fields`, which also holds binding refs like orderBy.field) so
+  // a column silently dropped from the grid UI can't pass by being referenced elsewhere.
+  const required = ["round", "approved", "findings"];
+  for (const r of refs.filter((x) => x.table === "plan_reviews")) {
+    for (const col of required) {
+      assert(
+        r.columns.includes(col),
+        `${r.page}: plan_reviews grid must expose the "${col}" column`,
+      );
+    }
+  }
+});

package/workers/finalize/worker.ts

@@ -3,6 +3,7 @@
 // is on, or (b) close the PR out as `converged` (review-only mode).
 import type { AppJobHandler } from "@nanobpm/urban";
 import { AUTO_MERGE, startMerge } from "../../app/service.ts";
+import { maybeStartRetro } from "../../app/retro.ts";
 
 // Extends Record so the declared fields are typed while the job may still carry
 // other process variables (e.g. io.nanobpm.agentResult, read by transcriptOf).
@@ -83,6 +84,14 @@ const handler: AppJobHandler<In> = async (job, app) => {
     open_escalation_question: null,
   });
 
+  // Only the review-only terminal path ends the PR here as `converged` — in auto-merge mode the
+  // terminal point is pr.mark-merged (which triggers the retro), and a PR parked in `waiting_deps`
+  // is still in flight. So fire the retro trigger only when this PR actually reached its terminal
+  // state in finalize. Best-effort: must never fail the finalize job.
+  if (status === "converged") {
+    await maybeStartRetro(app.data, app.engine, prKey, app.log);
+  }
+
   return {};
 };
 

package/workers/mark-merged/worker.ts

@@ -1,6 +1,7 @@
 // pr.mark-merged — the PR has landed (directly or via the merge queue). Record the terminal
 // `merged` state; the merge audit trail is written by pr.merge, so this only closes the row out.
 import type { AppJobHandler } from "@nanobpm/urban";
+import { maybeStartRetro } from "../../app/retro.ts";
 
 interface In extends Record<string, unknown> {
   prKey: string;
@@ -15,6 +16,11 @@ const handler: AppJobHandler<In> = async (job, app) => {
     open_escalation_id: null,
     open_escalation_question: null,
   });
+
+  // If this PR was the last of its epic to land, kick off the retrospective. Best-effort: a
+  // failure here (or no epic) must never fail marking the PR merged — the retro is advisory.
+  await maybeStartRetro(app.data, app.engine, job.variables.prKey, app.log);
+
   return {};
 };
 

package/workers/record-plan-review/worker.test.ts

@@ -0,0 +1,82 @@
+// Red/green for the plan-review gate (issue #86).
+//
+// Previously the fan-out PROCEEDED when the review-round cap was reached without approval
+// ("proceed regardless rather than dead-lock"). That dispatched an un-vetted plan and — when the
+// plan was empty (e.g. the planner agent couldn't persist its result) — completed the whole epic
+// GREEN having done nothing (instance 21). We now HARD-FAIL: the terminal, unapproved round raises
+// a non-retryable `PLAN_REJECTED` BpmnError (→ incident), so an un-approved plan never dispatches.
+import { assertEquals, assertRejects } from "jsr:@std/assert@1";
+import { BpmnError } from "@nanobpm/urban";
+import handler from "./worker.ts";
+import { MAX_PLAN_REVIEW_ROUNDS, type PlanReview } from "../../app/plan.ts";
+
+function fakeApp(existing: PlanReview[] = []) {
+  const rows: PlanReview[] = [...existing];
+  const match = (r: PlanReview, q: Record<string, unknown>) =>
+    Object.entries(q).every(([f, v]) => (r as unknown as Record<string, unknown>)[f] === v);
+  return {
+    data: {
+      table() {
+        return {
+          // deno-lint-ignore no-explicit-any
+          findOne: (q: any) => Promise.resolve(rows.find((r) => match(r, q)) ?? null),
+          // deno-lint-ignore no-explicit-any
+          count: (q: any) => Promise.resolve(rows.filter((r) => match(r, q)).length),
+          insert: (row: PlanReview) => {
+            rows.push(row);
+            return Promise.resolve(row);
+          },
+        };
+      },
+    },
+    log: () => {},
+    _rows: rows,
+    // deno-lint-ignore no-explicit-any
+  } as any;
+}
+
+// Seed `n` prior recorded rounds for a plan so the next job lands on round `n` (0-based).
+function priorRounds(planKey: string, n: number): PlanReview[] {
+  return Array.from({ length: n }, (_, i) => ({
+    plan_key: planKey,
+    round: i,
+    approved: 0,
+    findings: null,
+    created_at: "2026-01-01T00:00:00.000Z",
+    job_key: `prior-${i}`,
+  }));
+}
+
+const call = async (app: unknown, vars: Record<string, unknown>, jobKey = "j-new") =>
+  // deno-lint-ignore no-explicit-any
+  await handler({ variables: vars, jobKey } as any, app as any);
+
+Deno.test("approved round proceeds (planApproved=true, no throw)", async () => {
+  const app = fakeApp(priorRounds("o/r#1", 0));
+  const out = await call(app, { planKey: "o/r#1", approved: true });
+  assertEquals((out as { planApproved: boolean }).planApproved, true);
+});
+
+Deno.test("unapproved, non-final round revises (planApproved=false, no throw)", async () => {
+  // First round of a 3-round cap: not final, so revise.
+  const app = fakeApp(priorRounds("o/r#2", 0));
+  const out = await call(app, { planKey: "o/r#2", approved: false, findings: "fix X" });
+  assertEquals((out as { planApproved: boolean; planFindings: string }).planApproved, false);
+  assertEquals((out as { planFindings: string }).planFindings, "fix X");
+});
+
+Deno.test("unapproved FINAL round hard-fails with PLAN_REJECTED incident", async () => {
+  // Seed cap-1 prior rounds so this job is the last permitted round; unapproved ⇒ must throw.
+  const app = fakeApp(priorRounds("o/r#3", MAX_PLAN_REVIEW_ROUNDS - 1));
+  const err = await assertRejects(
+    () => call(app, { planKey: "o/r#3", approved: false, findings: "still wrong" }),
+    BpmnError,
+  );
+  assertEquals((err as BpmnError).errorCode, "PLAN_REJECTED");
+});
+
+Deno.test("approved on the FINAL round still proceeds (no throw)", async () => {
+  const app = fakeApp(priorRounds("o/r#4", MAX_PLAN_REVIEW_ROUNDS - 1));
+  const out = await call(app, { planKey: "o/r#4", approved: true });
+  assertEquals((out as { planApproved: boolean }).planApproved, true);
+});

package/workers/record-plan-review/worker.ts

@@ -6,13 +6,17 @@
 //   • derives the current round from the append-only `plan_reviews` log (no counter variable),
 //     using the engine jobKey as an idempotency guard so a retried job reuses its row,
 //   • records this round's verdict + findings,
-//   • decides the loop: `planApproved` (reviewer said yes) and `reviewExhausted` (the round cap
-//     is reached, so we proceed regardless rather than dead-lock on a reviewer that never
-//     approves), and re-emits the findings as `planFindings` so a revise round feeds the planner.
+//   • decides the loop: emits `planApproved` (reviewer said yes → the BPMN gateway proceeds to
+//     `select-wave`) or, when unapproved, re-emits the findings as `planFindings` so a revise
+//     round feeds the planner and loops back to `plan`.
 //
-// The BPMN gateway proceeds to `select-wave` when `planApproved or reviewExhausted`, else loops
-// back to `plan`. A missing/ambiguous `approved` is treated as NOT approved (revise) — but the
-// round cap still bounds the loop, so the plan can never wedge.
+// When the review-round cap is reached WITHOUT approval, this worker HARD-FAILS: it throws a
+// non-retryable `PLAN_REJECTED` BpmnError (→ incident) rather than proceeding regardless
+// (issue #86). Proceeding used to dispatch an un-vetted plan and — when the plan was empty — let
+// the whole epic complete GREEN having done nothing. The cap still bounds the loop; it now bounds
+// it into an incident, not a silent proceed. A missing/ambiguous `approved` is treated as NOT
+// approved (revise until the cap).
+import { BpmnError } from "@nanobpm/urban";
 import type { AppJobHandler } from "@nanobpm/urban";
 import { MAX_PLAN_REVIEW_ROUNDS, type PlanReview, planReviews } from "../../app/plan.ts";
 
@@ -23,7 +27,6 @@ interface In extends Record<string, unknown> {
 }
 interface Out extends Record<string, unknown> {
   planApproved: boolean;
-  reviewExhausted: boolean;
   planFindings: string;
 }
 
@@ -56,7 +59,7 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   // Idempotency guard: deriving the round from count(plan_reviews) is not retry-safe on its own.
   // A job retried after the insert (crash/timeout post-write) re-runs with the SAME jobKey — if
   // this job already recorded a row, reuse it rather than appending a duplicate, which would
-  // inflate the count and trip `reviewExhausted` early. Otherwise this is the first attempt:
+  // inflate the count and reach the review-round cap early. Otherwise this is the first attempt:
   // derive the 0-based next round from the append-only log and record it under this jobKey.
   const recorded: PlanReview = (await reviews.findOne({ plan_key: planKey, job_key: jobKey })) ??
     await (async () => {
@@ -77,16 +80,29 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   const roundApproved = recorded.approved === 1;
   const roundFindings = recorded.findings ?? "";
 
-  // Exhausted once this round is the last permitted one (round is 0-based).
-  const reviewExhausted = round + 1 >= MAX_PLAN_REVIEW_ROUNDS;
-  if (!roundApproved) {
-    app.log(reviewExhausted ? "warn" : "info", `record-plan-review: ${planKey} round ${round}`, {
-      approved: roundApproved,
-      reviewExhausted,
+  if (roundApproved) {
+    return { planApproved: true, planFindings: roundFindings };
+  }
+
+  // Not approved this round. Hard-fail once the round cap is reached (issue #86): previously the
+  // fan-out PROCEEDED regardless ("don't dead-lock on a reviewer that never approves"), which
+  // dispatched an un-vetted plan and — when the plan was empty — completed the epic GREEN having
+  // done nothing (instance 21). Instead raise a non-retryable BpmnError: no boundary catches
+  // `PLAN_REJECTED`, so the engine parks the instance on an incident rather than dispatching an
+  // un-approved plan. The round is 0-based, so `round + 1 >= cap` is the last permitted round.
+  if (round + 1 >= MAX_PLAN_REVIEW_ROUNDS) {
+    app.log("error", `record-plan-review: ${planKey} not approved after ${MAX_PLAN_REVIEW_ROUNDS} round(s)`, {
+      round,
     });
+    throw new BpmnError(
+      "PLAN_REJECTED",
+      `${planKey}: plan not approved after ${MAX_PLAN_REVIEW_ROUNDS} review round(s)`,
+    );
   }
 
-  return { planApproved: roundApproved, reviewExhausted, planFindings: roundFindings };
+  // Otherwise loop: the planner revises against this round's findings.
+  app.log("info", `record-plan-review: ${planKey} round ${round} — revise`, { approved: false });
+  return { planApproved: false, planFindings: roundFindings };
 };
 
 export default handler;

package/workers/record-results/worker.test.ts

@@ -0,0 +1,91 @@
+// Red/green for the no-work terminal guard (issue #86).
+//
+// `record-results` is the epic's finalizer. Before this guard it always marked the plan `done` and
+// completed the process GREEN — even when ZERO PRs were opened (empty plan, or every task
+// blocked/skipped). A no-op run was indistinguishable from success (instance 21). It now raises a
+// non-retryable `NO_WORK_DISPATCHED` BpmnError (→ incident) when the epic finalizes with no opened
+// PR, recording a `failed` terminal status + outcome first, so "accomplished nothing" surfaces
+// instead of masquerading as a completed epic.
+import { assertEquals, assertRejects } from "jsr:@std/assert@1";
+import { BpmnError } from "@nanobpm/urban";
+import handler from "./worker.ts";
+import type { PlanTaskStatus } from "../../app/plan.ts";
+
+interface Row {
+  id: number;
+  plan_key: string;
+  task_id: string;
+  status: PlanTaskStatus;
+}
+
+function fakeApp(rows: Row[]) {
+  const plans: Record<string, unknown>[] = [];
+  return {
+    data: {
+      table(name: string, key: string) {
+        if (name === "plans") {
+          return {
+            // deno-lint-ignore no-explicit-any
+            update: (k: any, patch: any) => {
+              plans.push({ [key]: k, ...patch });
+              return Promise.resolve(patch);
+            },
+          };
+        }
+        // plan_tasks
+        return {
+          // deno-lint-ignore no-explicit-any
+          find: (q: any) =>
+            Promise.resolve(
+              rows.filter((r) =>
+                Object.entries(q).every(([f, v]) =>
+                  (r as unknown as Record<string, unknown>)[f] === v
+                )
+              ),
+            ),
+        };
+      },
+    },
+    log: () => {},
+    _plans: plans,
+    // deno-lint-ignore no-explicit-any
+  } as any;
+}
+
+const call = async (app: unknown, planKey = "o/r#1") =>
+  // deno-lint-ignore no-explicit-any
+  await handler({ variables: { planKey } } as any, app as any);
+
+Deno.test("no opened PRs (empty plan) hard-fails with NO_WORK_DISPATCHED", async () => {
+  const app = fakeApp([]);
+  const err = await assertRejects(() => call(app), BpmnError);
+  assertEquals((err as BpmnError).errorCode, "NO_WORK_DISPATCHED");
+  // The failure outcome + terminal `failed` status must be recorded before throwing, so the DB
+  // state matches the parked incident and startPlan can re-plan it.
+  const plan = app._plans.at(-1) as Record<string, unknown>;
+  assertEquals(plan.status, "failed");
+  assertEquals(plan.outcome, "no work dispatched — the planner produced no tasks");
+});
+
+Deno.test("tasks present but none opened (all skipped/blocked) hard-fails", async () => {
+  const app = fakeApp([
+    { id: 1, plan_key: "o/r#1", task_id: "a", status: "skipped" },
+    { id: 2, plan_key: "o/r#1", task_id: "b", status: "blocked" },
+  ]);
+  const err = await assertRejects(() => call(app), BpmnError);
+  assertEquals((err as BpmnError).errorCode, "NO_WORK_DISPATCHED");
+  const plan = app._plans.at(-1) as Record<string, unknown>;
+  assertEquals(plan.status, "failed");
+  assertEquals(plan.outcome, "no work dispatched — every task was blocked or skipped");
+});
+
+Deno.test("at least one opened PR finalizes cleanly (no throw)", async () => {
+  const app = fakeApp([
+    { id: 1, plan_key: "o/r#1", task_id: "a", status: "opened" },
+    { id: 2, plan_key: "o/r#1", task_id: "b", status: "skipped" },
+  ]);
+  await call(app);
+  const plan = app._plans.at(-1) as Record<string, unknown>;
+  assertEquals(plan.status, "done");
+  assertEquals(plan.outcome, "1 PR(s) dispatched to convergence");
+});