@nanobpm/nano-workforce 0.104.0 → 0.106.0

package/app/service.test.ts

@@ -6,11 +6,11 @@
 // loop already guards in `startPlan`). Drives `submitPr` against an in-memory data layer with the
 // GitHub transport forced off so it is hermetic.
 import { test } from "node:test";
-import { assertEquals } from "#test-assert";
+import { assertEquals, assertRejects, assertStringIncludes } from "#test-assert";
 import { memDataFor } from "../test/worldDb.ts";
 import { DurableResumeRegistry } from "./durableResume.ts";
 import { WorldStore } from "./world/index.ts";
-import { parsePr, pollCapabilityGatesImpl, pollIncidentsImpl, pollWaveGatesImpl, repoEnvelopeVars, startMerge, submitPr, worldRestoreSha } from "./service.ts";
+import { abandonClosedPr, parsePr, pollCapabilityGatesImpl, pollIncidentsImpl, pollWaveGatesImpl, repoEnvelopeVars, startMerge, submitPr, worldRestoreSha } from "./service.ts";
 
 function memTable(rows: any[], key: string) {
   return {
@@ -755,7 +755,195 @@ test("pollWaveGatesImpl never releases the barrier on an unverifiable subscripti
   });
 });
 
-// ── pollCapabilityGatesImpl — the host half of the cross-repo capability edge (issue #289) ──────────
+// #352: a wave WEDGES forever at `wait-wave-merged` when one member PR is closed on GitHub WITHOUT
+// merging (abandoned / superseded / perpetually conflicting). The old gate released only when EVERY
+// wave-target PR reached `merged`, so a closed-unmerged member kept `allMerged = false` forever and
+// the epic could never advance. The fix classifies each target against live GitHub state and, for a
+// closed-unmerged one, (a) treats it as NON-blocking so the wave completes on its surviving merged
+// members and (b) reconciles it terminal — flipping BOTH the `pull_requests` row and its
+// `plan_tasks` row to `abandoned` so it drops out of `waveMergeTargets` and the epic read model.
+//
+// Forces token transport WITH a token and stubs `fetch` to answer both the single-PR GET (the closed
+// member reports state="closed", merged:false) and `/message-subscriptions/search` (barrier open).
+function closedMemberFetch(open: Set<string>, closedNumbers: Set<number>) {
+  return (url: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    const u = typeof url === "string" ? url : url.toString();
+    const pullMatch = u.match(/\/repos\/[^/]+\/[^/]+\/pulls\/(\d+)$/);
+    if (pullMatch) {
+      const n = Number(pullMatch[1]);
+      const body = closedNumbers.has(n)
+        ? { merged: false, state: "closed", mergeable_state: "dirty" }
+        : { merged: true, state: "closed", mergeable_state: "clean" };
+      return Promise.resolve(
+        new Response(JSON.stringify(body), { status: 200, headers: { "content-type": "application/json" } }),
+      );
+    }
+    if (u.endsWith("/message-subscriptions/search")) {
+      const pik = (JSON.parse(String(init?.body ?? "{}")) as { filter?: { processInstanceKey?: string } })
+        .filter?.processInstanceKey ?? "";
+      const items = open.has(pik)
+        ? [{ messageName: "wave-merged", correlationKey: "owner/repo#67", messageSubscriptionState: "CREATED" }]
+        : [];
+      return Promise.resolve(
+        new Response(JSON.stringify({ items }), { status: 200, headers: { "content-type": "application/json" } }),
+      );
+    }
+    throw new Error(`unexpected fetch: ${u}`);
+  };
+}
+
+test("pollWaveGatesImpl releases the wave when a member PR is closed-unmerged and reconciles it terminal (#352)", async () => {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevTok = process.env["GITHUB_TOKEN"];
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  process.env["GITHUB_TOKEN"] = "test-token"; // token present → fetchPrState hits the stubbed REST GET
+  try {
+    const PLAN_KEY = "owner/repo#67";
+    const PI = "PI-13794";
+    const plan = { plan_key: PLAN_KEY, process_key: PI, gate_wave: 2 as number | null, updated_at: "t0" };
+    const stores: Record<string, { rows: any[]; key: string }> = {
+      plans: { rows: [plan], key: "plan_key" },
+      plan_tasks: {
+        rows: [
+          // A surviving MERGED member (tracked row → no network) and a member whose PR was CLOSED
+          // on GitHub without merging while its task was still `opened` (never reached merge stage).
+          { id: "owner/repo#67:a", plan_key: PLAN_KEY, wave: 2, status: "opened", pr_key: "owner/repo#68" },
+          { id: "owner/repo#67:b", plan_key: PLAN_KEY, wave: 2, status: "opened", pr_key: "owner/repo#70" },
+        ],
+        key: "id",
+      },
+      pull_requests: {
+        rows: [
+          { pr_key: "owner/repo#68", status: "merged" },
+          { pr_key: "owner/repo#70", status: "converging" }, // not merged in the DB → falls to live GitHub read
+        ],
+        key: "pr_key",
+      },
+      merges: { rows: [], key: "id" },
+    };
+    const data = {
+      table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+    } as any;
+
+    const published: { name: string; correlationKey?: string }[] = [];
+    const engine = {
+      publishMessage: (input: { name: string; correlationKey?: string }) => {
+        published.push(input);
+        return Promise.resolve();
+      },
+    } as any;
+    const headers = { "content-type": "application/json" };
+    const prevFetch = globalThis.fetch;
+
+    globalThis.fetch = closedMemberFetch(new Set([PI]), new Set([70])) as typeof fetch;
+    try {
+      await pollWaveGatesImpl(data, engine, "test-token", "http://engine/v2", headers);
+    } finally {
+      globalThis.fetch = prevFetch;
+    }
+
+    // The barrier RELEASES — the closed-unmerged member no longer wedges the wave.
+    assertEquals(published.length, 1, "must publish wave-merged once the closed member is treated non-blocking");
+    assertEquals(published[0]?.name, "wave-merged");
+    assertEquals(published[0]?.correlationKey, PLAN_KEY);
+
+    // The closed member is reconciled terminal: PR row + its plan_tasks row flip to `abandoned`,
+    // and a terminal `merges` audit row is recorded (the canonical abandon writer).
+    const prRow = stores.pull_requests.rows.find((r) => r.pr_key === "owner/repo#70");
+    assertEquals(prRow?.status, "abandoned");
+    const taskRow = stores.plan_tasks.rows.find((r) => r.id === "owner/repo#67:b");
+    assertEquals(taskRow?.status, "abandoned");
+    assertEquals(stores.merges.rows.length, 1);
+    assertEquals((stores.merges.rows[0] as any).outcome, "abandoned");
+    assertEquals((stores.merges.rows[0] as any).method, "pr-closed");
+    // The surviving merged member is untouched.
+    assertEquals(stores.plan_tasks.rows.find((r) => r.id === "owner/repo#67:a")?.status, "opened");
+  } finally {
+    if (prevMode !== undefined) process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+    else delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    if (prevTok !== undefined) process.env["GITHUB_TOKEN"] = prevTok;
+    else delete process.env["GITHUB_TOKEN"];
+  }
+});
+
+// #352 review: `abandonClosedPr` must be genuinely idempotent. It is reached from BOTH observers of a
+// closed-unmerged member (merge worker + wave gate) and can be retried by the poller, so an
+// unconditional `merges` insert would spam the audit with duplicate `outcome:"abandoned"/method:
+// "pr-closed"` rows and skew reporting. Re-running it re-stamps the terminal status but writes the
+// audit row only once.
+test("abandonClosedPr is idempotent — the terminal merges audit row is written at most once (#352)", async () => {
+  const stores: Record<string, { rows: any[]; key: string }> = {
+    pull_requests: { rows: [{ pr_key: "owner/repo#70", status: "converging" }], key: "pr_key" },
+    plan_tasks: { rows: [{ id: "owner/repo#67:b", plan_key: "owner/repo#67", wave: 2, status: "opened", pr_key: "owner/repo#70" }], key: "id" },
+    merges: { rows: [], key: "id" },
+  };
+  const data = {
+    table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+  } as any;
+
+  await abandonClosedPr(data, "owner/repo#70", "closed without merging");
+  await abandonClosedPr(data, "owner/repo#70", "closed without merging"); // retry / second observer
+
+  // Terminal status re-stamped, but exactly one audit row despite two calls.
+  assertEquals(stores.pull_requests.rows.find((r) => r.pr_key === "owner/repo#70")?.status, "abandoned");
+  assertEquals(stores.plan_tasks.rows.find((r) => r.id === "owner/repo#67:b")?.status, "abandoned");
+  assertEquals(stores.merges.rows.length, 1, "no duplicate abandoned/pr-closed audit rows on retry");
+  assertEquals((stores.merges.rows[0] as any).method, "pr-closed");
+});
+
+// #352 review (suppressed advisory app/service.ts:863): `abandonClosedPr` writes the terminal
+// `merges` audit row — an FK child of `pull_requests.pr_key` — and must not assume the parent row
+// exists. The merge-worker caller pre-heals with `ensurePr`, but the wave-gate self-heal path
+// (`pollWaveGatesImpl`) does NOT, so in an engine/app.db desync the canonical writer could observe a
+// closed member whose `pull_requests` row is missing and hit a `FOREIGN KEY constraint failed`,
+// wedging the poller pass. The canonical writer must self-heal the parent (idempotent `ensurePr`)
+// before the FK-child insert, symmetrically for BOTH callers. Read-model witness: with a missing
+// parent row the old code's `prs.update` was a silent no-op, so the PR was never reconciled terminal.
+test("abandonClosedPr self-heals a missing pull_requests parent row before the FK-child audit insert (#352)", async () => {
+  const stores: Record<string, { rows: any[]; key: string }> = {
+    pull_requests: { rows: [], key: "pr_key" }, // desync: parent row is MISSING
+    plan_tasks: { rows: [{ id: "owner/repo#67:c", plan_key: "owner/repo#67", wave: 3, status: "opened", pr_key: "owner/repo#71" }], key: "id" },
+    merges: { rows: [], key: "id" },
+  };
+  const data = {
+    table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+  } as any;
+
+  await abandonClosedPr(data, "owner/repo#71", "closed without merging");
+
+  // The parent row is reconstructed AND flipped terminal, so the FK-child audit row has a parent.
+  const parent = stores.pull_requests.rows.find((r) => r.pr_key === "owner/repo#71");
+  assertEquals(parent?.status, "abandoned", "missing parent pull_requests row is self-healed and reconciled terminal");
+  assertEquals(parent?.repo, "owner/repo", "reconstructed parent carries the parsed repo");
+  assertEquals(parent?.number, 71, "reconstructed parent carries the parsed number");
+  assertEquals(stores.plan_tasks.rows.find((r) => r.id === "owner/repo#67:c")?.status, "abandoned");
+  assertEquals(stores.merges.rows.length, 1, "terminal audit row written once");
+});
+
+// #352 review (suppressed advisory app/service.ts:861): the self-heal only runs when `parsePr(prKey)`
+// succeeds, so a MALFORMED prKey (engine/app.db desync, a process-variable regression) would skip
+// the heal yet still reach `merges.insert` — which, with a missing parent, fails with an opaque
+// `FOREIGN KEY constraint failed`, the exact incident this helper exists to prevent. The canonical
+// writer must fail closed with a clear, actionable error naming the bad key, not leak an FK incident.
+test("abandonClosedPr rejects a malformed prKey with a clear error before any FK-child insert (#352)", async () => {
+  const stores: Record<string, { rows: any[]; key: string }> = {
+    pull_requests: { rows: [], key: "pr_key" },
+    plan_tasks: { rows: [], key: "id" },
+    merges: { rows: [], key: "id" },
+  };
+  const data = {
+    table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+  } as any;
+
+  const err = await assertRejects(() => abandonClosedPr(data, "not-a-valid-pr-key", "closed without merging"));
+  assertStringIncludes((err as Error).message, "malformed prKey");
+  assertStringIncludes((err as Error).message, "not-a-valid-pr-key");
+  // No audit row and no terminal side effects leaked before the guard fired.
+  assertEquals(stores.merges.rows.length, 0, "no FK-child audit insert attempted on a malformed prKey");
+  assertEquals(stores.pull_requests.rows.length, 0, "no parent row written on a malformed prKey");
+});
+
+
 //
 // plan-fanout parks a task with capability `needs` at the `wait-caps-resolved` message barrier. This
 // reconciler, on every pass, (a) starts the durable `readiness-gate` once per need, (b) does a single

