@nanobpm/nano-workforce 0.154.0 → 0.155.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.155.0](https://github.com/nanobpm/nano-workforce/compare/v0.154.0...v0.155.0) (2026-08-29)
+
+### Features
+
+* **delivery-units:** delivery_units aggregate table (ADR 0006 S2, [#589](https://github.com/nanobpm/nano-workforce/issues/589)) ([#601](https://github.com/nanobpm/nano-workforce/issues/601)) ([6949fc4](https://github.com/nanobpm/nano-workforce/commit/6949fc4d3ee567b95497e43391ba15e9367a88e0))
+
 ## [0.154.0](https://github.com/nanobpm/nano-workforce/compare/v0.153.0...v0.154.0) (2026-08-29)
 
 ### Features

package/app/deliveryUnit.test.ts

@@ -0,0 +1,244 @@
+// Coverage for ADR 0006 slice S2 (#589) — the `delivery_units` aggregate and its DB-level sync.
+//
+// Proves, against a REAL in-memory SQLite with the full migration set applied:
+//   1. VOCABULARY PARITY — the TS `DELIVERY_UNIT_KINDS` closed enum matches the `CHECK (kind IN (…))`
+//      constraint in migration 088 (the two lowerings of the §2 kind enum can't drift).
+//   2. DERIVATION PARITY — for every source status of every shape, the DB triggers/backfill derive the
+//      same canonical `delivery_status` as the S1 read models (app/deliveryUnitStatus.ts) and the same
+//      `dispatch_status` as the TS `dispatchStatusForDelivery` (the SQL and TS lowerings agree).
+//   3. IDENTITY — the derived `unit_id` matches the TS `*UnitId` helpers, and an epic slice node hangs
+//      under its epic (`parent_unit_id`), so the aggregate's universal key is what the door will name.
+//   4. COMPAT-VIEW PARITY — each legacy-shaped `<table>__units` VIEW is row-for-row identical to its
+//      base table over insert/update/delete, so a read path can swap onto the aggregate losslessly.
+import { DatabaseSync } from "node:sqlite";
+import { test } from "node:test";
+import { applyMigrationSet, readMigrationSetFromDisk } from "#test-migrations";
+import { assert, assertEquals } from "#test-assert";
+import {
+  DELIVERY_UNIT_KINDS,
+  deliveryGraphUnitId,
+  dispatchStatusForDelivery,
+  epicUnitId,
+  featureUnitId,
+  planTaskUnitId,
+} from "./deliveryUnit.ts";
+import {
+  type DeliveryUnitStatus,
+  deliveryGraphDeliveryStatus,
+  featureDeliveryStatus,
+  planDeliveryStatus,
+  PLAN_STATUSES,
+  planTaskDeliveryStatus,
+  toDeliveryUnitStatus,
+} from "./deliveryUnitStatus.ts";
+import { DELIVERY_GRAPH_RUN_STATUSES } from "./deliveryGraphRun.ts";
+import { FEATURE_RUN_STATUSES } from "./feature.ts";
+import { PLAN_TASK_STATUSES } from "./plan.ts";
+
+function freshDb(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  db.exec("PRAGMA foreign_keys = ON;");
+  applyMigrationSet(db, readMigrationSetFromDisk());
+  return db;
+}
+
+const NOW = "2026-01-01T00:00:00Z";
+const row = (db: DatabaseSync, sql: string, ...p: unknown[]) => db.prepare(sql).get(...(p as never[])) as Record<string, unknown>;
+const rows = (db: DatabaseSync, sql: string, ...p: unknown[]) => db.prepare(sql).all(...(p as never[])) as Record<string, unknown>[];
+const exec = (db: DatabaseSync, sql: string, ...p: unknown[]) => db.prepare(sql).run(...(p as never[]));
+
+test("VOCABULARY PARITY: DELIVERY_UNIT_KINDS matches migration 088's CHECK (kind IN (…))", () => {
+  const mig = readMigrationSetFromDisk().find((m) => m.name === "088_delivery_units.sql");
+  assert(mig, "088_delivery_units.sql must exist");
+  const m = mig.sql.match(/kind IN \(([^)]*)\)/);
+  assert(m, "088 must declare a CHECK (kind IN (…)) constraint");
+  const declared = m[1].split(",").map((s) => s.trim().replace(/^'|'$/g, ""));
+  assertEquals(declared, [...DELIVERY_UNIT_KINDS], "the SQL kind enum and the TS enum must agree");
+});
+
+test("DERIVATION PARITY: feature triggers derive the S1 canonical + dispatch status for every source status", () => {
+  const db = freshDb();
+  FEATURE_RUN_STATUSES.forEach((status, i) => {
+    const key = `o/r#${100 + i}`;
+    exec(
+      db,
+      `INSERT INTO feature_runs(feature_key,repo,issue_number,issue_url,base_branch,status,created_at,updated_at)
+       VALUES(?,?,?,?,?,?,?,?)`,
+      key, "o/r", 100 + i, "u", "main", status, NOW, NOW,
+    );
+    const u = row(db, "SELECT * FROM delivery_units WHERE unit_id=?", featureUnitId(key));
+    const canonical = toDeliveryUnitStatus(featureDeliveryStatus, status) as DeliveryUnitStatus;
+    assertEquals(u.kind, "feature");
+    assertEquals(u.delivery_status, canonical, `feature ${status} → canonical`);
+    assertEquals(u.dispatch_status, dispatchStatusForDelivery(canonical), `feature ${status} → dispatch`);
+    assertEquals(u.status, status, "raw legacy status is preserved verbatim");
+  });
+});
+
+test("DERIVATION PARITY: epic (plans) triggers derive the S1 canonical + dispatch status for every source status", () => {
+  const db = freshDb();
+  PLAN_STATUSES.forEach((status, i) => {
+    const key = `o/r#${200 + i}`;
+    exec(
+      db,
+      `INSERT INTO plans(plan_key,repo,issue_number,issue_url,status,created_at,updated_at)
+       VALUES(?,?,?,?,?,?,?)`,
+      key, "o/r", 200 + i, "u", status, NOW, NOW,
+    );
+    const u = row(db, "SELECT * FROM delivery_units WHERE unit_id=?", epicUnitId(key));
+    const canonical = toDeliveryUnitStatus(planDeliveryStatus, status) as DeliveryUnitStatus;
+    assertEquals(u.kind, "epic");
+    assertEquals(u.delivery_status, canonical, `epic ${status} → canonical`);
+    assertEquals(u.dispatch_status, dispatchStatusForDelivery(canonical), `epic ${status} → dispatch`);
+  });
+});
+
+test("DERIVATION PARITY + IDENTITY: plan-task nodes derive status and hang under their epic", () => {
+  const db = freshDb();
+  const planKey = "o/r#300";
+  exec(
+    db,
+    `INSERT INTO plans(plan_key,repo,issue_number,issue_url,status,created_at,updated_at) VALUES(?,?,?,?,?,?,?)`,
+    planKey, "o/r", 300, "u", "dispatched", NOW, NOW,
+  );
+  PLAN_TASK_STATUSES.forEach((status, i) => {
+    exec(
+      db,
+      `INSERT INTO plan_tasks(plan_key,task_index,task_id,status,created_at,updated_at) VALUES(?,?,?,?,?,?)`,
+      planKey, i, `t${i}`, status, NOW, NOW,
+    );
+    const u = row(db, "SELECT * FROM delivery_units WHERE unit_id=?", planTaskUnitId(planKey, i));
+    const canonical = toDeliveryUnitStatus(planTaskDeliveryStatus, status) as DeliveryUnitStatus;
+    assertEquals(u.kind, "plan-task");
+    assertEquals(u.delivery_status, canonical, `plan-task ${status} → canonical`);
+    assertEquals(u.dispatch_status, dispatchStatusForDelivery(canonical), `plan-task ${status} → dispatch`);
+    assertEquals(u.parent_unit_id, epicUnitId(planKey), "a node hangs under its epic composition");
+    assertEquals(u.node_index, i, "the node carries its slice ordinal");
+  });
+});
+
+test("DERIVATION PARITY: delivery-graph triggers derive the S1 canonical + dispatch status for every source status", () => {
+  const db = freshDb();
+  DELIVERY_GRAPH_RUN_STATUSES.forEach((status, i) => {
+    const key = `dg${i}`;
+    exec(
+      db,
+      `INSERT INTO delivery_graph_runs(run_key,digest,status,created_at,updated_at) VALUES(?,?,?,?,?)`,
+      key, "abc", status, NOW, NOW,
+    );
+    const u = row(db, "SELECT * FROM delivery_units WHERE unit_id=?", deliveryGraphUnitId(key));
+    const canonical = toDeliveryUnitStatus(deliveryGraphDeliveryStatus, status) as DeliveryUnitStatus;
+    assertEquals(u.kind, "delivery-graph");
+    assertEquals(u.delivery_status, canonical, `delivery-graph ${status} → canonical`);
+    assertEquals(u.dispatch_status, dispatchStatusForDelivery(canonical), `delivery-graph ${status} → dispatch`);
+  });
+});
+
+test("FAIL CLOSED: an unknown legacy status yields NULL delivery_status AND NULL dispatch_status (no inconsistent row)", () => {
+  // The legacy `status` columns are plain TEXT NOT NULL without a CHECK, so an unexpected value can
+  // reach the triggers. `dispatch_status` is derived FROM the canonical `delivery_status`, so when the
+  // status is unrecognised (delivery_status → NULL) dispatch_status MUST also be NULL — never a
+  // dangling 'dispatched'/'settled' on a row whose delivery_status is NULL.
+  const db = freshDb();
+  const cases: [string, () => void, string][] = [
+    [
+      "feature",
+      () =>
+        exec(
+          db,
+          `INSERT INTO feature_runs(feature_key,repo,issue_number,issue_url,base_branch,status,created_at,updated_at) VALUES(?,?,?,?,?,?,?,?)`,
+          "o/r#900", "o/r", 900, "u", "main", "bogus-status", NOW, NOW,
+        ),
+      featureUnitId("o/r#900"),
+    ],
+    [
+      "epic",
+      () =>
+        exec(
+          db,
+          `INSERT INTO plans(plan_key,repo,issue_number,issue_url,status,created_at,updated_at) VALUES(?,?,?,?,?,?,?)`,
+          "o/r#901", "o/r", 901, "u", "bogus-status", NOW, NOW,
+        ),
+      epicUnitId("o/r#901"),
+    ],
+    [
+      "delivery-graph",
+      () =>
+        exec(
+          db,
+          `INSERT INTO delivery_graph_runs(run_key,digest,status,created_at,updated_at) VALUES(?,?,?,?,?)`,
+          "dg900", "abc", "bogus-status", NOW, NOW,
+        ),
+      deliveryGraphUnitId("dg900"),
+    ],
+  ];
+  for (const [kind, insert, unitId] of cases) {
+    insert();
+    const u = row(db, "SELECT delivery_status, dispatch_status FROM delivery_units WHERE unit_id=?", unitId);
+    assertEquals(u.delivery_status, null, `${kind} unknown status → NULL delivery_status`);
+    assertEquals(u.dispatch_status, null, `${kind} unknown status → NULL dispatch_status (fail closed)`);
+  }
+
+  // plan-task needs a parent epic row first.
+  exec(db, `INSERT INTO plans(plan_key,repo,issue_number,issue_url,status,created_at,updated_at) VALUES(?,?,?,?,?,?,?)`, "o/r#902", "o/r", 902, "u", "planning", NOW, NOW);
+  exec(db, `INSERT INTO plan_tasks(plan_key,task_index,task_id,status,created_at,updated_at) VALUES(?,?,?,?,?,?)`, "o/r#902", 0, "t0", "bogus-status", NOW, NOW);
+  const pt = row(db, "SELECT delivery_status, dispatch_status FROM delivery_units WHERE unit_id=?", planTaskUnitId("o/r#902", 0));
+  assertEquals(pt.delivery_status, null, "plan-task unknown status → NULL delivery_status");
+  assertEquals(pt.dispatch_status, null, "plan-task unknown status → NULL dispatch_status (fail closed)");
+});
+
+// ── COMPAT-VIEW PARITY — each `<table>__units` VIEW is byte-identical to its base table. ────────────
+const norm = (r: Record<string, unknown>[]) =>
+  JSON.stringify(r.map((x) => Object.fromEntries(Object.entries(x).sort())));
+
+function assertViewParity(db: DatabaseSync, base: string, view: string) {
+  assertEquals(norm(rows(db, `SELECT * FROM ${base} ORDER BY 1`)), norm(rows(db, `SELECT * FROM ${view} ORDER BY 1`)), `${view} must equal ${base}`);
+}
+
+test("COMPAT-VIEW PARITY: every legacy surface is served row-for-row from the aggregate across insert/update/delete", () => {
+  const db = freshDb();
+  exec(
+    db,
+    `INSERT INTO feature_runs(feature_key,repo,issue_number,issue_url,base_branch,status,converge,auto_merge,outcome,delivery_label,title,created_at,updated_at)
+     VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?)`,
+    "o/r#1", "o/r", 1, "u", "main", "running", 1, 0, null, null, "Feat", NOW, NOW,
+  );
+  exec(
+    db,
+    `INSERT INTO plans(plan_key,repo,issue_number,issue_url,title,status,task_count,base_branch,epic_phase,created_at,updated_at)
+     VALUES(?,?,?,?,?,?,?,?,?,?,?)`,
+    "o/r#2", "o/r", 2, "u", "Epic", "planning", 2, "main", "Planning", NOW, NOW,
+  );
+  exec(
+    db,
+    `INSERT INTO plan_tasks(plan_key,task_index,task_id,title,prompt,status,pr_key,summary,wave,created_at,updated_at)
+     VALUES(?,?,?,?,?,?,?,?,?,?,?)`,
+    "o/r#2", 0, "t0", "Slice", "do it", "pending", null, null, 1, NOW, NOW,
+  );
+  exec(
+    db,
+    `INSERT INTO delivery_graph_runs(run_key,process_key,digest,status,side_effecting,node_count,human_node_count,side_effect_count,title,created_at,updated_at)
+     VALUES(?,?,?,?,?,?,?,?,?,?,?)`,
+    "dg1", null, "deadbeef", "awaiting-approval", 1, 5, 2, 3, "Graph", NOW, NOW,
+  );
+
+  const pairs: [string, string][] = [
+    ["feature_runs", "feature_runs__units"],
+    ["plans", "plans__units"],
+    ["plan_tasks", "plan_tasks__units"],
+    ["delivery_graph_runs", "delivery_graph_runs__units"],
+  ];
+  for (const [b, v] of pairs) assertViewParity(db, b, v);
+
+  // UPDATE — a status transition (and a projected column) must re-project onto the aggregate.
+  exec(db, "UPDATE feature_runs SET status=?, pr_key=?, updated_at=? WHERE feature_key=?", "merged", "o/r#5", "2026-02", "o/r#1");
+  const fu = row(db, "SELECT delivery_status, dispatch_status FROM delivery_units WHERE unit_id=?", featureUnitId("o/r#1"));
+  assertEquals(fu.delivery_status, "merged");
+  assertEquals(fu.dispatch_status, "settled");
+  for (const [b, v] of pairs) assertViewParity(db, b, v);
+
+  // DELETE — the aggregate row is dropped with the legacy row.
+  exec(db, "DELETE FROM plan_tasks WHERE plan_key=?", "o/r#2");
+  assertEquals(rows(db, "SELECT * FROM delivery_units WHERE kind='plan-task'").length, 0, "deleting a slice drops its node unit");
+  assertViewParity(db, "plan_tasks", "plan_tasks__units");
+});

package/app/deliveryUnit.ts

@@ -0,0 +1,109 @@
+// ADR 0006 slice S2 (#589) — the `delivery_units` aggregate, TS side.
+//
+// S2 collapses the four legacy delivery-unit representations (`feature_runs`, `plans`, `plan_tasks`,
+// `delivery_graph_runs`) onto ONE kind-tagged aggregate table (`db/migrations/088_delivery_units.sql`).
+// The data-level sync is done at the DB layer — triggers mirror every legacy write into the aggregate
+// (089), a backfill seeds pre-existing rows (090), and legacy-shaped compat VIEWs are served FROM the
+// aggregate (091) — so this module carries NO write path of its own; it is the canonical TS home for
+// the aggregate's VOCABULARY (the closed `kind` enum, the `dispatch_status` lifecycle), the universal
+// `unit_id` derivation, and the `dispatch_status` derivation. The last two are also lowered to SQL in
+// the trigger/backfill migrations; app/deliveryUnit.test.ts proves the two lowerings agree over the
+// full status/shape matrix (the same declare-once / parity-guard discipline S1 uses for the status
+// union — derivation over duplication).
+//
+// SCOPE (S2). This owns the aggregate's identity + dispatch vocabulary and a read gateway. The single
+// dispatch door (S3) will key on `dispatch_status`; repointing live writers onto `delivery_units` and
+// retiring the legacy write paths is the later CONTRACT phase (S3), sequenced after the
+// `instanceTracking` doors move. Nothing here changes existing behaviour.
+
+import type { DataLayer, Table } from "@nanobpm/urban";
+import { type DeliveryUnitStatus, isDeliveryUnitSettled } from "./deliveryUnitStatus.ts";
+
+/**
+ * The closed §2 `kind` enum covering every delivery unit. A run of an epic is ONE unit (`kind='epic'`,
+ * a composition over its slices); each slice is a `plan-task` node under it. `feature` is the
+ * degenerate 1-node unit; `delivery-graph` is the arbitrary-DAG unit. `bugfix`/`chore` are reserved
+ * §2 members with no legacy table yet. Kept in lockstep with the `CHECK (kind IN (…))` constraint in
+ * migration 088 — a parity test pins the two.
+ */
+export const DELIVERY_UNIT_KINDS = ["feature", "epic", "plan-task", "delivery-graph", "bugfix", "chore"] as const;
+export type DeliveryUnitKind = (typeof DELIVERY_UNIT_KINDS)[number];
+
+/**
+ * The `dispatch_status` lifecycle — the single dispatch door's status (ADR 0006 §4; the S3 door
+ * collapses onto it). Derived from the canonical {@link DeliveryUnitStatus}:
+ *  - `pending`    — created, not yet dispatched to an executor (canonical `requested`).
+ *  - `dispatched` — a live executor/instance is working the unit (a live/parked non-terminal status).
+ *  - `settled`    — terminal, or a live PR resting stage (`opened`/`converging`): re-dispatchable. This
+ *                   is exactly the {@link isDeliveryUnitSettled} predicate, so the dispatch door's
+ *                   short-circuit gate matches the redispatch-settled semantics S1 defined.
+ */
+export const DISPATCH_STATUSES = ["pending", "dispatched", "settled"] as const;
+export type DeliveryUnitDispatchStatus = (typeof DISPATCH_STATUSES)[number];
+
+/**
+ * Derive the `dispatch_status` from a canonical delivery-unit status — the TS lowering of the CASE the
+ * sync-trigger/backfill migrations (089/090) apply in SQL. `requested` ⇒ `pending`; a settled status
+ * (terminal or a PR resting stage) ⇒ `settled`; every other (live/parked) status ⇒ `dispatched`.
+ */
+export function dispatchStatusForDelivery(status: DeliveryUnitStatus): DeliveryUnitDispatchStatus {
+  if (status === "requested") return "pending";
+  if (isDeliveryUnitSettled(status)) return "settled";
+  return "dispatched";
+}
+
+// ── Universal `unit_id` — the cross-representation fact every agent can name and the dispatch door
+//    keys on (#464 "What survives" #4). Kept in lockstep with the `unit_id` expressions the
+//    trigger/backfill migrations build; app/deliveryUnit.test.ts pins the two. ─────────────────────
+
+/** The `feature:<feature_key>` unit id for a single-issue feature run. */
+export const featureUnitId = (featureKey: string): string => `feature:${featureKey}`;
+
+/** The `epic:<plan_key>` unit id for an epic (the `plans` aggregate row). */
+export const epicUnitId = (planKey: string): string => `epic:${planKey}`;
+
+/**
+ * The `plan-task:<plan_key>#<task_index>` unit id for one epic slice NODE. Its composition parent is
+ * {@link epicUnitId}(planKey) — the epic unit it hangs under.
+ */
+export const planTaskUnitId = (planKey: string, taskIndex: number): string => `plan-task:${planKey}#${taskIndex}`;
+
+/** The `delivery-graph:<run_key>` unit id for a delivery-graph run. */
+export const deliveryGraphUnitId = (runKey: string): string => `delivery-graph:${runKey}`;
+
+/**
+ * One row of the `delivery_units` aggregate. `unit_id`/`kind` are the identity pair; `delivery_status`
+ * is the canonical S1 union value; `status` is the raw legacy source status (kept verbatim so the
+ * compat VIEWs reconstruct legacy rows losslessly); `dispatch_status` is the door lifecycle. The
+ * per-shape legacy columns ride the same row (nullable off-kind). Read-only for S2 — the physical
+ * write target stays the legacy tables (the triggers mirror in).
+ */
+export interface DeliveryUnitRow {
+  unit_id: string;
+  kind: DeliveryUnitKind;
+  legacy_key: string | null;
+  legacy_id: number | null;
+  parent_unit_id: string | null;
+  node_index: number | null;
+  delivery_status: DeliveryUnitStatus | null;
+  dispatch_status: DeliveryUnitDispatchStatus | null;
+  status: string | null;
+  repo: string | null;
+  issue_number: number | null;
+  issue_url: string | null;
+  title: string | null;
+  base_branch: string | null;
+  process_key: string | null;
+  pr_key: string | null;
+  outcome: string | null;
+  created_at: string | null;
+  updated_at: string | null;
+}
+
+/**
+ * The read gateway over the `delivery_units` aggregate, keyed on the universal `unit_id`. Read-only in
+ * S2 (writes flow through the legacy tables + the sync triggers); the S3 dispatch door will own the
+ * write path once the legacy writers retire.
+ */
+export const deliveryUnits = (data: DataLayer): Table<DeliveryUnitRow> =>
+  data.table<DeliveryUnitRow>("delivery_units", "unit_id");

package/db/migrations/088_delivery_units.sql

@@ -0,0 +1,94 @@
+-- ADR 0006 slice S2 (#589) — the `delivery_units` aggregate: ONE kind-tagged table consolidating the
+-- four legacy delivery-unit representations (`feature_runs`, `plans`, `plan_tasks`,
+-- `delivery_graph_runs`) that ADR 0006 §2 declared to be one aggregate. S1 (#494) delivered the derived
+-- status union (app/deliveryUnitStatus.ts); this is its data-aggregate half.
+--
+-- EXPAND phase (ADR 0006 §S2 rollout, expand-and-contract): this migration + 089 (sync triggers) + 090
+-- (backfill) ADD the aggregate and keep it in lockstep with the legacy tables, which stay the physical
+-- WRITE target through S2 (the framework `instanceTracking` bindings + every app writer still target
+-- them; ADR 0065 makes `instanceTracking` a SOURCE that no longer writes base rows, so the legacy base
+-- `status` is only ever written through the app gateways — mirrored here at the DB level). 091 adds the
+-- legacy-shaped compat VIEWs served FROM this aggregate, parity-tested against the base tables
+-- (app/deliveryUnit.test.ts). Repointing live writers onto `delivery_units` and retiring the legacy
+-- write paths is the later CONTRACT phase (S3), which the ADR sequences after the `instanceTracking`
+-- doors move.
+--
+-- Identity (#464 "What survives"): `unit_id` is the universal, human-nameable cross-representation key
+-- the dispatch door (S3) keys on — `feature:<key>` / `epic:<plan_key>` / `plan-task:<plan_key>#<idx>` /
+-- `delivery-graph:<run_key>`. A run of an epic is ONE unit (`kind='epic'`); each of its slices is a
+-- `kind='plan-task'` node under it (`parent_unit_id = 'epic:<plan_key>'`). `kind` is the closed §2 enum.
+-- `dispatch_status` is the single dispatch door's status (S3 collapses onto it): 'pending' (created,
+-- not yet dispatched), 'dispatched' (a live executor/instance), 'settled' (terminal or a live PR
+-- resting stage — re-dispatchable), derived from the canonical `delivery_status`.
+--
+-- Every column except the identity pair (`unit_id`/`kind`) is nullable so a sync trigger over a
+-- partial legacy row can never trip a NOT NULL. `delivery_status` is the canonical S1 union value;
+-- `status` is the raw legacy source status (kept verbatim so the compat VIEWs reconstruct the legacy
+-- rows losslessly). The runner wraps each file in its own transaction — no BEGIN/COMMIT here. Numbered
+-- after the current highest prefix (087).
+
+CREATE TABLE IF NOT EXISTS delivery_units (
+  unit_id TEXT PRIMARY KEY,
+  kind TEXT NOT NULL CHECK (kind IN ('feature', 'epic', 'plan-task', 'delivery-graph', 'bugfix', 'chore')),
+  legacy_key TEXT,
+  legacy_id INTEGER,
+  parent_unit_id TEXT,
+  node_index INTEGER,
+  delivery_status TEXT,
+  dispatch_status TEXT,
+  repo TEXT,
+  issue_number INTEGER,
+  issue_url TEXT,
+  title TEXT,
+  base_branch TEXT,
+  status TEXT,
+  process_key TEXT,
+  pr_key TEXT,
+  outcome TEXT,
+  acknowledged_at TEXT,
+  list_bucket TEXT,
+  created_at TEXT,
+  updated_at TEXT,
+  converge INTEGER,
+  auto_merge INTEGER,
+  delivery_label TEXT,
+  stage TEXT,
+  stage_state TEXT,
+  stage_skipped TEXT,
+  attention TEXT,
+  task_count INTEGER,
+  gate_wave INTEGER,
+  blackboard_token TEXT,
+  retro_started_at TEXT,
+  epic_phase TEXT,
+  promotion_pr TEXT,
+  promotion_state TEXT,
+  ack_open INTEGER,
+  wait_gate TEXT,
+  wait_gate_label TEXT,
+  bound_artifacts TEXT,
+  task_id TEXT,
+  prompt TEXT,
+  summary TEXT,
+  wave INTEGER,
+  open_question TEXT,
+  answer TEXT,
+  draft_pr_key TEXT,
+  corr_key TEXT,
+  process_definition_id TEXT,
+  digest TEXT,
+  side_effecting INTEGER,
+  node_count INTEGER,
+  human_node_count INTEGER,
+  side_effect_count INTEGER,
+  phase TEXT,
+  phase_node_id TEXT,
+  human_labels TEXT
+);
+
+CREATE INDEX IF NOT EXISTS ix_delivery_units_kind ON delivery_units (kind);
+CREATE INDEX IF NOT EXISTS ix_delivery_units_dispatch_status ON delivery_units (dispatch_status);
+CREATE INDEX IF NOT EXISTS ix_delivery_units_parent ON delivery_units (parent_unit_id);
+CREATE INDEX IF NOT EXISTS ix_delivery_units_process_key ON delivery_units (process_key);
+CREATE INDEX IF NOT EXISTS ix_delivery_units_pr_key ON delivery_units (pr_key);
+CREATE INDEX IF NOT EXISTS ix_delivery_units_legacy_key ON delivery_units (legacy_key);

package/db/migrations/089_delivery_units_sync_triggers.sql

@@ -0,0 +1,94 @@
+-- ADR 0006 slice S2 (#589) — DB-level sync triggers mirroring every legacy delivery-unit write into
+-- the `delivery_units` aggregate (088). AFTER INSERT/UPDATE/DELETE on each of the four legacy tables
+-- keeps the aggregate in perfect lockstep regardless of WHICH writer touched the base row — the app
+-- gateways (app/feature.ts, app/plan.ts, app/deliveryGraphRun.ts), the plan/wave/results workers, the
+-- service pollers, AND the raw-SQL compare-and-swap in `claimRunForLaunch` (app/deliveryGraphRun.ts)
+-- that bypasses the gateway. A trigger fires at the DB level, so there is no drift surface and no
+-- write-path code to keep in sync (derivation over duplication). ADR 0065 makes `instanceTracking` a
+-- SOURCE that no longer writes base rows, so the base `status` these triggers read is always the
+-- worker-owned transient — the terminal fold stays derived on the legacy `__tracking` VIEWs.
+--
+-- `INSERT OR REPLACE` on the derived `unit_id` makes each trigger idempotent (an update re-projects
+-- the whole row). `delivery_status` (canonical S1 union) and `dispatch_status` are computed by the
+-- same CASE lowerings app/deliveryUnit.ts mirrors in TS, guarded at parity by app/deliveryUnit.test.ts.
+-- The runner wraps each file in its own transaction — no BEGIN/COMMIT here.
+
+DROP TRIGGER IF EXISTS feature_runs__du_ai;
+CREATE TRIGGER feature_runs__du_ai AFTER INSERT ON feature_runs
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, repo, issue_number, issue_url, title, base_branch, status, process_key, pr_key, converge, auto_merge, outcome, delivery_label, acknowledged_at, stage, stage_state, stage_skipped, attention, list_bucket, created_at, updated_at)
+  VALUES ('feature:' || NEW.feature_key, 'feature', NEW.feature_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'running' THEN 'running' WHEN NEW.status = 'escalated' THEN 'escalated' WHEN NEW.status = 'opened' THEN 'opened' WHEN NEW.status = 'converging' THEN 'converging' WHEN NEW.status = 'awaiting_operator' THEN 'awaiting_operator' WHEN NEW.status = 'merged' THEN 'merged' WHEN NEW.status = 'converged' THEN 'converged' WHEN NEW.status = 'blocked' THEN 'blocked' WHEN NEW.status = 'skipped' THEN 'skipped' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('opened', 'converging', 'merged', 'converged', 'blocked', 'skipped', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('running', 'escalated', 'awaiting_operator') THEN 'dispatched' ELSE NULL END, NEW.repo, NEW.issue_number, NEW.issue_url, NEW.title, NEW.base_branch, NEW.status, NEW.process_key, NEW.pr_key, NEW.converge, NEW.auto_merge, NEW.outcome, NEW.delivery_label, NEW.acknowledged_at, NEW.stage, NEW.stage_state, NEW.stage_skipped, NEW.attention, NEW.list_bucket, NEW.created_at, NEW.updated_at);
+END;
+
+DROP TRIGGER IF EXISTS feature_runs__du_au;
+CREATE TRIGGER feature_runs__du_au AFTER UPDATE ON feature_runs
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, repo, issue_number, issue_url, title, base_branch, status, process_key, pr_key, converge, auto_merge, outcome, delivery_label, acknowledged_at, stage, stage_state, stage_skipped, attention, list_bucket, created_at, updated_at)
+  VALUES ('feature:' || NEW.feature_key, 'feature', NEW.feature_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'running' THEN 'running' WHEN NEW.status = 'escalated' THEN 'escalated' WHEN NEW.status = 'opened' THEN 'opened' WHEN NEW.status = 'converging' THEN 'converging' WHEN NEW.status = 'awaiting_operator' THEN 'awaiting_operator' WHEN NEW.status = 'merged' THEN 'merged' WHEN NEW.status = 'converged' THEN 'converged' WHEN NEW.status = 'blocked' THEN 'blocked' WHEN NEW.status = 'skipped' THEN 'skipped' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('opened', 'converging', 'merged', 'converged', 'blocked', 'skipped', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('running', 'escalated', 'awaiting_operator') THEN 'dispatched' ELSE NULL END, NEW.repo, NEW.issue_number, NEW.issue_url, NEW.title, NEW.base_branch, NEW.status, NEW.process_key, NEW.pr_key, NEW.converge, NEW.auto_merge, NEW.outcome, NEW.delivery_label, NEW.acknowledged_at, NEW.stage, NEW.stage_state, NEW.stage_skipped, NEW.attention, NEW.list_bucket, NEW.created_at, NEW.updated_at);
+END;
+
+DROP TRIGGER IF EXISTS feature_runs__du_ad;
+CREATE TRIGGER feature_runs__du_ad AFTER DELETE ON feature_runs
+BEGIN
+  DELETE FROM delivery_units WHERE unit_id = 'feature:' || OLD.feature_key;
+END;
+
+DROP TRIGGER IF EXISTS plans__du_ai;
+CREATE TRIGGER plans__du_ai AFTER INSERT ON plans
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, repo, issue_number, issue_url, title, status, task_count, process_key, outcome, gate_wave, blackboard_token, retro_started_at, base_branch, epic_phase, promotion_pr, promotion_state, acknowledged_at, list_bucket, ack_open, wait_gate, wait_gate_label, bound_artifacts, created_at, updated_at)
+  VALUES ('epic:' || NEW.plan_key, 'epic', NEW.plan_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'planning' THEN 'requested' WHEN NEW.status = 'dispatched' THEN 'running' WHEN NEW.status = 'done' THEN 'done' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('planning') THEN 'pending' WHEN NEW.status IN ('done', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('dispatched') THEN 'dispatched' ELSE NULL END, NEW.repo, NEW.issue_number, NEW.issue_url, NEW.title, NEW.status, NEW.task_count, NEW.process_key, NEW.outcome, NEW.gate_wave, NEW.blackboard_token, NEW.retro_started_at, NEW.base_branch, NEW.epic_phase, NEW.promotion_pr, NEW.promotion_state, NEW.acknowledged_at, NEW.list_bucket, NEW.ack_open, NEW.wait_gate, NEW.wait_gate_label, NEW.bound_artifacts, NEW.created_at, NEW.updated_at);
+END;
+
+DROP TRIGGER IF EXISTS plans__du_au;
+CREATE TRIGGER plans__du_au AFTER UPDATE ON plans
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, repo, issue_number, issue_url, title, status, task_count, process_key, outcome, gate_wave, blackboard_token, retro_started_at, base_branch, epic_phase, promotion_pr, promotion_state, acknowledged_at, list_bucket, ack_open, wait_gate, wait_gate_label, bound_artifacts, created_at, updated_at)
+  VALUES ('epic:' || NEW.plan_key, 'epic', NEW.plan_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'planning' THEN 'requested' WHEN NEW.status = 'dispatched' THEN 'running' WHEN NEW.status = 'done' THEN 'done' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('planning') THEN 'pending' WHEN NEW.status IN ('done', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('dispatched') THEN 'dispatched' ELSE NULL END, NEW.repo, NEW.issue_number, NEW.issue_url, NEW.title, NEW.status, NEW.task_count, NEW.process_key, NEW.outcome, NEW.gate_wave, NEW.blackboard_token, NEW.retro_started_at, NEW.base_branch, NEW.epic_phase, NEW.promotion_pr, NEW.promotion_state, NEW.acknowledged_at, NEW.list_bucket, NEW.ack_open, NEW.wait_gate, NEW.wait_gate_label, NEW.bound_artifacts, NEW.created_at, NEW.updated_at);
+END;
+
+DROP TRIGGER IF EXISTS plans__du_ad;
+CREATE TRIGGER plans__du_ad AFTER DELETE ON plans
+BEGIN
+  DELETE FROM delivery_units WHERE unit_id = 'epic:' || OLD.plan_key;
+END;
+
+DROP TRIGGER IF EXISTS plan_tasks__du_ai;
+CREATE TRIGGER plan_tasks__du_ai AFTER INSERT ON plan_tasks
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, title, prompt, status, pr_key, summary, wave, open_question, answer, draft_pr_key, corr_key, created_at, updated_at, task_id)
+  VALUES ('plan-task:' || NEW.plan_key || '#' || NEW.task_index, 'plan-task', NEW.plan_key, NEW.id, 'epic:' || NEW.plan_key, NEW.task_index, CASE WHEN NEW.status = 'pending' THEN 'requested' WHEN NEW.status = 'opened' THEN 'opened' WHEN NEW.status = 'blocked' THEN 'blocked' WHEN NEW.status = 'skipped' THEN 'skipped' WHEN NEW.status = 'escalated' THEN 'escalated' WHEN NEW.status = 'waiting-for-lane' THEN 'waiting' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('pending') THEN 'pending' WHEN NEW.status IN ('opened', 'blocked', 'skipped', 'abandoned') THEN 'settled' WHEN NEW.status IN ('escalated', 'waiting-for-lane') THEN 'dispatched' ELSE NULL END, NEW.title, NEW.prompt, NEW.status, NEW.pr_key, NEW.summary, NEW.wave, NEW.open_question, NEW.answer, NEW.draft_pr_key, NEW.corr_key, NEW.created_at, NEW.updated_at, NEW.task_id);
+END;
+
+DROP TRIGGER IF EXISTS plan_tasks__du_au;
+CREATE TRIGGER plan_tasks__du_au AFTER UPDATE ON plan_tasks
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, title, prompt, status, pr_key, summary, wave, open_question, answer, draft_pr_key, corr_key, created_at, updated_at, task_id)
+  VALUES ('plan-task:' || NEW.plan_key || '#' || NEW.task_index, 'plan-task', NEW.plan_key, NEW.id, 'epic:' || NEW.plan_key, NEW.task_index, CASE WHEN NEW.status = 'pending' THEN 'requested' WHEN NEW.status = 'opened' THEN 'opened' WHEN NEW.status = 'blocked' THEN 'blocked' WHEN NEW.status = 'skipped' THEN 'skipped' WHEN NEW.status = 'escalated' THEN 'escalated' WHEN NEW.status = 'waiting-for-lane' THEN 'waiting' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('pending') THEN 'pending' WHEN NEW.status IN ('opened', 'blocked', 'skipped', 'abandoned') THEN 'settled' WHEN NEW.status IN ('escalated', 'waiting-for-lane') THEN 'dispatched' ELSE NULL END, NEW.title, NEW.prompt, NEW.status, NEW.pr_key, NEW.summary, NEW.wave, NEW.open_question, NEW.answer, NEW.draft_pr_key, NEW.corr_key, NEW.created_at, NEW.updated_at, NEW.task_id);
+END;
+
+DROP TRIGGER IF EXISTS plan_tasks__du_ad;
+CREATE TRIGGER plan_tasks__du_ad AFTER DELETE ON plan_tasks
+BEGIN
+  DELETE FROM delivery_units WHERE unit_id = 'plan-task:' || OLD.plan_key || '#' || OLD.task_index;
+END;
+
+DROP TRIGGER IF EXISTS delivery_graph_runs__du_ai;
+CREATE TRIGGER delivery_graph_runs__du_ai AFTER INSERT ON delivery_graph_runs
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, process_key, process_definition_id, digest, status, side_effecting, node_count, human_node_count, side_effect_count, title, phase, phase_node_id, human_labels, created_at, updated_at)
+  VALUES ('delivery-graph:' || NEW.run_key, 'delivery-graph', NEW.run_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'awaiting-approval' THEN 'requested' WHEN NEW.status = 'running' THEN 'running' WHEN NEW.status = 'done' THEN 'done' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('awaiting-approval') THEN 'pending' WHEN NEW.status IN ('done', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('running') THEN 'dispatched' ELSE NULL END, NEW.process_key, NEW.process_definition_id, NEW.digest, NEW.status, NEW.side_effecting, NEW.node_count, NEW.human_node_count, NEW.side_effect_count, NEW.title, NEW.phase, NEW.phase_node_id, NEW.human_labels, NEW.created_at, NEW.updated_at);
+END;
+
+DROP TRIGGER IF EXISTS delivery_graph_runs__du_au;
+CREATE TRIGGER delivery_graph_runs__du_au AFTER UPDATE ON delivery_graph_runs
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, process_key, process_definition_id, digest, status, side_effecting, node_count, human_node_count, side_effect_count, title, phase, phase_node_id, human_labels, created_at, updated_at)
+  VALUES ('delivery-graph:' || NEW.run_key, 'delivery-graph', NEW.run_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'awaiting-approval' THEN 'requested' WHEN NEW.status = 'running' THEN 'running' WHEN NEW.status = 'done' THEN 'done' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('awaiting-approval') THEN 'pending' WHEN NEW.status IN ('done', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('running') THEN 'dispatched' ELSE NULL END, NEW.process_key, NEW.process_definition_id, NEW.digest, NEW.status, NEW.side_effecting, NEW.node_count, NEW.human_node_count, NEW.side_effect_count, NEW.title, NEW.phase, NEW.phase_node_id, NEW.human_labels, NEW.created_at, NEW.updated_at);
+END;
+
+DROP TRIGGER IF EXISTS delivery_graph_runs__du_ad;
+CREATE TRIGGER delivery_graph_runs__du_ad AFTER DELETE ON delivery_graph_runs
+BEGIN
+  DELETE FROM delivery_units WHERE unit_id = 'delivery-graph:' || OLD.run_key;
+END;

package/db/migrations/090_delivery_units_backfill.sql

@@ -0,0 +1,120 @@
+-- ADR 0006 slice S2 (#589) — backfill the `delivery_units` aggregate (088) from the existing rows of
+-- the four legacy tables, using the SAME projection the sync triggers (089) apply going forward. Idempotent
+-- (`INSERT OR IGNORE` on the `unit_id` PK) so re-running the migration set — or upgrading an install
+-- whose triggers already mirrored some rows — never double-inserts. Runs AFTER the triggers so a fresh
+-- install with seeded legacy rows is fully covered either way (triggers fire on live writes; this seeds
+-- pre-existing rows). The runner wraps each file in its own transaction — no BEGIN/COMMIT here.
+
+INSERT OR IGNORE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, repo, issue_number, issue_url, title, base_branch, status, process_key, pr_key, converge, auto_merge, outcome, delivery_label, acknowledged_at, stage, stage_state, stage_skipped, attention, list_bucket, created_at, updated_at)
+  SELECT 'feature:' || feature_runs.feature_key AS unit_id,
+         'feature' AS kind,
+         feature_runs.feature_key AS legacy_key,
+         NULL AS legacy_id,
+         NULL AS parent_unit_id,
+         NULL AS node_index,
+         CASE WHEN feature_runs.status = 'running' THEN 'running' WHEN feature_runs.status = 'escalated' THEN 'escalated' WHEN feature_runs.status = 'opened' THEN 'opened' WHEN feature_runs.status = 'converging' THEN 'converging' WHEN feature_runs.status = 'awaiting_operator' THEN 'awaiting_operator' WHEN feature_runs.status = 'merged' THEN 'merged' WHEN feature_runs.status = 'converged' THEN 'converged' WHEN feature_runs.status = 'blocked' THEN 'blocked' WHEN feature_runs.status = 'skipped' THEN 'skipped' WHEN feature_runs.status = 'failed' THEN 'failed' WHEN feature_runs.status = 'abandoned' THEN 'abandoned' ELSE NULL END AS delivery_status,
+         CASE WHEN feature_runs.status IN ('opened', 'converging', 'merged', 'converged', 'blocked', 'skipped', 'failed', 'abandoned') THEN 'settled' WHEN feature_runs.status IN ('running', 'escalated', 'awaiting_operator') THEN 'dispatched' ELSE NULL END AS dispatch_status,
+         feature_runs.repo AS repo,
+         feature_runs.issue_number AS issue_number,
+         feature_runs.issue_url AS issue_url,
+         feature_runs.title AS title,
+         feature_runs.base_branch AS base_branch,
+         feature_runs.status AS status,
+         feature_runs.process_key AS process_key,
+         feature_runs.pr_key AS pr_key,
+         feature_runs.converge AS converge,
+         feature_runs.auto_merge AS auto_merge,
+         feature_runs.outcome AS outcome,
+         feature_runs.delivery_label AS delivery_label,
+         feature_runs.acknowledged_at AS acknowledged_at,
+         feature_runs.stage AS stage,
+         feature_runs.stage_state AS stage_state,
+         feature_runs.stage_skipped AS stage_skipped,
+         feature_runs.attention AS attention,
+         feature_runs.list_bucket AS list_bucket,
+         feature_runs.created_at AS created_at,
+         feature_runs.updated_at AS updated_at
+  FROM feature_runs;
+
+INSERT OR IGNORE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, repo, issue_number, issue_url, title, status, task_count, process_key, outcome, gate_wave, blackboard_token, retro_started_at, base_branch, epic_phase, promotion_pr, promotion_state, acknowledged_at, list_bucket, ack_open, wait_gate, wait_gate_label, bound_artifacts, created_at, updated_at)
+  SELECT 'epic:' || plans.plan_key AS unit_id,
+         'epic' AS kind,
+         plans.plan_key AS legacy_key,
+         NULL AS legacy_id,
+         NULL AS parent_unit_id,
+         NULL AS node_index,
+         CASE WHEN plans.status = 'planning' THEN 'requested' WHEN plans.status = 'dispatched' THEN 'running' WHEN plans.status = 'done' THEN 'done' WHEN plans.status = 'failed' THEN 'failed' WHEN plans.status = 'abandoned' THEN 'abandoned' ELSE NULL END AS delivery_status,
+         CASE WHEN plans.status IN ('planning') THEN 'pending' WHEN plans.status IN ('done', 'failed', 'abandoned') THEN 'settled' WHEN plans.status IN ('dispatched') THEN 'dispatched' ELSE NULL END AS dispatch_status,
+         plans.repo AS repo,
+         plans.issue_number AS issue_number,
+         plans.issue_url AS issue_url,
+         plans.title AS title,
+         plans.status AS status,
+         plans.task_count AS task_count,
+         plans.process_key AS process_key,
+         plans.outcome AS outcome,
+         plans.gate_wave AS gate_wave,
+         plans.blackboard_token AS blackboard_token,
+         plans.retro_started_at AS retro_started_at,
+         plans.base_branch AS base_branch,
+         plans.epic_phase AS epic_phase,
+         plans.promotion_pr AS promotion_pr,
+         plans.promotion_state AS promotion_state,
+         plans.acknowledged_at AS acknowledged_at,
+         plans.list_bucket AS list_bucket,
+         plans.ack_open AS ack_open,
+         plans.wait_gate AS wait_gate,
+         plans.wait_gate_label AS wait_gate_label,
+         plans.bound_artifacts AS bound_artifacts,
+         plans.created_at AS created_at,
+         plans.updated_at AS updated_at
+  FROM plans;
+
+INSERT OR IGNORE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, title, prompt, status, pr_key, summary, wave, open_question, answer, draft_pr_key, corr_key, created_at, updated_at, task_id)
+  SELECT 'plan-task:' || plan_tasks.plan_key || '#' || plan_tasks.task_index AS unit_id,
+         'plan-task' AS kind,
+         plan_tasks.plan_key AS legacy_key,
+         plan_tasks.id AS legacy_id,
+         'epic:' || plan_tasks.plan_key AS parent_unit_id,
+         plan_tasks.task_index AS node_index,
+         CASE WHEN plan_tasks.status = 'pending' THEN 'requested' WHEN plan_tasks.status = 'opened' THEN 'opened' WHEN plan_tasks.status = 'blocked' THEN 'blocked' WHEN plan_tasks.status = 'skipped' THEN 'skipped' WHEN plan_tasks.status = 'escalated' THEN 'escalated' WHEN plan_tasks.status = 'waiting-for-lane' THEN 'waiting' WHEN plan_tasks.status = 'abandoned' THEN 'abandoned' ELSE NULL END AS delivery_status,
+         CASE WHEN plan_tasks.status IN ('pending') THEN 'pending' WHEN plan_tasks.status IN ('opened', 'blocked', 'skipped', 'abandoned') THEN 'settled' WHEN plan_tasks.status IN ('escalated', 'waiting-for-lane') THEN 'dispatched' ELSE NULL END AS dispatch_status,
+         plan_tasks.title AS title,
+         plan_tasks.prompt AS prompt,
+         plan_tasks.status AS status,
+         plan_tasks.pr_key AS pr_key,
+         plan_tasks.summary AS summary,
+         plan_tasks.wave AS wave,
+         plan_tasks.open_question AS open_question,
+         plan_tasks.answer AS answer,
+         plan_tasks.draft_pr_key AS draft_pr_key,
+         plan_tasks.corr_key AS corr_key,
+         plan_tasks.created_at AS created_at,
+         plan_tasks.updated_at AS updated_at,
+         plan_tasks.task_id AS task_id
+  FROM plan_tasks;
+
+INSERT OR IGNORE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, process_key, process_definition_id, digest, status, side_effecting, node_count, human_node_count, side_effect_count, title, phase, phase_node_id, human_labels, created_at, updated_at)
+  SELECT 'delivery-graph:' || delivery_graph_runs.run_key AS unit_id,
+         'delivery-graph' AS kind,
+         delivery_graph_runs.run_key AS legacy_key,
+         NULL AS legacy_id,
+         NULL AS parent_unit_id,
+         NULL AS node_index,
+         CASE WHEN delivery_graph_runs.status = 'awaiting-approval' THEN 'requested' WHEN delivery_graph_runs.status = 'running' THEN 'running' WHEN delivery_graph_runs.status = 'done' THEN 'done' WHEN delivery_graph_runs.status = 'failed' THEN 'failed' WHEN delivery_graph_runs.status = 'abandoned' THEN 'abandoned' ELSE NULL END AS delivery_status,
+         CASE WHEN delivery_graph_runs.status IN ('awaiting-approval') THEN 'pending' WHEN delivery_graph_runs.status IN ('done', 'failed', 'abandoned') THEN 'settled' WHEN delivery_graph_runs.status IN ('running') THEN 'dispatched' ELSE NULL END AS dispatch_status,
+         delivery_graph_runs.process_key AS process_key,
+         delivery_graph_runs.process_definition_id AS process_definition_id,
+         delivery_graph_runs.digest AS digest,
+         delivery_graph_runs.status AS status,
+         delivery_graph_runs.side_effecting AS side_effecting,
+         delivery_graph_runs.node_count AS node_count,
+         delivery_graph_runs.human_node_count AS human_node_count,
+         delivery_graph_runs.side_effect_count AS side_effect_count,
+         delivery_graph_runs.title AS title,
+         delivery_graph_runs.phase AS phase,
+         delivery_graph_runs.phase_node_id AS phase_node_id,
+         delivery_graph_runs.human_labels AS human_labels,
+         delivery_graph_runs.created_at AS created_at,
+         delivery_graph_runs.updated_at AS updated_at
+  FROM delivery_graph_runs;

