@nanobpm/nano-workforce 0.29.0 → 0.30.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [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/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/retro.test.ts

@@ -0,0 +1,353 @@
+// 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.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("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: [],
+    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" }],
+    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");
+});
+
+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: [] };
+  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 } }));
+});
+
+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 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 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;
+  }
+});

package/app/retro.ts

@@ -0,0 +1,281 @@
+// Epic retrospective — the post-completion reflection stage (016_plan_retro.sql).
+//
+// The blackboard's `learning` kind (app/blackboard.ts) lets implementer agents share reusable
+// gotchas *while they work*. This module closes the loop: when an epic finishes, a retro agent
+// distils those learnings (plus task deltas and escalations) and promotes the recurring ones into
+// the target repo's AGENTS.md / a script / a CI step, via a human-reviewed PR.
+//
+// "Epic finished" is emergent, not a single BPMN node: `plan-fanout` only DISPATCHES the fleet
+// (it marks the plan `done` at dispatch time), after which each PR lands asynchronously on its own
+// `merge-loop`. So the true completion signal is *the last of a plan's PRs reaching a terminal
+// state*. `maybeStartRetro` is called from the two terminal points — `pr.mark-merged` (auto-merge)
+// and `pr.finalize`'s review-only `converged` path — and fires the retro exactly once.
+//
+// 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 { isUniqueViolation, readBlackboard } from "./blackboard.ts";
+import { aggregateEpicDeltas } from "./taskDelta.ts";
+import { TERMINAL_STATUSES } from "./service.ts";
+
+export const RETRO_PROCESS_ID = "retro";
+
+/** Opt-out env toggle. Retro runs by default; set NANO_AUTO_RETRO=0/false to disable (e.g. in a
+ * review-only deployment that doesn't want the fleet opening promotion PRs). */
+export function autoRetroEnabled(): boolean {
+  const v = (globalThis as { process?: { env?: Record<string, string | undefined> } })
+    .process?.env?.NANO_AUTO_RETRO;
+  if (v == null) return true;
+  const s = v.trim().toLowerCase();
+  return s !== "0" && s !== "false" && s !== "off" && s !== "no";
+}
+
+const now = () => new Date().toISOString();
+
+/** A PR is in a terminal state (derived from app/service.ts TERMINAL_STATUSES, the single source of
+ * truth). A plan is settled only once every PR-producing task has reached one of these. */
+const TERMINAL_PR_STATUSES = new Set(TERMINAL_STATUSES);
+
+/** Task statuses that are settled WITHOUT a landed PR: the planner/dispatcher decided not to (or
+ * could not) produce one, so they never block epic completion. `escalated`/`waiting-for-lane` are
+ * still in flight; `pending`/`opened` are checked against their PR. */
+const SETTLED_TASKLESS = new Set(["skipped", "blocked"]);
+
+interface PlanRow extends Record<string, unknown> {
+  plan_key: string;
+  repo: string;
+  issue_url: string;
+  title: string | null;
+  status: string;
+  retro_started_at?: string | null;
+}
+
+const plansTbl = (data: DataLayer) => data.table<PlanRow>("plans", "plan_key");
+const prsTbl = (data: DataLayer) =>
+  data.table<{ pr_key: string; status: string }>("pull_requests", "pr_key");
+const retroStartsTbl = (data: DataLayer) =>
+  data.table<{ plan_key: string; started_at: string }>("plan_retro_starts", "plan_key");
+
+/** Resolve the plan a PR belongs to, or undefined when the PR was submitted standalone (not part
+ * of a fan-out). A PR is linked to a plan via the `plan_tasks.pr_key` it produced. */
+export async function planKeyForPr(data: DataLayer, prKey: string): Promise<string | undefined> {
+  if (!prKey) return undefined;
+  const row = await planTasks(data).findOne({ pr_key: prKey });
+  return row?.plan_key;
+}
+
+/** Is every one of a plan's tasks settled? Settled = skipped/blocked (never produced a landing
+ * PR), or a task whose PR has reached a terminal state. A `pending`/`escalated`/`waiting-for-lane`
+ * task, or an `opened` task whose PR is still in flight, means the epic is not done yet. */
+export async function isPlanComplete(data: DataLayer, planKey: string): Promise<boolean> {
+  const tasks = await planTasks(data).find({ plan_key: planKey });
+  if (tasks.length === 0) return false; // an empty plan has nothing to retrospect
+  for (const t of tasks) {
+    if (SETTLED_TASKLESS.has(t.status)) continue;
+    // Any task that is meant to yield a PR must have a terminal PR to be settled.
+    if (!t.pr_key) return false; // pending/escalated/etc. with no PR yet → still in flight
+    const pr = await prsTbl(data).get(t.pr_key);
+    if (!pr || !TERMINAL_PR_STATUSES.has(pr.status)) return false;
+  }
+  return true;
+}
+
+/** The material a retro reflects on, assembled from a plan's advisory knowledge. */
+export interface RetroDigest {
+  planKey: string;
+  repo: string;
+  issueUrl: string;
+  title: string | null;
+  learnings: { author_task: string; body: string; created_at: string }[];
+  touchedFiles: string[];
+  contractChanges: { taskId: string; change: string }[];
+  constraints: { taskId: string; constraint: string }[];
+  notes: { author_task: string; kind: string; body: string }[];
+  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. */
+export async function gatherRetro(data: DataLayer, planKey: string): Promise<RetroDigest> {
+  const plan = await plansTbl(data).get(planKey);
+  const entries = await readBlackboard(data, planKey);
+  const learnings = entries
+    .filter((e) => e.kind === "learning")
+    .map((e) => ({ author_task: e.author_task, body: e.body, created_at: e.created_at }));
+  const notes = entries
+    .filter((e) => e.kind !== "learning")
+    .map((e) => ({ author_task: e.author_task, kind: e.kind, body: e.body }));
+  const deltas = await aggregateEpicDeltas(data, planKey);
+  return {
+    planKey,
+    repo: plan?.repo ?? planKey.split("#")[0] ?? "",
+    issueUrl: plan?.issue_url ?? "",
+    title: plan?.title ?? null,
+    learnings,
+    touchedFiles: deltas.touchedFiles,
+    contractChanges: deltas.contractChanges,
+    constraints: deltas.constraints,
+    notes,
+    counts: {
+      learnings: learnings.length,
+      deltas: deltas.deltas.length,
+      notes: notes.length,
+    },
+  };
+}
+
+/** Render the digest as the compact markdown brief handed to the retro agent (rides `appendPrompt`,
+ * concatenated after the base `{{retro}}` prompt — so it owns its own leading separator). */
+export function renderRetroBrief(d: RetroDigest): string {
+  const lines: string[] = [
+    "",
+    "",
+    "---",
+    "",
+    `## Retro input — epic ${d.planKey}`,
+    "",
+    `Target repo: **${d.repo}**${d.issueUrl ? ` · issue: ${d.issueUrl}` : ""}`,
+    d.title ? `Epic: ${d.title}` : "",
+    "",
+    `### 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 {
+    for (const l of d.learnings) lines.push(`- **[${l.author_task}]** ${l.body}`);
+  }
+  if (d.constraints.length > 0) {
+    lines.push("", `### Constraints discovered (${d.constraints.length})`);
+    for (const c of d.constraints) lines.push(`- **[${c.taskId}]** ${c.constraint}`);
+  }
+  if (d.contractChanges.length > 0) {
+    lines.push("", `### Contract changes (${d.contractChanges.length})`);
+    for (const c of d.contractChanges) lines.push(`- **[${c.taskId}]** ${c.change}`);
+  }
+  if (d.touchedFiles.length > 0) {
+    lines.push("", `### Files touched beyond original slices`, d.touchedFiles.map((f) => `\`${f}\``).join(", "));
+  }
+  if (d.notes.length > 0) {
+    lines.push("", `### Other blackboard notes (${d.notes.length})`);
+    for (const n of d.notes) lines.push(`- **[${n.author_task}]** _${n.kind}_: ${n.body}`);
+  }
+  return lines.join("\n");
+}
+
+/** True when a digest carries nothing worth an agent run — no learnings, no deltas, no notes. */
+export function isDigestEmpty(d: RetroDigest): boolean {
+  return d.counts.learnings === 0 && d.counts.deltas === 0 && d.counts.notes === 0;
+}
+
+/** The persisted retro shape (written by pr.retro-record). */
+export interface RetroInput {
+  status: string; // filed | skipped | blocked
+  prKey?: string | null;
+  learnings?: number;
+  summary?: string | null;
+  report?: string | null;
+}
+
+const retrosTbl = (data: DataLayer) =>
+  data.table<{ plan_key: string } & Record<string, unknown>>("plan_retros", "plan_key");
+
+async function claimRetroStart(data: DataLayer, planKey: string): Promise<boolean> {
+  try {
+    await retroStartsTbl(data).insert({ plan_key: planKey, started_at: now() });
+    return true;
+  } catch (err) {
+    // Only a UNIQUE/PK collision means "another starter already elected itself" — a benign
+    // duplicate the fire-once guard exists to detect. Any other constraint (e.g. a FOREIGN KEY
+    // failure from a missing plan row) is real corruption and must propagate, not be swallowed.
+    if (isUniqueViolation(err)) return false;
+    throw err;
+  }
+}
+
+/** Upsert a plan's retro row (idempotent on plan_key, so a job retry overwrites in place).
+ *
+ * Insert-first, then fall back to update only on a verified unique/PK violation: a get-then-insert
+ * can race (two concurrent retries both see no row, then one insert wins and the other throws), so
+ * we treat "row already exists" as the update path rather than an error. */
+export async function recordRetro(
+  data: DataLayer,
+  planKey: string,
+  input: RetroInput,
+): Promise<void> {
+  const ts = now();
+  const fields = {
+    status: input.status,
+    pr_key: input.prKey ?? null,
+    learnings: input.learnings ?? 0,
+    summary: input.summary ?? null,
+    report: input.report ?? null,
+    updated_at: ts,
+  };
+  try {
+    await retrosTbl(data).insert({ plan_key: planKey, created_at: ts, ...fields });
+  } catch (err) {
+    // Fall back to update only on a verified UNIQUE/PK violation (the get-then-insert race, or a
+    // job retry). Restrict to unique/duplicate/primary-key: a FOREIGN KEY (or other) constraint
+    // failure would otherwise be swallowed here, making the write look successful while doing
+    // nothing — so rethrow anything that isn't a duplicate-row collision.
+    if (!isUniqueViolation(err)) throw err;
+    await retrosTbl(data).update(planKey, fields);
+  }
+}
+
+/** Called from a PR's terminal point (mark-merged / finalize review-only). If that PR was the last
+ * of its plan to land AND there is anything to reflect on, start the `retro` process exactly once.
+ *
+ * Best-effort and non-blocking: any failure here must never fail the terminal job that called it —
+ * the retro is advisory. The fire-once guard is `plan_retro_starts`: a PRIMARY KEY insert
+ * atomically elects one starter across app processes before we stamp `plans.retro_started_at`
+ * and start the instance. */
+export async function maybeStartRetro(
+  data: DataLayer,
+  engine: EngineClient,
+  prKey: string,
+  log?: (level: "info" | "warn" | "error", msg: string, meta?: Record<string, unknown>) => void,
+): Promise<{ started: boolean; planKey?: string; reason?: string }> {
+  if (!autoRetroEnabled()) return { started: false, reason: "disabled" };
+  try {
+    const planKey = await planKeyForPr(data, prKey);
+    if (!planKey) return { started: false, reason: "no-plan" };
+
+    const plan = await plansTbl(data).get(planKey);
+    if (!plan) return { started: false, reason: "no-plan" };
+    if (plan.retro_started_at) return { started: false, planKey, reason: "already-started" };
+
+    if (!(await isPlanComplete(data, planKey))) return { started: false, planKey, reason: "incomplete" };
+
+    const digest = await gatherRetro(data, planKey);
+    if (isDigestEmpty(digest)) {
+      if (!(await claimRetroStart(data, planKey))) return { started: false, planKey, reason: "already-started" };
+      // Nothing to reflect on — stamp anyway so we don't re-check on every future terminal PR of a
+      // (now settled) plan, and record a skipped retro for visibility.
+      await plansTbl(data).update(planKey, { retro_started_at: now(), updated_at: now() });
+      await recordRetro(data, planKey, { status: "skipped", summary: "No learnings, deltas, or notes to retrospect." });
+      return { started: false, planKey, reason: "nothing-to-retro" };
+    }
+
+    if (!(await claimRetroStart(data, planKey))) return { started: false, planKey, reason: "already-started" };
+
+    // 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,
+      },
+    });
+    log?.("info", `retro: started for epic ${planKey}`, { processInstanceKey, learnings: digest.counts.learnings });
+    return { started: true, planKey };
+  } catch (err) {
+    log?.("error", `retro: could not start for PR ${prKey}`, { err: String(err) });
+    return { started: false, reason: "error" };
+  }
+}

