@nanobpm/nano-workforce 0.105.0 → 0.106.1

package/.github/workflows/ci.yml

@@ -16,6 +16,11 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          # Full history + tags: the migration immutability gate (check:migrations) diffs against the
+          # merge-base with origin/main, and the upgrade smoke test materialises the previous release
+          # tag's migration set — both need history a shallow clone doesn't have (issue #357).
+          fetch-depth: 0
 
       - name: Setup Node.js
         uses: actions/setup-node@v4

package/AGENTS.md

@@ -273,6 +273,36 @@ Migrations live in `db/migrations/*.sql` and are **auto-applied on boot** from
   prefix while `main` keeps advancing, so the branch-local "next" number collides
   on merge. Two files must never share a prefix; `npm run check:migrations`
   (a CI gate) enforces this and fails the build on any new duplicate.
+- **A merged migration is IMMUTABLE — never rename, delete, or edit it.** The
+  runtime keys the `_urban_migrations` ledger by *filename*, so a renamed file is
+  a *new* migration to the runner: it re-runs its DDL against an already-migrated
+  DB and aborts boot (`duplicate column …`); a deleted file desyncs the ledger
+  from the schema; an edited file silently no-ops on every existing install (the
+  name is already recorded) while diverging fresh ones. To change a merged
+  migration's effect, add a NEW migration. `npm run check:migrations` also gates
+  this — it diffs `db/migrations/` against the merge-base with `origin/main` and
+  fails on any rename/delete/edit — and the upgrade smoke test
+  (`app/migration-upgrade-smoke.test.ts`) materialises the previous release's
+  migration set and upgrades it to the current set, catching non-idempotent DDL a
+  fresh-DB CI never exercises (issue #357). Both need history: CI checks out with
+  `fetch-depth: 0`.
+
+### Healing an install wedged by a renamed migration
+
+If a live node fails to boot with `migration "NNN_…sql" failed and was rolled
+back … duplicate column` because a migration was renamed *before* the immutability
+gate existed (e.g. `043_user_tasks_subject_title.sql` → `046_…`, issue #357),
+reconcile its ledger — this makes **no schema change**, only aliases the old
+ledger row to the new filename, and is safe to re-run:
+
+```bash
+npm run heal:migrations -- /path/to/the/app.sqlite   # then restart the node
+```
+
+The known renames live in `RENAMED_MIGRATIONS` (`app/migrationHeal.ts`), the
+single source of truth the heal script and its tests share. This list only heals
+the pre-gate past — the immutability gate above prevents any new entry from ever
+being needed.
 
 ## Runtime & CI gates
 
@@ -286,7 +316,7 @@ npm run typecheck                                     # tsc --noEmit (Node)
 npm run check                                         # urban check (manifest validation)
 npm run layout:check                                  # BPMN diagram freshness (no drift)
 npm run check:prompts                                 # agent-prompt linkedResource resolution
-npm run check:migrations                              # migration prefixes (no collisions)
+npm run check:migrations                              # migration prefixes + immutability (no rename/delete/edit of a merged migration)
 npm run check:contracts                               # contract registry (no synonyms / undeclared env keys)
 npm test                                              # unit tests (node --test)
 ```

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [0.106.1](https://github.com/nanobpm/nano-workforce/compare/v0.106.0...v0.106.1) (2026-08-20)
+
+
+### Bug Fixes
+
+* **migrations:** gate migration immutability + add upgrade smoke test ([#357](https://github.com/nanobpm/nano-workforce/issues/357)) ([#359](https://github.com/nanobpm/nano-workforce/issues/359)) ([7f7c6a6](https://github.com/nanobpm/nano-workforce/commit/7f7c6a6c59dac33602441c729dca897b3b23fabc)), closes [#311](https://github.com/nanobpm/nano-workforce/issues/311) [#316](https://github.com/nanobpm/nano-workforce/issues/316) [#351](https://github.com/nanobpm/nano-workforce/issues/351) [#355](https://github.com/nanobpm/nano-workforce/issues/355)
+
+# [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/migration-upgrade-smoke.test.ts

@@ -0,0 +1,55 @@
+// Upgrade smoke test (issue #357) — CI only ever migrates a FRESH database, so it never exercises the
+// one state where the forward-only contract actually breaks: a *pre-existing* install upgrading to
+// the current set. This materialises the migration set at the previous release tag, applies the
+// current set on top the way the runtime does (ledger keyed by filename, skip-applied / apply-new),
+// and asserts the upgrade completes cleanly.
+//
+// It covers the whole failure class on a real release boundary — a renamed/deleted migration
+// re-running, non-idempotent DDL, or an ordering assumption — rather than any single instance. When
+// the tag is unavailable (a shallow clone without tags) it skips with a diagnostic; CI checks out
+// full history + tags (`fetch-depth: 0`), so the real upgrade path is always exercised there.
+import { DatabaseSync } from "node:sqlite";
+import test from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import {
+  applyMigrationSet,
+  previousReleaseTag,
+  readMigrationSetFromDisk,
+  readMigrationSetFromGit,
+} from "#test-migrations";
+
+test("upgrading a DB from the previous release's migrations to the current set applies cleanly", (t) => {
+  const tag = previousReleaseTag();
+  if (tag === null) {
+    t.skip("no previous release tag reachable (shallow clone without tags) — CI runs this with fetch-depth: 0");
+    return;
+  }
+  const baseline = readMigrationSetFromGit(tag);
+  if (baseline === null) {
+    t.skip(`migration set at ${tag} unavailable — CI runs this with fetch-depth: 0`);
+    return;
+  }
+
+  const db = new DatabaseSync(":memory:");
+  // Stand up the DB exactly as the previous release left it...
+  applyMigrationSet(db, baseline);
+  const ledgerBefore = new Set(
+    (db.prepare("SELECT name FROM _urban_migrations").all() as { name: string }[]).map((r) => r.name),
+  );
+
+  // ...then upgrade in place to the current set. A rename/delete/non-idempotent migration throws here.
+  const current = readMigrationSetFromDisk();
+  applyMigrationSet(db, current);
+
+  // Every current migration is now recorded, and nothing the baseline applied went missing.
+  const ledgerAfter = new Set(
+    (db.prepare("SELECT name FROM _urban_migrations").all() as { name: string }[]).map((r) => r.name),
+  );
+  for (const file of current) {
+    assert(ledgerAfter.has(file.name), `current migration ${file.name} is recorded as applied after upgrade`);
+  }
+  for (const name of ledgerBefore) {
+    assert(ledgerAfter.has(name), `baseline migration ${name} remains in the ledger after upgrade`);
+  }
+  assertEquals(ledgerAfter.size, current.length, "the upgraded ledger holds exactly the current set");
+});

package/app/migrationHeal.test.ts

@@ -0,0 +1,75 @@
+// Regression guard for issue #357 — a migration renamed after it merged (`043_user_tasks_subject_
+// title.sql` -> `046_…` in #316) re-runs against an already-migrated DB and aborts boot with
+// "duplicate column name: subject_title", because the ledger is keyed by filename.
+//
+// This reproduces that exact break on the CURRENT migration set (RED), then proves
+// `healMigrationLedger` reconciles the ledger so the upgrade completes cleanly (GREEN) — the recovery
+// path for installs that migrated under the old name before the rename landed.
+import { DatabaseSync } from "node:sqlite";
+import test from "node:test";
+import { healMigrationLedger, RENAMED_MIGRATIONS } from "../app/migrationHeal.ts";
+import { assert, assertEquals, assertThrows } from "#test-assert";
+import { applyMigrationSet, readMigrationSetFromDisk } from "#test-migrations";
+
+const NEW_NAME = "046_user_tasks_subject_title.sql";
+const OLD_NAME = "043_user_tasks_subject_title.sql";
+
+// A DB migrated fully with the CURRENT set, then rewound to model an install that applied the
+// renamed migration under its OLD filename: the schema change is present, but the ledger records the
+// old name — exactly the state a boot between #311 and #316 left behind.
+function dbAppliedUnderOldName(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  applyMigrationSet(db, readMigrationSetFromDisk());
+  db.prepare("UPDATE _urban_migrations SET name=? WHERE name=?").run(OLD_NAME, NEW_NAME);
+  return db;
+}
+
+const applied = (db: DatabaseSync, name: string): boolean =>
+  (db.prepare("SELECT 1 AS one FROM _urban_migrations WHERE name=?").get(name) as
+    | { one: number }
+    | undefined) !== undefined;
+
+test("RENAMED_MIGRATIONS pins the 043->046 user_tasks_subject_title rename", () => {
+  assertEquals(RENAMED_MIGRATIONS.get(NEW_NAME), OLD_NAME);
+});
+
+test("#357 repro: re-applying the current set to a DB migrated under the old name aborts on duplicate column", () => {
+  const db = dbAppliedUnderOldName();
+  // The renamed migration is unapplied under its NEW name, so the runtime re-runs its
+  // `ALTER TABLE user_tasks ADD COLUMN subject_title` against a table that already has the column.
+  const err = assertThrows(() => applyMigrationSet(db, readMigrationSetFromDisk()));
+  assert(
+    /duplicate column name: subject_title/.test(err.message),
+    `expected a duplicate-column abort, got: ${err.message}`,
+  );
+});
+
+test("heal reconciles the ledger so the upgrade completes cleanly", () => {
+  const db = dbAppliedUnderOldName();
+
+  const healed = healMigrationLedger(db);
+  assertEquals(healed, [NEW_NAME], "the new filename was aliased into the ledger");
+  assert(applied(db, NEW_NAME), "046 is now recorded as applied");
+  assert(applied(db, OLD_NAME), "the historical 043 ledger row is left intact");
+
+  // With the ledger reconciled, the renamed migration is skipped and the boot-time upgrade is clean.
+  const newly = applyMigrationSet(db, readMigrationSetFromDisk());
+  assertEquals(newly, [], "no migration re-runs after the heal");
+});
+
+test("heal is idempotent and a no-op on a healthy DB", () => {
+  // A DB that applied the migration under its CURRENT name needs no healing.
+  const clean = new DatabaseSync(":memory:");
+  applyMigrationSet(clean, readMigrationSetFromDisk());
+  assertEquals(healMigrationLedger(clean), [], "clean install: nothing to heal");
+
+  // Healing twice changes nothing the second time.
+  const broken = dbAppliedUnderOldName();
+  assertEquals(healMigrationLedger(broken), [NEW_NAME]);
+  assertEquals(healMigrationLedger(broken), [], "second heal is a no-op");
+});
+
+test("heal is a no-op on a fresh DB with no migration ledger", () => {
+  const fresh = new DatabaseSync(":memory:");
+  assertEquals(healMigrationLedger(fresh), [], "no ledger table => nothing to heal");
+});

package/app/migrationHeal.ts

@@ -0,0 +1,74 @@
+// migrationHeal — recover installs broken by a migration that was RENAMED after it had already
+// merged and applied (issue #357).
+//
+// The runtime (`@nanobpm/urban` applyMigrations) keys the `_urban_migrations` ledger by FILENAME, so
+// a renamed migration is a *different* migration to the runner: it re-runs its DDL against a schema
+// that already has the change, and a bare `ALTER TABLE ... ADD COLUMN` then aborts boot with
+// "duplicate column". The direct hazard is now blocked forward by the immutability gate
+// (`scripts/check-migrations.ts`), but installs that migrated under the OLD name *before* the rename
+// landed are already stuck and need their ledger reconciled.
+//
+// The fix is a ledger-alias, NOT a schema change and NOT an edit to the renamed migration (editing a
+// merged migration is itself forbidden by the immutability gate, and would silently no-op on every
+// already-migrated DB anyway): if the old filename is recorded as applied, the new filename names the
+// exact same forward-only change, so it is safe — and correct — to record the new filename as applied
+// too. `healMigrationLedger` does that, guarded so it only ever fires on the broken state.
+//
+// `RENAMED_MIGRATIONS` is the single source of truth for known historical renames. It exists ONLY to
+// heal the pre-gate past — the immutability gate prevents any new entry from ever being needed.
+import type { DatabaseSync } from "node:sqlite";
+
+const MIGRATIONS_TABLE = "_urban_migrations";
+
+// new filename -> old filename, for merged migrations that were renamed before the immutability gate
+// existed. Each entry names the SAME forward-only change under two prefixes, so aliasing the ledger
+// from the old name to the new is lossless.
+//
+// - `046_user_tasks_subject_title.sql` was merged as `043_user_tasks_subject_title.sql` (#311) and
+//   renumbered to 046 (#316) to break a prefix collision with `043_pr_epic_phase.sql`. Any DB that
+//   booted between those two PRs applied it as 043 and now re-runs it as 046 → "duplicate column
+//   name: subject_title" (issue #357).
+export const RENAMED_MIGRATIONS: ReadonlyMap<string, string> = new Map([
+  ["046_user_tasks_subject_title.sql", "043_user_tasks_subject_title.sql"],
+]);
+
+/** Does the `_urban_migrations` ledger table exist? A fresh/never-migrated DB has nothing to heal. */
+function ledgerExists(db: DatabaseSync): boolean {
+  return (
+    db
+      .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?")
+      .get(MIGRATIONS_TABLE) !== undefined
+  );
+}
+
+function isApplied(db: DatabaseSync, name: string): boolean {
+  return db.prepare(`SELECT 1 AS one FROM ${MIGRATIONS_TABLE} WHERE name=?`).get(name) !== undefined;
+}
+
+/**
+ * Reconcile the migration ledger for known historical renames, in place. For every rename where the
+ * OLD filename is recorded as applied but the NEW one is not, record the new filename as applied
+ * (aliasing the ledger) so the runtime stops re-running the renamed migration.
+ *
+ * Idempotent and safe on every state:
+ *  - old applied, new missing  -> alias inserted (the broken install; the only case that acts)
+ *  - both applied              -> no-op (overlay-drift install carrying both files)
+ *  - only new applied          -> no-op (clean install that never saw the old name)
+ *  - neither applied / no ledger-> no-op (fresh DB)
+ *
+ * @returns the new filenames that were aliased in (empty when nothing needed healing).
+ */
+export function healMigrationLedger(db: DatabaseSync, now: () => Date = () => new Date()): string[] {
+  if (!ledgerExists(db)) return [];
+  const healed: string[] = [];
+  for (const [newName, oldName] of RENAMED_MIGRATIONS) {
+    if (isApplied(db, oldName) && !isApplied(db, newName)) {
+      db.prepare(`INSERT OR IGNORE INTO ${MIGRATIONS_TABLE} (name, applied_at) VALUES (?, ?)`).run(
+        newName,
+        now().toISOString(),
+      );
+      healed.push(newName);
+    }
+  }
+  return healed;
+}