@nanobpm/nano-workforce 0.104.0 → 0.105.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.105.0](https://github.com/nanobpm/nano-workforce/compare/v0.104.0...v0.105.0) (2026-08-19)
+
+
+### Features
+
+* examine epic implementation against spec in retro (conformance) ([#355](https://github.com/nanobpm/nano-workforce/issues/355)) ([c52d059](https://github.com/nanobpm/nano-workforce/commit/c52d0594d767c551d31ed967d1ef79cb30e82ceb)), closes [#217](https://github.com/nanobpm/nano-workforce/issues/217) [#216](https://github.com/nanobpm/nano-workforce/issues/216) [#217](https://github.com/nanobpm/nano-workforce/issues/217)
+
 # [0.104.0](https://github.com/nanobpm/nano-workforce/compare/v0.103.0...v0.104.0) (2026-08-19)
 
 

package/README.md

@@ -153,6 +153,7 @@ capability):
 | `fix-ci` | `senior:fix-ci` | `merge-loop` | Green a `blocked` PR's failing checks |
 | `rebase` | `senior:rebase` | `merge-loop` | Rebase a conflicting PR up to date with its base |
 | `retro` | `senior:retro` | `retro` | Synthesize a finished epic's learnings and promote the recurring ones |
+| `conformance` | `senior:conformance` | `retro` | Examine a finished epic's implementation against its spec; report met/deviations on the issue |
 
 - `--command 'copilot -p - --allow-all-tools'` starts the Copilot CLI reading its
   prompt from **stdin** (`-p -`). The harness pipes the whole job JSON (prompt +

package/app/abandon.ts

@@ -20,11 +20,20 @@
 import type { DataLayer } from "@nanobpm/urban";
 import { publicBaseUrl } from "./blackboard.ts";
 
-/** The one app-row status that means "this run was cancelled". Convergence/merge terminal states
- * `converged`/`merged` are NOT abandonment — only an explicit cancel flips a live run here. */
+/** The one app-row status meaning a PR is terminally abandoned — the run must not be worked on
+ * further. Two disjoint producers flip a row here, and both are non-completion terminals that must
+ * stop a servicing agent:
+ *   1. an explicit **cancel** of a live convergence/merge run (Urban's cancel primitive, via the
+ *      `instanceTracking` `onTerminated.set` patch), and
+ *   2. **`abandonClosedPr`** reconciling a wave-member PR that was **closed on GitHub without
+ *      merging** (#352) — for both `pull_requests` and its `plan_tasks`.
+ * Convergence/merge terminal states `converged`/`merged` are NOT abandonment. In either abandoned
+ * case a servicing agent should stop, so the abandon-check endpoint treating both as `abandoned:
+ * true` is correct. */
 export const ABANDONED_STATUS = "abandoned";
 
-/** True when a PR's app-row status means the run was cancelled and the agent must not act. */
+/** True when a PR's app-row status is terminally abandoned (run cancelled, or PR closed-unmerged)
+ * and the agent must not act. */
 export function isAbandoned(status: string | null | undefined): boolean {
   return status === ABANDONED_STATUS;
 }

package/app/conformance.test.ts

@@ -0,0 +1,220 @@
+// Unit tests for the spec-conformance review stage (app/conformance.ts, 052_plan_conformance.sql).
+import { test } from "node:test";
+import { assert, assertEquals, assertStringIncludes } from "#test-assert";
+import type { DataLayer } from "@nanobpm/urban";
+import { memBlackboardSource } from "../test/blackboardDb.ts";
+import { appendEntry } from "./blackboard.ts";
+import {
+  gatherConformance,
+  hasDeliveredImplementation,
+  hasDeliveredImplementationForPlan,
+  recordConformance,
+  renderConformanceBrief,
+} from "./conformance.ts";
+
+// In-memory record gateway matching the Table<T> subset conformance.ts uses.
+function memData(): { data: DataLayer; stores: Record<string, any[]> } {
+  const stores: Record<string, any[]> = {};
+  const seq: Record<string, number> = {};
+  function tbl(name: string, pk = "id") {
+    const rows = (stores[name] ??= [] as any[]);
+    const match = (r: any, where: any) => Object.entries(where).every(([k, v]) => r[k] === v);
+    return {
+      async insert(row: any) {
+        if (pk !== "id" && rows.some((r) => r[pk] === row[pk])) {
+          throw new Error(`UNIQUE constraint failed: ${name}.${pk}`);
+        }
+        const id = (seq[name] = (seq[name] ?? 0) + 1);
+        rows.push(pk === "id" ? { id, ...row } : { ...row });
+        return pk === "id" ? id : row[pk];
+      },
+      async find(where: any = {}) {
+        return rows.filter((r) => match(r, where));
+      },
+      async findOne(where: any = {}) {
+        return rows.find((r) => match(r, where));
+      },
+      async get(id: any) {
+        return rows.find((row) => row[pk] === id);
+      },
+      async update(id: any, patch: any) {
+        const r = rows.find((row) => row[pk] === id);
+        if (r) Object.assign(r, patch);
+      },
+    };
+  }
+  const data = { table: (n: string, pk?: string) => tbl(n, pk), source: memBlackboardSource().source } as any as DataLayer;
+  return { data, stores };
+}
+
+const PLAN = "acme/widgets#7";
+
+function seedPlan(stores: Record<string, any[]>) {
+  stores["plans"] = [{
+    plan_key: PLAN,
+    repo: "acme/widgets",
+    issue_url: "https://github.com/acme/widgets/issues/7",
+    title: "Widgets epic",
+    status: "done",
+  }];
+}
+function seedTask(stores: Record<string, any[]>, task: Record<string, unknown>) {
+  (stores["plan_tasks"] ??= []).push({ plan_key: PLAN, ...task });
+}
+function seedPr(stores: Record<string, any[]>, pr_key: string, status: string) {
+  (stores["pull_requests"] ??= []).push({ pr_key, status });
+}
+
+test("gatherConformance: collects the spec, only LANDED PRs, and raised scope-changes", async () => {
+  const { data, stores } = memData();
+  seedPlan(stores);
+  seedTask(stores, { id: 1, task_index: 0, task_id: "t1", title: "Auth", prompt: "add JWT auth", status: "opened", pr_key: "acme/widgets#10" });
+  seedTask(stores, { id: 2, task_index: 1, task_id: "t2", title: "Rate limit", prompt: "add rate limiting", status: "opened", pr_key: "acme/widgets#11" });
+  seedTask(stores, { id: 3, task_index: 2, task_id: "t3", title: "Webhook", prompt: "retry webhooks", status: "opened", pr_key: "acme/widgets#12" });
+  seedTask(stores, { id: 4, task_index: 3, task_id: "t4", title: "Docs", prompt: "write docs", status: "skipped", pr_key: null });
+  seedPr(stores, "acme/widgets#10", "merged"); // landed
+  seedPr(stores, "acme/widgets#11", "converged"); // landed (review-only)
+  seedPr(stores, "acme/widgets#12", "abandoned"); // NOT landed
+  await appendEntry(data, PLAN, { author_task: "t2", kind: "scope-change", body: "narrowed rate limit to per-IP only" });
+  await appendEntry(data, PLAN, { author_task: "t1", kind: "learning", body: "not a scope change" });
+
+  const d = await gatherConformance(data, PLAN);
+  assertEquals(d.repo, "acme/widgets");
+  assertEquals(d.issueUrl, "https://github.com/acme/widgets/issues/7");
+  assertEquals(d.slices.length, 4);
+  // Only merged/converged PRs are "delivered"; abandoned and task-less slices are excluded.
+  assertEquals(d.deliveredPrs, ["acme/widgets#10", "acme/widgets#11"]);
+  assertEquals(d.slices.find((s) => s.taskId === "t3")?.landed, false);
+  assertEquals(d.slices.find((s) => s.taskId === "t4")?.landed, false);
+  // Only scope-change entries surface as raised deviations — learnings are ignored.
+  assertEquals(d.scopeChanges.length, 1);
+  assertEquals(d.scopeChanges[0].author_task, "t2");
+});
+
+test("gatherConformance: sorts slices by task_index", async () => {
+  const { data, stores } = memData();
+  seedPlan(stores);
+  seedTask(stores, { id: 1, task_index: 2, task_id: "t3", status: "skipped", pr_key: null });
+  seedTask(stores, { id: 2, task_index: 0, task_id: "t1", status: "skipped", pr_key: null });
+  seedTask(stores, { id: 3, task_index: 1, task_id: "t2", status: "skipped", pr_key: null });
+  const d = await gatherConformance(data, PLAN);
+  assertEquals(d.slices.map((s) => s.taskId), ["t1", "t2", "t3"]);
+});
+
+test("gatherConformance: uses pre-fetched blackboard entries instead of re-scanning", async () => {
+  const { data, stores } = memData();
+  seedPlan(stores);
+  seedTask(stores, { id: 1, task_index: 0, task_id: "t1", status: "skipped", pr_key: null });
+  // A scope-change lives in the store, but the caller passes an EMPTY pre-fetched snapshot — the
+  // function must honour what it was handed and not re-read the store.
+  await appendEntry(data, PLAN, { author_task: "t1", kind: "scope-change", body: "should be ignored" });
+  const d = await gatherConformance(data, PLAN, []);
+  assertEquals(d.scopeChanges.length, 0);
+});
+
+test("hasDeliveredImplementation: true iff at least one PR landed", async () => {
+  const { data, stores } = memData();
+  seedPlan(stores);
+  seedTask(stores, { id: 1, task_index: 0, task_id: "t1", status: "opened", pr_key: "acme/widgets#10" });
+  seedPr(stores, "acme/widgets#10", "abandoned");
+  assert(!hasDeliveredImplementation(await gatherConformance(data, PLAN)));
+  stores["pull_requests"] = [{ pr_key: "acme/widgets#10", status: "merged" }];
+  assert(hasDeliveredImplementation(await gatherConformance(data, PLAN)));
+});
+
+test("hasDeliveredImplementationForPlan: matches the digest without a blackboard scan", async () => {
+  const { data, stores } = memData();
+  seedPlan(stores);
+  seedTask(stores, { id: 1, task_index: 0, task_id: "t1", status: "opened", pr_key: "acme/widgets#10" });
+  seedTask(stores, { id: 2, task_index: 1, task_id: "t2", status: "skipped", pr_key: null });
+  seedPr(stores, "acme/widgets#10", "abandoned");
+  // No landed PR yet — agrees with the full-digest helper.
+  assertEquals(await hasDeliveredImplementationForPlan(data, PLAN), false);
+  assertEquals(hasDeliveredImplementation(await gatherConformance(data, PLAN)), false);
+  // A landed PR flips both to true.
+  stores["pull_requests"] = [{ pr_key: "acme/widgets#10", status: "converged" }];
+  assertEquals(await hasDeliveredImplementationForPlan(data, PLAN), true);
+  assertEquals(hasDeliveredImplementation(await gatherConformance(data, PLAN)), true);
+  // The cheap check must not touch the blackboard.
+  const before = (stores["blackboard"] ?? []).length;
+  await hasDeliveredImplementationForPlan(data, PLAN);
+  assertEquals((stores["blackboard"] ?? []).length, before);
+});
+
+test("renderConformanceBrief: lists PRs to examine, the spec, and raised deviations", () => {
+  const brief = renderConformanceBrief({
+    planKey: PLAN,
+    repo: "acme/widgets",
+    issueUrl: "https://x/7",
+    title: "Epic",
+    slices: [
+      { taskId: "t1", title: "Auth", prompt: "add JWT auth", status: "opened", prKey: "acme/widgets#10", landed: true },
+      { taskId: "t2", title: "Docs", prompt: null, status: "skipped", prKey: null, landed: false },
+    ],
+    deliveredPrs: ["acme/widgets#10"],
+    scopeChanges: [{ author_task: "t1", body: "narrowed to per-IP", created_at: "now" }],
+  });
+  assertStringIncludes(brief, "gh pr diff");
+  assertStringIncludes(brief, "acme/widgets#10");
+  assertStringIncludes(brief, "add JWT auth");
+  assertStringIncludes(brief, "narrowed to per-IP");
+  assertStringIncludes(brief, "RAISED during implementation");
+});
+
+test("renderConformanceBrief: states 'none' for no delivered PRs and no scope-changes", () => {
+  const brief = renderConformanceBrief({
+    planKey: PLAN, repo: "acme/widgets", issueUrl: "", title: null,
+    slices: [], deliveredPrs: [], scopeChanges: [],
+  });
+  assertStringIncludes(brief, "no implementation to verify");
+  assertStringIncludes(brief, "treat any deviation you find as UNRAISED");
+});
+
+test("recordConformance: inserts then updates the same plan_key row in place", async () => {
+  const { data, stores } = memData();
+  await recordConformance(data, PLAN, {
+    status: "filed",
+    commentUrl: "https://x/7#issuecomment-1",
+    slicesMet: 4,
+    slicesReduced: 1,
+    slicesNotVerified: 1,
+    deviationsRaised: 2,
+    deviationsUnraised: 1,
+    hasDeviations: true,
+    summary: "6 items, 4 met",
+    report: "full report",
+  });
+  assertEquals(stores["plan_conformance"].length, 1);
+  const row = stores["plan_conformance"][0];
+  assertEquals(row.status, "filed");
+  assertEquals(row.comment_url, "https://x/7#issuecomment-1");
+  assertEquals(row.slices_met, 4);
+  assertEquals(row.has_deviations, 1);
+
+  await recordConformance(data, PLAN, { status: "skipped", summary: "nothing shipped" });
+  assertEquals(stores["plan_conformance"].length, 1, "same plan_key must not duplicate");
+  assertEquals(stores["plan_conformance"][0].status, "skipped");
+  assertEquals(stores["plan_conformance"][0].has_deviations, 0);
+});
+
+test("recordConformance: rethrows a non-unique (FOREIGN KEY) constraint error instead of swallowing it", async () => {
+  let updated = false;
+  const table = {
+    async insert() {
+      throw new Error("FOREIGN KEY constraint failed");
+    },
+    async update() {
+      updated = true;
+    },
+  };
+  const data = { table: () => table } as any as DataLayer;
+  let threw = false;
+  try {
+    await recordConformance(data, PLAN, { status: "filed" });
+  } catch (err) {
+    threw = true;
+    assertStringIncludes(String(err), "FOREIGN KEY");
+  }
+  assert(threw, "the FK error must propagate");
+  assertEquals(updated, false, "must not silently fall back to update on a non-unique error");
+});

package/app/conformance.ts

@@ -0,0 +1,240 @@
+// 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();
+
+/** 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");
+
+/** 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;
+}
+
+/** 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 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,
+    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);
+  }
+}

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/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];