package/db/migrations/016_plan_retro.sql

@@ -0,0 +1,38 @@
+-- Epic retrospective — the post-completion reflection stage (blackboard `learning` follow-up).
+--
+-- An epic (a `plans` row) is dispatched by `plan-fanout` and its slices land asynchronously,
+-- each PR riding its own `merge-loop`. "Epic complete" is therefore emergent: it is the moment
+-- the LAST of a plan's PRs reaches a terminal state (merged / converged / abandoned). When that
+-- happens, `maybeStartRetro` (app/retro.ts) starts one `retro` process instance for the plan.
+--
+-- The retro agent (`senior:retro`) reads the plan's accumulated coordination knowledge — the
+-- `learning` blackboard entries agents posted while implementing, plus their task deltas and
+-- escalations — clusters and ranks it, and opens a PR against the TARGET repo promoting the
+-- recurring gotchas into that repo's AGENTS.md / a script / a CI step (human-reviewed, never
+-- auto-committed). The report it produces is recorded here.
+
+-- Fire-once guard. Set (to an ISO timestamp) the instant `maybeStartRetro` starts the retro
+-- process for this plan, so a second PR of the same plan reaching terminal state near-simultaneously
+-- cannot start a duplicate retro. NULL = no retro has been started for this plan.
+ALTER TABLE plans ADD COLUMN retro_started_at TEXT;
+
+-- Atomic start election for multi-process deployments. `maybeStartRetro` first inserts here; the
+-- PRIMARY KEY lets exactly one worker claim a plan before it stamps `plans.retro_started_at` and
+-- starts the BPMN instance.
+CREATE TABLE plan_retro_starts (
+  plan_key      TEXT PRIMARY KEY REFERENCES plans(plan_key),
+  started_at    TEXT NOT NULL
+);
+
+-- One row per epic retrospective. Written by `pr.retro-record` from the `senior:retro` agent's
+-- result. Advisory knowledge, like the blackboard it distils — it gates no control flow.
+CREATE TABLE plan_retros (
+  plan_key      TEXT PRIMARY KEY REFERENCES plans(plan_key),
+  status        TEXT NOT NULL,               -- filed | skipped | blocked (the agent's result status)
+  pr_key        TEXT,                         -- the promotion PR the agent opened on the target repo ("<owner>/<repo>#<n>"), or NULL
+  learnings     INTEGER NOT NULL DEFAULT 0,  -- raw count of `learning` blackboard entries included in the retro digest
+  summary       TEXT,                         -- the agent's human-readable retro summary
+  report        TEXT,                         -- the full retro report / transcript (nullable)
+  created_at    TEXT NOT NULL,
+  updated_at    TEXT NOT NULL
+);

package/nano.app.json

@@ -74,6 +74,14 @@
     {
       "taskType": "pr.persist-task-escalation",
       "handler": "workers/persist-task-escalation/worker.ts"
+    },
+    {
+      "taskType": "pr.retro-gather",
+      "handler": "workers/retro-gather/worker.ts"
+    },
+    {
+      "taskType": "pr.retro-record",
+      "handler": "workers/retro-record/worker.ts"
     }
   ],
   "surfaces": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.29.0",
