@nanobpm/nano-workforce 0.30.0 → 0.31.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.31.0](https://github.com/nanobpm/nano-workforce/compare/v0.30.0...v0.31.0) (2026-08-09)
+
+
+### Bug Fixes
+
+* **retro:** record a blocked retro when the retro process fails to start ([#92](https://github.com/nanobpm/nano-workforce/issues/92)) ([22bf171](https://github.com/nanobpm/nano-workforce/commit/22bf17114160bcd269b26fe635afdcc44c249dbe)), closes [#84](https://github.com/nanobpm/nano-workforce/issues/84)
+* surface no-op plan-fanout epics as incidents instead of green ([#86](https://github.com/nanobpm/nano-workforce/issues/86)) ([#88](https://github.com/nanobpm/nano-workforce/issues/88)) ([8178aad](https://github.com/nanobpm/nano-workforce/commit/8178aad61fbf409990d331a4b08c786782d44cd1))
+
+
+### Features
+
+* **retro:** fold plan-review trace and task outcomes into the retro digest ([#91](https://github.com/nanobpm/nano-workforce/issues/91)) ([00d37e5](https://github.com/nanobpm/nano-workforce/commit/00d37e5a8c19238736d14b46401e7a3a41ee2083)), closes [#84](https://github.com/nanobpm/nano-workforce/issues/84) [#87](https://github.com/nanobpm/nano-workforce/issues/87) [#90](https://github.com/nanobpm/nano-workforce/issues/90)
+* surface plan_reviews audit trace on epic and home pages ([#89](https://github.com/nanobpm/nano-workforce/issues/89)) ([2abaa25](https://github.com/nanobpm/nano-workforce/commit/2abaa253ac5bdd4d31a7bee1a0de412e5df56aae)), closes [#87](https://github.com/nanobpm/nano-workforce/issues/87) [#87](https://github.com/nanobpm/nano-workforce/issues/87) [#87](https://github.com/nanobpm/nano-workforce/issues/87) [#87](https://github.com/nanobpm/nano-workforce/issues/87) [#87](https://github.com/nanobpm/nano-workforce/issues/87)
+
 # [0.30.0](https://github.com/nanobpm/nano-workforce/compare/v0.29.0...v0.30.0) (2026-08-09)
 
 

package/SPEC.md

@@ -420,7 +420,10 @@ Start(issue) → plan → record-plan → implement (parallel MI) → record-res
 - **`record-results`** — app worker `pr.record-results`. Zips `results` back onto
   `plan_tasks` by index, and for each opened `pr` calls the same idempotent
   `submitPr` as §4 — **the handoff**: every fleet-produced PR enrols into the
-  review-convergence loop. Sets `plans` status `done`.
+  review-convergence loop. On success it sets `plans` status `done`; if the epic
+  finalizes having opened **zero** PRs (empty plan, or every task blocked/skipped)
+  it raises a non-retryable `NO_WORK_DISPATCHED` incident instead of completing
+  green — a no-op run must not masquerade as success (issue #86).
 
 **Payloads are untyped** (no `nano:shapes`/`io.nanobpm.dataEnvelope`): the vocab is
 scalar-only and cannot express the `tasks`/`results` lists, so the workers self-type

package/app/plan.test.ts

@@ -53,8 +53,8 @@ Deno.test("valid positive integer → honoured", () => {
 //
 // `plan_reviews` is append-only and the review round is derived from `count(plan_reviews)`.
 // When `startPlan` re-plans a previously finished issue it must clear the prior review rows,
-// otherwise the stale count inflates the next round index and can trip `reviewExhausted` early,
-// bypassing the adversarial gate. This drives `startPlan` against an in-memory data layer and
+// otherwise the stale count inflates the next round index and can reach the review-round cap
+// early, bypassing the adversarial gate. This drives `startPlan` against an in-memory data layer and
 // asserts the `plan_reviews` rows for the plan key are gone after a re-plan.
 import { startPlan } from "./plan.ts";
 

package/app/plan.ts

@@ -150,8 +150,9 @@ export function positiveIntEnv(name: string, fallback: number): number {
   return Number.isInteger(n) && n > 0 ? n : fallback;
 }
 
-/** Max adversarial plan-review rounds before the fan-out proceeds regardless (so a reviewer that
- * never approves can't dead-lock the plan). The last round's findings are still recorded. */
+/** Max adversarial plan-review rounds. Reaching the cap WITHOUT approval is a hard failure: the
+ * fan-out raises a `PLAN_REJECTED` incident rather than dispatching an un-approved plan (issue
+ * #86). The last round's findings are still recorded. */
 export const MAX_PLAN_REVIEW_ROUNDS = positiveIntEnv("NANO_PLAN_REVIEW_ROUNDS", 3);
 
 /** A plan is "done" in exactly these states; everything else (planning, dispatched)
@@ -205,7 +206,7 @@ export async function startPlan(data: DataLayer, engine: EngineClient, parsed: P
     }
     // `plan_reviews` is append-only and the review round is derived from
     // `count(plan_reviews)`, so stale rows from the prior run would inflate the
-    // next round index and trip `reviewExhausted` early (bypassing the gate).
+    // next round index and reach the review-round cap early (bypassing the gate).
     // Clear them here — the table is keyed on `plan_key`, so one delete drops the
     // whole set (mirrors how record-plan clears `plan_task_deps`).
     await planReviews(data).delete(parsed.planKey);

package/app/retro.test.ts

@@ -97,6 +97,10 @@ function seedTask(stores: Record<string, any[]>, task: Record<string, unknown>)
 function seedPr(stores: Record<string, any[]>, pr_key: string, status: string) {
   (stores["pull_requests"] ??= []).push({ pr_key, status });
 }
+// deno-lint-ignore no-explicit-any
+function seedReview(stores: Record<string, any[]>, round: number, approved: number, findings: string | null) {
+  (stores["plan_reviews"] ??= []).push({ plan_key: PLAN, round, approved, findings, created_at: `t${round}`, job_key: null });
+}
 
 Deno.test("autoRetroEnabled: on by default; disabled by 0/false/off/no", () => {
   const prev = process.env.NANO_AUTO_RETRO;
@@ -177,10 +181,42 @@ Deno.test("gatherRetro: separates learnings from notes and folds in deltas", asy
   assertEquals(d.repo, "acme/widgets");
 });
 
+Deno.test("gatherRetro: folds in the plan-review trace and task-outcome shape", async () => {
+  const { data, stores } = memData();
+  seedPlan(stores);
+  seedTask(stores, { id: "t1", task_id: "t1", status: "opened", pr_key: "acme/widgets#10" });
+  seedTask(stores, { id: "t2", task_id: "t2", status: "skipped", pr_key: null });
+  seedTask(stores, { id: "t3", task_id: "t3", status: "opened", pr_key: "acme/widgets#11" });
+  // Two rejected rounds then an approval — out of order to prove the sort.
+  seedReview(stores, 1, 0, "still missing the migration ordering");
+  seedReview(stores, 0, 0, "task t2 depends on t3 but is sequenced first");
+  seedReview(stores, 2, 1, "");
+
+  const d = await gatherRetro(data, PLAN);
+  assertEquals(d.reviewRounds, 3);
+  assertEquals(d.planApproved, true);
+  assertEquals(d.reviewRejections.map((r) => r.round), [0, 1]);
+  assertEquals(d.reviewRejections[0].findings, "task t2 depends on t3 but is sequenced first");
+  assertEquals(d.taskOutcomes.total, 3);
+  assertEquals(d.taskOutcomes.byStatus, { opened: 2, skipped: 1 });
+});
+
+Deno.test("gatherRetro: no reviews → zero rounds, not approved, empty rejections", async () => {
+  const { data, stores } = memData();
+  seedPlan(stores);
+  const d = await gatherRetro(data, PLAN);
+  assertEquals(d.reviewRounds, 0);
+  assertEquals(d.planApproved, false);
+  assertEquals(d.reviewRejections, []);
+  assertEquals(d.taskOutcomes, { total: 0, byStatus: {} });
+});
+
 Deno.test("renderRetroBrief: renders learnings + constraints; states 'none' with no learnings", () => {
   const empty = renderRetroBrief({
     planKey: PLAN, repo: "acme/widgets", issueUrl: "", title: null,
     learnings: [], touchedFiles: [], contractChanges: [], constraints: [], notes: [],
+    reviewRounds: 0, reviewRejections: [], planApproved: false,
+    taskOutcomes: { total: 0, byStatus: {} },
     counts: { learnings: 0, deltas: 0, notes: 0 },
   });
   assertStringIncludes(empty, "none");
@@ -192,20 +228,31 @@ Deno.test("renderRetroBrief: renders learnings + constraints; states 'none' with
     contractChanges: [{ taskId: "t1", change: "shape" }],
     constraints: [{ taskId: "t1", constraint: "must X" }],
     notes: [{ author_task: "t2", kind: "note", body: "watch the release lane" }],
+    reviewRounds: 2,
+    reviewRejections: [{ round: 0, findings: "wrong dependency order" }],
+    planApproved: true,
+    taskOutcomes: { total: 2, byStatus: { opened: 1, skipped: 1 } },
     counts: { learnings: 1, deltas: 1, notes: 1 },
   });
   assertStringIncludes(brief, "regen first");
   assertStringIncludes(brief, "must X");
   assertStringIncludes(brief, "watch the release lane");
   assertStringIncludes(brief, "acme/widgets");
+  assertStringIncludes(brief, "Plan review");
+  assertStringIncludes(brief, "wrong dependency order");
+  assertStringIncludes(brief, "Task outcomes");
 });
 
-Deno.test("isDigestEmpty: true only when there are no learnings, deltas, or notes", () => {
-  const base = { planKey: PLAN, repo: "", issueUrl: "", title: null, learnings: [], touchedFiles: [], contractChanges: [], constraints: [], notes: [] };
+Deno.test("isDigestEmpty: empty only with no learnings/deltas/notes AND no review rejections", () => {
+  const base = { planKey: PLAN, repo: "", issueUrl: "", title: null, learnings: [], touchedFiles: [], contractChanges: [], constraints: [], notes: [], reviewRounds: 0, reviewRejections: [], planApproved: false, taskOutcomes: { total: 0, byStatus: {} } };
   assert(isDigestEmpty({ ...base, counts: { learnings: 0, deltas: 0, notes: 0 } }));
   assert(!isDigestEmpty({ ...base, counts: { learnings: 1, deltas: 0, notes: 0 } }));
   assert(!isDigestEmpty({ ...base, counts: { learnings: 0, deltas: 2, notes: 0 } }));
   assert(!isDigestEmpty({ ...base, counts: { learnings: 0, deltas: 0, notes: 1 } }));
+  // A rejected review round is reflection material even with no learnings/deltas/notes.
+  assert(!isDigestEmpty({ ...base, reviewRounds: 2, reviewRejections: [{ round: 0, findings: "bad seq" }], counts: { learnings: 0, deltas: 0, notes: 0 } }));
+  // ...but task-outcome shape alone (a cleanly-approved plan) is not.
+  assert(isDigestEmpty({ ...base, reviewRounds: 1, planApproved: true, taskOutcomes: { total: 3, byStatus: { opened: 3 } }, counts: { learnings: 0, deltas: 0, notes: 0 } }));
 });
 
 Deno.test("recordRetro: inserts then updates the same plan_key row in place", async () => {
@@ -278,6 +325,55 @@ Deno.test("maybeStartRetro: starts the retro exactly once when the last PR lands
   assertEquals(started.length, 1, "fire-once guard");
 });
 
+Deno.test("maybeStartRetro: a createInstance failure records a blocked retro (fire-once guard already consumed)", async () => {
+  const { data, stores } = memData();
+  seedPlan(stores);
+  seedTask(stores, { id: "t1", status: "opened", pr_key: "acme/widgets#10" });
+  seedPr(stores, "acme/widgets#10", "merged");
+  await appendEntry(data, PLAN, { author_task: "t1", kind: "learning", body: "regen first" });
+  // deno-lint-ignore no-explicit-any require-await
+  const engine = { async createInstance() { throw new Error("gateway down"); } } as any as EngineClient;
+
+  const r = await maybeStartRetro(data, engine, "acme/widgets#10");
+  assertEquals(r, { started: false, planKey: PLAN, reason: "start-failed" });
+  // The guard is consumed (stamp + claim), so it will never retry...
+  assert(stores["plans"][0].retro_started_at, "retro_started_at is stamped");
+  assertEquals(stores["plan_retro_starts"].length, 1);
+  // ...but the failure is now visible as a blocked retro rather than a silent gap.
+  assertEquals(stores["plan_retros"].length, 1);
+  assertEquals(stores["plan_retros"][0].status, "blocked");
+  assertEquals(stores["plan_retros"][0].pr_key, null);
+  assertStringIncludes(String(stores["plan_retros"][0].summary), "gateway down");
+});
+
+Deno.test("maybeStartRetro: a secondary blocked-retro persistence failure still returns start-failed (not error)", async () => {
+  const { data, stores } = memData();
+  seedPlan(stores);
+  seedTask(stores, { id: "t1", status: "opened", pr_key: "acme/widgets#10" });
+  seedPr(stores, "acme/widgets#10", "merged");
+  await appendEntry(data, PLAN, { author_task: "t1", kind: "learning", body: "regen first" });
+  // deno-lint-ignore no-explicit-any require-await
+  const engine = { async createInstance() { throw new Error("gateway down"); } } as any as EngineClient;
+  // recordRetro rethrows non-unique DB errors; simulate the blocked-retro insert hitting a
+  // FOREIGN KEY failure so the persistence in the createInstance-failure handler throws.
+  // deno-lint-ignore no-explicit-any
+  const failingData = {
+    // deno-lint-ignore no-explicit-any
+    table: (name: string, pk?: string) => {
+      const t = (data as any).table(name, pk);
+      if (name !== "plan_retros") return t;
+      return { ...t, insert: () => Promise.reject(new Error("FOREIGN KEY constraint failed")) };
+    },
+  } as any as DataLayer;
+
+  const r = await maybeStartRetro(failingData, engine, "acme/widgets#10");
+  // The secondary persistence failure must NOT be masked as `error` — the guard is still consumed,
+  // so the caller must see `start-failed`, and no phantom retro row is written.
+  assertEquals(r, { started: false, planKey: PLAN, reason: "start-failed" });
+  assert(stores["plans"][0].retro_started_at, "retro_started_at is stamped");
+  assertEquals(stores["plan_retros"].length, 0);
+});
+
 Deno.test("maybeStartRetro: a pre-claimed retro start does not start a duplicate process", async () => {
   const { data, stores } = memData();
   seedPlan(stores);
@@ -323,6 +419,23 @@ Deno.test("maybeStartRetro: complete but empty → records a skipped retro, does
   assertEquals(stores["plan_retros"][0].status, "skipped");
 });
 
+Deno.test("maybeStartRetro: a rejected review round alone is enough to fire the retro", async () => {
+  const { data, stores } = memData();
+  seedPlan(stores);
+  seedTask(stores, { id: "t1", status: "opened", pr_key: "acme/widgets#10" });
+  seedPr(stores, "acme/widgets#10", "merged");
+  // No learnings/deltas/notes — only the plan-review trace carries a rejection.
+  seedReview(stores, 0, 0, "task ordering is wrong");
+  seedReview(stores, 1, 1, "");
+  const { engine, started } = fakeEngine();
+
+  const r = await maybeStartRetro(data, engine, "acme/widgets#10");
+  assertEquals(r.started, true);
+  assertEquals(r.planKey, PLAN);
+  assertEquals(started.length, 1);
+  assert(stores["plans"][0].retro_started_at, "retro_started_at must be stamped");
+});
+
 Deno.test("maybeStartRetro: a PR not part of any plan is a no-op", async () => {
   const { data } = memData();
   const { engine, started } = fakeEngine();

package/app/retro.ts

@@ -14,7 +14,7 @@
 // Data access goes through the record gateway (`data.table`), never hand-written SQL — matching
 // app/plan.ts, app/blackboard.ts, and app/taskDelta.ts.
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
-import { planTasks } from "./plan.ts";
+import { planReviews, planTasks } from "./plan.ts";
 import { isUniqueViolation, readBlackboard } from "./blackboard.ts";
 import { aggregateEpicDeltas } from "./taskDelta.ts";
 import { TERMINAL_STATUSES } from "./service.ts";
@@ -92,12 +92,24 @@ export interface RetroDigest {
   contractChanges: { taskId: string; change: string }[];
   constraints: { taskId: string; constraint: string }[];
   notes: { author_task: string; kind: string; body: string }[];
+  // Plan-review trace (006_plan_review.sql): how many adversarial review rounds the plan needed
+  // before fan-out, and the critique from every rejected round — the "what was wrong with the
+  // first cut of the decomposition" signal, which is prime retro material even when implementers
+  // posted no learnings of their own. `planApproved` reflects the final round's verdict.
+  reviewRounds: number;
+  reviewRejections: { round: number; findings: string }[];
+  planApproved: boolean;
+  // Execution shape: how the plan's tasks actually resolved (opened a PR, were skipped/blocked,
+  // etc.). Lets the retro reason over decomposition accuracy — e.g. a high skipped/blocked ratio
+  // hints the plan over-decomposed.
+  taskOutcomes: { total: number; byStatus: Record<string, number> };
   counts: { learnings: number; deltas: number; notes: number };
 }
 
 /** Gather a plan's reflection material: the `learning` blackboard entries (the headline), plus the
- * task-delta rollup (contract changes, discovered constraints, cross-slice file touches) and any
- * other non-learning blackboard notes for colour. Reads only — no writes. */
+ * task-delta rollup (contract changes, discovered constraints, cross-slice file touches), the
+ * plan-review trace (rounds + rejection findings), the task-outcome shape, and any other
+ * non-learning blackboard notes for colour. Reads only — no writes. */
 export async function gatherRetro(data: DataLayer, planKey: string): Promise<RetroDigest> {
   const plan = await plansTbl(data).get(planKey);
   const entries = await readBlackboard(data, planKey);
@@ -108,6 +120,22 @@ export async function gatherRetro(data: DataLayer, planKey: string): Promise<Ret
     .filter((e) => e.kind !== "learning")
     .map((e) => ({ author_task: e.author_task, kind: e.kind, body: e.body }));
   const deltas = await aggregateEpicDeltas(data, planKey);
+
+  // Plan-review trace, ordered by round. A rejected round is `approved === 0`; only rounds that
+  // carry findings are worth quoting (an empty rejection has nothing to teach).
+  const reviews = (await planReviews(data).find({ plan_key: planKey }))
+    .slice()
+    .sort((a, b) => a.round - b.round);
+  const reviewRejections = reviews
+    .filter((r) => r.approved === 0 && (r.findings ?? "").trim() !== "")
+    .map((r) => ({ round: r.round, findings: r.findings as string }));
+  const planApproved = reviews.length > 0 && reviews[reviews.length - 1].approved === 1;
+
+  // Task-outcome shape (counts by final status).
+  const tasks = await planTasks(data).find({ plan_key: planKey });
+  const byStatus: Record<string, number> = {};
+  for (const t of tasks) byStatus[t.status] = (byStatus[t.status] ?? 0) + 1;
+
   return {
     planKey,
     repo: plan?.repo ?? planKey.split("#")[0] ?? "",
@@ -118,6 +146,10 @@ export async function gatherRetro(data: DataLayer, planKey: string): Promise<Ret
     contractChanges: deltas.contractChanges,
     constraints: deltas.constraints,
     notes,
+    reviewRounds: reviews.length,
+    reviewRejections,
+    planApproved,
+    taskOutcomes: { total: tasks.length, byStatus },
     counts: {
       learnings: learnings.length,
       deltas: deltas.deltas.length,
@@ -139,8 +171,29 @@ export function renderRetroBrief(d: RetroDigest): string {
     `Target repo: **${d.repo}**${d.issueUrl ? ` · issue: ${d.issueUrl}` : ""}`,
     d.title ? `Epic: ${d.title}` : "",
     "",
-    `### Learnings agents posted while implementing (${d.learnings.length})`,
+    `### Plan review — ${d.reviewRounds} round(s), ${d.planApproved ? "approved" : "not approved"}`,
   ];
+  if (d.reviewRejections.length === 0) {
+    lines.push(
+      d.reviewRounds === 0
+        ? "_(no review rounds recorded)_"
+        : "_(approved with no recorded rejections)_",
+    );
+  } else {
+    lines.push(`The plan was revised after ${d.reviewRejections.length} rejected round(s):`);
+    for (const r of d.reviewRejections) lines.push(`- **round ${r.round}**: ${r.findings}`);
+  }
+  if (d.taskOutcomes.total > 0) {
+    const shape = Object.entries(d.taskOutcomes.byStatus)
+      .sort((a, b) => a[0].localeCompare(b[0]))
+      .map(([s, n]) => `${s}: ${n}`)
+      .join(", ");
+    lines.push("", `### Task outcomes (${d.taskOutcomes.total} task(s))`, shape);
+  }
+  lines.push(
+    "",
+    `### Learnings agents posted while implementing (${d.learnings.length})`,
+  );
   if (d.learnings.length === 0) {
     lines.push("_(none — agents posted no `learning` entries for this epic)_");
   } else {
@@ -164,9 +217,14 @@ export function renderRetroBrief(d: RetroDigest): string {
   return lines.join("\n");
 }
 
-/** True when a digest carries nothing worth an agent run — no learnings, no deltas, no notes. */
+/** True when a digest carries nothing worth an agent run. A plan is worth retrospecting when
+ * implementers shared material (learnings/deltas/notes) OR the plan itself needed revision — a
+ * rejected review round's findings are reflection material in their own right, even when no
+ * learning was posted. (Task-outcome shape alone is NOT: a cleanly-approved plan whose tasks all
+ * ran has nothing to teach.) */
 export function isDigestEmpty(d: RetroDigest): boolean {
-  return d.counts.learnings === 0 && d.counts.deltas === 0 && d.counts.notes === 0;
+  return d.counts.learnings === 0 && d.counts.deltas === 0 && d.counts.notes === 0 &&
+    d.reviewRejections.length === 0;
 }
 
 /** The persisted retro shape (written by pr.retro-record). */
@@ -264,14 +322,40 @@ export async function maybeStartRetro(
     // Stamp before starting so restarts/retries can take the cheap already-started path.
     await plansTbl(data).update(planKey, { retro_started_at: now(), updated_at: now() });
 
-    const { processInstanceKey } = await engine.createInstance({
-      processDefinitionId: RETRO_PROCESS_ID,
-      variables: {
-        planKey,
-        repo: digest.repo,
-        issueUrl: digest.issueUrl,
-      },
-    });
+    let processInstanceKey: string | number | undefined;
+    try {
+      ({ processInstanceKey } = await engine.createInstance({
+        processDefinitionId: RETRO_PROCESS_ID,
+        variables: {
+          planKey,
+          repo: digest.repo,
+          issueUrl: digest.issueUrl,
+        },
+      }));
+    } catch (err) {
+      // The fire-once guard is already consumed (retro_started_at stamped, plan_retro_starts
+      // claimed), so this plan will never re-enter the start path. If we returned here with no
+      // record, the epic surface would show a plan that "started a retro" with nothing to show and
+      // no way to retry. Persist a `blocked` retro instead so the failure stays visible and the
+      // system state is consistent. Recording must not mask the original error in the log.
+      log?.("error", `retro: could not start process for epic ${planKey}`, { err: String(err) });
+      // Persisting the blocked record is best-effort: recordRetro rethrows non-unique DB errors, and
+      // if that escaped here it would fall through to the outer catch and return `error` instead of
+      // `start-failed` — reintroducing the very silent-gap failure this path guards against (guard
+      // consumed, no durable record). Swallow a secondary persistence failure and log it separately
+      // so the createInstance failure path always reports `start-failed`.
+      try {
+        await recordRetro(data, planKey, {
+          status: "blocked",
+          summary: `Retro process could not be started: ${String(err)}`,
+        });
+      } catch (persistErr) {
+        log?.("error", `retro: could not persist blocked retro for epic ${planKey}`, {
+          err: String(persistErr),
+        });
+      }
+      return { started: false, planKey, reason: "start-failed" };
+    }
     log?.("info", `retro: started for epic ${planKey}`, { processInstanceKey, learnings: digest.counts.learnings });
     return { started: true, planKey };
   } catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.30.0",
+  "version": "0.31.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/pages/epic.page.json

@@ -23,7 +23,7 @@
       "type": "text",
       "id": "subtitle",
       "props": {
-        "text": "Read-only observability over each plan's wave state, merge-exclusion graph, coordination notes, and trial-merge gate results.",
+        "text": "Read-only observability over each plan's review trace, wave state, merge-exclusion graph, coordination notes, and trial-merge gate results.",
         "variant": "sub"
       }
     },
@@ -70,6 +70,27 @@
         }
       }
     },
+    {
+      "type": "dataGrid",
+      "id": "plan-reviews",
+      "props": {
+        "title": "Plan review trace",
+        "refreshMs": 5000,
+        "data": {
+          "kind": "datasource",
+          "source": "app",
+          "table": "plan_reviews",
+          "orderBy": { "field": "round", "dir": "asc" }
+        },
+        "columns": [
+          { "field": "plan_key", "header": "Plan" },
+          { "field": "round", "header": "Round" },
+          { "field": "approved", "header": "Approved? (1/0)" },
+          { "field": "findings", "header": "Reviewer findings" },
+          { "field": "created_at", "header": "Recorded" }
+        ]
+      }
+    },
     {
       "type": "dataGrid",
       "id": "wave-state",

package/pages/home.page.json

@@ -228,6 +228,20 @@
                 { "field": "summary", "header": "Summary" }
               ]
             },
+            {
+              "title": "Plan reviews",
+              "source": "app",
+              "table": "plan_reviews",
+              "parentField": "plan_key",
+              "childField": "plan_key",
+              "orderBy": { "field": "round", "dir": "asc" },
+              "columns": [
+                { "field": "round", "header": "Round" },
+                { "field": "approved", "header": "Approved? (1/0)" },
+                { "field": "findings", "header": "Reviewer findings" },
+                { "field": "created_at", "header": "Recorded" }
+              ]
+            },
             {
               "title": "Escalations",
               "source": "app",

package/resources/processes/plan-fanout.bpmn

@@ -216,7 +216,7 @@
     <bpmn:sequenceFlow id="f_toRecordPlanReview" sourceRef="review-plan" targetRef="record-plan-review" />
     <bpmn:sequenceFlow id="f_toGwPlanReview" sourceRef="record-plan-review" targetRef="gw-plan-review" />
     <bpmn:sequenceFlow id="f_plan_proceed" name="approved" sourceRef="gw-plan-review" targetRef="select-wave">
-      <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=planApproved or reviewExhausted</bpmn:conditionExpression>
+      <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=planApproved</bpmn:conditionExpression>
     </bpmn:sequenceFlow>
     <bpmn:sequenceFlow id="f_plan_revise" name="revise" sourceRef="gw-plan-review" targetRef="plan" />
     <bpmn:sequenceFlow id="f_toImplement" sourceRef="select-wave" targetRef="implement" />

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/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");
+});

package/workers/record-results/worker.ts

@@ -2,8 +2,15 @@
 //
 // PR enrollment now happens per wave in `pr.record-wave` (so later waves can declare earlier
 // waves' PRs as dependencies), leaving this worker as the terminal finalizer: it summarizes the
-// plan from `plan_tasks` and marks it `done`. It reads no `results` — every task's outcome was
-// already recorded by `record-wave` (opened / blocked) or `select-wave` (skipped).
+// plan from `plan_tasks`. It reads no `results` — every task's outcome was already recorded by
+// `record-wave` (opened / blocked) or `select-wave` (skipped).
+//
+// Two terminal outcomes:
+//   • at least one PR opened → mark the plan `done` (dispatched to convergence).
+//   • zero PRs opened → record a `failed` outcome for observability, then throw the non-retryable
+//     `NO_WORK_DISPATCHED` BpmnError so the engine parks the instance on an incident instead of
+//     completing green (issue #86). The `failed` status is terminal, so `startPlan` can re-plan it.
+import { BpmnError } from "@nanobpm/urban";
 import type { AppJobHandler } from "@nanobpm/urban";
 import { planTasks } from "../../app/plan.ts";
 
@@ -18,11 +25,34 @@ const handler: AppJobHandler<In> = async (job, app) => {
   const rows = await planTasks(app.data).find({ plan_key: planKey });
   const opened = rows.filter((r) => r.status === "opened").length;
 
-  const patch: Record<string, unknown> = { status: "done", updated_at: ts };
-  // When the planner emitted no tasks, `record-plan` already set a meaningful outcome (its
-  // note) and moved the plan to `done`. Preserve it rather than overwriting with "0 PR(s)…".
-  if (rows.length > 0) patch.outcome = `${opened} PR(s) dispatched to convergence`;
-  await app.data.table("plans", "plan_key").update(planKey, patch);
+  // Categorical no-work guard (issue #86): the epic reached its finalizer having opened ZERO PRs —
+  // an empty plan (e.g. the planner agent could not persist its result), or every task
+  // blocked/skipped. It accomplished nothing, so it must NOT complete green and masquerade as
+  // success. Record a `failed` terminal outcome for observability (so the DB state matches the
+  // parked incident and `startPlan` can re-plan it — `dispatched`/`done` would otherwise block a
+  // restart), then raise a non-retryable BpmnError so the engine parks the instance on an incident
+  // (no boundary catches `NO_WORK_DISPATCHED`) instead of completing the process. This backstops
+  // any zero-work path regardless of the review outcome.
+  if (opened === 0) {
+    const outcome = rows.length === 0
+      ? "no work dispatched — the planner produced no tasks"
+      : "no work dispatched — every task was blocked or skipped";
+    await app.data.table("plans", "plan_key").update(planKey, {
+      status: "failed",
+      outcome,
+      updated_at: ts,
+    });
+    app.log("error", `record-results: ${planKey} finalized with 0 opened PRs`, {
+      taskCount: rows.length,
+    });
+    throw new BpmnError("NO_WORK_DISPATCHED", `${planKey}: ${outcome}`);
+  }
+
+  await app.data.table("plans", "plan_key").update(planKey, {
+    status: "done",
+    outcome: `${opened} PR(s) dispatched to convergence`,
+    updated_at: ts,
+  });
 
   return {};
 };