package/app/service.ts

@@ -9,7 +9,7 @@
 // `Table<T>` surface), not hand-written SQL. Row shapes are declared inline here.
 import { readFileSync } from "node:fs";
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
-import { abandonUrl, mintAbandonToken, renderAbandonBrief } from "./abandon.ts";
+import { ABANDONED_STATUS, abandonUrl, mintAbandonToken, renderAbandonBrief } from "./abandon.ts";
 import { agentSlaTimeout } from "./agentSla.ts";
 import {
   CAPS_RESOLVED_MESSAGE,
@@ -21,6 +21,12 @@ import {
   renderResolvedDepsBrief,
   UnresolvableCapabilityRefError,
 } from "./capabilityNeed.ts";
+import {
+  activeConformanceReviews,
+  CONFORMANCE_ESCALATION_ELEMENT,
+  conformanceEscalationQuestion,
+} from "./conformance.ts";
+import { isUniqueConstraintFence } from "./dbFence.ts";
 import { deriveDelivery, TERMINAL_STATUSES } from "./delivery.ts";
 import { fleetSupportsDurableResume } from "./durableResume.ts";
 import { backfillFeatureStages, deriveFeatureDelivery, FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT, FEATURE_RUN_STATUSES, type FeatureRunStatus, featureEscalations, featureRuns } from "./feature.ts";
@@ -844,6 +850,110 @@ async function isDepMerged(data: DataLayer, depKey: string, token: string): Prom
   }
 }
 