+  "version": "0.30.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/prompts/retro.md

@@ -0,0 +1,86 @@
+# Retro agent — distil an epic's learnings and promote the recurring ones
+
+You are the **retrospective agent**. An epic (a fan-out `plan`) has finished — every one of its
+slices has landed (merged, converged, or abandoned). While the fleet worked, its agents shared
+reusable gotchas on a coordination **blackboard** as `learning` entries ("regenerate the API
+surface before building", "nextest, not `cargo test`, for the console suite", …). Your job is to
+turn that scattered, per-agent knowledge into a **durable improvement** to the target repository,
+so the *next* fleet — and human contributors — never re-learn it the hard way.
+
+You are the mechanism that lifts a lesson from "a thing one agent happened to hit" to "a thing the
+repo now tells everyone up front."
+
+## Input
+
+The job payload (stdin JSON) carries:
+
+- `variables.planKey` — the epic's key, e.g. `owner/repo#123`.
+- `variables.repo` — the **target repo** `owner/repo` you will open a promotion PR against.
+- `variables.issueUrl` — the epic's source issue, for context (`gh issue view`).
+- **`variables.retroDigest`** — appended to this prompt below the `---` separator: the epic's
+  accumulated knowledge already gathered for you — the `learning` entries agents posted, the
+  constraints and contract changes they discovered, and the files they touched beyond their
+  original slices. **This is your primary material.** You do not need to reconstruct it.
+
+You have `gh` / git authenticated for the target repository.
+
+## What to do
+
+1. **Read the digest** (below the separator). Also read prior retros for cross-epic recurrence:
+   look for an `AGENTS.md` "Learnings" / "Gotchas" section already in the repo, and skim recent
+   merged PRs titled like `retro:` — a lesson that keeps recurring across epics is the highest-
+   value promotion.
+2. **Cluster and dedupe.** Group the raw learnings into distinct lessons. A lesson mentioned by
+   several agents, or one that also appears in a prior retro, ranks highest. Drop one-offs that are
+   genuinely specific to a single slice and won't recur.
+3. **Rank by recurrence × severity.** Promote the lessons that are both *reusable* (a future agent
+   or contributor would hit them) and *costly* (they broke a build, wasted a wave, or caused a
+   merge collision). A single well-placed line beats an exhaustive dump.
+4. **Choose the right home for each promoted lesson** — the whole point is to make the knowledge
+   *load-bearing*, not just written down:
+   - **`AGENTS.md`** (or `CONTRIBUTING.md`) — a convention, a "before you build, run X", a
+     non-obvious constraint. The default home.
+   - **A script** — if the lesson is "always run these steps in this order", encode it as a
+     script (or a `make`/`npm`/`deno task` target) so it can't be forgotten.
+   - **A CI step** — if the lesson is "this class of mistake should never merge", add a guard/gate
+     so CI catches it mechanically. Prefer this for anything a machine can check.
+   Pick the *most enforceable* home a lesson supports: CI gate > script > doc.
+5. **Open ONE pull request** against `variables.repo` with `gh pr create`, collecting your
+   promotions. Keep it small and reviewable — this is a **human-reviewed** PR; you propose, a human
+   decides. Sign off (DCO: `git commit -s`). Link the epic issue. Title it `retro: <short summary>`.
+   Do **not** request Copilot review yourself and do **not** merge it.
+6. Clean up any scratch clone/worktree you created.
+
+## When there's nothing worth promoting
+
+If, after clustering, no lesson is durable enough to justify a change to the repo — the learnings
+were all slice-specific noise, or already documented — **do not manufacture a PR**. Emit
+`status: "skipped"` with a one-line reason. A retro that correctly files nothing is a success, not
+a failure; a low-signal PR that wastes a human's review is the bad outcome.
+
+## Output contract
+
+Write a JSON object of **result variables** to the file named by the `AGENT_RESULT_FILE`
+environment variable:
+
+```json
+{
+  "status": "filed",
+  "summary": "Promoted 3 lessons: regen-before-build (AGENTS.md), nextest gate (CI), migration-order note (AGENTS.md).",
+  "pr": "owner/repo#789"
+}
+```
+
+Rules:
+
+- `status` — one of:
+  - `filed` — you opened a promotion PR. Set `pr`.
+  - `skipped` — nothing durable enough to promote. Explain in `summary`; omit `pr`.
+  - `blocked` — you could not proceed (e.g. no write access to the target repo). Explain in
+    `summary`; omit `pr`.
+- `pr` — the promotion PR as `owner/repo#<number>` (or its URL), for `filed`. Omit / null it
+  otherwise.
+- `summary` — a short human-readable result naming the lessons you promoted (or why you skipped).
+
+You are advisory: you never block a fleet, and every change you propose is a human's to accept.
+Promote what will genuinely save the next contributor time; leave the rest.

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/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/retro-gather/worker.test.ts

@@ -0,0 +1,78 @@
+import { assert, assertEquals, assertStringIncludes } from "jsr:@std/assert@1";
+import type { DataLayer } from "@nanobpm/urban";
+import { appendEntry } from "../../app/blackboard.ts";
+import handler from "./worker.ts";
+
+// 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) {
+        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() {},
+    };
+  }
+  // deno-lint-ignore no-explicit-any
+  const data = { table: (n: string, pk?: string) => tbl(n, pk) } as any as DataLayer;
+  return { data, stores };
+}
+
+Deno.test("retro-gather: emits a digest brief + learning count for the plan", async () => {
+  const { data, stores } = memData();
+  stores["plans"] = [{ plan_key: "o/r#3", repo: "o/r", issue_url: "https://x/3", title: "Epic" }];
+  await appendEntry(data, "o/r#3", { author_task: "t1", kind: "learning", body: "regen before build" });
+  await appendEntry(data, "o/r#3", { author_task: "t2", kind: "learning", body: "use nextest" });
+
+  const app = { data, log: () => undefined };
+  const out = await handler(
+    // deno-lint-ignore no-explicit-any
+    { variables: { planKey: "o/r#3" } } as any,
+    // deno-lint-ignore no-explicit-any
+    app as any,
+  ) as Record<string, unknown>;
+
+  assertEquals(out.retroLearnings, 2);
+  assertStringIncludes(String(out.retroDigest), "regen before build");
+  assertStringIncludes(String(out.retroDigest), "use nextest");
+  assertStringIncludes(String(out.retroDigest), "o/r#3");
+});
+
+Deno.test("retro-gather: an epic with no learnings still renders a valid brief", async () => {
+  const { data, stores } = memData();
+  stores["plans"] = [{ plan_key: "o/r#4", repo: "o/r", issue_url: "", title: null }];
+  const app = { data, log: () => undefined };
+  const out = await handler(
+    // deno-lint-ignore no-explicit-any
+    { variables: { planKey: "o/r#4" } } as any,
+    // deno-lint-ignore no-explicit-any
+    app as any,
+  ) as Record<string, unknown>;
+
+  assertEquals(out.retroLearnings, 0);
+  assert(typeof out.retroDigest === "string");
+  assertStringIncludes(String(out.retroDigest), "none");
+});

