@nanobpm/nano-workforce 0.124.0 → 0.125.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.125.0](https://github.com/nanobpm/nano-workforce/compare/v0.124.0...v0.125.0) (2026-08-23)
+
+
+### Features
+
+* **read-model:** declare feature_read_model once via Urban defineReadModel (ADR-0065 step 2) ([#472](https://github.com/nanobpm/nano-workforce/issues/472)) ([6424efb](https://github.com/nanobpm/nano-workforce/commit/6424efbeabec60366567e218f12edd996bb96780)), closes [#422](https://github.com/nanobpm/nano-workforce/issues/422)
+
 # [0.124.0](https://github.com/nanobpm/nano-workforce/compare/v0.123.2...v0.124.0) (2026-08-23)
 
 

package/app/featureReadModel.test.ts

@@ -1,39 +1,41 @@
-// Read-model VIEW coverage for the feature-run pipeline projection (issue #439 — the status-driven
-// follow-up to epic #412, "Retire worker-maintained denormalized projections in favour of SQL
-// VIEWs").
+// Read-model coverage for the feature-run pipeline projection (issues #412 → #439 → #422), now
+// authored via Urban's ADR-0065 declare-once primitive (`defineReadModel`, app/featureReadModel.ts).
 //
-// 039_feature_pipeline_stage.sql denormalised the pipeline projection
-// (`stage`/`stage_state`/`stage_skipped`/`attention`/`list_bucket`) onto the `feature_runs` row,
-// written by the `featureRuns()` gateway (app/feature.ts) at WRITE TIME from the pure `deriveStage` /
-// `deriveListBucket` (app/stage.ts). That "the gateway is the sole write path" invariant did NOT hold
-// for the framework `instanceTracking` reconciler, which writes `feature_runs.status` through the RAW
-// datasource on a terminated instance — bypassing the gateway and freezing the display columns.
-// 073_feature_read_model.sql retires the write-time projection: the derived columns are now a VIEW
-// over each row's own `status`/`pr_key`/`converge`/`auto_merge`/`acknowledged_at`, so there is no
-// stored column and no write-path for any writer to leave stale. 075_feature_read_model_attention_
-// from_user_tasks.sql then moves `attention` off the drift-prone `status` variable onto ENGINE TRUTH
-// — an OPEN `feature-blocked`/`feature-escalation` row in the `user_tasks` inbox (issue #422).
+// 039_feature_pipeline_stage.sql denormalised the projection (`stage`/`stage_state`/`stage_skipped`/
+// `attention`/`list_bucket`) onto the `feature_runs` row at WRITE TIME; 073 retired that into a VIEW
+// over each row's own columns; 075 moved `attention` onto ENGINE TRUTH (an OPEN `user_tasks` row,
+// issue #422). Each of those hand-wired the derived columns TWICE — the SQL CASE/EXISTS AND the TS
+// oracle (`deriveStage`/`deriveListBucket`) — kept in lockstep by a bespoke parity test (drift
+// surface #2). 076_feature_read_model_declare_once.sql supersedes them: every derived column is now
+// emitted from the ONE `featureReadModel` declaration, which ALSO drives the TS via `fnFor`. This
+// suite therefore guards THREE things:
 //
-// This exercises the REAL SQLite view (073+075 applied to an in-memory DB, mirroring
-// app/plansReadModel.test.ts / app/mergesPerDayView.test.ts) and pins that its CASE expressions
-// reproduce `deriveStage` / `deriveListBucket` EXACTLY over the full status × open-task matrix — the
-// SAME pure helpers the acknowledge operations guard on — plus RED/GREEN guards reproducing the
-// reconciler bypass (a RAW-datasource `status` write must leave the projection correct) and the #422
-// answered-escalation drift (a sticky `status='escalated'` with no open task must show no ⚠).
+//   1. DRIFT GUARD — migration 076 embeds each derived column's SQL VERBATIM from
+//      `featureReadModel.sqlSelectFor(...)`, so the checked-in VIEW cannot drift from the declaration.
+//   2. FRAMEWORK PARITY GUARD — `assertReadModelParity` proves the SQL and TS lowerings the ONE
+//      declaration compiles to agree (the role the old hand-written lockstep test played, now
+//      framework-owned).
+//   3. END-TO-END BEHAVIOUR on the REAL migration VIEW (076 applied to an in-memory DB): the full
+//      status × open-task matrix vs the model-derived oracle, the stale-stored-column ignore, the
+//      reconciler `status`-bypass, the #422 answered-escalation drift, and the page binding.
 import { readFileSync } from "node:fs";
 import { DatabaseSync } from "node:sqlite";
 import { test } from "node:test";
 import { fileURLToPath } from "node:url";
+import { assertReadModelParity, type ParityDb, type ParitySample } from "@nanobpm/urban";
 import { assert, assertEquals } from "#test-assert";
 import { FEATURE_RUN_STATUSES } from "./feature.ts";
+import { FEATURE_READ_MODEL_BASE_ALIAS, FEATURE_READ_MODEL_DERIVED, featureReadModel } from "./featureReadModel.ts";
 import { deriveListBucket, deriveStage } from "./stage.ts";
 
 const MIG = (name: string) => readFileSync(fileURLToPath(new URL(`../db/migrations/${name}`, import.meta.url)), "utf8");
 const PAGE = (name: string) => JSON.parse(readFileSync(fileURLToPath(new URL(`../pages/${name}`, import.meta.url)), "utf8"));
 
-// The base `feature_runs` shape the view reads (028 + 030's delivery_label + 035's title + 039's
-// acknowledged_at & the now-vestigial stored stage/… columns), plus migration 073. The stored derived
-// columns are present precisely so the tests can seed STALE values and prove the VIEW ignores them.
+const MIGRATION_076 = "076_feature_read_model_declare_once.sql";
+
+// The base `feature_runs` shape the VIEW reads, plus the `user_tasks` inbox (034) the `attention`
+// derivation `EXISTS`-reads. The stored derived columns are present precisely so the tests can seed
+// STALE values and prove the VIEW ignores them.
 function viewDb(): DatabaseSync {
   const db = new DatabaseSync(":memory:");
   db.exec(
@@ -43,16 +45,12 @@ function viewDb(): DatabaseSync {
        outcome TEXT, delivery_label TEXT, acknowledged_at TEXT, created_at TEXT, updated_at TEXT,
        stage TEXT, stage_state TEXT, stage_skipped TEXT, attention TEXT, list_bucket TEXT);`,
   );
-  // The `user_tasks` inbox (034_user_tasks_inbox.sql) — the engine-truth source the 075 VIEW derives
-  // `attention` from (a row IFF an escalation user task is OPEN). Minimal shape: the three columns the
-  // correlated EXISTS lookups read, plus its PK.
   db.exec(
     `CREATE TABLE user_tasks (
        user_task_key TEXT PRIMARY KEY, element_id TEXT NOT NULL, subject_type TEXT NOT NULL,
        subject_key TEXT NOT NULL);`,
   );
-  db.exec(MIG("073_feature_read_model.sql"));
-  db.exec(MIG("075_feature_read_model_attention_from_user_tasks.sql"));
+  db.exec(MIG(MIGRATION_076));
   return db;
 }
 
@@ -71,7 +69,7 @@ interface SampleRun {
   auto_merge?: number;
   acknowledged_at?: string | null;
   // Deliberately-stale STORED projection columns (simulating a row the gateway last projected while
-  // in a different status). The VIEW must ignore these and re-derive from `status`.
+  // in a different status). The VIEW must ignore these and re-derive.
   stored?: Partial<Record<"stage" | "stage_state" | "stage_skipped" | "attention" | "list_bucket", string>>;
 }
 
@@ -114,7 +112,67 @@ function projection(db: DatabaseSync, feature_key: string): Record<string, unkno
   return { ...r };
 }
 
-test("feature_read_model derives stage/stage_state/stage_skipped/attention EXACTLY like deriveStage, over every status × converge/auto_merge/pr_key × open-task combination", () => {
+// A `ParityDb` over node:sqlite's `DatabaseSync` for `assertReadModelParity` (which needs positional
+// `exec`/`all`/`run`, whereas `DatabaseSync` exposes query methods on prepared statements).
+function parityDb(db: DatabaseSync): ParityDb {
+  return {
+    exec: (sql) => db.exec(sql),
+    all: <T = Record<string, unknown>>(sql: string, params: unknown[] = []) =>
+      db.prepare(sql).all(...(params as never[])) as T[],
+    run: (sql, params: unknown[] = []) => {
+      const r = db.prepare(sql).run(...(params as never[]));
+      return { changes: Number(r.changes), lastInsertRowid: r.lastInsertRowid };
+    },
+  };
+}
+
+test("DRIFT GUARD: migration 076 embeds each derived column VERBATIM from featureReadModel.sqlSelectFor (the VIEW cannot drift from the declaration)", () => {
+  const sql = MIG(MIGRATION_076);
+  for (const col of FEATURE_READ_MODEL_DERIVED) {
+    const emitted = featureReadModel.sqlSelectFor(col, { baseAlias: FEATURE_READ_MODEL_BASE_ALIAS });
+    assert(
+      sql.includes(`${emitted} AS ${col}`),
+      `migration ${MIGRATION_076} no longer embeds the declaration's SQL for "${col}" — regenerate it ` +
+        `from featureReadModel (or add a new superseding migration). Expected to contain:\n  ${emitted} AS ${col}`,
+    );
+  }
+  // The VIEW is a DROP+CREATE that supersedes 073/075, and keeps every base column as an aliased
+  // pass-through so the static pages↔schema contract guard still sees them.
+  assert(/DROP VIEW IF EXISTS feature_read_model;/.test(sql), "076 must DROP the superseded VIEW first");
+  assert(/CREATE VIEW feature_read_model AS/.test(sql), "076 must (re)create feature_read_model");
+  for (const base of ["feature_key", "status", "pr_key", "converge", "auto_merge", "acknowledged_at", "title", "repo"]) {
+    assert(sql.includes(`fr.${base} AS ${base}`), `076 must pass base column "${base}" through the VIEW`);
+  }
+});
+
+test("FRAMEWORK PARITY GUARD: featureReadModel's SQL and TS lowerings agree over the full status × open-task matrix (assertReadModelParity)", () => {
+  const samples: ParitySample[] = [];
+  for (const status of FEATURE_RUN_STATUSES) {
+    for (const converge of [0, 1]) {
+      for (const auto_merge of [0, 1]) {
+        for (const pr_key of [null, "o/r#pr"]) {
+          for (const acknowledged_at of [null, "2026-02-02T00:00:00Z"]) {
+            const el = status === "escalated" ? "feature-escalation" : status === "awaiting_operator" ? "feature-blocked" : null;
+            for (const openTask of el !== null ? [false, true] : [false]) {
+              const userTasks =
+                openTask && el !== null ? [{ subject_type: "feature", subject_key: "self", element_id: el }] : [];
+              samples.push({
+                baseRow: { feature_key: "self", status, pr_key, converge, auto_merge, acknowledged_at },
+                projections: { user_tasks: userTasks },
+              });
+            }
+          }
+        }
+      }
+    }
+  }
+  // A bare in-memory handle: the guard builds/drops its OWN TEMP fixtures, so it needs no schema.
+  const db = new DatabaseSync(":memory:");
+  assertReadModelParity(featureReadModel, parityDb(db), samples);
+  db.close();
+});
+
+test("the migration 076 VIEW derives stage/stage_state/stage_skipped/attention EXACTLY like deriveStage, over every status × converge/auto_merge/pr_key × open-task combination", () => {
   const db = viewDb();
   const cases: Array<{ key: string; run: SampleRun; hasOpenBlockedTask: boolean; hasOpenEscalationTask: boolean }> = [];
   let i = 0;
@@ -123,10 +181,7 @@ test("feature_read_model derives stage/stage_state/stage_skipped/attention EXACT
       for (const auto_merge of [0, 1]) {
         for (const pr_key of [null, `o/r#pr${i}`]) {
           // The open-task dimension only matters for the two human-wait statuses (escalated/
-          // awaiting_operator), whose derivation reads open tasks — for them exercise BOTH
-          // task-present and task-absent (the #422 drift case = the task already gone). Every other
-          // status ignores open tasks (`el` is null, so no task is ever created), so iterating the
-          // dimension there would only duplicate identical cases; iterate [false] alone.
+          // awaiting_operator); every other status ignores open tasks, so iterate [false] alone there.
           const el = status === "escalated" ? "feature-escalation" : status === "awaiting_operator" ? "feature-blocked" : null;
           for (const openTask of el !== null ? [false, true] : [false]) {
             const key = `o/r#${i++}`;
@@ -162,7 +217,7 @@ test("feature_read_model derives stage/stage_state/stage_skipped/attention EXACT
   }
 });
 
-test("feature_read_model derives list_bucket EXACTLY like deriveListBucket (history iff terminal AND acknowledged)", () => {
+test("the migration 076 VIEW derives list_bucket EXACTLY like deriveListBucket (history iff terminal AND acknowledged)", () => {
   const db = viewDb();
   let i = 0;
   const cases: Array<{ key: string; status: string; ackAt: string | null }> = [];
@@ -182,7 +237,7 @@ test("feature_read_model derives list_bucket EXACTLY like deriveListBucket (hist
   }
 });
 
-test("feature_read_model IGNORES any stale STORED projection columns — it reads only from status et al.", () => {
+test("the migration 076 VIEW IGNORES any stale STORED projection columns — it reads only from status et al.", () => {
   const db = viewDb();
   // A merged run whose STORED columns lie (frozen from when it was `running`). The VIEW must re-derive.
   addRun(db, "o/r#stale", {
@@ -202,10 +257,10 @@ test("feature_read_model IGNORES any stale STORED projection columns — it read
 test("RED/GREEN GUARD #422: an ANSWERED escalation (status sticky 'escalated', no open user task) shows NO ⚠; the badge tracks the OPEN task, not status", () => {
   // The `feature` process answer-loop returns the token to `implement-task` without resetting the
   // `status` variable, so a run whose escalation was already answered still reads `status="escalated"`
-  // until its next agent job completes (observed live on merlin: feature instance 31779). The OLD VIEW
-  // derived `attention` from that value and rendered a stale ⚠ on Overview. The badge now derives from
-  // engine truth — the presence of an OPEN `feature-escalation` user task (`pollUserTasks` deletes the
-  // row the moment it is answered) — so it clears immediately regardless of the stale status.
+  // until its next agent job completes (observed live on merlin: feature instance 31779). The badge
+  // now derives from engine truth — the presence of an OPEN `feature-escalation` user task
+  // (`pollUserTasks` deletes the row the moment it is answered) — so it clears immediately regardless
+  // of the stale status.
   const db = viewDb();
 
   // Answered escalation: status STILL 'escalated' (stale) + a stored ⚠ that lied, but NO open task.
@@ -233,44 +288,32 @@ test("RED/GREEN GUARD #422: an ANSWERED escalation (status sticky 'escalated', n
 test("RED/GREEN GUARD: a RAW-datasource feature_runs.status write (the instanceTracking reconciler bypass) leaves the projection CORRECT (stage=Done, terminal stage_state, attention=null, Dismiss renderable, still Active)", () => {
   // Reproduce the framework `instanceTracking` reconciler class of bug: on a terminated (cancelled)
   // process instance it writes `{status:"abandoned"}` to `feature_runs` through the RAW datasource,
-  // bypassing the (now retired) projecting `featureRuns` gateway. Under the OLD write-time projection
-  // the stored `stage`/`stage_state`/`attention`/`list_bucket` would FREEZE at their pre-terminal
-  // values — the merlin symptom: a cancelled run wedged in Active as a live-looking `Implementing ⚠`,
-  // its Dismiss gated shut on a NULL stage_state. Because the projection is now a VIEW over `status`,
-  // the read model stays correct with no write-path for any writer to leave it stale.
+  // bypassing the (now retired) projecting `featureRuns` gateway. Because the projection is a VIEW over
+  // `status`, the read model stays correct with no write-path for any writer to leave it stale.
   const db = viewDb();
-  // A live run mid-flight — its (soon-stale) stored projection says Implementing / ⚠ / active.
   addRun(db, "o/r#kill", {
     status: "running",
     stored: { stage: "Implementing", stage_state: undefined, attention: undefined, list_bucket: "active" },
   });
   assertEquals(projection(db, "o/r#kill").stage, "Implementing", "precondition: live run renders Implementing");
 
-  // The reconciler flips status terminal via the RAW table — NOT the gateway. (Simulated with a raw
-  // UPDATE, exactly what the raw datasource emits.) It touches none of the display columns.
   db.prepare("UPDATE feature_runs SET status = 'abandoned' WHERE feature_key = ?").run("o/r#kill");
 
   const row = projection(db, "o/r#kill");
   const oracle = deriveStage({ status: "abandoned", pr_key: null, converge: 0, auto_merge: 0 });
-  // The projection tracks `status` through the VIEW — the merlin drift can no longer happen.
   assertEquals(row.stage, "Done", "an abandoned run is Done, not wedged at Implementing");
   assertEquals(row.stage, oracle.stage);
   assertEquals(row.stage_state, "failed", "abandoned renders a terminal FAILED state (was frozen NULL)");
   assertEquals(row.stage_state, oracle.state);
   assertEquals(row.attention, null, "the stale ⚠ badge is gone");
   assertEquals(row.attention, oracle.attention);
-  // Dismiss's `showWhenField` is `stage_state`: a non-null terminal state makes it renderable.
   assert(row.stage_state != null, "Dismiss is renderable (stage_state is non-null) so the run can be ticked off");
-  // Unacknowledged terminal → still Active (History only after the operator dismisses it).
   assertEquals(row.list_bucket, "active", "a just-cancelled run sits in Active until dismissed");
   assertEquals(row.list_bucket, deriveListBucket("abandoned", null));
 });
 
 test("the Feature page binds the derived feature_read_model VIEW (not the raw feature_runs table)", () => {
   // `feature.page.json`'s runs grid is the ONLY thing making the UI consume the derived projection.
-  // `feature_runs` remains a valid schema table, so reverting this binding would leave every SQL-view
-  // test green while the display silently resumed reading the stale stored columns; pin it here
-  // (suppressed advisory feature.page.json — issue #439).
   const page = PAGE("feature.page.json");
   const runs = (page.nodes ?? []).find((n: { id: string }) => n.id === "feature-runs");
   assert(runs, "feature page must keep the Feature runs grid");

package/app/featureReadModel.ts

@@ -0,0 +1,152 @@
+// The `feature_read_model` derived read model — DECLARED ONCE and compiled to BOTH backends via
+// Urban's ADR-0065 reconciling-read-model primitive (`defineReadModel`, `@nanobpm/urban`).
+//
+// Background (issues #412 → #439 → #422). The Feature Runs surface renders DERIVED state — a run's
+// pipeline `stage`, its `stage_state`/`stage_skipped`, its `attention` badge, its Active/History
+// `list_bucket`. None of these are ground truth: each is a pure function of the row's own
+// `status`/`pr_key`/`converge`/`auto_merge`/`acknowledged_at` plus, for `attention`, the engine's
+// open-user-task set. #412/#439 retired the WRITE-TIME denormalised projection into a SQLite VIEW
+// (`feature_read_model`) so no writer can freeze a stored column; #458 (migration 075) then re-pointed
+// `attention` off the drift-prone `status` variable onto ENGINE TRUTH — an OPEN `user_tasks` row.
+//
+// Two drift surfaces survived that hand-wired VIEW (ADR-0065, nano-ide#452):
+//   * #2 — every derived column was authored TWICE: the SQL `CASE`/`EXISTS` inside the migration VIEW
+//     AND the TypeScript oracle (`deriveStage`/`deriveListBucket`, app/stage.ts), kept in lockstep by
+//     a hand-written parity test. The lockstep test does not remove the duplication; it only alarms
+//     when the two copies diverge.
+//   * #3 — the migration, the VIEW DDL and the parity test were all hand-wired per projection.
+//
+// This module closes surface #2 STRUCTURALLY (ADR-0065 rollout step 2 — "declare once → compile to
+// both", no engine-truth change): each derivation is expressed ONCE in Urban's closed expression DSL,
+// and Urban compiles it to BOTH the SQLite VIEW select-list (`sqlSelectFor` — emitted verbatim into
+// migration 076, drift-guarded) AND the runtime TS function (`fnFor` — the sole engine behind the
+// `deriveStage`/`deriveListBucket` adapters in app/stage.ts). There is nothing left to keep in
+// lockstep: the two lowerings fall out of the SAME AST, and `assertReadModelParity` (app/
+// featureReadModel.test.ts) is now a framework-owned regression guard that the two lowerings agree,
+// not an app-authored mirror of two hand-maintained copies.
+//
+// SCOPE (step 2). The `attention` derivation reads the app's own `user_tasks` inbox by name (the same
+// engine-truth source migration 075 used) via the DSL's `exists(...)`; promoting that to the framework
+// canonical `urban_open_user_tasks` projection and inverting `instanceTracking` writer→source are the
+// LATER ADR-0065 rollout steps (3/4), deliberately out of scope here.
+
+import { and, caseWhen, col, defineReadModel, type Expr, eq, exists, lit, neq, not, or, pcol, type ReadModel, when } from "@nanobpm/urban";
+
+/** The 6 TRULY-terminal statuses that map to the `Done` stage — the single source of truth for the
+ * terminal tier of BOTH the pipeline `stage`/`stage_state` derivations and the `list_bucket` history
+ * partition. Distinct from `FEATURE_TERMINAL_STATUSES` (app/feature.ts), the redispatch-settled set,
+ * which also counts `opened`/`converging` as terminal — those are LIVE pipeline stages (`PR open`/
+ * `Converging`), NOT `Done`, so the two lists must stay separate. Re-exported from app/stage.ts for
+ * back-compat with its existing importers. */
+export const STAGE_DONE_STATUSES: readonly string[] = ["merged", "converged", "blocked", "failed", "skipped", "abandoned"];
+
+/** The DSL projection name the `attention` derivation `exists(...)`-reads. Unregistered in the
+ * `projectionRegistry`, so it resolves to the same-named physical table — the app's own `user_tasks`
+ * inbox (034_user_tasks_inbox.sql), reconciled by `pollUserTasks` (app/service.ts): a row exists IFF a
+ * native operator user task is currently OPEN, deleted the moment it closes. (ADR-0065 step 3 will
+ * promote this to the framework's canonical `urban_open_user_tasks` projection.) */
+export const USER_TASKS_PROJECTION = "user_tasks";
+
+/** `status IN (…)` as a closed-DSL predicate: an OR of equalities over the base row's `status`. */
+const statusIn = (...statuses: readonly string[]): Expr => or(...statuses.map((s) => eq(col("status"), lit(s))));
+
+/** The terminal tier — the row's `status` is one of the 6 `Done` statuses. */
+const isDone: Expr = statusIn(...STAGE_DONE_STATUSES);
+
+/** The canonical pipeline `stage`. TOTAL over all 11 statuses. Terminal → `Done`; else `converging`
+ * → `Converging`; else a raised PR (`pr_key` set, mirroring `(pr_key ?? "") !== ""`) or `opened` →
+ * `PR open`; else a live/parked implementation status → `Implementing`; else `Requested`. */
+const stage: Expr = caseWhen(
+  [
+    when(isDone, lit("Done")),
+    when(eq(col("status"), lit("converging")), lit("Converging")),
+    when(or(neq(col("pr_key"), lit("")), eq(col("status"), lit("opened"))), lit("PR open")),
+    when(statusIn("running", "escalated", "awaiting_operator"), lit("Implementing")),
+  ],
+  lit("Requested"),
+);
+
+/** The active stage's render state in the `kind:"pipeline"` column's vocabulary: `ok` (merged/
+ * converged), `blocked` (terminal blocked), `failed` (failed/skipped/abandoned), else NULL (in
+ * progress). A pure function of `status`, so it is correct even for a parked/live status (NULL). */
+const stageState: Expr = caseWhen(
+  [
+    when(statusIn("merged", "converged"), lit("ok")),
+    when(eq(col("status"), lit("blocked")), lit("blocked")),
+    when(statusIn("failed", "skipped", "abandoned"), lit("failed")),
+  ],
+  lit(null),
+);
+
+/** The space-separated set of pipeline stages NOT in this row's path, purely from `converge`/
+ * `auto_merge`: no converge ⇒ both `Converging` and `Merging` are skipped; converge but no auto-merge
+ * ⇒ only `Merging`; else none. (`not(col(...))` mirrors the TS `!truthy(...)` under the shared
+ * "NULL → false" rule.) */
+const stageSkipped: Expr = caseWhen(
+  [
+    when(not(col("converge")), lit("Converging Merging")),
+    when(not(col("auto_merge")), lit("Merging")),
+  ],
+  lit(""),
+);
+
+/** The correlation predicate for an OPEN operator user task of `elementId` on this feature run: a
+ * `user_tasks` row keyed `subject_type='feature'`, `subject_key=<this row's feature_key>` (how
+ * `pollUserTasks` keys them — app/service.ts `DEFAULT_SUBJECT_TYPE`/`contextFor`). */
+const openTaskWhere = (elementId: string): Expr =>
+  and(eq(pcol("subject_type"), lit("feature")), eq(pcol("subject_key"), col("feature_key")), eq(pcol("element_id"), lit(elementId)));
+
+/** The `attention` badge, derived from ENGINE TRUTH — the presence of an OPEN native user task — NOT
+ * from the drift-prone `status` variable (issue #422). `blocked` glyph IFF an open `feature-blocked`
+ * task exists; `⚠` IFF an open `feature-escalation` task exists; else no badge. Once a task is
+ * answered its `user_tasks` row is gone, so the badge clears immediately even while `status` still
+ * reads a stale `"escalated"` on the answer-loop back into `implement-task`. */
+const attention: Expr = caseWhen(
+  [
+    when(exists(USER_TASKS_PROJECTION, openTaskWhere("feature-blocked")), lit("blocked")),
+    when(exists(USER_TASKS_PROJECTION, openTaskWhere("feature-escalation")), lit("⚠")),
+  ],
+  lit(null),
+);
+
+/** `<col> IS NOT NULL` in the closed DSL, which has no dedicated null-test operator: a SELF-equality.
+ * `eq` collapses a nullish operand to false in BOTH backends (`COALESCE(x = x, 0)` in SQL, the nullish
+ * guard in `compareValues` for TS), and any NON-null value equals itself, so this is true IFF the column
+ * is non-NULL — faithful to 073/075's `acknowledged_at IS NOT NULL` and free of the SQLite string→number
+ * truthiness coercion a bare `col(...)` boolean predicate would otherwise rely on (e.g. `''`/`'abc'`). */
+const isNotNull = (name: string): Expr => eq(col(name), col(name));
+
+/** The Active/History partition: `history` IFF the row is in a truly-terminal status AND has been
+ * acknowledged; otherwise `active` (live runs + terminal-but-UNACKNOWLEDGED runs). `acknowledged_at IS
+ * NOT NULL` is expressed via {@link isNotNull} so it stays byte-equivalent to 073/075's VIEW and does
+ * not depend on string→number coercion in either backend. */
+const listBucket: Expr = caseWhen([when(and(isDone, isNotNull("acknowledged_at")), lit("history"))], lit("active"));
+
+/** The keys of {@link featureReadModel}'s DERIVED columns, in the order migration 076 emits them.
+ * Base columns are identity pass-throughs (not derivations) and are listed in the migration directly. */
+export const FEATURE_READ_MODEL_DERIVED = ["stage", "stage_state", "stage_skipped", "attention", "list_bucket"] as const;
+export type FeatureReadModelDerivedColumn = (typeof FEATURE_READ_MODEL_DERIVED)[number];
+
+/**
+ * The declare-once `feature_read_model` derived columns. `selectBaseColumns: false` because the base
+ * columns are plain identity pass-throughs enumerated in migration 076 (so the static pages↔schema
+ * contract guard, which reads a VIEW's columns off an aliased select-list, sees them); this model owns
+ * only the five real DERIVATIONS. Both the migration VIEW (`sqlSelectFor`, drift-guarded) and the
+ * runtime TS oracle (`fnFor`, behind app/stage.ts) are generated from THIS single declaration.
+ */
+export const featureReadModel: ReadModel = defineReadModel({
+  name: "feature_read_model",
+  baseTable: "feature_runs",
+  selectBaseColumns: false,
+  derive: {
+    stage,
+    stage_state: stageState,
+    stage_skipped: stageSkipped,
+    attention,
+    list_bucket: listBucket,
+  },
+});
+
+/** The base alias the managed VIEW gives `feature_runs` — pinned so the emitted derived-column SQL
+ * (`fr."col"`) matches migration 076 exactly (the drift guard compares against this alias). */
+export const FEATURE_READ_MODEL_BASE_ALIAS = "fr";

package/app/stage.ts

@@ -1,41 +1,36 @@
-// Canonical feature-run pipeline stage model (issue #254 §1) — the ONE source of truth for the
-// derived pipeline surface the Feature view renders. Mirrors the single-source-of-truth style of
-// `deriveDelivery` (app/delivery.ts) and `classifyEscalation` (app/escalationTaxonomy.ts): a PURE,
-// read-only function with no data access. The feature_runs gateway (app/feature.ts) projects its
-// output onto the stored `stage`/`stage_state`/`stage_skipped`/`attention` columns at write time,
-// exactly as `delivery_label` is projected — so the declarative dataGrid page consumes ready, stored
-// columns (bound by `{"field":…}`) and never has to call TS or express OR/null in its flat filter DSL.
+// Canonical feature-run pipeline stage model (issue #254 §1) — the ergonomic TS façade over the ONE
+// derived-read-model declaration in app/featureReadModel.ts. The pipeline surface the Feature view
+// renders (`stage`/`stage_state`/`stage_skipped`/`attention`/`list_bucket`) is DERIVED, never ground
+// truth: each column is a pure function of a feature run's own `status`/`pr_key`/`converge`/
+// `auto_merge`/`acknowledged_at` plus, for `attention`, the engine's OPEN-user-task set.
 //
-// The mapping is TOTAL and DETERMINISTIC over all 11 FEATURE_RUN_STATUSES, computed from ONLY the
-// fields stored on the row — never a "previous"/"underlying" stage, because a FeatureRun stores only
-// its CURRENT status (any prior stage was overwritten on transition). Do NOT duplicate this mapping
-// anywhere (not in SQL, not in the page, not in each poller/worker): every writer flows through the
-// gateway, which is the single caller.
+// SINGLE SOURCE OF TRUTH (ADR-0065, nano-ide#452). These derivations are declared ONCE, in Urban's
+// closed expression DSL (`featureReadModel`, app/featureReadModel.ts), and compiled to BOTH the SQLite
+// VIEW (migration 076) and the runtime TS functions used here. `deriveStage`/`deriveListBucket` are
+// now thin ADAPTERS that evaluate that declaration's compiled functions (`fnFor`) — they do NOT
+// re-express the CASE/EXISTS logic in TypeScript, so the SQL and TS lowerings cannot drift (the former
+// hand-written parity test becomes the framework-owned `assertReadModelParity` regression guard). The
+// mapping remains TOTAL and DETERMINISTIC over all 11 FEATURE_RUN_STATUSES. Do NOT duplicate it
+// anywhere (not in SQL, not in the page, not in each poller/worker): every reader flows through the
+// VIEW or these adapters, both sourced from the one declaration.
+
+import { type FeatureReadModelDerivedColumn, featureReadModel, STAGE_DONE_STATUSES, USER_TASKS_PROJECTION } from "./featureReadModel.ts";
+
+// Re-exported for back-compat with existing importers (operations/acknowledgeDone.ts). Its canonical
+// home is now app/featureReadModel.ts, where it feeds the terminal tier of the derived columns.
+export { STAGE_DONE_STATUSES };
 
 /** The canonical pipeline stage keys, in path order. `Merging` is a path/visual stage the renderer
  * fills as upcoming — no status maps to it as the ACTIVE stage (intentional). */
 export const STAGE_KEYS = ["Requested", "Implementing", "PR open", "Converging", "Merging", "Done"] as const;
 export type StageKey = (typeof STAGE_KEYS)[number];
 
-/** The active stage's render state, in the urban 0.53.0 `kind:"pipeline"` column's EXACT vocabulary:
+/** The active stage's render state, in the urban `kind:"pipeline"` column's EXACT vocabulary:
  * `ok` (Done ✓ success), `failed` (Done ✕ failure), `blocked` (blocked glyph), or `null` (in-progress
  * → the renderer treats it as `active`). Any OTHER string silently degrades to `active` in the
  * renderer, so a failed run MUST emit `'failed'` (not `'fail'`) to render as a failure. */
 export type StageState = "ok" | "failed" | "blocked" | null;
 
-/** The 6 TRULY-terminal statuses that map to the `Done` stage. Distinct from
- * `FEATURE_TERMINAL_STATUSES` (app/feature.ts), which is the redispatch-settled set and also counts
- * `opened`/`converging` as terminal — those are LIVE pipeline stages (`PR open`/`Converging`), NOT
- * Done, so this list must stay separate. Also the basis of the `list_bucket` history partition. */
-export const STAGE_DONE_STATUSES: readonly string[] = [
-  "merged",
-  "converged",
-  "blocked",
-  "failed",
-  "skipped",
-  "abandoned",
-];
-
 /** The subset of a FeatureRun `deriveStage` reads. FeatureRun (app/feature.ts) structurally satisfies
  * this; keeping the input structural avoids a stage.ts ↔ feature.ts import cycle. */
 export interface StageInput {
@@ -48,7 +43,8 @@ export interface StageInput {
    * authoritative "who is waiting on a human" set). `attention` derives from THESE, never from the
    * drift-prone `status` variable — so once an escalation is answered (its `user_tasks` row deleted)
    * the badge clears immediately even while `status` still reads a stale `"escalated"`. Omitted/false
-   * ⇒ no open task ⇒ no badge. `feature_read_model` (075) mirrors this with correlated EXISTS lookups. */
+   * ⇒ no open task ⇒ no badge. These booleans are lowered into synthetic `user_tasks` projection rows
+   * so this façade evaluates the SAME `exists(...)` derivation the VIEW compiles. */
   hasOpenBlockedTask?: boolean | null;
   hasOpenEscalationTask?: boolean | null;
 }
@@ -62,60 +58,58 @@ export interface DerivedStage {
   attention: string | null;
 }
 
-const truthy = (v: number | boolean | null | undefined): boolean => v === true || (typeof v === "number" && v !== 0);
-
-/** Derive the canonical pipeline stage, its render state, its not-in-path set, and its attention badge
- * for one feature run. Pure and read-only — TOTAL over all 11 statuses (never returns undefined). */
-export function deriveStage(run: StageInput): DerivedStage {
-  const { status } = run;
+/** The synthetic correlation key threaded through the `attention` derivation: the base row's
+ * `feature_key` and each synthesised open-task row's `subject_key` share this value so the compiled
+ * `exists(... WHERE subject_key = feature_key ...)` predicate matches. Its concrete value is
+ * immaterial (it never leaves this function); it only has to be consistent between the two. */
+const SELF_KEY = "self";
 
-  // TERMINAL tier — the 6 truly-terminal statuses collapse to Done. Unconditional: terminal `blocked`
-  // is the issue §1 'Done ✕' row (state `blocked`), NOT Implementing.
-  let stage: StageKey;
-  let state: StageState;
-  if (STAGE_DONE_STATUSES.includes(status)) {
-    stage = "Done";
-    state =
-      status === "merged" || status === "converged"
-        ? "ok"
-        : status === "blocked"
-          ? "blocked"
-          : "failed"; // failed / skipped / abandoned
-  } else {
-    // LIVE/PARKED tier — one shared rule for every non-terminal status. `escalated`/`awaiting_operator`
-    // are parked but their stored fields still describe WHERE in the pipeline they stalled, so they run
-    // through the same rule as a live run; their attention comes from the badge (below), not the stage.
-    if (status === "converging") stage = "Converging";
-    else if ((run.pr_key ?? "") !== "" || status === "opened") stage = "PR open";
-    else if (status === "running" || status === "escalated" || status === "awaiting_operator") stage = "Implementing";
-    else stage = "Requested";
-    state = null;
-  }
-
-  // `skipped`: stages not in this row's path, purely from converge/auto_merge.
-  const converge = truthy(run.converge);
-  const autoMerge = truthy(run.auto_merge);
-  const skippedKeys: StageKey[] = !converge ? ["Converging", "Merging"] : !autoMerge ? ["Merging"] : [];
+/** The `user_tasks` projection rows a `StageInput`'s open-task booleans stand for — one row per OPEN
+ * operator user task, keyed exactly as `pollUserTasks` records them, so the compiled `attention`
+ * derivation sees the same engine-truth shape at runtime and here. */
+function openTaskRows(run: StageInput): Array<Record<string, unknown>> {
+  const rows: Array<Record<string, unknown>> = [];
+  if (run.hasOpenBlockedTask === true) rows.push({ subject_type: "feature", subject_key: SELF_KEY, element_id: "feature-blocked" });
+  if (run.hasOpenEscalationTask === true) rows.push({ subject_type: "feature", subject_key: SELF_KEY, element_id: "feature-escalation" });
+  return rows;
+}
 
-  // `attention`: a short badge for the active stage (the renderer colours it from `state`). This is how
-  // a parked `awaiting_operator`/`escalated` run surfaces as attention WITHOUT altering its stage.
-  // Derived from ENGINE TRUTH — the presence of an OPEN native user task (issue #422), NOT from the
-  // `status` variable. `status` is worker-written imperatively and goes stale on the answer-loop back
-  // into `implement-task` (the process does not reset it), so a run whose escalation was already
-  // ANSWERED still reads `status="escalated"` until its next job completes; sourcing the badge from
-  // that value made the read model lie (a resolved run flagged ⚠ on Overview). The authoritative
-  // "who is waiting on a human" set is the `user_tasks` inbox (`pollUserTasks`), which holds a row
-  // IFF the task is open and deletes it the moment it is answered — so a run shows the blocked glyph
-  // IFF an open `feature-blocked` task exists, and ⚠ IFF an open `feature-escalation` task exists.
-  // Once answered, the row is gone and the badge clears regardless of the stale `status`.
-  const attention = truthy(run.hasOpenBlockedTask) ? "blocked" : truthy(run.hasOpenEscalationTask) ? "⚠" : null;
+/** Evaluate one derived column from the ONE `featureReadModel` declaration for a base row (plus any
+ * projection rows the derivation correlates against). This is the single seam where the framework's
+ * compiled-function boundary is crossed: `fnFor(column)` returns `unknown` (a derivation can compile to
+ * any DSL value), while the caller statically knows the declared `lit(...)` shape of each column. */
+function evalDerived<T>(column: FeatureReadModelDerivedColumn, baseRow: Record<string, unknown>, projections?: Record<string, Array<Record<string, unknown>>>): T {
+  // biome-ignore lint/plugin: runtime/framework contract boundary — `fnFor` returns `unknown`; each derived column yields one of its declared DSL `lit(...)` values, whose type the caller knows.
+  return featureReadModel.fnFor(column)(baseRow, projections) as T;
+}
 
-  return { stage, state, skipped: skippedKeys.join(" "), attention };
+/** Derive the canonical pipeline stage, its render state, its not-in-path set, and its attention badge
+ * for one feature run. Pure and read-only — TOTAL over all 11 statuses (never returns undefined). The
+ * four columns are evaluated from the ONE `featureReadModel` declaration (app/featureReadModel.ts), so
+ * this façade and the SQLite VIEW compute byte-identical values by construction. */
+export function deriveStage(run: StageInput): DerivedStage {
+  const baseRow = {
+    feature_key: SELF_KEY,
+    status: run.status,
+    pr_key: run.pr_key ?? null,
+    converge: run.converge ?? null,
+    auto_merge: run.auto_merge ?? null,
+  };
+  const projections = { [USER_TASKS_PROJECTION]: openTaskRows(run) };
+  return {
+    stage: evalDerived<StageKey>("stage", baseRow, projections),
+    state: evalDerived<StageState>("stage_state", baseRow, projections),
+    skipped: evalDerived<string>("stage_skipped", baseRow, projections),
+    attention: evalDerived<string | null>("attention", baseRow, projections),
+  };
 }
 
-/** The Active/History partition label (§5), maintained at write time so the flat-DSL page tabs filter
- * on a stored `list_bucket` column with only `in` clauses. `history` iff the row is in a truly-terminal
- * status AND acknowledged; otherwise `active` (live runs + terminal-but-UNACKNOWLEDGED runs). */
+/** The Active/History partition label (§5): `history` iff the row is in a truly-terminal status AND
+ * acknowledged; otherwise `active` (live runs + terminal-but-UNACKNOWLEDGED runs). DERIVED on read from
+ * the ONE `featureReadModel` `list_bucket` declaration — the same AST the VIEW compiles (migration 076),
+ * NOT a write-time projection: the page's tabs filter the VIEW's derived `list_bucket`, and the stored
+ * `feature_runs.list_bucket` base column is vestigial (retired as a write projection, issue #439). This
+ * adapter is the TS lowering of that derivation, used off the write path (redispatch gating, tests). */
 export function deriveListBucket(status: string, acknowledgedAt: string | null | undefined): "active" | "history" {
-  return STAGE_DONE_STATUSES.includes(status) && acknowledgedAt != null ? "history" : "active";
+  return evalDerived<"active" | "history">("list_bucket", { status, acknowledged_at: acknowledgedAt ?? null });
 }

package/db/migrations/076_feature_read_model_declare_once.sql

@@ -0,0 +1,53 @@
+-- Feature-run read model: DECLARE ONCE, compile to BOTH backends (ADR-0065, nano-ide#452).
+--
+-- This migration SUPERSEDES the hand-wired `feature_read_model` VIEW of 073_feature_read_model.sql and
+-- 075_feature_read_model_attention_from_user_tasks.sql. Those authored each derived column TWICE — the
+-- SQL CASE/EXISTS here AND the TypeScript oracle (deriveStage/deriveListBucket, app/stage.ts) — kept in
+-- lockstep by a hand-written parity test (drift surface #2, ADR-0065). This VIEW is no longer
+-- hand-written: every DERIVED column body below is emitted VERBATIM from the ONE declaration in
+-- app/featureReadModel.ts (`featureReadModel.sqlSelectFor(col, { baseAlias: "fr" })`), which ALSO drives the
+-- runtime TS via `fnFor` — the two lowerings fall out of the same closed-DSL AST and cannot diverge.
+-- A drift guard (app/featureReadModel.test.ts) fails if this file stops matching the declaration, and
+-- `assertReadModelParity` proves the SQL and TS lowerings agree.
+--
+-- SEMANTICS ARE UNCHANGED from 075: `attention` still derives from ENGINE TRUTH — an OPEN native user
+-- task in the `user_tasks` inbox (a `feature-blocked` row => blocked glyph, a `feature-escalation` row
+-- => `⚠`), NOT the drift-prone `status` variable (issue #422); `stage`/`stage_state`/`stage_skipped`/
+-- `list_bucket` are the same pure functions of the row. Only the AUTHORING moves to the framework
+-- primitive; the projected values are identical.
+--
+-- Forward-only VIEW redefinition (DROP then CREATE). 073/075 are MERGED, IMMUTABLE migrations — never
+-- edited; this is a NEW migration superseding their VIEW body. `feature_runs` (028+) and `user_tasks`
+-- (034) already exist earlier in the chain, and 075 already created the supporting
+-- `idx_user_tasks_subject_element` index the correlated attention EXISTS lookups seek, so it is not
+-- re-created here. Base columns are plain identity pass-throughs (aliased so the static pages<->schema
+-- contract guard sees the VIEW columns); `feature_runs fr` stays the sole top-level FROM (the user_tasks
+-- lookups are nested EXISTS subqueries at paren depth >= 1). The runner wraps each file in its own
+-- transaction, so this file must NOT contain BEGIN/COMMIT.
+
+DROP VIEW IF EXISTS feature_read_model;
+
+CREATE VIEW feature_read_model AS
+SELECT
+  fr.feature_key AS feature_key,
+  fr.repo AS repo,
+  fr.issue_number AS issue_number,
+  fr.issue_url AS issue_url,
+  fr.title AS title,
+  fr.base_branch AS base_branch,
+  fr.status AS status,
+  fr.process_key AS process_key,
+  fr.pr_key AS pr_key,
+  fr.converge AS converge,
+  fr.auto_merge AS auto_merge,
+  fr.outcome AS outcome,
+  fr.delivery_label AS delivery_label,
+  fr.acknowledged_at AS acknowledged_at,
+  fr.created_at AS created_at,
+  fr.updated_at AS updated_at,
+  CASE WHEN COALESCE((COALESCE(("fr"."status" = 'merged'), 0) OR COALESCE(("fr"."status" = 'converged'), 0) OR COALESCE(("fr"."status" = 'blocked'), 0) OR COALESCE(("fr"."status" = 'failed'), 0) OR COALESCE(("fr"."status" = 'skipped'), 0) OR COALESCE(("fr"."status" = 'abandoned'), 0)), 0) THEN 'Done' WHEN COALESCE(("fr"."status" = 'converging'), 0) THEN 'Converging' WHEN COALESCE((COALESCE(("fr"."pr_key" <> ''), 0) OR COALESCE(("fr"."status" = 'opened'), 0)), 0) THEN 'PR open' WHEN COALESCE((COALESCE(("fr"."status" = 'running'), 0) OR COALESCE(("fr"."status" = 'escalated'), 0) OR COALESCE(("fr"."status" = 'awaiting_operator'), 0)), 0) THEN 'Implementing' ELSE 'Requested' END AS stage,
+  CASE WHEN COALESCE((COALESCE(("fr"."status" = 'merged'), 0) OR COALESCE(("fr"."status" = 'converged'), 0)), 0) THEN 'ok' WHEN COALESCE(("fr"."status" = 'blocked'), 0) THEN 'blocked' WHEN COALESCE((COALESCE(("fr"."status" = 'failed'), 0) OR COALESCE(("fr"."status" = 'skipped'), 0) OR COALESCE(("fr"."status" = 'abandoned'), 0)), 0) THEN 'failed' ELSE NULL END AS stage_state,
+  CASE WHEN (NOT COALESCE("fr"."converge", 0)) THEN 'Converging Merging' WHEN (NOT COALESCE("fr"."auto_merge", 0)) THEN 'Merging' ELSE '' END AS stage_skipped,
+  CASE WHEN EXISTS (SELECT 1 FROM "user_tasks" AS "__urban_proj_0" WHERE COALESCE((COALESCE(("__urban_proj_0"."subject_type" = 'feature'), 0) AND COALESCE(("__urban_proj_0"."subject_key" = "fr"."feature_key"), 0) AND COALESCE(("__urban_proj_0"."element_id" = 'feature-blocked'), 0)), 0)) THEN 'blocked' WHEN EXISTS (SELECT 1 FROM "user_tasks" AS "__urban_proj_0" WHERE COALESCE((COALESCE(("__urban_proj_0"."subject_type" = 'feature'), 0) AND COALESCE(("__urban_proj_0"."subject_key" = "fr"."feature_key"), 0) AND COALESCE(("__urban_proj_0"."element_id" = 'feature-escalation'), 0)), 0)) THEN '⚠' ELSE NULL END AS attention,
+  CASE WHEN COALESCE((COALESCE((COALESCE(("fr"."status" = 'merged'), 0) OR COALESCE(("fr"."status" = 'converged'), 0) OR COALESCE(("fr"."status" = 'blocked'), 0) OR COALESCE(("fr"."status" = 'failed'), 0) OR COALESCE(("fr"."status" = 'skipped'), 0) OR COALESCE(("fr"."status" = 'abandoned'), 0)), 0) AND COALESCE(("fr"."acknowledged_at" = "fr"."acknowledged_at"), 0)), 0) THEN 'history' ELSE 'active' END AS list_bucket
+FROM feature_runs fr;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.124.0",
+  "version": "0.125.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",
@@ -59,7 +59,7 @@
   },
   "dependencies": {
     "@nanobpm/agentic": "^0.1.0",
-    "@nanobpm/urban": "^0.77.1",
+    "@nanobpm/urban": "^0.80.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2"
   },
   "devDependencies": {

package/scripts/check-migrations.test.ts

@@ -103,3 +103,25 @@ test("collision detector flags a non-NNN shape and grandfathers historical dupes
     "grandfathered prefix 075 is not a new violation",
   );
 });
+
+// The grandfather is keyed by the EXACT historical FILENAME set, not just the prefix (Copilot review,
+// #472): pardoning a prefix wholesale would let any future `075_*.sql` slip in unnoticed, defeating the
+// gate for that slot forever. A THIRD file taking a grandfathered prefix is a genuinely NEW collision
+// and must still fail — only the specific already-merged files are exempt.
+test("a NEW file joining a grandfathered prefix is still caught (exact-filename exemption)", () => {
+  // The two real, pardoned 075 files alone: exempt.
+  assertEquals(
+    collisionErrorsFromFiles(["075_delivery_graph_proposals.sql", "075_feature_read_model_attention_from_user_tasks.sql"]),
+    [],
+    "the exact historical 075 pair stays exempt",
+  );
+  // A third file at the same grandfathered prefix is NEW → must fail, naming the offender only.
+  const errors = collisionErrorsFromFiles([
+    "075_delivery_graph_proposals.sql",
+    "075_feature_read_model_attention_from_user_tasks.sql",
+    "075_someone_elses_next_free_prefix.sql",
+  ]);
+  assertEquals(errors.length, 1, "a new file on a grandfathered prefix is one violation");
+  assert(/prefix 075/.test(errors[0]));
+  assert(/075_someone_elses_next_free_prefix.sql is NEW/.test(errors[0]), "the NEW file is named as the offender");
+});

package/scripts/check-migrations.ts

@@ -52,6 +52,7 @@ const MIGRATIONS_DIR = join(REPO_ROOT, "db", "migrations");
 // boot, issue #357). The two create disjoint tables (`worker_durable_resume`, `plan_conformance`), so
 // apply order is irrelevant. Grandfather 052; any NEW duplicate prefix still fails the build.
 //
+//
 // 075 is the same merge-skew story across two PRs that never saw each other (issue #470): #458 landed
 // `075_feature_read_model_attention_from_user_tasks` and #460/#463 landed `075_delivery_graph_proposals`,
 // each the branch-local "next" prefix, colliding silently only once both were on main (releases then
@@ -59,9 +60,23 @@ const MIGRATIONS_DIR = join(REPO_ROOT, "db", "migrations");
 // a merged migration would re-run it and abort boot, and the immutability check would itself flag the
 // rename. They create DISJOINT objects (`075_delivery_graph_proposals` adds the `delivery_graph_proposals`
 // table + its indexes; `075_feature_read_model_…` redefines the `feature_read_model` VIEW and adds one
-// `user_tasks` index), so their relative apply order is irrelevant. Grandfather 075; any NEW duplicate
-// prefix still fails the build (the next migration is 076).
-const GRANDFATHERED_DUPES: ReadonlySet<string> = new Set(["004", "005", "006", "007", "049", "052", "075"]);
+// `user_tasks` index), so their relative apply order is irrelevant. Grandfather 075 (the next migration
+// is 076, which supersedes 075's `feature_read_model` VIEW body — a NEW, unique prefix).
+//
+// The exemption is keyed by the EXACT set of colliding FILENAMES per prefix, not merely the prefix, so
+// it only pardons the specific historical files that already merged — a THIRD file taking a
+// grandfathered prefix (a fresh 075_*.sql, say) is NOT in the set and still fails the gate. This keeps
+// "any NEW duplicate prefix still fails" literally true even for prefixes that already carry a pardoned
+// collision (Copilot review, #472).
+const GRANDFATHERED_DUPES: ReadonlyMap<string, ReadonlySet<string>> = new Map([
+  ["004", new Set(["004_merge.sql", "004_planning.sql"])],
+  ["005", new Set(["005_job_activation.sql", "005_plan_deps.sql"])],
+  ["006", new Set(["006_plan_review.sql", "006_task_escalation.sql"])],
+  ["007", new Set(["007_plan_review_job_key.sql", "007_wave_gate.sql"])],
+  ["049", new Set(["049_drop_feature_escalation_surface.sql", "049_plan_task_needs.sql", "049_world_checkpoint.sql"])],
+  ["052", new Set(["052_plan_conformance.sql", "052_worker_durable_resume.sql"])],
+  ["075", new Set(["075_delivery_graph_proposals.sql", "075_feature_read_model_attention_from_user_tasks.sql"])],
+]);
 
 const PREFIX = /^(\d{3})_[^/]*\.sql$/;
 
@@ -185,13 +200,22 @@ export function collisionErrorsFromFiles(files: readonly string[]): string[] {
   }
 
   for (const [prefix, group] of byPrefix) {
-    if (group.length > 1 && !GRANDFATHERED_DUPES.has(prefix)) {
-      errors.push(
-        `  prefix ${prefix} is used by ${group.length} files: ${[...group].sort().join(", ")} — ` +
+    if (group.length <= 1) continue;
+    // Keyed by the EXACT historical filename set: a grandfathered prefix pardons ONLY those specific
+    // already-merged files. Any file in the group NOT in that set is a NEW collision and still fails.
+    const exempt = GRANDFATHERED_DUPES.get(prefix);
+    const unexpected = exempt ? group.filter((f) => !exempt.has(f)) : group;
+    if (unexpected.length === 0) continue;
+    errors.push(
+      exempt
+        ? `  prefix ${prefix} is used by ${group.length} files: ${[...group].sort().join(", ")} — only the ` +
+          `grandfathered historical set (${[...exempt].sort().join(", ")}) may share this prefix; ` +
+          `${[...unexpected].sort().join(", ")} is NEW. Renumber it to the next free prefix ` +
+          `(check origin/main, not your branch point).`
+        : `  prefix ${prefix} is used by ${group.length} files: ${[...group].sort().join(", ")} — ` +
           `two migrations cannot share an apply-order slot. Renumber the newer one to the next ` +
           `free prefix (check origin/main, not your branch point).`,
-      );
-    }
+    );
   }
 
   return errors;