+/** Canonically retire a **closed-unmerged** PR's read model. Writes the terminal `merges` audit row
+ * and flips BOTH the `pull_requests` row and every `plan_tasks` row keyed to the PR to `abandoned`.
+ *
+ * This is the ONE canonical abandon implementation, reached from BOTH entry points that observe a
+ * wave/merge member closed on GitHub without merging (#352):
+ *   • the merge stage — `workers/merge` `attempt-merge` closed short-circuit (#342), and
+ *   • the wave-merge gate — `pollWaveGatesImpl`'s self-heal for a PR closed out-of-band while its
+ *     task was still `opened` (never reached the merge stage, so `pollMerges` never saw it).
+ *
+ * Flipping the **task** row (not only the PR row) is essential: `waveMergeTargets` keys on
+ * `plan_tasks.status`, so a still-`opened` task keeps a dead PR in the blocking set and wedges the
+ * wave barrier forever; an `abandoned` task drops out (the wave completes on its surviving merged
+ * members) and stops `isPlanComplete`/the Epics table counting a phantom open task. Idempotent for a
+ * poller retry (or the two observers — merge worker + wave gate — racing the same closed PR):
+ * re-running just re-stamps the same terminal status, and the terminal `merges` audit row is written
+ * only once: the fast-path guard skips the insert when an `abandoned`/`pr-closed` row already exists,
+ * and — because that check-then-insert is racy under the two observers (merge worker + wave gate)
+ * racing the same closed PR — a DB-level partial UNIQUE fence (`ux_merges_abandon_pr_closed`,
+ * migration 053) rejects a concurrent duplicate, which we swallow as the same idempotent outcome. So
+ * retries (sequential OR concurrent) can't spam the audit with duplicate rows and skew reporting.
+ *
+ * Self-heals the FK parent first: the `merges` audit row is an FK child of `pull_requests.pr_key`, so
+ * before writing it we ensure the parent row exists via the idempotent {@link ensurePr}. The merge
+ * worker already pre-heals, but the wave-gate self-heal path does not — and in an engine/app.db
+ * desync (the exact class `ensurePr` heals) it can observe a closed member whose `pull_requests` row
+ * is missing. Healing inside the ONE canonical writer covers BOTH callers symmetrically, so the
+ * FK-child insert can never hit `FOREIGN KEY constraint failed` and wedge the poller pass. */
+export async function abandonClosedPr(data: DataLayer, prKey: string, detail: string): Promise<void> {
+  const ts = now();
+  const parsed = parsePr(prKey);
+  // Self-heal the FK parent, but ONLY when `prKey` is well-formed. A malformed key can't be healed
+  // (there's no repo/number to `ensurePr`), and silently skipping the heal would let the downstream
+  // `merges.insert` fail with an opaque `FOREIGN KEY constraint failed` — the exact incident this
+  // helper exists to prevent. Fail closed with a clear, actionable error instead.
+  if (!parsed) {
+    throw new Error(`abandonClosedPr: malformed prKey ${JSON.stringify(prKey)} — cannot self-heal the pull_requests FK parent`);
+  }
+  await ensurePr(data, { prKey, repo: parsed.repo, number: parsed.number });
+  const merges = data.table("merges", "id");
+  const alreadyAudited =
+    (await merges.findOne({ pr_key: prKey, outcome: "abandoned", method: "pr-closed" })) !== null;
+  if (!alreadyAudited) {
+    try {
+      await merges.insert({
+        pr_key: prKey,
+        outcome: "abandoned",
+        method: "pr-closed",
+        detail,
+        at: ts,
+      });
+    } catch (err) {
+      // The `find`-then-`insert` guard above is racy: the merge worker and the wave-gate self-heal
+      // path can both observe "no row" and both insert. The partial UNIQUE fence
+      // (`ux_merges_abandon_pr_closed`, migration 053) rejects the loser — tolerate that collision as
+      // the SAME idempotent outcome the guard intends, and only that. Any other error rethrows.
+      if (!isUniqueConstraintFence(err)) throw err;
+    }
+  }
+  await prs(data).update(prKey, { status: ABANDONED_STATUS, updated_at: ts });
+  const tasks = planTasks(data);
+  for (const t of await tasks.find({ pr_key: prKey })) {
+    await tasks.update(t.id, { status: ABANDONED_STATUS, updated_at: ts });
+  }
+}
+
+/** Classify a wave-merge target PR against GitHub ground truth for the wave gate (#352):
+ *   • `cleared` — merged (tracked `merged` row, an out-of-band `merged` live state, or an
+ *     already-`abandoned` tracked row / non-PR ref that can never block) → non-blocking.
+ *   • `closed`  — live GitHub state is closed WITHOUT merging → non-blocking, and the caller must
+ *     reconcile it terminal via {@link abandonClosedPr} so it leaves the target set.
+ *   • `pending` — still open, or read successfully but in an ambiguous (`unknown`) live state → still
+ *     blocks the wave. A *thrown* transport error (network/5xx) is NOT swallowed here: it rethrows so
+ *     the poller pass logs and retries — behaviourally identical for the barrier (it stays armed and
+ *     re-checks next pass), and canonical with {@link isDepMerged}, which rethrows transient failures
+ *     the same way. Only a `not-a-pull-request` error is caught (→ `cleared`).
+ *
+ * Mirrors {@link isDepMerged} (tracked-row fast path, then a live read, `not-a-pull-request` treated
+ * as cleared, transient errors rethrown) but adds the closed-unmerged branch the wave barrier lacked
+ * — the direct analogue of the merge stage's `classifyPrLiveness === "closed"` abandon. Conservative:
+ * an unreadable PR never resolves to a terminal `cleared`/`closed`, so a false negative only costs a
+ * retry while a false positive that would drop a live member is impossible. */
+async function classifyWaveTarget(
+  data: DataLayer,
+  prKey: string,
+  token: string,
+): Promise<"cleared" | "closed" | "pending"> {
+  const tracked = await prs(data).get(prKey);
+  if (tracked && tracked.status === "merged") return "cleared";
+  if (tracked && tracked.status === ABANDONED_STATUS) return "cleared"; // already reconciled terminal → non-blocking, no re-reconcile needed
+  const parsed = parsePr(prKey);
+  if (!parsed) return "cleared"; // unparseable ref can't be checked → never wedge the barrier
+  let st: Awaited<ReturnType<typeof fetchPrState>>;
+  try {
+    st = await fetchPrState(parsed.repo, parsed.number, token);
+  } catch (err) {
+    if (isNotAPullRequestError(err)) return "cleared"; // an issue/missing number can never merge
+    throw err;
+  }
+  const liveness = classifyPrLiveness(st);
+  if (liveness === "merged") return "cleared";
+  if (liveness === "closed") return "closed";
+  return "pending"; // read OK but open or ambiguous (`unknown`) live state → stay conservative and keep blocking
+}
+
 /** Flip a PR into the transient `merging` status and publish the correlating message, reverting
  * to `prevStatus` if the publish fails. `merging` is deliberately a status no poll branch scans
  * (so a slow pass can't double-signal), which means a publish failure *after* the flip would
@@ -1409,7 +1519,23 @@ export async function pollWaveGatesImpl(
       let allMerged = true;
       const tasks = await planTasks(data).find({ plan_key: planKey });
       for (const prKey of waveMergeTargets(tasks, gateWave)) {
-        if (!(await isDepMerged(data, prKey, token))) {
+        const state = await classifyWaveTarget(data, prKey, token);
+        if (state === "closed") {
+          // Self-heal (#352): a wave-target PR closed on GitHub WITHOUT merging (abandoned /
+          // superseded / perpetually conflicting) can never reach `merged`, so it must NOT keep the
+          // barrier armed forever. Retire it through the canonical abandon writer — flipping the
+          // `plan_tasks` row terminal so it drops out of `waveMergeTargets` and the epic read model —
+          // and treat it as non-blocking: the wave completes on its surviving merged members. This is
+          // the wave-gate reach of the SAME abandon path the merge stage uses for a closed member.
+          await abandonClosedPr(
+            data,
+            prKey,
+            "wave-target PR was closed on GitHub without merging — reconciling terminal so the wave gate can advance",
+          );
+          console.log(`[poller] wave-target closed without merging -> ${prKey}`);
+          continue;
+        }
+        if (state === "pending") {
           allMerged = false;
           break;
         }
@@ -2078,6 +2204,41 @@ export async function pollUserTasks(data: DataLayer, engine: EngineClient) {
     }
   }
 
+  // Conformance-review acks (`conformance-escalation`) — the advisory `retro` process parks on a
+  // human ack when the spec-conformance audit finds the epic did NOT cleanly meet its spec (issue
+  // #216). retro is not one of the delivery aggregates above, so its instance is tracked on
+  // `plan_conformance` (migration 054): scan each row still `reviewing`, read its open ack task, and
+  // project it keyed to the epic (plan) subject, sourcing the question from the audit's `summary`.
+  for (const review of await activeConformanceReviews(data)) {
+    if (!review.process_key) continue;
+    let tasks: { userTaskKey: string; elementId?: string }[];
+    try {
+      tasks = await engine.openUserTasks({ processInstanceKey: review.process_key });
+    } catch (err) {
+      console.error(`[poller] user tasks (conformance ${review.plan_key}): ${err}`);
+      continue;
+    }
+    const plan = await plans(data).get(review.plan_key);
+    for (const t of tasks) {
+      if (t.elementId !== CONFORMANCE_ESCALATION_ELEMENT) continue;
+      push(
+        buildUserTaskRow(
+          {
+            userTaskKey: t.userTaskKey,
+            elementId: CONFORMANCE_ESCALATION_ELEMENT,
+            subjectType: "plan",
+            subjectKey: review.plan_key,
+            subjectTitle: plan?.title ?? null,
+            subjectUrl: plan?.issue_url ?? null,
+            question: conformanceEscalationQuestion(review),
+            processKey: review.process_key,
+          },
+          at,
+        ),
+      );
+    }
+  }
+
   const persisted = await userTasks(data).all();
   const { inserts, updates, deletes } = reconcileUserTasks(persisted, desired);
   for (const row of inserts) await userTasks(data).insert(row);

package/app/userTasks.test.ts

@@ -5,6 +5,7 @@
 // These are the pure source of truth the poller projects.
 import { test } from "node:test";
 import { assert, assertEquals } from "#test-assert";
+import { CONFORMANCE_ESCALATION_ELEMENT } from "./conformance.ts";
 import type { PlanReview } from "./plan.ts";
 import type { TrialMergeAuditRow } from "./trialMerge.ts";
 import {
@@ -63,6 +64,25 @@ test("buildUserTaskRow: a blank question / missing url normalises to null", () =
   assertEquals(row?.kind_label, "Trial merge");
 });
 
+test("buildUserTaskRow: a conformance-escalation projects the 'Conformance review' label (issue #216)", () => {
+  const row = buildUserTaskRow(
+    {
+      userTaskKey: "ut-c",
+      elementId: CONFORMANCE_ESCALATION_ELEMENT,
+      subjectType: "plan",
+      subjectKey: "o/r#7",
+      subjectTitle: "Ship the cache",
+      question: "slice 2 reduced",
+    },
+    AT,
+  );
+  assert(row !== null);
+  assertEquals(row?.element_id, "conformance-escalation");
+  assertEquals(row?.kind_label, "Conformance review");
+  assertEquals(row?.subject_type, "plan");
+  assertEquals(row?.question, "slice 2 reduced");
+});
+
 test("buildUserTaskRow: an unknown (non-escalation) element yields null — no arbitrary user task leaks", () => {
   const row = buildUserTaskRow(
     { userTaskKey: "ut-3", elementId: "some-internal-task", subjectType: "plan", subjectKey: "o/r#3" },

package/app/userTasks.ts

@@ -18,6 +18,7 @@
 // tasks visible; a completed task's row is removed on the next pass when the engine no longer reports
 // it open.
 import type { DataLayer } from "@nanobpm/urban";
+import { CONFORMANCE_ESCALATION_ELEMENT } from "./conformance.ts";
 import { FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT, type FeatureEscalationRow } from "./feature.ts";
 import type { PlanReview } from "./plan.ts";
 import type { TrialMergeAuditRow } from "./trialMerge.ts";
@@ -74,6 +75,7 @@ export const USER_TASK_KIND_LABELS: Readonly<Record<string, string>> = {
   [TRIAL_MERGE_ELEMENT]: "Trial merge",
   [PR_WAIT_ANSWER_ELEMENT]: "PR review",
   [PR_WAIT_MERGE_ANSWER_ELEMENT]: "PR merge",
+  [CONFORMANCE_ESCALATION_ELEMENT]: "Conformance review",
 };
 
 /** The denormalised context the poller has resolved for an open escalation user task. */