package/workers/retro-gather/worker.ts

@@ -0,0 +1,28 @@
+// pr.retro-gather — first step of the `retro` process. Assemble the plan's accumulated
+// coordination knowledge (the `learning` blackboard entries agents posted while implementing, plus
+// the task-delta rollup and any other blackboard notes) into a compact markdown brief, and emit it
+// as `retroDigest`. The next step maps that onto the `senior:retro` agent's `appendPrompt`, so the
+// agent reflects on real material rather than re-deriving it.
+import type { AppJobHandler } from "@nanobpm/urban";
+import { gatherRetro, renderRetroBrief } from "../../app/retro.ts";
+
+interface In extends Record<string, unknown> {
+  planKey: string;
+}
+
+interface Out extends Record<string, unknown> {
+  retroDigest: string;
+  retroLearnings: number;
+}
+
+const handler: AppJobHandler<In, Out> = async (job, app) => {
+  const planKey = job.variables.planKey;
+  const digest = await gatherRetro(app.data, planKey);
+  app.log("info", `retro-gather: ${planKey} — ${digest.counts.learnings} learnings, ${digest.counts.deltas} deltas`);
+  return {
+    retroDigest: renderRetroBrief(digest),
+    retroLearnings: digest.counts.learnings,
+  };
+};
+
+export default handler;

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

