@nanobpm/nano-workforce 0.105.0 → 0.106.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.106.0](https://github.com/nanobpm/nano-workforce/compare/v0.105.0...v0.106.0) (2026-08-20)
+
+
+### Features
+
+* escalate unmet/undisclosed conformance deviations to the Tasks inbox ([#356](https://github.com/nanobpm/nano-workforce/issues/356)) ([5ad24bc](https://github.com/nanobpm/nano-workforce/commit/5ad24bcadf833934804973a25fd96f4eb4d28a84)), closes [#354](https://github.com/nanobpm/nano-workforce/issues/354) [#354](https://github.com/nanobpm/nano-workforce/issues/354)
+
 # [0.105.0](https://github.com/nanobpm/nano-workforce/compare/v0.104.0...v0.105.0) (2026-08-19)
 
 

package/README.md

@@ -153,7 +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 |
+| `conformance` | `senior:conformance` | `retro` | Examine a finished epic's implementation against its spec; report met/deviations on the issue, and escalate an unmet/undisclosed deviation to the Tasks inbox as a non-blocking ack |
 
 - `--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/agentCompletion.test.ts

@@ -229,6 +229,34 @@ test("feature-blocked is HUMAN-completable but NOT agent-completable (issue #332
   assertEquals(completed[0].variables, { note: "reassigned to a human" });
 });
 
+test("conformance-escalation is HUMAN-completable but NOT agent-completable (issue #216)", async () => {
+  // The retro conformance ack mirrors feature-blocked: a HUMAN operator retires it via
+  // `completeEscalationAsHuman`, but it stays OUTSIDE the agent surface (`ESCALATION_TASK_ELEMENTS`) —
+  // an agent must never acknowledge a conformance review on a human's behalf.
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores);
+  const { engine, completed } = fakeEngine([{ userTaskKey: "ut-c", elementId: "conformance-escalation" }]);
+
+  const asAgent = await completeEscalationAsAgent(data, engine, {
+    userTaskKey: "ut-c",
+    agentId: "bot",
+    variables: { note: "n" },
+  });
+  assertEquals(asAgent.ok, false, "the agent completer refuses conformance-escalation");
+  assertEquals(asAgent.reason, "not a completable task");
+  assertEquals(completed.length, 0);
+
+  const asHuman = await completeEscalationAsHuman(data, engine, {
+    userTaskKey: "ut-c",
+    operatorId: "alice",
+    variables: { note: "filed follow-up" },
+  });
+  assertEquals(asHuman.ok, true, "the human completer retires conformance-escalation");
+  assertEquals(asHuman.elementId, "conformance-escalation");
+  assertEquals(completed.length, 1);
+  assertEquals(completed[0].variables, { note: "filed follow-up" });
+});
+
 test("human completer refuses a non-escalation user task and is a no-op for an unknown key", async () => {
   const stores = { task_completions: { rows: [] as any[], key: "id" } };
   const data = memData(stores);

package/app/agentCompletion.ts

@@ -22,6 +22,7 @@
 
 import { readFileSync } from "node:fs";
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
+import { CONFORMANCE_ESCALATION_ELEMENT } from "./conformance.ts";
 
 const now = () => new Date().toISOString();
 
@@ -79,13 +80,23 @@ export const ESCALATION_TASK_ELEMENTS: ReadonlySet<string> = new Set([
  *  `acknowledge-blocked` door onto the one canonical `complete-user-task` door). */
 export const FEATURE_BLOCKED_TASK_ELEMENT = "feature-blocked";
 
+/** The `conformance-escalation` operator user-task element id (retro.bpmn) — the native ack a retro
+ *  run parks on when the spec-conformance audit finds the epic did NOT cleanly meet its spec (a
+ *  reduced / not-verified slice, or an unraised deviation). Like `feature-blocked` it is a human-only
+ *  acknowledgement (never agent-answerable), so it lives OUTSIDE `ESCALATION_TASK_ELEMENTS` and only
+ *  the HUMAN completer accepts it (issue #216). Re-exported from the canonical
+ *  `CONFORMANCE_ESCALATION_ELEMENT` (app/conformance.ts) — one source of truth, no drift surface. */
+export const CONFORMANCE_ESCALATION_TASK_ELEMENT = CONFORMANCE_ESCALATION_ELEMENT;
+
 /** The user-task `elementId`s a HUMAN operator may complete from the Tasks inbox via the one canonical
  *  `complete-user-task` door: every agent-answerable escalation PLUS the human-only `feature-blocked`
- *  acknowledgement. The AGENT completer stays scoped to `ESCALATION_TASK_ELEMENTS` (no `feature-blocked`),
- *  so widening the human surface never lets an agent retire a blocked run. */
+ *  and `conformance-escalation` acknowledgements. The AGENT completer stays scoped to
+ *  `ESCALATION_TASK_ELEMENTS` (neither ack), so widening the human surface never lets an agent retire
+ *  a blocked run or a conformance review. */
 export const HUMAN_COMPLETABLE_ELEMENTS: ReadonlySet<string> = new Set([
   ...ESCALATION_TASK_ELEMENTS,
   FEATURE_BLOCKED_TASK_ELEMENT,
+  CONFORMANCE_ESCALATION_TASK_ELEMENT,
 ]);
 
 /** Each escalation `elementId` → the `.form` whose contract governs its completion variables (the
@@ -98,6 +109,7 @@ const ESCALATION_FORM_BY_ELEMENT: Readonly<Record<string, string>> = {
   "wait-answer": "pr-escalation",
   "wait-merge-answer": "pr-escalation",
   "feature-blocked": "feature-blocked",
+  [CONFORMANCE_ESCALATION_TASK_ELEMENT]: "conformance-escalation",
 };
 
 /** A field's `conditional.hide` rule, parsed from the FEEL subset the `.form` files use

package/app/conformance.test.ts

@@ -1,10 +1,12 @@
 // 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 { assert, assertEquals, assertRejects, assertStringIncludes } from "#test-assert";
 import type { DataLayer } from "@nanobpm/urban";
 import { memBlackboardSource } from "../test/blackboardDb.ts";
 import { appendEntry } from "./blackboard.ts";
 import {
+  acknowledgeConformance,
+  activeConformanceReviews,
   gatherConformance,
   hasDeliveredImplementation,
   hasDeliveredImplementationForPlan,
@@ -218,3 +220,94 @@ test("recordConformance: rethrows a non-unique (FOREIGN KEY) constraint error in
   assert(threw, "the FK error must propagate");
   assertEquals(updated, false, "must not silently fall back to update on a non-unique error");
 });
+
+test("recordConformance: persists the retro instance key and the escalation review_status (issue #216)", async () => {
+  const { data, stores } = memData();
+  await recordConformance(data, PLAN, {
+    status: "filed",
+    commentUrl: "https://x/7#c",
+    hasDeviations: true,
+    summary: "slice 2 reduced",
+    processKey: "retro-inst-7",
+    reviewStatus: "reviewing",
+  });
+  const row = stores["plan_conformance"][0];
+  assertEquals(row.process_key, "retro-inst-7");
+  assertEquals(row.review_status, "reviewing");
+
+  // Absent tracking fields default: no processKey, and a settled `reviewed`.
+  await recordConformance(data, "acme/widgets#8", { status: "skipped" });
+  const clean = stores["plan_conformance"].find((r) => r.plan_key === "acme/widgets#8");
+  assertEquals(clean.process_key, null);
+  assertEquals(clean.review_status, "reviewed");
+});
+
+test("recordConformance: rejects an untrackable `reviewing` row with a null processKey (invariant guard)", async () => {
+  const { data, stores } = memData();
+  // A `reviewing` row with no `process_key` is unreachable: `pollUserTasks` skips rows without a
+  // key and the `instanceTracking` binding keys off `process_key`, so it would strand the review
+  // forever. The API must refuse to persist that state, not just the worker call site.
+  await assertRejects(
+    () =>
+      recordConformance(data, PLAN, {
+        status: "filed",
+        hasDeviations: true,
+        reviewStatus: "reviewing",
+      }),
+    Error,
+    "untrackable",
+  );
+  assertEquals(stores["plan_conformance"] ?? [], []);
+});
+
+test("activeConformanceReviews: returns only the rows still `reviewing`", async () => {
+  const { data, stores } = memData();
+  stores["plan_conformance"] = [
+    { plan_key: "a/b#1", process_key: "p1", review_status: "reviewing", summary: "s1" },
+    { plan_key: "a/b#2", process_key: "p2", review_status: "reviewed", summary: "s2" },
+  ];
+  const active = await activeConformanceReviews(data);
+  assertEquals(active.map((r) => r.plan_key), ["a/b#1"]);
+});
+
+test("acknowledgeConformance: settles the row at reviewed and folds the note into the summary", async () => {
+  const { data, stores } = memData();
+  stores["plan_conformance"] = [
+    { plan_key: PLAN, process_key: "p1", review_status: "reviewing", summary: "slice 2 reduced" },
+  ];
+  await acknowledgeConformance(data, PLAN, "filed follow-up #9");
+  const row = stores["plan_conformance"][0];
+  assertEquals(row.review_status, "reviewed");
+  assertEquals(row.summary, "slice 2 reduced\n\nOperator ack: filed follow-up #9");
+});
+
+test("acknowledgeConformance: fails loudly when the plan_conformance row is missing", async () => {
+  const { data } = memData();
+  await assertRejects(
+    () => acknowledgeConformance(data, PLAN, "filed follow-up #9"),
+    Error,
+    PLAN,
+  );
+});
+
+test("acknowledgeConformance: is idempotent — a retry after settling does not re-append the note", async () => {
+  const { data, stores } = memData();
+  stores["plan_conformance"] = [
+    { plan_key: PLAN, process_key: "p1", review_status: "reviewing", summary: "slice 2 reduced" },
+  ];
+  await acknowledgeConformance(data, PLAN, "filed follow-up #9");
+  await acknowledgeConformance(data, PLAN, "filed follow-up #9");
+  const row = stores["plan_conformance"][0];
+  assertEquals(row.review_status, "reviewed");
+  assertEquals(row.summary, "slice 2 reduced\n\nOperator ack: filed follow-up #9");
+});
+
+test("acknowledgeConformance: a blank note settles the row without changing the summary", async () => {
+  const { data, stores } = memData();
+  stores["plan_conformance"] = [
+    { plan_key: PLAN, process_key: "p1", review_status: "reviewing", summary: "auth cache unverified" },
+  ];
+  await acknowledgeConformance(data, PLAN, "  ");
+  assertEquals(stores["plan_conformance"][0].review_status, "reviewed");
+  assertEquals(stores["plan_conformance"][0].summary, "auth cache unverified");
+});

package/app/conformance.ts

@@ -21,6 +21,14 @@ 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
@@ -50,6 +58,30 @@ async function isLanded(data: DataLayer, prKey: string | null | undefined): Prom
 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 {
@@ -205,6 +237,12 @@ export interface ConformanceInput {
   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).
@@ -218,6 +256,19 @@ export async function recordConformance(
   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,
@@ -229,6 +280,8 @@ export async function recordConformance(
     has_deviations: input.hasDeviations ? 1 : 0,
     summary: input.summary ?? null,
     report: input.report ?? null,
+    process_key: processKey,
+    review_status: reviewStatus,
     updated_at: ts,
   };
   try {
@@ -238,3 +291,39 @@ export async function recordConformance(
     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/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/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/service.ts

@@ -21,6 +21,11 @@ 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";
@@ -2199,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/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": [
@@ -166,6 +180,10 @@
       "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"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.105.0",
+  "version": "0.106.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/pages/tasks.page.json

@@ -532,6 +532,90 @@
         },
         "refreshMs": 5000
       }
+    },
+    {
+      "type": "dataGrid",
+      "id": "conformance-reviews",
+      "props": {
+        "title": "Conformance reviews",
+        "data": {
+          "kind": "datasource",
+          "source": "app",
+          "table": "user_tasks",
+          "filter": [
+            {
+              "field": "element_id",
+              "in": [
+                "conformance-escalation"
+              ]
+            }
+          ],
+          "orderBy": {
+            "field": "updated_at",
+            "dir": "desc"
+          }
+        },
+        "columns": [
+          {
+            "field": "subject_title",
+            "template": "{{subject_title}}",
+            "header": "Epic",
+            "subtitleField": "subject_key",
+            "truncate": true,
+            "linkField": "subject_url"
+          },
+          {
+            "field": "question",
+            "header": "Findings"
+          },
+          {
+            "field": "subject_url",
+            "header": "Issue"
+          },
+          {
+            "field": "process_key",
+            "header": "Process",
+            "link": {
+              "kind": "processExplorer",
+              "keyField": "process_key"
+            }
+          },
+          {
+            "field": "updated_at",
+            "header": "Updated",
+            "format": "datetime"
+          }
+        ],
+        "rowKey": "user_task_key",
+        "detail": {
+          "linkField": "subject_url",
+          "fields": [
+            {
+              "field": "question",
+              "label": "Findings"
+            }
+          ],
+          "form": {
+            "showWhenField": "user_task_key",
+            "title": "Acknowledge conformance review",
+            "promptField": "question",
+            "inputKey": "note",
+            "inputLabel": "Disposition note (what you decided / follow-up)",
+            "submitLabel": "Acknowledge & close",
+            "action": {
+              "path": "/app/api/actions/complete-user-task",
+              "successLabel": "Acknowledged — the review will close",
+              "body": {
+                "userTaskKey": "{{row.user_task_key}}",
+                "variables": {
+                  "note": "{{form.note}}"
+                }
+              }
+            }
+          }
+        },
+        "refreshMs": 5000
+      }
     }
   ]
 }

package/resources/forms/conformance-escalation.form

@@ -0,0 +1,17 @@
+{
+  "id": "conformance-escalation",
+  "schemaVersion": 18,
+  "type": "default",
+  "components": [
+    {
+      "type": "text",
+      "text": "The spec-conformance review found this epic did **not** cleanly meet its spec — a slice was reduced or could not be verified against the code, or a deviation was made that nobody raised during implementation. The delivery already landed, so this is a **non-blocking** follow-up: review the report on the epic issue, decide any remediation, then acknowledge to close it.",
+      "label": "Conformance review"
+    },
+    {
+      "type": "textarea",
+      "key": "note",
+      "label": "Disposition note (what you decided / follow-up — recorded on the review)"
+    }
+  ]
+}

package/resources/processes/retro.bpmn

@@ -61,7 +61,32 @@
         </zeebe:properties>
       </bpmn:extensionElements>
       <bpmn:incoming>f_toRecordConformance</bpmn:incoming>
-      <bpmn:outgoing>f_toSynthesize</bpmn:outgoing>
+      <bpmn:outgoing>f_toDeviationsGw</bpmn:outgoing>
+    </bpmn:serviceTask>
+    <bpmn:exclusiveGateway id="gw-deviations" name="deviations?" default="f_noDeviations">
+      <bpmn:incoming>f_toDeviationsGw</bpmn:incoming>
+      <bpmn:outgoing>f_deviations</bpmn:outgoing>
+      <bpmn:outgoing>f_noDeviations</bpmn:outgoing>
+    </bpmn:exclusiveGateway>
+    <bpmn:userTask id="conformance-escalation" name="Conformance review (human)">
+      <bpmn:extensionElements>
+        <zeebe:formDefinition formId="conformance-escalation" />
+        <zeebe:userTask />
+        <zeebe:assignmentDefinition candidateGroups="operators" />
+      </bpmn:extensionElements>
+      <bpmn:incoming>f_deviations</bpmn:incoming>
+      <bpmn:outgoing>f_toConformanceAck</bpmn:outgoing>
+    </bpmn:userTask>
+    <bpmn:serviceTask id="record-conformance-ack" name="Record acknowledgement">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="pr.conformance-ack" />
+        <zeebe:ioMapping>
+          <zeebe:input source="=planKey" target="planKey" />
+          <zeebe:input source="=if (is defined(note)) then note else null" target="note" />
+        </zeebe:ioMapping>
+      </bpmn:extensionElements>
+      <bpmn:incoming>f_toConformanceAck</bpmn:incoming>
+      <bpmn:outgoing>f_ackToSynthesize</bpmn:outgoing>
     </bpmn:serviceTask>
     <bpmn:serviceTask id="synthesize" name="Synthesize &#38; promote (agent)">
       <bpmn:extensionElements>
@@ -73,7 +98,8 @@
           <zeebe:input source="=retroDigest" target="appendPrompt" />
         </zeebe:ioMapping>
       </bpmn:extensionElements>
-      <bpmn:incoming>f_toSynthesize</bpmn:incoming>
+      <bpmn:incoming>f_noDeviations</bpmn:incoming>
+      <bpmn:incoming>f_ackToSynthesize</bpmn:incoming>
       <bpmn:outgoing>f_toRecord</bpmn:outgoing>
     </bpmn:serviceTask>
     <bpmn:serviceTask id="record" name="Record retro">
@@ -92,7 +118,13 @@
     <bpmn:sequenceFlow id="f_start" sourceRef="Start" targetRef="gather" />
     <bpmn:sequenceFlow id="f_toConformance" sourceRef="gather" targetRef="conformance" />
     <bpmn:sequenceFlow id="f_toRecordConformance" sourceRef="conformance" targetRef="record-conformance" />
-    <bpmn:sequenceFlow id="f_toSynthesize" sourceRef="record-conformance" targetRef="synthesize" />
+    <bpmn:sequenceFlow id="f_toDeviationsGw" sourceRef="record-conformance" targetRef="gw-deviations" />
+    <bpmn:sequenceFlow id="f_deviations" name="deviations" sourceRef="gw-deviations" targetRef="conformance-escalation">
+      <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=hasDeviations = true</bpmn:conditionExpression>
+    </bpmn:sequenceFlow>
+    <bpmn:sequenceFlow id="f_noDeviations" sourceRef="gw-deviations" targetRef="synthesize" />
+    <bpmn:sequenceFlow id="f_toConformanceAck" sourceRef="conformance-escalation" targetRef="record-conformance-ack" />
+    <bpmn:sequenceFlow id="f_ackToSynthesize" sourceRef="record-conformance-ack" targetRef="synthesize" />
     <bpmn:sequenceFlow id="f_toRecord" sourceRef="synthesize" targetRef="record" />
     <bpmn:sequenceFlow id="f_toEnd" sourceRef="record" targetRef="End" />
   </bpmn:process>
@@ -113,16 +145,28 @@
       <bpmndi:BPMNShape id="BPMNShape_record-conformance" bpmnElement="record-conformance">
         <dc:Bounds x="616" y="80" width="100" height="80" />
       </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_gw-deviations" bpmnElement="gw-deviations" isMarkerVisible="true">
+        <dc:Bounds x="776" y="95" width="50" height="50" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="770" y="65" width="62" height="14" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_conformance-escalation" bpmnElement="conformance-escalation">
+        <dc:Bounds x="751" y="240" width="100" height="80" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_record-conformance-ack" bpmnElement="record-conformance-ack">
+        <dc:Bounds x="911" y="240" width="100" height="80" />
+      </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_synthesize" bpmnElement="synthesize">
-        <dc:Bounds x="816" y="80" width="100" height="80" />
+        <dc:Bounds x="1056" y="80" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_record" bpmnElement="record">
-        <dc:Bounds x="1016" y="80" width="100" height="80" />
+        <dc:Bounds x="1256" y="80" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_End" bpmnElement="End">
-        <dc:Bounds x="1216" y="102" width="36" height="36" />
+        <dc:Bounds x="1456" y="102" width="36" height="36" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1194" y="143" width="80" height="14" />
+          <dc:Bounds x="1434" y="143" width="80" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNEdge id="BPMNEdge_f_start" bpmnElement="f_start">
@@ -137,17 +181,34 @@
         <di:waypoint x="516" y="120" />
         <di:waypoint x="616" y="120" />
       </bpmndi:BPMNEdge>
-      <bpmndi:BPMNEdge id="BPMNEdge_f_toSynthesize" bpmnElement="f_toSynthesize">
+      <bpmndi:BPMNEdge id="BPMNEdge_f_toDeviationsGw" bpmnElement="f_toDeviationsGw">
         <di:waypoint x="716" y="120" />
-        <di:waypoint x="816" y="120" />
+        <di:waypoint x="776" y="120" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_noDeviations" bpmnElement="f_noDeviations">
+        <di:waypoint x="826" y="120" />
+        <di:waypoint x="1056" y="120" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_deviations" bpmnElement="f_deviations">
+        <di:waypoint x="801" y="145" />
+        <di:waypoint x="801" y="240" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_toConformanceAck" bpmnElement="f_toConformanceAck">
+        <di:waypoint x="851" y="280" />
+        <di:waypoint x="911" y="280" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_ackToSynthesize" bpmnElement="f_ackToSynthesize">
+        <di:waypoint x="1011" y="280" />
+        <di:waypoint x="1106" y="280" />
+        <di:waypoint x="1106" y="160" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_toRecord" bpmnElement="f_toRecord">
-        <di:waypoint x="916" y="120" />
-        <di:waypoint x="1016" y="120" />
+        <di:waypoint x="1156" y="120" />
+        <di:waypoint x="1256" y="120" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_toEnd" bpmnElement="f_toEnd">
-        <di:waypoint x="1116" y="120" />
-        <di:waypoint x="1216" y="120" />
+        <di:waypoint x="1356" y="120" />
+        <di:waypoint x="1456" y="120" />
       </bpmndi:BPMNEdge>
     </bpmndi:BPMNPlane>
   </bpmndi:BPMNDiagram>

package/workers/conformance-ack/worker.test.ts

@@ -0,0 +1,50 @@
+// Unit coverage for pr.conformance-ack — the operator acknowledged a conformance-review escalation
+// (issue #216). It must settle the parked `plan_conformance` row at `review_status = 'reviewed'` so
+// the inbox scan drops it (the retro instance COMPLETES normally, so `instanceTracking.onTerminated`
+// never fires) and fold the operator's disposition note into the audit `summary`.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { noopLog } from "../../test/log.ts";
+import handler from "./worker.ts";
+
+function fakeApp(rows: Record<string, unknown>[]) {
+  const stores: Record<string, Record<string, unknown>[]> = { plan_conformance: rows };
+  return {
+    data: {
+      table(name: string, key: string) {
+        const store = (stores[name] ??= []);
+        return {
+          get: (k: any) => Promise.resolve(store.find((r) => r[key] === k)),
+          find: (q: any) => Promise.resolve(store.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+          insert: (row: any) => {
+            store.push(row);
+            return Promise.resolve(store.length);
+          },
+          update: (k: any, patch: any) => {
+            const row = store.find((r) => r[key] === k);
+            if (row) Object.assign(row, patch);
+            return Promise.resolve(row);
+          },
+        };
+      },
+    },
+    log: noopLog(),
+  } as any;
+}
+
+test("conformance-ack: settles the review at reviewed and appends the operator note to the summary", async () => {
+  const rows = [{ plan_key: "owner/repo#7", review_status: "reviewing", summary: "slice 2 reduced" }];
+  const app = fakeApp(rows);
+  const out = await handler({ variables: { planKey: "owner/repo#7", note: "filed follow-up #9" } } as any, app);
+  assertEquals(out, {});
+  assertEquals(rows[0].review_status, "reviewed");
+  assertEquals(rows[0].summary, "slice 2 reduced\n\nOperator ack: filed follow-up #9");
+});
+
+test("conformance-ack: a blank note settles the review without touching the summary", async () => {
+  const rows = [{ plan_key: "owner/repo#8", review_status: "reviewing", summary: "auth cache unverified" }];
+  const app = fakeApp(rows);
+  await handler({ variables: { planKey: "owner/repo#8", note: "   " } } as any, app);
+  assertEquals(rows[0].review_status, "reviewed");
+  assertEquals(rows[0].summary, "auth cache unverified");
+});

package/workers/conformance-ack/worker.ts

@@ -0,0 +1,31 @@
+// pr.conformance-ack — an operator acknowledged a conformance-review escalation (issue #216).
+//
+// When the spec-conformance audit finds the epic did NOT cleanly meet its spec, the `retro` process
+// routes to the `conformance-escalation` operator user task (retro.bpmn), which parks the instance
+// on the operators' inbox with `plan_conformance.review_status = 'reviewing'`. This worker fires once
+// the operator completes that ack task: it settles the row at `reviewed` (so the inbox scan drops it)
+// and folds the operator's optional disposition note into the audit `summary`. The instance then
+// continues to the lessons (retro) synthesis, so the ack is NON-blocking — delivery already landed.
+// Persistence goes through the record gateway (`app.data`), never hand-written SQL.
+import type { AppJobHandler } from "@nanobpm/urban";
+import { acknowledgeConformance } from "../../app/conformance.ts";
+
+interface In extends Record<string, unknown> {
+  planKey: string;
+  note?: unknown;
+}
+
+const str = (v: unknown): string | undefined =>
+  typeof v === "string" && v.trim().length > 0 ? v.trim() : undefined;
+
+const handler: AppJobHandler<In, Record<string, never>> = async (job, app) => {
+  const planKey = job.variables.planKey;
+  const note = str(job.variables.note);
+
+  await acknowledgeConformance(app.data, planKey, note);
+  app.log.info("conformance-ack", { planKey, note: note ?? null });
+
+  return {};
+};
+
+export default handler;

package/workers/conformance-record/worker.test.ts

@@ -1,5 +1,5 @@
 import { test } from "node:test";
-import { assertEquals } from "#test-assert";
+import { assertEquals, assertRejects } from "#test-assert";
 import { noopLog } from "../../test/log.ts";
 import handler from "./worker.ts";
 
@@ -36,8 +36,9 @@ function fakeApp() {
 
 test("conformance-record: persists a filed conformance from hoisted result vars", async () => {
   const { app, stores } = fakeApp();
-  await handler(
+  const out = await handler(
     {
+      processInstanceKey: "retro-inst-5",
       variables: {
         planKey: "o/r#5",
         status: "filed",
@@ -66,12 +67,17 @@ test("conformance-record: persists a filed conformance from hoisted result vars"
   assertEquals(row.deviations_unraised, 1);
   assertEquals(row.has_deviations, 1);
   assertEquals(row.report, "the full conformance report");
+  // Tracks the retro instance and enters the inbox scan (issue #216) — a deviation escalates.
+  assertEquals(row.process_key, "retro-inst-5");
+  assertEquals(row.review_status, "reviewing");
+  // The gateway routes off the returned ground-truth flag, not the agent's hoisted var.
+  assertEquals(out, { hasDeviations: true });
 });
 
 test("conformance-record: derives has_deviations from ground truth even when the agent flag is absent", async () => {
   const { app, stores } = fakeApp();
   await handler(
-    { variables: { planKey: "o/r#6", status: "filed", commentUrl: "https://x/6#c", slicesNotVerified: 1 } } as any,
+    { processInstanceKey: "retro-inst-6", variables: { planKey: "o/r#6", status: "filed", commentUrl: "https://x/6#c", slicesNotVerified: 1 } } as any,
     app as any,
   );
   // The agent didn't set hasDeviations, but a not-verified item means the epic didn't cleanly meet spec.
@@ -80,12 +86,15 @@ test("conformance-record: derives has_deviations from ground truth even when the
 
 test("conformance-record: a clean epic records has_deviations = 0", async () => {
   const { app, stores } = fakeApp();
-  await handler(
-    { variables: { planKey: "o/r#7", status: "filed", commentUrl: "https://x/7#c", slicesMet: 3, hasDeviations: false } } as any,
+  const out = await handler(
+    { processInstanceKey: "retro-inst-7", variables: { planKey: "o/r#7", status: "filed", commentUrl: "https://x/7#c", slicesMet: 3, hasDeviations: false } } as any,
     app as any,
   );
   assertEquals(stores.plan_conformance[0].has_deviations, 0);
   assertEquals(stores.plan_conformance[0].slices_met, 3);
+  // No deviation → settles straight to `reviewed`, never entering the inbox scan.
+  assertEquals(stores.plan_conformance[0].review_status, "reviewed");
+  assertEquals(out, { hasDeviations: false });
 });
 
 test("conformance-record: coerces filed without a comment URL to skipped", async () => {
@@ -139,6 +148,7 @@ test("conformance-record: coerces string-encoded numeric counts hoisted by the a
   // These must be parsed, not silently coerced to 0 (which would wrongly clear the verdict).
   await handler(
     {
+      processInstanceKey: "retro-inst-12",
       variables: {
         planKey: "o/r#12",
         status: "filed",
@@ -167,6 +177,7 @@ test("conformance-record: honours a string-encoded hasDeviations flag", async ()
   // string "true" must still record a deviation — a stringified boolean can't silently be dropped.
   await handler(
     {
+      processInstanceKey: "retro-inst-13",
       variables: {
         planKey: "o/r#13",
         status: "filed",
@@ -197,3 +208,34 @@ test("conformance-record: defaults to skipped when the agent reported nothing",
   );
   assertEquals(stores.plan_conformance[0].status, "skipped");
 });
+
+test("conformance-record: coerces a numeric processInstanceKey to a string (TEXT process_key never drifts)", async () => {
+  const { app, stores } = fakeApp();
+  await handler(
+    { processInstanceKey: 220592130 as any, variables: { planKey: "o/r#11", status: "filed", commentUrl: "https://x/11#c", slicesNotVerified: 1 } } as any,
+    app as any,
+  );
+  const row = stores.plan_conformance[0];
+  assertEquals(row.process_key, "220592130");
+  assertEquals(typeof row.process_key, "string");
+  assertEquals(row.review_status, "reviewing");
+});
+
+test("conformance-record: fails (not a silent, untrackable escalation) when there is no processKey but there are deviations", async () => {
+  const { app, stores } = fakeApp();
+  // No `processInstanceKey` + deviations: the handler would otherwise return `hasDeviations:true`
+  // (routing retro to `conformance-escalation`) while the row is `reviewed`/`process_key=null`, an
+  // ack `pollUserTasks` can never surface nor `onTerminated` clear — an invisible, wedged escalation.
+  // Fail loudly instead so the run retries/alerts rather than encoding that silent state.
+  await assertRejects(
+    () =>
+      handler(
+        { variables: { planKey: "o/r#12", status: "filed", commentUrl: "https://x/12#c", slicesNotVerified: 1, hasDeviations: true } } as any,
+        app as any,
+      ),
+    Error,
+    "no processInstanceKey",
+  );
+  // Nothing was persisted: the throw precedes the write, so no untrackable row is left behind.
+  assertEquals(stores.plan_conformance.length, 0);
+});

package/workers/conformance-record/worker.ts

@@ -73,6 +73,28 @@ const handler: AppJobHandler<In> = async (job, app) => {
     (asBool(job.variables.hasDeviations) ||
       slicesReduced > 0 || slicesNotVerified > 0 || deviationsUnraised > 0);
 
+  // Track this retro instance on the conformance row so `pollUserTasks` can find the escalation ack
+  // task, but only mark it `reviewing` when there IS something to escalate — a clean run settles
+  // straight to `reviewed` and never enters the inbox scan (migration 054). Coerce the instance key
+  // to a string (the engine can hand back a numeric key) so `plan_conformance.process_key` (TEXT)
+  // never drifts to a number and break the string-filter reads in `pollUserTasks`/`openUserTasks` —
+  // the same `String(...)` coercion app/service.ts applies when it stamps `process_key`.
+  const processKey = job.processInstanceKey != null ? String(job.processInstanceKey) : null;
+
+  // Invariant: an escalation must be trackable. If we found deviations to escalate but have no
+  // process key to key the `reviewing` row off, the `hasDeviations` return below would still route
+  // retro to the `conformance-escalation` user task — yet `pollUserTasks` can never surface that ack
+  // (it skips rows without `process_key`) nor can the `onTerminated` binding ever clear it, so the
+  // escalation wedges forever, invisible to any human. Rather than record that silent, unreachable
+  // state, fail loudly so the run retries/alerts. `job.processInstanceKey` is always present for an
+  // activated job, so this only fires on a genuine engine-contract violation.
+  if (hasDeviations && processKey == null) {
+    throw new Error(
+      `conformance-record: ${planKey} has deviations to escalate but no processInstanceKey to track ` +
+        "the escalation — refusing to route to an untrackable conformance-escalation ack task",
+    );
+  }
+
   await recordConformance(app.data, planKey, {
     status,
     commentUrl: filed ? commentUrl : null,
@@ -84,12 +106,22 @@ const handler: AppJobHandler<In> = async (job, app) => {
     hasDeviations,
     summary,
     report,
+    processKey,
+    // Only enter the `reviewing` inbox scan when we actually have a `processKey` to key off — a
+    // null key can never be found by `pollUserTasks` (it skips rows without `process_key`) nor
+    // cleared by the `instanceTracking` `onTerminated` binding, so a `reviewing` row with no key
+    // would wedge forever. The invariant guard above already rejected `hasDeviations` with a null
+    // key, so `reviewing` here always carries a non-null `processKey`.
+    reviewStatus: hasDeviations ? "reviewing" : "reviewed",
   });
 
   app.log.info(
     `conformance-record: ${planKey} — status=${status} deviations=${hasDeviations ? "yes" : "no"}`,
   );
-  return {};
+  // Return the ground-truth `hasDeviations` as a process variable so the `gw-deviations` gateway
+  // routes to the human ack task (retro.bpmn) — overriding the agent's hoisted flag with the value
+  // reconciled against the recorded counts above.
+  return { hasDeviations };
 };
 
 export default handler;