package/app/waves.test.ts

@@ -127,3 +127,15 @@ test("waveMergeTargets → a wave with no opened PRs clears vacuously (empty)",
   ];
   assertEquals(waveMergeTargets(tasks, 0), []);
 });
+
+// #352: a wave member whose PR was closed-unmerged is reconciled to the terminal `abandoned`
+// status. Such a task must NOT stay in the blocking set — a dead PR can never reach `merged`, so
+// leaving it in would wedge the wave-merge barrier forever. The surviving merged member is the only
+// target the gate waits on.
+test("waveMergeTargets → an abandoned (closed-unmerged) wave member drops out of the blocking set", () => {
+  const tasks: WaveGateTask[] = [
+    { wave: 0, status: "opened", pr_key: "o/r#1" },
+    { wave: 0, status: "abandoned", pr_key: "o/r#2" }, // PR closed without merging → reconciled terminal
+  ];
+  assertEquals(waveMergeTargets(tasks, 0), ["o/r#1"]);
+});

package/app/world/store.ts

@@ -10,6 +10,7 @@
 // duplicated (AGENTS.md "derivation over duplication": the tree is derived from `remote SHA +
 // effect-tail`, never snapshot into a log).
 import type { DataLayer, Table } from "@nanobpm/urban";
+import { isUniqueConstraintFence } from "../dbFence.ts";
 import type { Effect, EffectKind, Fence } from "./effect-ledger.ts";
 
 /** A persisted push-checkpoint row (`world_checkpoints`). */