@@ -0,0 +1,127 @@
+import { assertEquals } from "jsr:@std/assert@1";
+import handler from "./worker.ts";
+
+function fakeApp() {
+  // deno-lint-ignore no-explicit-any
+  const stores: Record<string, any[]> = { plan_retros: [] };
+  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) {
+        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);
+      },
+    };
+  }
+  const app = { data: { table: (n: string, pk?: string) => tbl(n, pk) }, log: () => undefined };
+  return { app, stores };
+}
+
+Deno.test("retro-record: persists a filed retro from hoisted result vars", async () => {
+  const { app, stores } = fakeApp();
+  await handler(
+    // deno-lint-ignore no-explicit-any
+    {
+      variables: {
+        planKey: "o/r#5",
+        retroLearnings: 4,
+        status: "filed",
+        pr: "o/r#42",
+        summary: "promoted 2 lessons",
+        "io.nanobpm.agentResult": { output: "the full report" },
+      },
+    } as any,
+    // deno-lint-ignore no-explicit-any
+    app as any,
+  );
+
+  assertEquals(stores.plan_retros.length, 1);
+  const row = stores.plan_retros[0];
+  assertEquals(row.status, "filed");
+  assertEquals(row.pr_key, "o/r#42");
+  assertEquals(row.learnings, 4);
+  assertEquals(row.summary, "promoted 2 lessons");
+  assertEquals(row.report, "the full report");
+});
+
+Deno.test("retro-record: defaults to skipped when the agent filed no PR", async () => {
+  const { app, stores } = fakeApp();
+  await handler(
+    // deno-lint-ignore no-explicit-any
+    { variables: { planKey: "o/r#6", summary: "nothing durable" } } as any,
+    // deno-lint-ignore no-explicit-any
+    app as any,
+  );
+  assertEquals(stores.plan_retros[0].status, "skipped");
+  assertEquals(stores.plan_retros[0].pr_key, null);
+});
+
+Deno.test("retro-record: honours an explicit blocked status", async () => {
+  const { app, stores } = fakeApp();
+  await handler(
+    // deno-lint-ignore no-explicit-any
+    { variables: { planKey: "o/r#7", status: "blocked", summary: "no write access" } } as any,
+    // deno-lint-ignore no-explicit-any
+    app as any,
+  );
+  assertEquals(stores.plan_retros[0].status, "blocked");
+});
+
+Deno.test("retro-record: ignores a PR unless the status is filed", async () => {
+  const { app, stores } = fakeApp();
+  await handler(
+    // deno-lint-ignore no-explicit-any
+    { variables: { planKey: "o/r#8", status: "skipped", pr: "o/r#43", summary: "not durable" } } as any,
+    // deno-lint-ignore no-explicit-any
+    app as any,
+  );
+  assertEquals(stores.plan_retros[0].status, "skipped");
+  assertEquals(stores.plan_retros[0].pr_key, null);
+});
+
+Deno.test("retro-record: defaults invalid status from PR presence", async () => {
+  const { app, stores } = fakeApp();
+  await handler(
+    // deno-lint-ignore no-explicit-any
+    { variables: { planKey: "o/r#9", status: "done", pr: "o/r#44" } } as any,
+    // deno-lint-ignore no-explicit-any
+    app as any,
+  );
+  assertEquals(stores.plan_retros[0].status, "filed");
+  assertEquals(stores.plan_retros[0].pr_key, "o/r#44");
+});
+
+Deno.test("retro-record: coerces filed without a PR to skipped", async () => {
+  const { app, stores } = fakeApp();
+  await handler(
+    // deno-lint-ignore no-explicit-any
+    { variables: { planKey: "o/r#10", status: "filed", summary: "forgot the PR" } } as any,
+    // deno-lint-ignore no-explicit-any
+    app as any,
+  );
+  assertEquals(stores.plan_retros[0].status, "skipped");
+  assertEquals(stores.plan_retros[0].pr_key, null);
+});

