@nanobpm/nano-workforce 0.28.0 → 0.30.0

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/deno.json

@@ -6,7 +6,7 @@
     ]
   },
   "imports": {
-    "@nanobpm/urban": "npm:@nanobpm/urban@^0.27.0"
+    "@nanobpm/urban": "npm:@nanobpm/urban@^0.28.0"
   },
   "tasks": {
     "start": "deno run --allow-net --allow-read --allow-write --allow-run=gh --allow-env main.ts",

package/deno.lock

@@ -3,7 +3,7 @@
   "specifiers": {
     "jsr:@std/assert@1": "1.0.19",
     "jsr:@std/internal@^1.0.12": "1.0.14",
-    "npm:@nanobpm/urban@0.27": "0.27.0",
+    "npm:@nanobpm/urban@0.28": "0.28.0",
     "npm:@semantic-release/changelog@^6.0.3": "6.0.3_semantic-release@24.2.9__typescript@5.9.3_typescript@5.9.3",
     "npm:@semantic-release/git@^10.0.1": "10.0.1_semantic-release@24.2.9__typescript@5.9.3_typescript@5.9.3",
     "npm:@semantic-release/npm@^13.1.5": "13.1.5_semantic-release@24.2.9__typescript@5.9.3",
@@ -82,8 +82,8 @@
         "ws"
       ]
     },
-    "@nanobpm/urban@0.27.0": {
-      "integrity": "sha512-FjGv0ttj2TqRTvYUjHDKwBWmZImn17VWjbYVmy6cMAjhtGa5cFsuJOWHwV1WTdkJhcvC3WcsjB6gaAxYQNzglg==",
+    "@nanobpm/urban@0.28.0": {
+      "integrity": "sha512-rhzgOV+Vb1CPuNoVHVX3OtxjHqzSp2gJIV2pi3EBi245ZjDRN0gSoPGd/MEnJdufxgWwDKuvhyljRDHE8T957w==",
       "dependencies": [
         "@nanobpm/nano-app-schema",
         "@nanobpm/nano-sdk",
@@ -1757,11 +1757,11 @@
   },
   "workspace": {
     "dependencies": [
-      "npm:@nanobpm/urban@0.27"
+      "npm:@nanobpm/urban@0.28"
     ],
     "packageJson": {
       "dependencies": [
-        "npm:@nanobpm/urban@0.27",
+        "npm:@nanobpm/urban@0.28",
         "npm:@semantic-release/changelog@^6.0.3",
         "npm:@semantic-release/git@^10.0.1",
         "npm:@semantic-release/npm@^13.1.5",

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.28.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",
@@ -40,7 +40,7 @@
     "test": "deno test -A"
   },
   "dependencies": {
-    "@nanobpm/urban": "^0.27.0"
+    "@nanobpm/urban": "^0.28.0"
   },
   "devDependencies": {
     "@semantic-release/changelog": "^6.0.3",

package/pages/epic.page.json

@@ -2,6 +2,18 @@
   "schemaVersion": "1.0",
   "title": "Epic Coordination",
   "nodes": [
+    {
+      "type": "nav",
+      "id": "nav",
+      "props": {
+        "variant": "bar",
+        "title": "Nano Workforce",
+        "items": [
+          { "label": "Convergence", "page": "home" },
+          { "label": "Epic", "page": "epic" }
+        ]
+      }
+    },
     {
       "type": "text",
       "id": "title",

package/pages/home.page.json

@@ -2,6 +2,18 @@
   "schemaVersion": "1.0",
   "title": "PR Review Convergence",
   "nodes": [
+    {
+      "type": "nav",
+      "id": "nav",
+      "props": {
+        "variant": "bar",
+        "title": "Nano Workforce",
+        "items": [
+          { "label": "Convergence", "page": "home" },
+          { "label": "Epic", "page": "epic" }
+        ]
+      }
+    },
     {
       "type": "text",
       "id": "title",

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 {};
 };