@nanobpm/nano-workforce 0.29.0 → 0.31.0

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+# [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)
+
+
+### Features
+
+* **retro:** epic retrospective workflow that promotes shared learnings ([#84](https://github.com/nanobpm/nano-workforce/issues/84)) ([306e46f](https://github.com/nanobpm/nano-workforce/commit/306e46ff333bc5baff199713bf3a71f0c294e897)), closes [#82](https://github.com/nanobpm/nano-workforce/issues/82)
+
 # [0.29.0](https://github.com/nanobpm/nano-workforce/compare/v0.28.0...v0.29.0) (2026-08-08)
 
 

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/blackboard.test.ts

@@ -5,6 +5,7 @@ import {
   appendEntry,
   blackboardUrl,
   detectFileClaimConflicts,
+  isUniqueViolation,
   mintBlackboardToken,
   normalizeKind,
   planKeyForToken,
@@ -297,3 +298,19 @@ Deno.test("detectFileClaimConflicts: beforeId restricts to strictly prior claims
   assertEquals(conflicts[0].author_task, "gap-2");
   assert(Number(later.id) > Number(mine.id));
 });
+
+Deno.test("isUniqueViolation: true for UNIQUE/PK, false for FOREIGN KEY and unrelated errors", () => {
+  // Extended SQLite codes.
+  assert(isUniqueViolation(Object.assign(new Error("x"), { code: "SQLITE_CONSTRAINT_UNIQUE" })));
+  assert(isUniqueViolation(Object.assign(new Error("x"), { code: "SQLITE_CONSTRAINT_PRIMARYKEY" })));
+  // Message-only (driver surfaced no code).
+  assert(isUniqueViolation(new Error("UNIQUE constraint failed: plan_retros.plan_key")));
+  assert(isUniqueViolation(new Error("PRIMARY KEY constraint failed")));
+  // The bug this guards: a bare "constraint" match would swallow an FK failure.
+  assert(!isUniqueViolation(new Error("FOREIGN KEY constraint failed")));
+  assert(!isUniqueViolation(Object.assign(new Error("fk"), { code: "SQLITE_CONSTRAINT_FOREIGNKEY" })));
+  // Unrelated / non-errors.
+  assert(!isUniqueViolation(new Error("network down")));
+  assert(!isUniqueViolation(null));
+  assert(!isUniqueViolation("nope"));
+});

package/app/blackboard.ts

@@ -307,11 +307,15 @@ export async function appendEntry(
   }
 }
 
-/** True when an error is a SQLite UNIQUE-constraint violation (however the driver surfaces it). */
-function isUniqueViolation(err: unknown): boolean {
+/** True only for a UNIQUE / PRIMARY-KEY / duplicate violation — never a foreign-key or other
+ * constraint failure. We match the *specific* violation (extended SQLite codes, or the specific
+ * words) rather than the bare word "constraint", so a `FOREIGN KEY constraint failed` (real data
+ * corruption, not a benign duplicate) is always rethrown rather than silently swallowed. */
+export function isUniqueViolation(err: unknown): boolean {
   if (!err || typeof err !== "object") return false;
   const code = (err as { code?: unknown }).code;
-  if (code === "SQLITE_CONSTRAINT_UNIQUE" || code === "SQLITE_CONSTRAINT") return true;
+  if (code === "SQLITE_CONSTRAINT_UNIQUE" || code === "SQLITE_CONSTRAINT_PRIMARYKEY") return true;
   const message = (err as { message?: unknown }).message;
-  return typeof message === "string" && /UNIQUE constraint failed/i.test(message);
+  return typeof message === "string" &&
+    /(unique|primary key) constraint failed|duplicate/i.test(message);
 }

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

@@ -0,0 +1,466 @@
+// Unit tests for the epic retrospective stage (app/retro.ts, 016_plan_retro.sql).
+import { assert, assertEquals, assertStringIncludes } from "jsr:@std/assert@1";
+import type { DataLayer, EngineClient } from "@nanobpm/urban";
+import { appendEntry } from "./blackboard.ts";
+import { recordTaskDelta } from "./taskDelta.ts";
+import {
+  autoRetroEnabled,
+  gatherRetro,
+  isDigestEmpty,
+  isPlanComplete,
+  maybeStartRetro,
+  planKeyForPr,
+  recordRetro,
+  renderRetroBrief,
+} from "./retro.ts";
+
+// In-memory record gateway matching the Table<T> subset retro.ts uses: insert/find/findOne/get/update.
+// deno-lint-ignore no-explicit-any
+function memData(): { data: DataLayer; stores: Record<string, any[]> } {
+  // deno-lint-ignore no-explicit-any
+  const stores: Record<string, any[]> = {};
+  const seq: Record<string, number> = {};
+  function tbl(name: string, pk = "id") {
+    // deno-lint-ignore no-explicit-any
+    const rows = (stores[name] ??= [] as any[]);
+    // deno-lint-ignore no-explicit-any
+    const match = (r: any, where: any) => Object.entries(where).every(([k, v]) => r[k] === v);
+    return {
+      // deno-lint-ignore no-explicit-any require-await
+      async insert(row: any) {
+        if (pk !== "id" && rows.some((r) => r[pk] === row[pk])) {
+          throw new Error(`UNIQUE constraint failed: ${name}.${pk}`);
+        }
+        const id = (seq[name] = (seq[name] ?? 0) + 1);
+        rows.push(pk === "id" ? { id, ...row } : { ...row });
+        return pk === "id" ? id : row[pk];
+      },
+      // deno-lint-ignore no-explicit-any require-await
+      async find(where: any = {}) {
+        return rows.filter((r) => match(r, where));
+      },
+      // deno-lint-ignore no-explicit-any require-await
+      async findOne(where: any = {}) {
+        return rows.find((r) => match(r, where));
+      },
+      // deno-lint-ignore no-explicit-any require-await
+      async get(id: any) {
+        return rows.find((row) => row[pk] === id);
+      },
+      // deno-lint-ignore no-explicit-any require-await
+      async update(id: any, patch: any) {
+        const r = rows.find((row) => row[pk] === id);
+        if (r) Object.assign(r, patch);
+      },
+    };
+  }
+  // deno-lint-ignore no-explicit-any
+  const data = { table: (n: string, pk?: string) => tbl(n, pk) } as any as DataLayer;
+  return { data, stores };
+}
+
+// A fake engine recording createInstance calls.
+function fakeEngine(): { engine: EngineClient; started: { processDefinitionId: string; variables: Record<string, unknown> }[] } {
+  const started: { processDefinitionId: string; variables: Record<string, unknown> }[] = [];
+  // deno-lint-ignore no-explicit-any
+  const engine = {
+    // deno-lint-ignore no-explicit-any require-await
+    async createInstance(req: any) {
+      started.push({ processDefinitionId: req.processDefinitionId, variables: req.variables });
+      return { processInstanceKey: `PI-${started.length}` };
+    },
+    // deno-lint-ignore no-explicit-any require-await
+  } as any as EngineClient;
+  return { engine, started };
+}
+
+const PLAN = "acme/widgets#7";
+
+// deno-lint-ignore no-explicit-any
+function seedPlan(stores: Record<string, any[]>, over: Record<string, unknown> = {}) {
+  stores["plans"] = [{
+    plan_key: PLAN,
+    repo: "acme/widgets",
+    issue_url: "https://github.com/acme/widgets/issues/7",
+    title: "Widgets epic",
+    status: "done",
+    retro_started_at: null,
+    ...over,
+  }];
+}
+
+// deno-lint-ignore no-explicit-any
+function seedTask(stores: Record<string, any[]>, task: Record<string, unknown>) {
+  (stores["plan_tasks"] ??= []).push({ plan_key: PLAN, ...task });
+}
+// deno-lint-ignore no-explicit-any
+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;
+  try {
+    delete process.env.NANO_AUTO_RETRO;
+    assert(autoRetroEnabled());
+    for (const v of ["0", "false", "off", "no", "FALSE"]) {
+      process.env.NANO_AUTO_RETRO = v;
+      assertEquals(autoRetroEnabled(), false, `"${v}" should disable`);
+    }
+    process.env.NANO_AUTO_RETRO = "1";
+    assert(autoRetroEnabled());
+  } finally {
+    if (prev == null) delete process.env.NANO_AUTO_RETRO;
+    else process.env.NANO_AUTO_RETRO = prev;
+  }
+});
+
+Deno.test("planKeyForPr: resolves the plan a PR's task belongs to; undefined when unlinked", async () => {
+  const { data, stores } = memData();
+  seedTask(stores, { id: "t1", status: "opened", pr_key: "acme/widgets#10" });
+  assertEquals(await planKeyForPr(data, "acme/widgets#10"), PLAN);
+  assertEquals(await planKeyForPr(data, "acme/widgets#99"), undefined);
+  assertEquals(await planKeyForPr(data, ""), undefined);
+});
+
+Deno.test("isPlanComplete: false while any task is still in flight", async () => {
+  const { data, stores } = memData();
+  seedTask(stores, { id: "t1", status: "opened", pr_key: "acme/widgets#10" });
+  seedTask(stores, { id: "t2", status: "pending", pr_key: null });
+  seedPr(stores, "acme/widgets#10", "merged");
+  // t2 is pending with no PR → not done.
+  assertEquals(await isPlanComplete(data, PLAN), false);
+});
+
+Deno.test("isPlanComplete: false when an opened task's PR is not yet terminal", async () => {
+  const { data, stores } = memData();
+  seedTask(stores, { id: "t1", status: "opened", pr_key: "acme/widgets#10" });
+  seedPr(stores, "acme/widgets#10", "waiting_deps"); // in the merge stage, not terminal
+  assertEquals(await isPlanComplete(data, PLAN), false);
+});
+
+Deno.test("isPlanComplete: true when every task is settled (terminal PR or skipped/blocked)", async () => {
+  const { data, stores } = memData();
+  seedTask(stores, { id: "t1", status: "opened", pr_key: "acme/widgets#10" });
+  seedTask(stores, { id: "t2", status: "skipped", pr_key: null });
+  seedTask(stores, { id: "t3", status: "opened", pr_key: "acme/widgets#11" });
+  seedPr(stores, "acme/widgets#10", "merged");
+  seedPr(stores, "acme/widgets#11", "converged");
+  assertEquals(await isPlanComplete(data, PLAN), true);
+});
+
+Deno.test("isPlanComplete: an empty plan has nothing to retrospect", async () => {
+  const { data } = memData();
+  assertEquals(await isPlanComplete(data, PLAN), false);
+});
+
+Deno.test("gatherRetro: separates learnings from notes and folds in deltas", async () => {
+  const { data, stores } = memData();
+  seedPlan(stores);
+  await appendEntry(data, PLAN, { author_task: "t1", kind: "learning", body: "regen the API surface before building" });
+  await appendEntry(data, PLAN, { author_task: "t2", kind: "learning", body: "use nextest not cargo test" });
+  await appendEntry(data, PLAN, { author_task: "t3", kind: "note", body: "just an FYI" });
+  await recordTaskDelta(data, PLAN, "t1", {
+    contractChange: "changed the envelope shape",
+    newlyTouches: ["shared/env.ts"],
+    affectsTasks: ["t2"],
+    constraint: "envelope must carry results[]",
+  });
+
+  const d = await gatherRetro(data, PLAN);
+  assertEquals(d.counts.learnings, 2);
+  assertEquals(d.learnings.map((l) => l.author_task).sort(), ["t1", "t2"]);
+  assertEquals(d.notes.length, 1);
+  assertEquals(d.constraints.length, 1);
+  assertEquals(d.contractChanges.length, 1);
+  assert(d.touchedFiles.includes("shared/env.ts"));
+  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");
+
+  const brief = renderRetroBrief({
+    planKey: PLAN, repo: "acme/widgets", issueUrl: "https://x/7", title: "Epic",
+    learnings: [{ author_task: "t1", body: "regen first", created_at: "now" }],
+    touchedFiles: ["a.ts"],
+    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: 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 () => {
+  const { data, stores } = memData();
+  await recordRetro(data, PLAN, { status: "filed", prKey: "acme/widgets#20", learnings: 3, summary: "promoted 2" });
+  assertEquals(stores["plan_retros"].length, 1);
+  assertEquals(stores["plan_retros"][0].status, "filed");
+  assertEquals(stores["plan_retros"][0].pr_key, "acme/widgets#20");
+
+  await recordRetro(data, PLAN, { status: "skipped", summary: "nothing to promote" });
+  assertEquals(stores["plan_retros"].length, 1, "same plan_key must not duplicate");
+  assertEquals(stores["plan_retros"][0].status, "skipped");
+  assertEquals(stores["plan_retros"][0].pr_key, null);
+});
+
+Deno.test("recordRetro: rethrows a non-unique (FOREIGN KEY) constraint error instead of swallowing it", async () => {
+  // A FK failure (e.g. plan_key missing in plans) must NOT be treated as a benign duplicate and
+  // fall through to a silent update — that would make the write look successful while doing nothing.
+  let updated = false;
+  const table = {
+    // deno-lint-ignore require-await
+    async insert() {
+      throw new Error("FOREIGN KEY constraint failed");
+    },
+    // deno-lint-ignore require-await
+    async update() {
+      updated = true;
+    },
+    // deno-lint-ignore require-await
+    async get() {
+      return undefined;
+    },
+  };
+  // deno-lint-ignore no-explicit-any
+  const data = { table: () => table } as any as DataLayer;
+  let threw = false;
+  try {
+    await recordRetro(data, PLAN, { status: "filed", prKey: "acme/widgets#20" });
+  } catch (err) {
+    threw = true;
+    assertStringIncludes(String(err), "FOREIGN KEY");
+  }
+  assert(threw, "the FK error must propagate");
+  assertEquals(updated, false, "must not silently fall back to update on a non-unique error");
+});
+
+Deno.test("maybeStartRetro: starts the retro exactly once when the last PR lands with material", async () => {
+  const { data, stores } = memData();
+  seedPlan(stores);
+  seedTask(stores, { id: "t1", status: "opened", pr_key: "acme/widgets#10" });
+  seedTask(stores, { id: "t2", status: "opened", pr_key: "acme/widgets#11" });
+  seedPr(stores, "acme/widgets#10", "merged");
+  seedPr(stores, "acme/widgets#11", "merged");
+  await appendEntry(data, PLAN, { author_task: "t1", kind: "learning", body: "regen first" });
+  const { engine, started } = fakeEngine();
+
+  const r1 = await maybeStartRetro(data, engine, "acme/widgets#11");
+  assertEquals(r1.started, true);
+  assertEquals(r1.planKey, PLAN);
+  assertEquals(started.length, 1);
+  assertEquals(started[0].processDefinitionId, "retro");
+  assertEquals(started[0].variables.planKey, PLAN);
+  assert(stores["plans"][0].retro_started_at, "retro_started_at must be stamped");
+  assertEquals(stores["plan_retro_starts"].length, 1);
+
+  // A sibling terminal PR of the same plan must NOT start a second retro.
+  const r2 = await maybeStartRetro(data, engine, "acme/widgets#10");
+  assertEquals(r2.started, false);
+  assertEquals(r2.reason, "already-started");
+  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);
+  seedTask(stores, { id: "t1", status: "opened", pr_key: "acme/widgets#10" });
+  seedPr(stores, "acme/widgets#10", "merged");
+  stores["plan_retro_starts"] = [{ plan_key: PLAN, started_at: "already" }];
+  await appendEntry(data, PLAN, { author_task: "t1", kind: "learning", body: "regen first" });
+  const { engine, started } = fakeEngine();
+
+  const r = await maybeStartRetro(data, engine, "acme/widgets#10");
+  assertEquals(r, { started: false, planKey: PLAN, reason: "already-started" });
+  assertEquals(started.length, 0);
+  assertEquals(stores["plans"][0].retro_started_at, null);
+});
+
+Deno.test("maybeStartRetro: bails while the plan is incomplete", async () => {
+  const { data, stores } = memData();
+  seedPlan(stores);
+  seedTask(stores, { id: "t1", status: "opened", pr_key: "acme/widgets#10" });
+  seedTask(stores, { id: "t2", status: "pending", pr_key: null });
+  seedPr(stores, "acme/widgets#10", "merged");
+  const { engine, started } = fakeEngine();
+
+  const r = await maybeStartRetro(data, engine, "acme/widgets#10");
+  assertEquals(r.started, false);
+  assertEquals(r.reason, "incomplete");
+  assertEquals(started.length, 0);
+  assertEquals(stores["plans"][0].retro_started_at, null, "must not stamp an incomplete plan");
+});
+
+Deno.test("maybeStartRetro: complete but empty → records a skipped retro, does not start the process", async () => {
+  const { data, stores } = memData();
+  seedPlan(stores);
+  seedTask(stores, { id: "t1", status: "opened", pr_key: "acme/widgets#10" });
+  seedPr(stores, "acme/widgets#10", "merged");
+  const { engine, started } = fakeEngine();
+
+  const r = await maybeStartRetro(data, engine, "acme/widgets#10");
+  assertEquals(r.started, false);
+  assertEquals(r.reason, "nothing-to-retro");
+  assertEquals(started.length, 0);
+  assert(stores["plans"][0].retro_started_at, "stamped so we don't re-check forever");
+  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();
+  const r = await maybeStartRetro(data, engine, "acme/widgets#99");
+  assertEquals(r.started, false);
+  assertEquals(r.reason, "no-plan");
+  assertEquals(started.length, 0);
+});
+
+Deno.test("maybeStartRetro: honours NANO_AUTO_RETRO=0", async () => {
+  const prev = process.env.NANO_AUTO_RETRO;
+  process.env.NANO_AUTO_RETRO = "0";
+  try {
+    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: "x" });
+    const { engine, started } = fakeEngine();
+    const r = await maybeStartRetro(data, engine, "acme/widgets#10");
+    assertEquals(r.started, false);
+    assertEquals(r.reason, "disabled");
+    assertEquals(started.length, 0);
+  } finally {
+    if (prev == null) delete process.env.NANO_AUTO_RETRO;
+    else process.env.NANO_AUTO_RETRO = prev;
+  }
+});