package/workers/retro-record/worker.ts

@@ -0,0 +1,60 @@
+// pr.retro-record — final step of the `retro` process. Persist the `senior:retro` agent's result
+// into `plan_retros` (016_plan_retro.sql): the outcome status, the promotion PR it opened on the
+// target repo (if any), the learning count it distilled, and its summary/report. Advisory only —
+// this gates no control flow; it exists so the epic surface can show what the retro concluded.
+//
+// The agentTask runner hoists the agent's result-JSON keys (`status`, `pr`, `summary`) into
+// top-level process variables (same as pr.record-plan-review reads `job.variables.approved`), and
+// exposes the raw transcript under the `io.nanobpm.agentResult` envelope's `.output`.
+import type { AppJobHandler } from "@nanobpm/urban";
+import { recordRetro } from "../../app/retro.ts";
+
+const AGENT_RESULT_KEY = "io.nanobpm.agentResult";
+const VALID_STATUSES = new Set(["filed", "skipped", "blocked"]);
+
+interface In extends Record<string, unknown> {
+  planKey: string;
+  retroLearnings?: number;
+  status?: unknown; // filed | skipped | blocked
+  pr?: unknown; // "<owner>/<repo>#<n>" of the promotion PR, when filed
+  summary?: unknown;
+}
+
+function asStr(v: unknown): string | null {
+  return typeof v === "string" && v.trim() !== "" ? v.trim() : null;
+}
+
+function asStatus(v: unknown, hasPr: boolean): "filed" | "skipped" | "blocked" {
+  const s = asStr(v);
+  if (s && VALID_STATUSES.has(s)) {
+    if (s === "filed" && !hasPr) return "skipped";
+    return s as "filed" | "skipped" | "blocked";
+  }
+  return hasPr ? "filed" : "skipped";
+}
+
+const handler: AppJobHandler<In> = async (job, app) => {
+  const planKey = job.variables.planKey;
+
+  const rawPrKey = asStr(job.variables.pr);
+  // Default to "filed" only when a PR is present; otherwise the agent decided not to file.
+  const status = asStatus(job.variables.status, rawPrKey !== null);
+  const prKey = status === "filed" ? rawPrKey : null;
+  const summary = asStr(job.variables.summary);
+
+  const env = job.variables[AGENT_RESULT_KEY] as { output?: unknown } | undefined;
+  const report = typeof env?.output === "string" ? env.output : null;
+
+  await recordRetro(app.data, planKey, {
+    status,
+    prKey,
+    learnings: typeof job.variables.retroLearnings === "number" ? job.variables.retroLearnings : 0,
+    summary,
+    report,
+  });
+
+  app.log("info", `retro-record: ${planKey} — status=${status}${prKey ? ` pr=${prKey}` : ""}`);
+  return {};
+};
+
+export default handler;