package/db/migrations/091_delivery_units_read_models.sql

@@ -0,0 +1,111 @@
+-- ADR 0006 slice S2 (#589) — legacy-shaped compatibility VIEWs served FROM the `delivery_units`
+-- aggregate (088). Each VIEW reconstructs one legacy table's exact column set from the kind-tagged
+-- aggregate row, so a read path can swap onto the aggregate with byte-identical results — the
+-- "legacy tables become VIEWs/rows over the aggregate" surface of ADR 0006 §2, guarded by the parity
+-- tests in app/deliveryUnit.test.ts (each VIEW is proven row-for-row equal to its base table over the
+-- full status/shape matrix). These are ADDITIVE read surfaces; the live pages/read-models keep binding
+-- the physical base tables until S3 moves the writers, so no behaviour changes here.
+--
+-- A single plain `CREATE VIEW … SELECT … FROM delivery_units` per shape (one top-level FROM, every
+-- column aliased) so the static pages<->schema contract guard can parse the column list. The runner
+-- wraps each file in its own transaction — no BEGIN/COMMIT here.
+
+DROP VIEW IF EXISTS feature_runs__units;
+CREATE VIEW feature_runs__units AS
+SELECT
+  du.legacy_key AS feature_key,
+  du.repo AS repo,
+  du.issue_number AS issue_number,
+  du.issue_url AS issue_url,
+  du.base_branch AS base_branch,
+  du.status AS status,
+  du.process_key AS process_key,
+  du.pr_key AS pr_key,
+  du.converge AS converge,
+  du.auto_merge AS auto_merge,
+  du.outcome AS outcome,
+  du.created_at AS created_at,
+  du.updated_at AS updated_at,
+  du.delivery_label AS delivery_label,
+  du.title AS title,
+  du.acknowledged_at AS acknowledged_at,
+  du.stage AS stage,
+  du.stage_state AS stage_state,
+  du.stage_skipped AS stage_skipped,
+  du.attention AS attention,
+  du.list_bucket AS list_bucket
+FROM delivery_units du
+WHERE du.kind = 'feature';
+
+DROP VIEW IF EXISTS plans__units;
+CREATE VIEW plans__units AS
+SELECT
+  du.legacy_key AS plan_key,
+  du.repo AS repo,
+  du.issue_number AS issue_number,
+  du.issue_url AS issue_url,
+  du.title AS title,
+  du.status AS status,
+  du.task_count AS task_count,
+  du.process_key AS process_key,
+  du.outcome AS outcome,
+  du.created_at AS created_at,
+  du.updated_at AS updated_at,
+  du.gate_wave AS gate_wave,
+  du.blackboard_token AS blackboard_token,
+  du.retro_started_at AS retro_started_at,
+  du.base_branch AS base_branch,
+  du.epic_phase AS epic_phase,
+  du.promotion_pr AS promotion_pr,
+  du.promotion_state AS promotion_state,
+  du.acknowledged_at AS acknowledged_at,
+  du.list_bucket AS list_bucket,
+  du.ack_open AS ack_open,
+  du.wait_gate AS wait_gate,
+  du.wait_gate_label AS wait_gate_label,
+  du.bound_artifacts AS bound_artifacts
+FROM delivery_units du
+WHERE du.kind = 'epic';
+
+DROP VIEW IF EXISTS plan_tasks__units;
+CREATE VIEW plan_tasks__units AS
+SELECT
+  du.legacy_id AS id,
+  du.legacy_key AS plan_key,
+  du.node_index AS task_index,
+  du.task_id AS task_id,
+  du.title AS title,
+  du.prompt AS prompt,
+  du.status AS status,
+  du.pr_key AS pr_key,
+  du.summary AS summary,
+  du.created_at AS created_at,
+  du.updated_at AS updated_at,
+  du.wave AS wave,
+  du.open_question AS open_question,
+  du.answer AS answer,
+  du.draft_pr_key AS draft_pr_key,
+  du.corr_key AS corr_key
+FROM delivery_units du
+WHERE du.kind = 'plan-task';
+
+DROP VIEW IF EXISTS delivery_graph_runs__units;
+CREATE VIEW delivery_graph_runs__units AS
+SELECT
+  du.legacy_key AS run_key,
+  du.process_key AS process_key,
+  du.process_definition_id AS process_definition_id,
+  du.digest AS digest,
+  du.status AS status,
+  du.side_effecting AS side_effecting,
+  du.node_count AS node_count,
+  du.human_node_count AS human_node_count,
+  du.side_effect_count AS side_effect_count,
+  du.title AS title,
+  du.phase AS phase,
+  du.phase_node_id AS phase_node_id,
+  du.human_labels AS human_labels,
+  du.created_at AS created_at,
+  du.updated_at AS updated_at
+FROM delivery_units du
+WHERE du.kind = 'delivery-graph';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.154.0",
+  "version": "0.155.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",