@@ -104,13 +105,12 @@ export class WorldStore {
    * concurrent/duplicate writer inserted the row BETWEEN our `findOne` and our `insert`. Every insert
    * in this store guards a UNIQUE constraint (`UNIQUE(pr_key, commit_sha)` / `(pr_key, checkpoint_offset)`
    * on checkpoints, `UNIQUE(pr_key, idempotency_key)` on effects), so a check-then-insert is inherently
-   * racy under the at-least-once persist-round delivery + a distributed fleet. This is the ONE place the
-   * store classifies a fence collision, so the three insert sites below turn it into the SAME intended
-   * idempotent outcome instead of each re-encoding the driver's error shape (a drift surface). Matched on
-   * the message substring the RAD `Table` surface propagates verbatim — the same one the schema tests
-   * assert on — because that surface hides the concrete driver error type. */
+   * racy under the at-least-once persist-round delivery + a distributed fleet. Delegates to the ONE
+   * canonical classifier ({@link isUniqueConstraintFence}) so this store, `abandonClosedPr`, and any
+   * future fence site share a single implementation instead of each re-encoding the driver's error
+   * shape (AGENTS.md: "no drift surfaces"). */
   static #isFenceCollision(err: unknown): boolean {
-    return err instanceof Error && /UNIQUE constraint failed/i.test(err.message);
+    return isUniqueConstraintFence(err);
   }
 
   /** Reconcile an existing ledger row's `applied` flag toward a LATER record's knowledge: flip a

package/db/migrations/004_planning.sql

@@ -26,7 +26,7 @@ CREATE TABLE plan_tasks (
   task_id     TEXT NOT NULL,               -- planner-supplied slug (or "t<index>")
   title       TEXT,
   prompt      TEXT,
-  status      TEXT NOT NULL,               -- pending | opened | blocked | skipped
+  status      TEXT NOT NULL,               -- pending | opened | blocked | skipped | escalated | waiting-for-lane | abandoned
   pr_key      TEXT,                         -- the PR this slice produced ("<owner>/<repo>#<n>")
   summary     TEXT,
   created_at  TEXT NOT NULL,

package/db/migrations/052_plan_conformance.sql

@@ -0,0 +1,28 @@
+-- Spec-conformance review — the post-completion "did we build what the spec asked for?" stage.
+--
+-- It rides the same `retro` process that already fires exactly once when an epic's LAST PR reaches
+-- a terminal state (see 016_plan_retro.sql / app/retro.ts). Before the retro agent distils lessons,
+-- a `senior:conformance` agent EXAMINES THE ACTUAL IMPLEMENTATION — it reads the delivered PR diffs,
+-- the code, and the tests (not just what agents claimed) — and checks each item of the spec (the
+-- epic issue + every slice's `prompt`) against what was really shipped. It posts a conformance
+-- report as a comment on the epic issue and emits per-item acceptance verdicts plus the two classes
+-- of deviation: those RAISED during implementation (`scope-change` blackboard entries) and those it
+-- found itself that were NEVER raised. This table records that result.
+--
+-- Advisory, like the retro it accompanies: it gates no delivery control flow (the epic already
+-- merged). One row per epic, keyed on plan_key.
+CREATE TABLE plan_conformance (
+  plan_key             TEXT PRIMARY KEY REFERENCES plans(plan_key),
+  status               TEXT NOT NULL,               -- filed | skipped | blocked (the agent's result status)
+  comment_url          TEXT,                         -- the conformance report comment the agent posted on the epic issue, or NULL
+  slices_met           INTEGER NOT NULL DEFAULT 0,  -- items fully delivered as specified
+  slices_reduced       INTEGER NOT NULL DEFAULT 0,  -- items delivered in a reduced/partial form, incl. met-in-unit-only (unit-tested but not proven live-wired)
+  slices_not_verified  INTEGER NOT NULL DEFAULT 0,  -- items the agent could not confirm from the implementation (e.g. no live wiring / synthetic only)
+  deviations_raised    INTEGER NOT NULL DEFAULT 0,  -- scope deviations agents flagged during implementation (`scope-change` entries)
+  deviations_unraised  INTEGER NOT NULL DEFAULT 0,  -- scope deviations the agent found by examining the code that were NEVER flagged
+  has_deviations       INTEGER NOT NULL DEFAULT 0,  -- 1 when anything is reduced / not-verified / an unraised deviation exists (drives escalation in a later slice)
+  summary              TEXT,                         -- the agent's human-readable conformance summary
+  report               TEXT,                         -- the full conformance report / transcript (nullable)
+  created_at           TEXT NOT NULL,
+  updated_at           TEXT NOT NULL
+);

package/db/migrations/053_merges_abandon_dedupe.sql

@@ -0,0 +1,29 @@
+-- Enforce the abandon-audit invariant at the DB level (#352, PR #354 review — suppressed advisory on
+-- app/service.ts:867). `abandonClosedPr`'s "write the terminal `merges` audit row only once" guard was
+-- a NON-ATOMIC find-then-insert: the two observers that reconcile a closed-unmerged member — the merge
+-- worker's `attempt-merge` closed short-circuit and the wave-gate self-heal in `pollWaveGatesImpl` —
+-- can run concurrently, so both observe "no row" between the `find` and the `insert` and both write an
+-- `abandoned`/`pr-closed` row for the same `pr_key`. Sequential-idempotency tests pass, but the guard
+-- is only best-effort under a real concurrent race.
+--
+-- Make the invariant a DB constraint (the canonical durable-fence idiom — cf. the `UNIQUE` fences on
+-- `world_effects`/`world_checkpoints` in 049): AT MOST ONE (outcome='abandoned', method='pr-closed')
+-- `merges` row per `pr_key`. The writer keeps its fast-path `find` guard (so the common retry never
+-- throws) but now tolerates the UNIQUE fence as the SAME idempotent outcome (see `app/dbFence.ts`).
+--
+-- Expand phase (additive, forward-only): first collapse any duplicates a pre-fence race already wrote
+-- — keep the earliest row (`MIN(id)`) per `pr_key` — so the partial UNIQUE index can be created on an
+-- already-populated database, then add the index. Only `abandoned`/`pr-closed` rows are touched;
+-- `merged`/`queued`/`blocked` audit rows are untouched and may still repeat per `pr_key`.
+DELETE FROM merges
+WHERE outcome = 'abandoned'
+  AND method = 'pr-closed'
+  AND id NOT IN (
+    SELECT MIN(id) FROM merges
+    WHERE outcome = 'abandoned' AND method = 'pr-closed'
+    GROUP BY pr_key
+  );
+
+CREATE UNIQUE INDEX IF NOT EXISTS ux_merges_abandon_pr_closed
+  ON merges (pr_key)
+  WHERE outcome = 'abandoned' AND method = 'pr-closed';

package/db/migrations/054_conformance_review_tracking.sql

@@ -0,0 +1,27 @@
+-- Conformance review — escalation instance tracking (issue #216).
+--
+-- When conformance finds the epic did NOT cleanly meet its spec (a reduced / not-verified item, or a
+-- deviation nobody raised), it escalates to the Tasks inbox as a NON-BLOCKING follow-up: the `retro`
+-- process parks on a native `conformance-escalation` user task until an operator acknowledges it.
+--
+-- The unified inbox (`user_tasks`, 034) is reconciled by `pollUserTasks`, which scans the open user
+-- tasks of each *instance-tracked* aggregate (feature_runs / plans / pull_requests). The retro process
+-- had no such tracking, so its user task was invisible to the inbox. These two columns make
+-- `plan_conformance` the retro run's tracking row: `process_key` is the retro process instance, and
+-- `review_status` is its escalation lifecycle — `reviewing` while the ack task is open (the poller
+-- scans these), `reviewed` once the run settles (set by `record-conformance` when there is nothing to
+-- escalate, by the `pr.conformance-ack` worker (`acknowledgeConformance`) when an operator
+-- acknowledges the escalation and the retro instance COMPLETES normally, and — as a crash/cancel
+-- safety net — by `instanceTracking.onTerminated` when the retro instance is TERMINATED rather than
+-- completing).
+--
+-- Forward-only, additive (expand): two nullable/defaulted columns on the table 052 just added; the
+-- runner wraps each file in its own transaction, so this file must NOT contain BEGIN/COMMIT.
+ALTER TABLE plan_conformance ADD COLUMN process_key TEXT;
+ALTER TABLE plan_conformance ADD COLUMN review_status TEXT NOT NULL DEFAULT 'reviewed';
+
+-- `pollUserTasks` scans open retro escalations by `review_status = 'reviewing'` every poll pass
+-- (app/conformance.ts `activeConformanceReviews`). Index it so the common-case status scan stays a
+-- cheap lookup instead of a full table scan as conformance rows accumulate — mirrors the
+-- `idx_feature_runs_status` precedent (028) for the equivalent status-scanned aggregate.
+CREATE INDEX IF NOT EXISTS idx_plan_conformance_review_status ON plan_conformance(review_status);

package/nano.app.json

@@ -67,6 +67,20 @@
         }
       },
       "pollMs": 5000
+    },
+    {
+      "table": "plan_conformance",
+      "keyField": "process_key",
+      "statusField": "review_status",
+      "activeStatuses": [
+        "reviewing"
+      ],
+      "onTerminated": {
+        "set": {
+          "review_status": "reviewed"
+        }
+      },
+      "pollMs": 5000
     }
   ],
   "workers": [
@@ -162,6 +176,14 @@
       "taskType": "pr.retro-record",
       "handler": "workers/retro-record/worker.ts"
     },
+    {
+      "taskType": "pr.conformance-record",
+      "handler": "workers/conformance-record/worker.ts"
+    },
+    {
+      "taskType": "pr.conformance-ack",
+      "handler": "workers/conformance-ack/worker.ts"
+    },
     {
       "taskType": "pr.progress-check",
       "handler": "workers/progress-check/worker.ts"
@@ -183,7 +205,8 @@
     "senior:plan-review",
     "senior:feature",
     "senior:trial-merge",
-    "senior:retro"
+    "senior:retro",
+    "senior:conformance"
   ],
   "surfaces": {
     "taskInbox": {