@nanobpm/nano-workforce 0.104.0 → 0.106.0

package/app/conformance.ts

@@ -0,0 +1,329 @@
+// Spec-conformance review — "did we build what the spec asked for?", examined against the ACTUAL
+// implementation.
+//
+// It rides the existing `retro` process (app/retro.ts): when an epic's last PR lands, a
+// `senior:conformance` agent runs BEFORE the lessons agent. Unlike retro — which reflects on what
+// implementers *claimed* via `learning` blackboard entries and task deltas — conformance is
+// deliberately grounded in the code: the digest it builds hands the agent the spec (the epic issue
+// + every slice's `prompt`) and the set of PRs that actually LANDED, so the agent reads the real
+// diffs/code/tests (`gh pr diff`, `git`) and verifies delivery rather than trusting the transcript.
+//
+// It surfaces two classes of deviation: those RAISED during implementation (`scope-change`
+// blackboard entries — quoted here so the agent can reconcile them) and those it finds itself that
+// were NEVER raised. The result is persisted to `plan_conformance` (052_plan_conformance.sql).
+//
+// Data access goes through the record gateway (`data.table`), never hand-written SQL — matching
+// app/retro.ts, app/plan.ts, and app/blackboard.ts.
+import type { DataLayer } from "@nanobpm/urban";
+import { type BlackboardEntry, isUniqueViolation, readBlackboard } from "./blackboard.ts";
+import { TERMINAL_STATUSES } from "./delivery.ts";
+import { planTasks } from "./plan.ts";
+
+const now = () => new Date().toISOString();
+
+/** The BPMN `elementId` of the conformance escalation user task (retro.bpmn). The inbox reconciler
+ * (`pollUserTasks`) and the human completer (`HUMAN_COMPLETABLE_ELEMENTS`) key off this. */
+export const CONFORMANCE_ESCALATION_ELEMENT = "conformance-escalation";
+
+/** The `review_status` a `plan_conformance` row carries while its escalation ack task is OPEN — the
+ * only status `pollUserTasks` scans (migration 054). Every settled run is `reviewed`. */
+export const CONFORMANCE_REVIEWING_STATUS = "reviewing";
+
+/** A slice PR "landed" — its implementation is really in the tree and worth examining — when its
+ * PR reached a terminal state that isn't `abandoned`. In auto-merge mode that terminal is `merged`;
+ * in review-only mode it is `converged`. Derived from app/delivery.ts TERMINAL_STATUSES (the single
+ * source of truth for PR-terminal states) minus `abandoned`, so conformance and retro can't drift
+ * about what counts as landed. */
+const LANDED_PR_STATUSES = new Set(TERMINAL_STATUSES.filter((s) => s !== "abandoned"));
+
+interface PlanRow extends Record<string, unknown> {
+  plan_key: string;
+  repo: string;
+  issue_url: string;
+  title: 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");
+
+/** A slice's PR "landed" iff it exists and reached a non-abandoned terminal status. The single
+ * predicate both {@link gatherConformance} and {@link hasDeliveredImplementationForPlan} apply, so
+ * the full digest and the cheap trigger check can't disagree about what counts as landed. */
+async function isLanded(data: DataLayer, prKey: string | null | undefined): Promise<boolean> {
+  if (!prKey) return false;
+  const pr = await prsTbl(data).get(prKey);
+  return !!pr && LANDED_PR_STATUSES.has(pr.status);
+}
+const conformanceTbl = (data: DataLayer) =>
+  data.table<{ plan_key: string } & Record<string, unknown>>("plan_conformance", "plan_key");
+
+/** A `plan_conformance` row viewed as a retro-run tracking record, for the inbox reconciler. */
+export interface ConformanceReviewRow extends Record<string, unknown> {
+  plan_key: string;
+  process_key: string | null;
+  review_status: string;
+  summary: string | null;
+}
+
+const conformanceReviewsTbl = (data: DataLayer) =>
+  data.table<ConformanceReviewRow>("plan_conformance", "plan_key");
+
+/** The conformance runs whose escalation ack task is still open (`review_status = 'reviewing'`) —
+ * the set `pollUserTasks` scans for an open `conformance-escalation` user task. */
+export async function activeConformanceReviews(data: DataLayer): Promise<ConformanceReviewRow[]> {
+  return await conformanceReviewsTbl(data).find({ review_status: CONFORMANCE_REVIEWING_STATUS });
+}
+
+/** The escalation question shown in the inbox row: the agent's conformance summary (which names the
+ * reduced / not-verified items and the unraised deviations). Best-effort — NULL when none recorded. */
+export function conformanceEscalationQuestion(row: { summary?: unknown } | undefined): string | null {
+  const s = row?.summary;
+  return typeof s === "string" && s.trim() ? s.trim() : null;
+}
+
+/** One item of the spec the agent must verify against the code: the slice's planner-supplied
+ * `prompt` (its acceptance brief), where it landed, and whether it landed at all. */
+export interface ConformanceSlice {
+  taskId: string;
+  title: string | null;
+  prompt: string | null;
+  status: string;
+  prKey: string | null;
+  landed: boolean;
+}
+
+/** The material a conformance review examines. Unlike {@link RetroDigest}, this is spec + delivery
+ * pointers (not distilled claims) — the agent turns `deliveredPrs` into real diffs to inspect. */
+export interface ConformanceDigest {
+  planKey: string;
+  repo: string;
+  issueUrl: string;
+  title: string | null;
+  slices: ConformanceSlice[];
+  /** The landed PR keys ("<owner>/<repo>#<n>") the agent must open and read the diff of. */
+  deliveredPrs: string[];
+  /** Deviations agents RAISED during implementation (`scope-change` blackboard entries). */
+  scopeChanges: { author_task: string; body: string; created_at: string }[];
+}
+
+/** Assemble the conformance material for a plan: the spec (issue + each slice's `prompt`), the set
+ * of PRs that actually landed (so the agent examines the real implementation), and the scope
+ * deviations raised during implementation. Reads only — no writes.
+ *
+ * `entries` lets a caller that has already scanned the blackboard for this plan (e.g.
+ * `pr.retro-gather`, which also runs {@link gatherRetro}) pass those entries in so the plan is
+ * scanned once, not once per gatherer — see workers/retro-gather. Omitted, it reads them itself. */
+export async function gatherConformance(
+  data: DataLayer,
+  planKey: string,
+  entries?: BlackboardEntry[],
+): Promise<ConformanceDigest> {
+  const plan = await plansTbl(data).get(planKey);
+  const tasks = (await planTasks(data).find({ plan_key: planKey }))
+    .slice()
+    .sort((a, b) => (a.task_index ?? 0) - (b.task_index ?? 0));
+
+  const slices: ConformanceSlice[] = [];
+  const deliveredPrs: string[] = [];
+  for (const t of tasks) {
+    const landed = await isLanded(data, t.pr_key);
+    if (landed && t.pr_key) deliveredPrs.push(t.pr_key);
+    slices.push({
+      taskId: t.task_id,
+      title: t.title ?? null,
+      prompt: t.prompt ?? null,
+      status: t.status,
+      prKey: t.pr_key ?? null,
+      landed,
+    });
+  }
+
+  const scopeChanges = (entries ?? (await readBlackboard(data, planKey)))
+    .filter((e) => e.kind === "scope-change")
+    .map((e) => ({ author_task: e.author_task, body: e.body, created_at: e.created_at }));
+
+  return {
+    planKey,
+    repo: plan?.repo ?? planKey.split("#")[0] ?? "",
+    issueUrl: plan?.issue_url ?? "",
+    title: plan?.title ?? null,
+    slices,
+    deliveredPrs,
+    scopeChanges,
+  };
+}
+
+/** True when there is real, landed implementation to examine. A plan whose slices were all
+ * skipped/blocked/abandoned shipped nothing, so there is nothing to check for conformance — the
+ * retro trigger uses this to decide whether the conformance run is worthwhile even when the retro
+ * digest itself is empty. */
+export function hasDeliveredImplementation(d: ConformanceDigest): boolean {
+  return d.deliveredPrs.length > 0;
+}
+
+/** Cheap trigger check for the retro gate: does this plan have ANY landed implementation to examine?
+ * Inspects only plan_tasks + pull_requests (short-circuiting on the first landed PR) and — unlike
+ * {@link gatherConformance} — performs no blackboard scan, so the empty-digest trigger in
+ * app/retro.ts doesn't pay to compute `scopeChanges` it would discard. Shares {@link isLanded} with
+ * the full digest so the two can't drift on what "landed" means. */
+export async function hasDeliveredImplementationForPlan(
+  data: DataLayer,
+  planKey: string,
+): Promise<boolean> {
+  const tasks = await planTasks(data).find({ plan_key: planKey });
+  for (const t of tasks) {
+    if (await isLanded(data, t.pr_key)) return true;
+  }
+  return false;
+}
+
+/** Render the digest as the compact markdown brief handed to the conformance agent (rides
+ * `appendPrompt`, concatenated after the base `conformance.md` linked-resource prompt — so it owns
+ * its own leading separator). It deliberately gives POINTERS (the spec text + the PRs to open), not
+ * conclusions: the agent must reach the verdicts by reading the code. */
+export function renderConformanceBrief(d: ConformanceDigest): string {
+  const lines: string[] = [
+    "",
+    "",
+    "---",
+    "",
+    `## Conformance input — epic ${d.planKey}`,
+    "",
+    `Target repo: **${d.repo}**${d.issueUrl ? ` · issue (the spec): ${d.issueUrl}` : ""}`,
+    d.title ? `Epic: ${d.title}` : "",
+    "",
+    "### Delivered PRs to examine",
+  ];
+  if (d.deliveredPrs.length === 0) {
+    lines.push("_(none landed — no implementation to verify)_");
+  } else {
+    lines.push(
+      `Read the actual diff of each with \`gh pr diff <n> --repo ${d.repo}\` (and the code/tests it touches):`,
+    );
+    for (const pr of d.deliveredPrs) lines.push(`- ${pr}`);
+  }
+
+  lines.push("", `### Spec — the ${d.slices.length} slice(s) planned`);
+  if (d.slices.length === 0) {
+    lines.push("_(no slices recorded — verify the epic issue body directly)_");
+  } else {
+    for (const s of d.slices) {
+      const where = s.landed && s.prKey ? `landed as ${s.prKey}` : `status: ${s.status}`;
+      lines.push("", `#### ${s.taskId}${s.title ? ` — ${s.title}` : ""} (${where})`);
+      lines.push(s.prompt ? s.prompt : "_(no per-slice prompt; verify against the epic issue body)_");
+    }
+  }
+
+  lines.push("", `### Deviations RAISED during implementation (${d.scopeChanges.length})`);
+  if (d.scopeChanges.length === 0) {
+    lines.push("_(none — no `scope-change` entries were posted; treat any deviation you find as UNRAISED)_");
+  } else {
+    lines.push("Reconcile each against the delivered code — a raised deviation is still a deviation:");
+    for (const c of d.scopeChanges) lines.push(`- **[${c.author_task}]** ${c.body}`);
+  }
+  return lines.join("\n");
+}
+
+/** The persisted conformance shape (written by pr.conformance-record from the agent's result). */
+export interface ConformanceInput {
+  status: string; // filed | skipped | blocked
+  commentUrl?: string | null;
+  slicesMet?: number;
+  slicesReduced?: number;
+  slicesNotVerified?: number;
+  deviationsRaised?: number;
+  deviationsUnraised?: number;
+  hasDeviations?: boolean;
+  summary?: string | null;
+  report?: string | null;
+  /** The retro process instance this conformance ran in — the tracking key `pollUserTasks` reads to
+   * find an open escalation user task (migration 054). */
+  processKey?: string | null;
+  /** Escalation lifecycle: `reviewing` while the ack task is open (poller scans these), else
+   * `reviewed`. Defaults to `reviewed` — only an escalation flips it to `reviewing`. */
+  reviewStatus?: "reviewing" | "reviewed";
+}
+
+/** Upsert a plan's conformance 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 — mirrors
+ * {@link recordRetro}: a get-then-insert can race, so "row already exists" is the update path, but
+ * any non-duplicate constraint failure must propagate rather than be silently swallowed. */
+export async function recordConformance(
+  data: DataLayer,
+  planKey: string,
+  input: ConformanceInput,
+): Promise<void> {
+  const ts = now();
+  const processKey = input.processKey ?? null;
+  const reviewStatus = input.reviewStatus ?? "reviewed";
+  // Invariant: a `reviewing` row must be trackable. `pollUserTasks` skips rows without a
+  // `process_key` and the `instanceTracking` binding keys off `process_key`, so a `reviewing` row
+  // with a null key can never be surfaced to an operator nor cleared — it wedges forever. The
+  // conformance-record worker already guards its own call site, but `recordConformance` is a public
+  // API: reject the untrackable combination here too so no future caller can encode it.
+  if (reviewStatus === CONFORMANCE_REVIEWING_STATUS && processKey == null) {
+    throw new Error(
+      `recordConformance: ${planKey} would persist review_status='reviewing' with no process_key — ` +
+        "refusing to record an untrackable escalation that no poller or onTerminated binding can clear",
+    );
+  }
+  const fields = {
+    status: input.status,
+    comment_url: input.commentUrl ?? null,
+    slices_met: input.slicesMet ?? 0,
+    slices_reduced: input.slicesReduced ?? 0,
+    slices_not_verified: input.slicesNotVerified ?? 0,
+    deviations_raised: input.deviationsRaised ?? 0,
+    deviations_unraised: input.deviationsUnraised ?? 0,
+    has_deviations: input.hasDeviations ? 1 : 0,
+    summary: input.summary ?? null,
+    report: input.report ?? null,
+    process_key: processKey,
+    review_status: reviewStatus,
+    updated_at: ts,
+  };
+  try {
+    await conformanceTbl(data).insert({ plan_key: planKey, created_at: ts, ...fields });
+  } catch (err) {
+    if (!isUniqueViolation(err)) throw err;
+    await conformanceTbl(data).update(planKey, fields);
+  }
+}
+
+/** Settle a conformance run's escalation once the operator acknowledges it: flip `review_status` to
+ * `reviewed` so `pollUserTasks` stops scanning it (its inbox row is already gone once the ack task
+ * closes) and stamp the disposition note into `summary` for the audit trail. Needed because the
+ * `retro` instance COMPLETES normally after the ack — `instanceTracking.onTerminated` only fires on a
+ * TERMINATED (crashed) instance, never a completed one, so nothing else would clear `reviewing`. */
+export async function acknowledgeConformance(
+  data: DataLayer,
+  planKey: string,
+  note?: string | null,
+): Promise<void> {
+  const trimmed = typeof note === "string" && note.trim() ? note.trim() : null;
+  const existing = await conformanceTbl(data).get(planKey);
+  // Invariant: the ack task only fires after the escalation parked this exact `planKey` at
+  // `review_status='reviewing'`, so the row must exist. A missing row means a wrong/mismatched
+  // `planKey` (or unexpected DB state); silently returning would let the `retro` instance COMPLETE
+  // while the real conformance row stays stuck in `reviewing`, so `pollUserTasks` scans it forever.
+  // Fail loudly so the job retries/alerts instead of silently encoding the mismatch.
+  if (!existing) {
+    throw new Error(
+      `acknowledgeConformance: no plan_conformance row for ${planKey} — ` +
+        "refusing to settle a missing/mismatched escalation that would leave the real row stuck in 'reviewing'",
+    );
+  }
+  // At-least-once worker semantics can retry `pr.conformance-ack` after a successful DB update; the
+  // row is already settled at `reviewed`, so short-circuit to keep the operation idempotent (a retry
+  // must not re-append a duplicate `Operator ack: …` block to the audit trail).
+  if (existing.review_status === "reviewed") return;
+  const prior = typeof existing.summary === "string" ? existing.summary : null;
+  const summary = trimmed ? (prior ? `${prior}\n\nOperator ack: ${trimmed}` : `Operator ack: ${trimmed}`) : prior;
+  await conformanceTbl(data).update(planKey, {
+    review_status: "reviewed",
+    summary,
+    updated_at: now(),
+  });
+}

package/app/dbFence.ts

@@ -0,0 +1,18 @@
+// nano-workforce — the ONE canonical classifier for a SQLite UNIQUE-constraint fence collision.
+//
+// A durable fence is a DB-level UNIQUE constraint that a check-then-insert races against: two
+// concurrent/duplicate writers both observe "no row" and both attempt the insert, so the loser hits
+// `UNIQUE constraint failed`. Turning that collision into the SAME intended idempotent outcome
+// (instead of a spurious job failure) is a recurring pattern across the app — the world store's
+// checkpoint/effect ledger (`db/migrations/049_world_checkpoint.sql`) and the merges-audit abandon
+// guard (`abandonClosedPr`, `db/migrations/053_merges_abandon_dedupe.sql`) both rely on it.
+//
+// This is the ONE place that classifies the collision so every catch site shares a single
+// implementation rather than re-encoding the driver's error shape (AGENTS.md: "no drift surfaces").
+// Matched on the message substring the RAD `Table` surface propagates verbatim — the same one the
+// schema/migration tests assert on — because that surface hides the concrete driver error type.
+
+/** True when `err` is a SQLite `UNIQUE constraint failed` — the durable fence firing. */
+export function isUniqueConstraintFence(err: unknown): boolean {
+  return err instanceof Error && /UNIQUE constraint failed/i.test(err.message);
+}

package/app/instance-tracking.test.ts

@@ -11,6 +11,7 @@ import { PR_ACTIVE_STATUSES, PLAN_ACTIVE_STATUSES, FEATURE_ACTIVE_STATUSES } fro
 import { TERMINAL_STATUSES } from "./delivery.ts";
 import { PLAN_TERMINAL_STATUSES } from "./plan.ts";
 import { FEATURE_TERMINAL_STATUSES } from "./feature.ts";
+import { CONFORMANCE_REVIEWING_STATUS } from "./conformance.ts";
 
 interface Binding {
   table: string;
@@ -117,3 +118,26 @@ test("FEATURE_ACTIVE_STATUSES is derived from the manifest binding (no drift)",
   const b = bindingFor(await bindings(), "feature_runs");
   assertEquals([...FEATURE_ACTIVE_STATUSES].sort(), [...(b.activeStatuses ?? [])].sort());
 });
+
+// The retro conformance-escalation lifecycle has exactly one in-flight `review_status` — `reviewing`
+// (the only status `pollUserTasks` scans via `activeConformanceReviews`) — and settles to `reviewed`.
+// Tie the manifest binding to the code's single source of truth (`CONFORMANCE_REVIEWING_STATUS`) so
+// the two can't drift: if a future change adds a new in-flight status but forgets the manifest, a
+// terminated retro instance would strand in `review_status='reviewing'` and never clear (issue #96
+// class of drift — the exact gap Copilot flagged on this binding).
+test("instanceTracking: plan_conformance activeStatuses is exactly the reviewing status (no drift)", async () => {
+  const b = bindingFor(await bindings(), "plan_conformance");
+  assertEquals([...(b.activeStatuses ?? [])].sort(), [CONFORMANCE_REVIEWING_STATUS]);
+});
+
+// The settled status the reconciler flips a terminated row to (`onTerminated.set.review_status`)
+// must NOT itself be listed active — otherwise `onTerminated` would leave the row scannable and the
+// reconciler could clobber a settled run (mirrors the "excludes every terminal status" guards above).
+test("instanceTracking: plan_conformance onTerminated status is not active", async () => {
+  const b = bindingFor(await bindings(), "plan_conformance");
+  const settled = b.onTerminated.set.review_status;
+  assert(
+    typeof settled === "string" && !b.activeStatuses?.includes(settled),
+    `onTerminated review_status "${String(settled)}" must not be listed active`,
+  );
+});

package/app/migration053.test.ts

@@ -0,0 +1,84 @@
+// Regression guard for migration 053 (#352, PR #354 review — suppressed advisory on app/service.ts:867):
+// the DB-level fence that makes `abandonClosedPr`'s terminal audit write TRULY idempotent under a
+// concurrent race, not merely best-effort. The partial `UNIQUE INDEX ux_merges_abandon_pr_closed ON
+// merges(pr_key) WHERE outcome='abandoned' AND method='pr-closed'` IS the fence: the merge worker and
+// the wave-gate self-heal path can both observe "no row" between the guard's `find` and its `insert`
+// and both attempt the write, and this index is what turns the loser's insert into a catchable
+// `UNIQUE constraint failed` instead of a duplicate audit row.
+import { readFileSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { assert, assertEquals, assertThrows } from "#test-assert";
+
+// The `merges` audit table as created by 004_merge.sql, minus the `pull_requests` FK parent (this
+// test proves the index behaviour in isolation, exactly as migration049.test.ts hosts the world
+// tables FK-free). Then apply 053 on top.
+function migratedDb(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  db.exec(`CREATE TABLE merges (
+    id       INTEGER PRIMARY KEY AUTOINCREMENT,
+    pr_key   TEXT NOT NULL,
+    outcome  TEXT NOT NULL,
+    method   TEXT,
+    detail   TEXT,
+    at       TEXT NOT NULL
+  );`);
+  const sql = readFileSync(fileURLToPath(new URL("../db/migrations/053_merges_abandon_dedupe.sql", import.meta.url)), "utf8");
+  db.exec(sql);
+  return db;
+}
+
+const insertAbandon = (db: DatabaseSync, prKey: string) =>
+  db
+    .prepare("INSERT INTO merges (pr_key, outcome, method, detail, at) VALUES (?, 'abandoned', 'pr-closed', 'd', 't')")
+    .run(prKey);
+
+test("migration 053 applies cleanly and enforces one abandoned/pr-closed row per pr_key", () => {
+  const db = migratedDb();
+  insertAbandon(db, "o/r#1");
+  // The race: a second observer inserting the SAME abandoned/pr-closed row now hits the fence.
+  assertThrows(() => insertAbandon(db, "o/r#1"), undefined, "UNIQUE constraint failed");
+  assertEquals(
+    Number((db.prepare("SELECT COUNT(*) c FROM merges WHERE pr_key='o/r#1'").get() as { c: number }).c),
+    1,
+    "the loser's duplicate was rejected — one terminal audit row survives",
+  );
+  // A DIFFERENT PR's abandon is independent — the index is per pr_key, not global.
+  insertAbandon(db, "o/r#2");
+  assertEquals(Number((db.prepare("SELECT COUNT(*) c FROM merges").get() as { c: number }).c), 2);
+});
+
+test("migration 053 only fences abandoned/pr-closed rows — merged/queued/blocked still repeat freely", () => {
+  const db = migratedDb();
+  const insertMerged = () =>
+    db.prepare("INSERT INTO merges (pr_key, outcome, method, detail, at) VALUES ('o/r#3','merged','squash','d','t')").run();
+  // A PR can carry several `merged` audit rows (retry / already-merged short-circuit) — the partial
+  // index must NOT constrain them (mergesPerDay dedupes with COUNT(DISTINCT pr_key)).
+  insertMerged();
+  insertMerged();
+  assertEquals(Number((db.prepare("SELECT COUNT(*) c FROM merges WHERE outcome='merged'").get() as { c: number }).c), 2);
+  // An abandoned row with a DIFFERENT method is also outside the partial predicate.
+  db.prepare("INSERT INTO merges (pr_key, outcome, method, detail, at) VALUES ('o/r#3','abandoned','other','d','t')").run();
+  db.prepare("INSERT INTO merges (pr_key, outcome, method, detail, at) VALUES ('o/r#3','abandoned','other','d','t')").run();
+  assertEquals(Number((db.prepare("SELECT COUNT(*) c FROM merges WHERE method='other'").get() as { c: number }).c), 2);
+});
+
+test("migration 053 collapses pre-existing duplicate abandoned/pr-closed rows, keeping the earliest", () => {
+  // Simulate a database where the pre-fence race already wrote duplicates, then apply the migration.
+  const db = new DatabaseSync(":memory:");
+  db.exec(`CREATE TABLE merges (
+    id INTEGER PRIMARY KEY AUTOINCREMENT, pr_key TEXT NOT NULL, outcome TEXT NOT NULL,
+    method TEXT, detail TEXT, at TEXT NOT NULL);`);
+  db.prepare("INSERT INTO merges (pr_key,outcome,method,detail,at) VALUES ('o/r#9','abandoned','pr-closed','first','t')").run();
+  db.prepare("INSERT INTO merges (pr_key,outcome,method,detail,at) VALUES ('o/r#9','abandoned','pr-closed','dup','t')").run();
+  db.prepare("INSERT INTO merges (pr_key,outcome,method,detail,at) VALUES ('o/r#8','abandoned','pr-closed','solo','t')").run();
+  const sql = readFileSync(fileURLToPath(new URL("../db/migrations/053_merges_abandon_dedupe.sql", import.meta.url)), "utf8");
+  db.exec(sql); // dedupe + create index; must not throw despite the pre-existing duplicate
+  const rows = db.prepare("SELECT pr_key, detail FROM merges ORDER BY pr_key").all() as { pr_key: string; detail: string }[];
+  assertEquals(rows.length, 2, "the duplicate for o/r#9 was collapsed");
+  assert(
+    rows.some((r) => r.pr_key === "o/r#9" && r.detail === "first"),
+    "the EARLIEST (MIN(id)) row survived the collapse",
+  );
+});

package/app/plan.ts

@@ -181,6 +181,12 @@ export const PLAN_TASK_STATUSES = [
   "skipped",
   "escalated",
   "waiting-for-lane",
+  // Terminal: the task's PR was closed on GitHub without merging (abandoned / superseded /
+  // perpetually conflicting). Set by the canonical abandon writer (`abandonClosedPr`, app/service.ts)
+  // reached from BOTH the merge stage and the wave-merge gate. An `abandoned` task drops out of
+  // `waveMergeTargets` (so a dead member never wedges the wave barrier — #352) and stops
+  // `isPlanComplete`/the Epics table counting a phantom open task.
+  "abandoned",
 ] as const;
 export type PlanTaskStatus = typeof PLAN_TASK_STATUSES[number];
 

package/app/pollUserTasks.test.ts

@@ -209,6 +209,43 @@ test("pollUserTasks: projects a blocked feature run (feature-blocked) with the d
   assertEquals(byKey["ut-blocked"].question, "agent gave up: no PR");
 });
 
+test("pollUserTasks: projects a conformance-escalation ack (issue #216) keyed to the epic, question from summary", async () => {
+  // The advisory `retro` process parks on a native `conformance-escalation` user task when the
+  // spec-conformance audit found the epic did not cleanly meet its spec. retro is not a delivery
+  // aggregate, so its instance is tracked on `plan_conformance` (review_status = 'reviewing'); the
+  // poller scans those rows, reads the open ack task from the engine, and projects it under the epic
+  // (plan) subject with the audit `summary` as its question. A settled ('reviewed') row is skipped.
+  const { data, stores } = memData({
+    plan_conformance: [
+      {
+        plan_key: "o/r#70",
+        process_key: "cp-70",
+        review_status: "reviewing",
+        summary: "slice 2 reduced; auth cache never verified",
+      },
+      { plan_key: "o/r#71", process_key: "cp-71", review_status: "reviewed", summary: "all clean" },
+    ],
+    plans: [
+      { plan_key: "o/r#70", status: "done", issue_url: "https://github.com/o/r/issues/70", title: "Ship the cache" },
+    ],
+  });
+  const engine = fakeEngine({
+    "cp-70": [{ userTaskKey: "ut-conf", elementId: "conformance-escalation" }],
+    "cp-71": [{ userTaskKey: "ut-conf-settled", elementId: "conformance-escalation" }],
+  });
+
+  await pollUserTasks(data, engine);
+
+  const byKey = Object.fromEntries((stores.user_tasks ?? []).map((r) => [r.user_task_key, r]));
+  assertEquals(Object.keys(byKey), ["ut-conf"]);
+  assertEquals(byKey["ut-conf"].element_id, "conformance-escalation");
+  assertEquals(byKey["ut-conf"].kind_label, "Conformance review");
+  assertEquals(byKey["ut-conf"].subject_type, "plan");
+  assertEquals(byKey["ut-conf"].subject_key, "o/r#70");
+  assertEquals(byKey["ut-conf"].subject_title, "Ship the cache");
+  assertEquals(byKey["ut-conf"].question, "slice 2 reduced; auth cache never verified");
+});
+
 test("pollUserTasks: removes a row once its task is no longer open (completed / out-of-band)", async () => {
   const { data, stores } = memData({
     user_tasks: [

package/app/retro.test.ts

@@ -166,6 +166,17 @@ test("gatherRetro: separates learnings from notes and folds in deltas", async ()
   assertEquals(d.repo, "acme/widgets");
 });
 
+test("gatherRetro: uses pre-fetched blackboard entries instead of re-scanning", async () => {
+  const { data, stores } = memData();
+  seedPlan(stores);
+  // A learning lives in the store, but the caller passes an EMPTY pre-fetched snapshot — gatherRetro
+  // must honour what it was handed and not re-read the store.
+  await appendEntry(data, PLAN, { author_task: "t1", kind: "learning", body: "should be ignored" });
+  const d = await gatherRetro(data, PLAN, []);
+  assertEquals(d.counts.learnings, 0);
+  assertEquals(d.notes.length, 0);
+});
+
 test("gatherRetro: folds in the plan-review trace and task-outcome shape", async () => {
   const { data, stores } = memData();
   seedPlan(stores);
@@ -382,11 +393,13 @@ test("maybeStartRetro: bails while the plan is incomplete", async () => {
   assertEquals(stores["plans"][0].retro_started_at, null, "must not stamp an incomplete plan");
 });
 
-test("maybeStartRetro: complete but empty → records a skipped retro, does not start the process", async () => {
+test("maybeStartRetro: complete but nothing landed (PR abandoned) → records a skipped retro, does not start", async () => {
   const { data, stores } = memData();
   seedPlan(stores);
+  // The only task's PR was abandoned: the plan is complete (abandoned is terminal) but shipped no
+  // code, so there is neither reflection material nor an implementation to audit.
   seedTask(stores, { id: "t1", status: "opened", pr_key: "acme/widgets#10" });
-  seedPr(stores, "acme/widgets#10", "merged");
+  seedPr(stores, "acme/widgets#10", "abandoned");
   const { engine, started } = fakeEngine();
 
   const r = await maybeStartRetro(data, engine, "acme/widgets#10");
@@ -397,6 +410,23 @@ test("maybeStartRetro: complete but empty → records a skipped retro, does not
   assertEquals(stores["plan_retros"][0].status, "skipped");
 });
 
+test("maybeStartRetro: complete with landed code but no learnings → still starts (conformance has something to verify)", async () => {
+  const { data, stores } = memData();
+  seedPlan(stores);
+  // A merged PR but zero learnings/deltas/notes: the retro digest is empty, but there IS delivered
+  // implementation to audit for conformance — so the process must still start.
+  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, true);
+  assertEquals(r.planKey, PLAN);
+  assertEquals(started.length, 1);
+  assertEquals(started[0].processDefinitionId, "retro");
+  assert(stores["plans"][0].retro_started_at, "retro_started_at must be stamped");
+});
+
 test("maybeStartRetro: a rejected review round alone is enough to fire the retro", async () => {
   const { data, stores } = memData();
   seedPlan(stores);

package/app/retro.ts

@@ -14,7 +14,8 @@
 // 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, Logger } from "@nanobpm/urban";
-import { isUniqueViolation, readBlackboard } from "./blackboard.ts";
+import { type BlackboardEntry, isUniqueViolation, readBlackboard } from "./blackboard.ts";
+import { hasDeliveredImplementationForPlan } from "./conformance.ts";
 import { TERMINAL_STATUSES } from "./delivery.ts";
 import { planReviews, planTasks } from "./plan.ts";
 import { aggregateEpicDeltas } from "./taskDelta.ts";
@@ -110,14 +111,22 @@ export interface RetroDigest {
 /** 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> {
+ * non-learning blackboard notes for colour. Reads only — no writes.
+ *
+ * `entries` lets a caller that has already scanned the blackboard for this plan (e.g.
+ * `pr.retro-gather`, which also runs {@link gatherConformance}) pass those entries in so the plan is
+ * scanned once, not once per gatherer — see workers/retro-gather. Omitted, it reads them itself. */
+export async function gatherRetro(
+  data: DataLayer,
+  planKey: string,
+  entries?: BlackboardEntry[],
+): Promise<RetroDigest> {
   const plan = await plansTbl(data).get(planKey);
-  const entries = await readBlackboard(data, planKey);
-  const learnings = entries
+  const bbEntries = entries ?? (await readBlackboard(data, planKey));
+  const learnings = bbEntries
     .filter((e) => e.kind === "learning")
     .map((e) => ({ author_task: e.author_task, body: e.body, created_at: e.created_at }));
-  const notes = entries
+  const notes = bbEntries
     .filter((e) => e.kind !== "learning")
     .map((e) => ({ author_task: e.author_task, kind: e.kind, body: e.body }));
   const deltas = await aggregateEpicDeltas(data, planKey);
@@ -310,12 +319,19 @@ export async function maybeStartRetro(
     if (!(await isPlanComplete(data, planKey))) return { started: false, planKey, reason: "incomplete" };
 
     const digest = await gatherRetro(data, planKey);
-    if (isDigestEmpty(digest)) {
+    // The retro digest can be empty (no learnings/deltas/notes, cleanly-approved plan) yet the epic
+    // still shipped real code — in which case conformance has something to verify even though the
+    // lessons agent has nothing to distil. So run whenever there is EITHER reflection material OR
+    // landed implementation to audit; only truly skip when there is neither. The landed-implementation
+    // probe is gathered lazily (only when the digest is empty) and via the lightweight
+    // hasDeliveredImplementationForPlan — which inspects only plan_tasks + PR status, with no
+    // blackboard scan — so we avoid discarded DB work on every terminal-PR event.
+    if (isDigestEmpty(digest) && !(await hasDeliveredImplementationForPlan(data, planKey))) {
       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.
+      // Nothing to reflect on and nothing shipped to verify — 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." });
+      await recordRetro(data, planKey, { status: "skipped", summary: "No learnings, deltas, notes, or landed implementation to retrospect." });
       return { started: false, planKey, reason: "nothing-to-retro" };
     }