@nanobpm/nano-workforce 0.29.0 → 0.31.0

package/app/retro.ts

@@ -0,0 +1,365 @@
+// 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 { planReviews, 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 }[];
+  // Plan-review trace (006_plan_review.sql): how many adversarial review rounds the plan needed
+  // before fan-out, and the critique from every rejected round — the "what was wrong with the
+  // first cut of the decomposition" signal, which is prime retro material even when implementers
+  // posted no learnings of their own. `planApproved` reflects the final round's verdict.
+  reviewRounds: number;
+  reviewRejections: { round: number; findings: string }[];
+  planApproved: boolean;
+  // Execution shape: how the plan's tasks actually resolved (opened a PR, were skipped/blocked,
+  // etc.). Lets the retro reason over decomposition accuracy — e.g. a high skipped/blocked ratio
+  // hints the plan over-decomposed.
+  taskOutcomes: { total: number; byStatus: Record<string, number> };
+  counts: { learnings: number; deltas: number; notes: number };
+}
+
+/** Gather a plan's reflection material: the `learning` blackboard entries (the headline), plus the
+ * task-delta rollup (contract changes, discovered constraints, cross-slice file touches), the
+ * plan-review trace (rounds + rejection findings), the task-outcome shape, and any other
+ * non-learning blackboard notes for colour. Reads only — no writes. */
+export async function gatherRetro(data: DataLayer, planKey: string): Promise<RetroDigest> {
+  const plan = await plansTbl(data).get(planKey);
+  const entries = await readBlackboard(data, planKey);
+  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);
+
+  // Plan-review trace, ordered by round. A rejected round is `approved === 0`; only rounds that
+  // carry findings are worth quoting (an empty rejection has nothing to teach).
+  const reviews = (await planReviews(data).find({ plan_key: planKey }))
+    .slice()
+    .sort((a, b) => a.round - b.round);
+  const reviewRejections = reviews
+    .filter((r) => r.approved === 0 && (r.findings ?? "").trim() !== "")
+    .map((r) => ({ round: r.round, findings: r.findings as string }));
+  const planApproved = reviews.length > 0 && reviews[reviews.length - 1].approved === 1;
+
+  // Task-outcome shape (counts by final status).
+  const tasks = await planTasks(data).find({ plan_key: planKey });
+  const byStatus: Record<string, number> = {};
+  for (const t of tasks) byStatus[t.status] = (byStatus[t.status] ?? 0) + 1;
+
+  return {
+    planKey,
+    repo: plan?.repo ?? planKey.split("#")[0] ?? "",
+    issueUrl: plan?.issue_url ?? "",
+    title: plan?.title ?? null,
+    learnings,
+    touchedFiles: deltas.touchedFiles,
+    contractChanges: deltas.contractChanges,
+    constraints: deltas.constraints,
+    notes,
+    reviewRounds: reviews.length,
+    reviewRejections,
+    planApproved,
+    taskOutcomes: { total: tasks.length, byStatus },
+    counts: {
+      learnings: learnings.length,
+      deltas: deltas.deltas.length,
+      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}` : "",
+    "",
+    `### Plan review — ${d.reviewRounds} round(s), ${d.planApproved ? "approved" : "not approved"}`,
+  ];
+  if (d.reviewRejections.length === 0) {
+    lines.push(
+      d.reviewRounds === 0
+        ? "_(no review rounds recorded)_"
+        : "_(approved with no recorded rejections)_",
+    );
+  } else {
+    lines.push(`The plan was revised after ${d.reviewRejections.length} rejected round(s):`);
+    for (const r of d.reviewRejections) lines.push(`- **round ${r.round}**: ${r.findings}`);
+  }
+  if (d.taskOutcomes.total > 0) {
+    const shape = Object.entries(d.taskOutcomes.byStatus)
+      .sort((a, b) => a[0].localeCompare(b[0]))
+      .map(([s, n]) => `${s}: ${n}`)
+      .join(", ");
+    lines.push("", `### Task outcomes (${d.taskOutcomes.total} task(s))`, shape);
+  }
+  lines.push(
+    "",
+    `### Learnings agents posted while implementing (${d.learnings.length})`,
+  );
+  if (d.learnings.length === 0) {
+    lines.push("_(none — agents posted no `learning` entries for this epic)_");
+  } else {
+    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. A plan is worth retrospecting when
+ * implementers shared material (learnings/deltas/notes) OR the plan itself needed revision — a
+ * rejected review round's findings are reflection material in their own right, even when no
+ * learning was posted. (Task-outcome shape alone is NOT: a cleanly-approved plan whose tasks all
+ * ran has nothing to teach.) */
+export function isDigestEmpty(d: RetroDigest): boolean {
+  return d.counts.learnings === 0 && d.counts.deltas === 0 && d.counts.notes === 0 &&
+    d.reviewRejections.length === 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() });
+
+    let processInstanceKey: string | number | undefined;
+    try {
+      ({ processInstanceKey } = await engine.createInstance({
+        processDefinitionId: RETRO_PROCESS_ID,
+        variables: {
+          planKey,
+          repo: digest.repo,
+          issueUrl: digest.issueUrl,
+        },
+      }));
+    } catch (err) {
+      // The fire-once guard is already consumed (retro_started_at stamped, plan_retro_starts
+      // claimed), so this plan will never re-enter the start path. If we returned here with no
+      // record, the epic surface would show a plan that "started a retro" with nothing to show and
+      // no way to retry. Persist a `blocked` retro instead so the failure stays visible and the
+      // system state is consistent. Recording must not mask the original error in the log.
+      log?.("error", `retro: could not start process for epic ${planKey}`, { err: String(err) });
+      // Persisting the blocked record is best-effort: recordRetro rethrows non-unique DB errors, and
+      // if that escaped here it would fall through to the outer catch and return `error` instead of
+      // `start-failed` — reintroducing the very silent-gap failure this path guards against (guard
+      // consumed, no durable record). Swallow a secondary persistence failure and log it separately
+      // so the createInstance failure path always reports `start-failed`.
+      try {
+        await recordRetro(data, planKey, {
+          status: "blocked",
+          summary: `Retro process could not be started: ${String(err)}`,
+        });
+      } catch (persistErr) {
+        log?.("error", `retro: could not persist blocked retro for epic ${planKey}`, {
+          err: String(persistErr),
+        });
+      }
+      return { started: false, planKey, reason: "start-failed" };
+    }
+    log?.("info", `retro: started for epic ${planKey}`, { processInstanceKey, learnings: digest.counts.learnings });
+    return { started: true, planKey };
+  } catch (err) {
+    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.31.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/pages/epic.page.json

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

package/pages/home.page.json

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

package/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/plan-fanout.bpmn

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