@nanobpm/nano-workforce 0.118.2 → 0.120.0

package/app/plansReadModel.test.ts

@@ -0,0 +1,262 @@
+// Read-model VIEW coverage for the plans-table wave (022) and delivery (029) projections (epic #412
+// — "Retire worker-maintained denormalized projections in favour of SQL VIEWs").
+//
+// Historically `plans.wave_count`/`current_wave`/`wave_label` (022_plan_wave_progress.sql) were
+// written by the wave workers, and `plans.delivery`/`delivery_label` (029_plan_delivery.sql) by
+// `pollDelivery` (app/service.ts) via the pure `deriveDelivery` (app/delivery.ts) — both denormalised
+// onto `plans` only because "Urban's datasource cannot read a SQL VIEW". That constraint is gone
+// (nano-ide#424), so 060/061 express the SAME projections as DERIVED views. This asserts the views
+// reproduce the previous projections' EXACT values — including the pre-formatted `wave_label` /
+// `delivery_label` display strings — over sample `plans` × `plan_tasks` × `pull_requests` rows, so
+// the wave-1 cleanup can drop the worker write-paths + columns with no behavioural change.
+//
+// The delivery assertions cross-check against the real `deriveDelivery` (the single source of truth
+// the poller used), not a re-implementation; the wave assertions pin the frontier derivation that
+// reproduces the workers' `current_wave` (record-plan starts at 0, advances per landed wave, pins to
+// wave_count-1 on completion).
+import { readFileSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+import { assert, assertEquals } from "#test-assert";
+import { deriveDelivery } from "./delivery.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"));
+
+// A DB with the base `plans` / `plan_tasks` / `pull_requests` shapes the views read (the `plans`
+// columns `plan_read_model` projects, and the full `plan_tasks` shape 059's `plan_wave_tasks`
+// reads), plus 059→061 applied in order.
+function viewDb(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  db.exec(
+    `CREATE TABLE plans (
+       plan_key TEXT PRIMARY KEY, repo TEXT, issue_number INTEGER, issue_url TEXT, title TEXT,
+       status TEXT, task_count INTEGER, process_key TEXT, outcome TEXT, created_at TEXT,
+       updated_at TEXT, epic_phase TEXT, base_branch TEXT, wait_gate_label TEXT, bound_artifacts TEXT,
+       promotion_pr TEXT, promotion_state TEXT, list_bucket TEXT, ack_open INTEGER);
+     CREATE TABLE plan_tasks (
+       id INTEGER PRIMARY KEY, plan_key TEXT, task_index INTEGER, task_id TEXT, title TEXT,
+       prompt TEXT, status TEXT, pr_key TEXT, summary TEXT, created_at TEXT, updated_at TEXT,
+       wave INTEGER, open_question TEXT, answer TEXT, draft_pr_key TEXT, corr_key TEXT);
+     CREATE TABLE pull_requests (pr_key TEXT PRIMARY KEY, url TEXT, status TEXT, process_key TEXT);`,
+  );
+  db.exec(MIG("059_plan_wave_summary.sql"));
+  db.exec(MIG("060_plan_wave_rollup.sql"));
+  db.exec(MIG("061_plan_delivery_rollup.sql"));
+  return db;
+}
+
+interface SampleTask {
+  status: string;
+  wave: number | null;
+  pr?: { status: string };
+  // A slice that OPENED a PR (so `pr_key` is set and it counts toward `prs_opened`) but whose
+  // `pull_requests` row is ABSENT — a DB desync. Mirrors `pollDelivery`'s `MISSING_PR_STATUS`
+  // sentinel: the LEFT JOIN yields `status IS NULL`, which `plan_delivery_counts` treats as
+  // in-flight (non-terminal), so it can never wrongly promote an epic to `landed`.
+  danglingPr?: boolean;
+}
+
+// Sentinel mirroring `pollDelivery`'s `MISSING_PR_STATUS` — the status fed to `deriveDelivery` for a
+// `pr_key` with no `pull_requests` row. Any non-terminal string works (it's counted as in-flight); it
+// exists only to keep the `deriveDelivery` cross-check aligned with the view's `status IS NULL` branch.
+const MISSING_PR_STATUS = "missing";
+
+// Insert a plan plus its tasks (and each task's PR, if any). PR keys are derived so the test rows
+// stay terse. Returns the flat `pull_requests.status` list `deriveDelivery` consumes (only tasks
+// that opened a PR), so the delivery assertions can cross-check the view against it.
+function addPlan(db: DatabaseSync, plan_key: string, status: string, tasks: SampleTask[]): string[] {
+  db.prepare(
+    "INSERT INTO plans (plan_key, repo, issue_number, issue_url, status, task_count, updated_at, list_bucket) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+  ).run(plan_key, "o/r", 1, `https://gh/${plan_key}`, status, tasks.length, "2026-01-01T00:00:00Z", "active");
+  const prStatuses: string[] = [];
+  tasks.forEach((t, i) => {
+    const prKey = t.pr || t.danglingPr ? `${plan_key}::pr${i}` : null;
+    db.prepare(
+      "INSERT INTO plan_tasks (plan_key, task_index, task_id, status, pr_key, wave) VALUES (?, ?, ?, ?, ?, ?)",
+    ).run(plan_key, i, `t${i}`, t.status, prKey, t.wave);
+    if (t.danglingPr) {
+      // Opened a PR (pr_key set → counts toward prs_opened) but NO `pull_requests` row: the DB desync
+      // `pollDelivery` feeds to `deriveDelivery` as MISSING_PR_STATUS (in-flight).
+      prStatuses.push(MISSING_PR_STATUS);
+    } else if (t.pr && prKey) {
+      db.prepare("INSERT INTO pull_requests (pr_key, url, status, process_key) VALUES (?, ?, ?, ?)").run(
+        prKey,
+        `https://gh/${prKey}`,
+        t.pr.status,
+        `P${i}`,
+      );
+      prStatuses.push(t.pr.status);
+    }
+  });
+  return prStatuses;
+}
+
+function delivery(db: DatabaseSync, plan_key: string): { delivery: unknown; delivery_label: unknown } {
+  return db.prepare("SELECT delivery, delivery_label FROM plan_delivery WHERE plan_key = ?").get(plan_key) as {
+    delivery: unknown;
+    delivery_label: unknown;
+  };
+}
+
+function counts(db: DatabaseSync, plan_key: string): { prs_opened: number; prs_merged: number; prs_in_flight: number } {
+  const r = db
+    .prepare("SELECT prs_opened, prs_merged, prs_in_flight FROM plan_delivery_counts WHERE plan_key = ?")
+    .get(plan_key) as { prs_opened: number; prs_merged: number; prs_in_flight: number };
+  return { ...r };
+}
+
+function waveLabel(db: DatabaseSync, plan_key: string): Record<string, unknown> | undefined {
+  const r = db.prepare("SELECT wave_count, current_wave, wave_label FROM plan_wave_label WHERE plan_key = ?").get(plan_key) as
+    | Record<string, unknown>
+    | undefined;
+  return r === undefined ? undefined : { ...r };
+}
+
+test("plan_delivery reproduces deriveDelivery exactly (converging / landed / not-done / resolved-not-landed / taskless)", () => {
+  const db = viewDb();
+  // A `done` epic with slices still in flight → converging.
+  const a = addPlan(db, "o/r#1", "done", [
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 1, pr: { status: "converging" } },
+    { status: "blocked", wave: 1 },
+  ]);
+  // A `done` epic with every slice PR merged → landed.
+  const b = addPlan(db, "o/r#2", "done", [
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+  ]);
+  // A `dispatched` (not-done) epic → no positive delivery signal yet, even with an open PR.
+  const c = addPlan(db, "o/r#3", "dispatched", [
+    { status: "opened", wave: 0, pr: { status: "converging" } },
+    { status: "pending", wave: 1 },
+    { status: "pending", wave: 2 },
+  ]);
+  // A `done` epic where every PR is terminal but not all merged (one abandoned) → resolved, NOT landed.
+  const d = addPlan(db, "o/r#4", "done", [
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 0, pr: { status: "abandoned" } },
+  ]);
+  // A `planning` epic with no tasks → no PRs → null.
+  const e = addPlan(db, "o/r#5", "planning", []);
+
+  for (const [plan_key, status, prStatuses] of [
+    ["o/r#1", "done", a],
+    ["o/r#2", "done", b],
+    ["o/r#3", "dispatched", c],
+    ["o/r#4", "done", d],
+    ["o/r#5", "planning", e],
+  ] as const) {
+    const expected = deriveDelivery(status, prStatuses);
+    const row = delivery(db, plan_key);
+    assertEquals(row.delivery, expected.delivery, `${plan_key}: delivery`);
+    assertEquals(row.delivery_label, expected.label, `${plan_key}: delivery_label`);
+  }
+
+  // Pin the exact pre-formatted strings so a formatting drift can't hide behind the cross-check.
+  assertEquals(delivery(db, "o/r#1").delivery_label, "2/3 slices merged, 1 converging");
+  assertEquals(delivery(db, "o/r#2").delivery_label, "2/2 slices merged");
+  assertEquals(delivery(db, "o/r#4").delivery, null);
+});
+
+test("plan_delivery_counts pins the two subtle predicates: `converged` is terminal, a dangling pr_key is in-flight", () => {
+  const db = viewDb();
+  // `converged` is in TERMINAL_STATUSES (review-only mode): a `done` epic whose only remaining PR is
+  // `converged` (not `merged`) is resolved-not-landed. It must NOT count as in-flight — so delivery is
+  // NULL, never `converging`. This pins the hard-coded terminal set in the view's SQL against
+  // TERMINAL_STATUSES; drop `converged` from either and prs_in_flight becomes 1 here.
+  const conv = addPlan(db, "o/r#c", "done", [
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 0, pr: { status: "converged" } },
+  ]);
+  assertEquals(counts(db, "o/r#c"), { prs_opened: 2, prs_merged: 1, prs_in_flight: 0 });
+  assertEquals(delivery(db, "o/r#c").delivery, null, "converged is terminal-not-merged → resolved, not landed");
+  assertEquals({ ...delivery(db, "o/r#c") }, { delivery: deriveDelivery("done", conv).delivery, delivery_label: deriveDelivery("done", conv).label });
+
+  // A dangling `pr_key` (task opened a PR but the `pull_requests` row is absent — the poller's
+  // MISSING_PR_STATUS desync). The LEFT JOIN yields `status IS NULL`, which the view's
+  // `p.status IS NULL OR …` branch counts as in-flight — so even though every OTHER PR merged, the
+  // epic stays `converging` and can never be wrongly promoted to `landed`.
+  const dangling = addPlan(db, "o/r#d", "done", [
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 0, danglingPr: true },
+  ]);
+  assertEquals(counts(db, "o/r#d"), { prs_opened: 2, prs_merged: 1, prs_in_flight: 1 });
+  assertEquals(delivery(db, "o/r#d").delivery, "converging", "a dangling pr_key keeps the epic in flight (never landed)");
+  assertEquals({ ...delivery(db, "o/r#d") }, {
+    delivery: deriveDelivery("done", dangling).delivery,
+    delivery_label: deriveDelivery("done", dangling).label,
+  });
+});
+
+test("plan_wave_label reproduces the workers' wave_count / current_wave / wave_label projection", () => {
+  const db = viewDb();
+  // Wave 0 fully merged, wave 1 still converging → frontier is wave 1 (the gating wave). "2/2".
+  addPlan(db, "o/r#1", "done", [
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 1, pr: { status: "converging" } },
+    { status: "blocked", wave: 1 },
+  ]);
+  // Single wave, all merged → frontier pins to the last index (0). "1/1".
+  addPlan(db, "o/r#2", "done", [
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+  ]);
+  // Three waves, freshly dispatched (all in flight) → frontier is wave 0. "1/3".
+  addPlan(db, "o/r#3", "dispatched", [
+    { status: "opened", wave: 0, pr: { status: "converging" } },
+    { status: "pending", wave: 1 },
+    { status: "pending", wave: 2 },
+  ]);
+  // No levelized tasks → no wave rollup row (matches the workers leaving a taskless plan NULL).
+  addPlan(db, "o/r#5", "planning", []);
+
+  assertEquals(waveLabel(db, "o/r#1"), { wave_count: 2, current_wave: 1, wave_label: "2/2" });
+  assertEquals(waveLabel(db, "o/r#2"), { wave_count: 1, current_wave: 0, wave_label: "1/1" });
+  assertEquals(waveLabel(db, "o/r#3"), { wave_count: 3, current_wave: 0, wave_label: "1/3" });
+  assertEquals(waveLabel(db, "o/r#5"), undefined);
+});
+
+test("plan_read_model joins the derived wave + delivery projections onto the plans row", () => {
+  const db = viewDb();
+  addPlan(db, "o/r#1", "done", [
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 1, pr: { status: "converging" } },
+  ]);
+  addPlan(db, "o/r#5", "planning", []);
+
+  const row = db.prepare("SELECT * FROM plan_read_model WHERE plan_key = ?").get("o/r#1") as Record<string, unknown>;
+  assertEquals(row.plan_key, "o/r#1");
+  assertEquals(row.status, "done");
+  assertEquals(row.list_bucket, "active");
+  assertEquals(row.wave_label, "2/2");
+  assertEquals(row.wave_count, 2);
+  assertEquals(row.current_wave, 1);
+  assertEquals(row.delivery, "converging");
+  assertEquals(row.delivery_label, "1/2 slices merged, 1 converging");
+
+  // A taskless plan still appears (LEFT JOINs), with the derived columns NULL.
+  const empty = db.prepare("SELECT wave_label, delivery, delivery_label FROM plan_read_model WHERE plan_key = ?").get("o/r#5") as Record<string, unknown>;
+  assertEquals({ ...empty }, { wave_label: null, delivery: null, delivery_label: null });
+});
+
+test("the operator pages read the derived plan_read_model VIEW for the wave/delivery cells", () => {
+  // Overview epics grid — binds the view and still surfaces wave_label + delivery_label.
+  const overview = PAGE("overview.page.json");
+  const epics = (overview.nodes ?? []).find((n: { id: string }) => n.id === "overview-epics");
+  assert(epics, "overview must keep the Active Epics grid");
+  assertEquals(epics.props.data.table, "plan_read_model");
+  const epicCols: string[] = epics.props.columns.map((c: { field: string }) => c.field);
+  assert(epicCols.includes("wave_label") && epicCols.includes("delivery_label"), "overview epics grid surfaces wave_label + delivery_label");
+
+  // Epic-detail wave banner + plan grid both read the view.
+  const detail = PAGE("epic-detail.page.json");
+  const byId = (id: string) => (detail.nodes ?? []).find((n: { id: string }) => n.id === id);
+  assertEquals(byId("wave-banner").props.data.table, "plan_read_model");
+  assertEquals(byId("epic-plan").props.data.table, "plan_read_model");
+  assert(/\{\{\s*wave_label\s*\}\}/.test(byId("wave-banner").props.header), "the banner surfaces wave_label");
+  assertEquals(byId("wave-banner").props.body, "delivery_label", "the banner body is the delivery_label");
+});

package/db/migrations/059_plan_wave_summary.sql

@@ -0,0 +1,93 @@
+-- Epic-detail wave visualization + task→representation links (issue #411).
+--
+-- The Epic detail page (pages/epic-detail.page.json) had no glanceable per-wave progress and no
+-- click-through from an in-flight task to the thing that represents it (its PR / process instance).
+-- Both are pure ROLLUPS of data that already exists — `plan_tasks` (the slices + their wave) joined
+-- to `pull_requests` (each slice's PR url + engine `process_key`) — so per AGENTS.md "Derivation over
+-- duplication / no drift surfaces" they are DERIVED, not denormalised onto a worker-written table.
+--
+-- Historically the codebase reached for a denormalised flat table here (see 022_plan_wave_progress,
+-- 029_plan_delivery, 051_merges_per_day) purely because Urban's datasource could not read a SQL
+-- VIEW. That constraint is gone (nano-ide#424: `gateway.schema()` now introspects
+-- `type IN ('table','view')` and tags a view read-only), so these are VIEWs — a single source of
+-- truth with NO write-path and no possibility of drift from `plan_tasks`.
+--
+-- Three views, layered so each is a plain `CREATE VIEW <name> AS SELECT … FROM …` (no CTE / no
+-- select-list subquery) — which keeps them parseable by the static pages↔schema contract guard
+-- (scripts/pages-contract.test.ts) that introspects the migrations to whitelist page columns:
+--
+--   • plan_wave_tasks   — per-task rows (every `plan_tasks` column) PLUS the link targets the
+--                         wave-state grid needs to reach a task's representation: `pr_url`
+--                         (pull_requests.url — the GitHub PR) and `process_key`
+--                         (pull_requests.process_key — the engine instance, for the processExplorer
+--                         link, exactly as the Plan grid links its own `process_key`).
+--   • plan_wave_counts  — one row per (plan_key, wave) with the six-way task partition
+--                         (total / merged / in_flight / blocked / escalated / skipped). A task is
+--                         `merged` iff its PR reached `pull_requests.status = 'merged'` (the same
+--                         merged predicate app/delivery.ts derives the epic rollup from); otherwise
+--                         it falls to its `plan_tasks.status` bucket, and everything else
+--                         (pending/opened/waiting-for-lane/abandoned) is `in_flight`. The CASE
+--                         priority makes the five named buckets DISJOINT so they always sum to
+--                         `total` — which is what lets the bar below use `total` as its width.
+--   • plan_wave_summary — the same counts PLUS `bar`, a PRE-FORMATTED progress string
+--                         (e.g. "▓▓▓░░ 3/5 merged · 1 in-flight · 1 blocked"). It is pre-formatted
+--                         because the dataGrid renderer has no per-cell templating — a bar has to be
+--                         a ready-to-show string. `▓` = merged, `░` = not-yet-merged; the block run
+--                         is built with SQLite string funcs (`hex(zeroblob(n))` → n '0' chars →
+--                         `replace` to the glyph), and only non-zero categories are named in the
+--                         suffix.
+--
+-- Forward-only, additive (a new read model, no schema change to any base table). The runner wraps
+-- each file in its own transaction, so this file must NOT contain BEGIN/COMMIT. Numbered after the
+-- current highest prefix (058).
+
+CREATE VIEW plan_wave_tasks AS
+SELECT
+  t.id AS id,
+  t.plan_key AS plan_key,
+  t.task_index AS task_index,
+  t.task_id AS task_id,
+  t.title AS title,
+  t.prompt AS prompt,
+  t.status AS status,
+  t.pr_key AS pr_key,
+  t.summary AS summary,
+  t.created_at AS created_at,
+  t.updated_at AS updated_at,
+  t.wave AS wave,
+  t.open_question AS open_question,
+  t.answer AS answer,
+  t.draft_pr_key AS draft_pr_key,
+  t.corr_key AS corr_key,
+  p.url AS pr_url,
+  p.process_key AS process_key
+FROM plan_tasks t
+LEFT JOIN pull_requests p ON p.pr_key = t.pr_key;
+
+CREATE VIEW plan_wave_counts AS
+SELECT
+  t.plan_key AS plan_key,
+  t.wave AS wave,
+  COUNT(*) AS total,
+  SUM(CASE WHEN p.status = 'merged' THEN 1 ELSE 0 END) AS merged,
+  SUM(CASE WHEN p.status = 'merged' THEN 0 WHEN t.status = 'skipped' THEN 1 ELSE 0 END) AS skipped,
+  SUM(CASE WHEN p.status = 'merged' THEN 0 WHEN t.status = 'blocked' THEN 1 ELSE 0 END) AS blocked,
+  SUM(CASE WHEN p.status = 'merged' THEN 0 WHEN t.status = 'escalated' THEN 1 ELSE 0 END) AS escalated,
+  SUM(CASE WHEN p.status = 'merged' THEN 0 WHEN t.status IN ('skipped', 'blocked', 'escalated') THEN 0 ELSE 1 END) AS in_flight
+FROM plan_tasks t
+LEFT JOIN pull_requests p ON p.pr_key = t.pr_key
+WHERE t.wave IS NOT NULL
+GROUP BY t.plan_key, t.wave;
+
+CREATE VIEW plan_wave_summary AS
+SELECT
+  c.plan_key AS plan_key,
+  c.wave AS wave,
+  c.total AS total,
+  c.merged AS merged,
+  c.in_flight AS in_flight,
+  c.blocked AS blocked,
+  c.escalated AS escalated,
+  c.skipped AS skipped,
+  replace(substr(hex(zeroblob(c.merged)), 1, c.merged), '0', '▓') || replace(substr(hex(zeroblob(c.total - c.merged)), 1, c.total - c.merged), '0', '░') || ' ' || c.merged || '/' || c.total || ' merged' || CASE WHEN c.in_flight > 0 THEN ' · ' || c.in_flight || ' in-flight' ELSE '' END || CASE WHEN c.blocked > 0 THEN ' · ' || c.blocked || ' blocked' ELSE '' END || CASE WHEN c.escalated > 0 THEN ' · ' || c.escalated || ' escalated' ELSE '' END || CASE WHEN c.skipped > 0 THEN ' · ' || c.skipped || ' skipped' ELSE '' END AS bar
+FROM plan_wave_counts c;

package/db/migrations/060_plan_wave_rollup.sql

@@ -0,0 +1,52 @@
+-- Wave-progress read model as a derived VIEW (epic #412 — retire worker-maintained projections).
+--
+-- 022_plan_wave_progress.sql denormalised `plans.wave_count` / `plans.current_wave` /
+-- `plans.wave_label` — a per-epic "wave X/N" at-a-glance projection — onto the `plans` row, written
+-- by the wave workers (`record-plan`, `select-wave`, `record-wave`). Its comment cites the sole
+-- reason it was a worker-maintained table rather than a VIEW: "Urban's datasource cannot read a SQL
+-- VIEW". That constraint is gone (nano-ide#424: `gateway.schema()` now introspects
+-- `type IN ('table','view')`), so — exactly like 059 did for the wave-summary rollup — this expresses
+-- the same projection as a DERIVED view: a single source of truth with NO write-path and no drift
+-- from `plan_tasks`.
+--
+-- Reuses 059's `plan_wave_counts` (one row per (plan_key, wave), with the six-way task partition,
+-- including `in_flight`) so the frontier can be derived purely, layered so each view stays a plain
+-- `CREATE VIEW <name> AS SELECT … FROM …` (no CTE / no select-list subquery) — which keeps them
+-- parseable by the static pages↔schema contract guard (scripts/pages-contract.test.ts).
+--
+--   • plan_wave_progress — one row per plan_key with the two numeric projections:
+--       - wave_count   = MAX(wave)+1 (the levelizer emits contiguous waves 0..N-1, so this equals
+--                        `app/waves.ts` `waveCount`). A plan with no LEVELIZED tasks contributes no
+--                        `plan_wave_counts` row, so it is absent here and reads NULL through the
+--                        downstream LEFT JOIN — matching the workers, which leave a taskless plan's
+--                        wave columns NULL.
+--       - current_wave = the live FRONTIER, derived (not process-state-tracked): the lowest wave
+--                        that still has an `in_flight` task (the wave the fleet is actively
+--                        implementing / the wave the merge-barrier is gating), else — once every
+--                        wave has settled (in_flight = 0 everywhere) — pinned to the last index
+--                        MAX(wave). This reproduces the workers' projection: `record-plan` starts it
+--                        at 0 (wave 0 is in flight), `record-wave`/`select-wave` advance it to the
+--                        next gating wave as each wave's PRs merge, and it pins to wave_count-1 on
+--                        completion (a finished epic reads N/N).
+--   • plan_wave_label    — the same two numbers PLUS `wave_label`, the PRE-FORMATTED 1-based "X/N"
+--                          display string (`(current_wave+1)/wave_count`) the epics-index and epic
+--                          banner render, because the dataGrid has no per-cell templating.
+--
+-- Forward-only, additive (a new read model; no schema change to any base table). The runner wraps
+-- each file in its own transaction, so this file must NOT contain BEGIN/COMMIT.
+
+CREATE VIEW plan_wave_progress AS
+SELECT
+  c.plan_key AS plan_key,
+  MAX(c.wave) + 1 AS wave_count,
+  COALESCE(MIN(CASE WHEN c.in_flight > 0 THEN c.wave END), MAX(c.wave)) AS current_wave
+FROM plan_wave_counts c
+GROUP BY c.plan_key;
+
+CREATE VIEW plan_wave_label AS
+SELECT
+  w.plan_key AS plan_key,
+  w.wave_count AS wave_count,
+  w.current_wave AS current_wave,
+  (w.current_wave + 1) || '/' || w.wave_count AS wave_label
+FROM plan_wave_progress w;

package/db/migrations/061_plan_delivery_rollup.sql

@@ -0,0 +1,98 @@
+-- Epic delivery read model as a derived VIEW, plus the composite `plans` read model the pages bind
+-- (epic #412 — retire worker-maintained projections).
+--
+-- 029_plan_delivery.sql denormalised `plans.delivery` ('converging'|'landed'|NULL) and
+-- `plans.delivery_label` onto the `plans` row, recomputed each poll pass by `pollDelivery`
+-- (app/service.ts) which joins each `plan_tasks.pr_key` → `pull_requests.status`. The PURE derivation
+-- lives in `deriveDelivery`/`TERMINAL_STATUSES` (app/delivery.ts). Its comment cites the sole reason
+-- it was a poller-maintained table rather than a VIEW: "Urban's datasource cannot read a SQL VIEW".
+-- That constraint is gone (nano-ide#424), so this expresses the SAME `deriveDelivery` logic as a
+-- DERIVED view — a single source of truth with NO write-path and no drift.
+--
+-- Layered so each view stays a plain `CREATE VIEW <name> AS SELECT … FROM …` (no CTE / no
+-- select-list subquery), parseable by scripts/pages-contract.test.ts:
+--
+--   • plan_delivery_counts — one row per plan_key with the three counts `deriveDelivery` folds over
+--                            the slice PRs (only tasks that OPENED a PR — `pr_key IS NOT NULL` —
+--                            count, mirroring `pollDelivery`'s `if (!t.pr_key) continue`):
+--                              - prs_opened   = number of slice tasks with a PR.
+--                              - prs_merged   = those whose PR reached `status = 'merged'`.
+--                              - prs_in_flight = those whose PR is NON-terminal (`status` NOT IN
+--                                `TERMINAL_STATUSES` = converged/merged/abandoned). A `pr_key` with
+--                                no `pull_requests` row (status NULL, the poller's MISSING_PR_STATUS
+--                                sentinel) is non-terminal, so it counts as in flight — a DB desync
+--                                can never wrongly promote an epic to `landed`.
+--   • plan_delivery        — the derived signal + PRE-FORMATTED label, per `deriveDelivery`:
+--                              - NULL when the plan is not `done` or opened no PRs (no positive
+--                                signal yet), OR every PR is terminal but not all merged
+--                                (resolved-not-landed).
+--                              - 'converging' + "M/O slices merged, F converging" when ≥1 PR is in
+--                                flight.
+--                              - 'landed' + "O/O slices merged" when every slice PR merged
+--                                (prs_in_flight = 0 AND prs_merged = prs_opened > 0).
+--   • plan_read_model      — the `plans` row with its wave (060) and delivery projections DERIVED
+--                            from the views instead of read from the denormalised columns. This is
+--                            the datasource the operator pages (overview / epic-detail) bind, so that
+--                            when the wave-1 cleanup task DROPs plans.wave_label / plans.current_wave
+--                            / plans.wave_count / plans.delivery / plans.delivery_label, every page
+--                            already reads the single-source-of-truth views. It projects only the
+--                            `plans` columns those pages reference, plus the five derived columns.
+--
+-- Forward-only, additive. NO BEGIN/COMMIT — the runner wraps each file in its own transaction.
+
+CREATE VIEW plan_delivery_counts AS
+SELECT
+  t.plan_key AS plan_key,
+  COUNT(t.pr_key) AS prs_opened,
+  SUM(CASE WHEN t.pr_key IS NOT NULL AND p.status = 'merged' THEN 1 ELSE 0 END) AS prs_merged,
+  SUM(CASE WHEN t.pr_key IS NOT NULL AND (p.status IS NULL OR p.status NOT IN ('converged', 'merged', 'abandoned')) THEN 1 ELSE 0 END) AS prs_in_flight
+FROM plan_tasks t
+LEFT JOIN pull_requests p ON p.pr_key = t.pr_key
+GROUP BY t.plan_key;
+
+CREATE VIEW plan_delivery AS
+SELECT
+  pl.plan_key AS plan_key,
+  CASE
+    WHEN pl.status IS NOT 'done' OR COALESCE(c.prs_opened, 0) = 0 THEN NULL
+    WHEN COALESCE(c.prs_in_flight, 0) > 0 THEN 'converging'
+    WHEN c.prs_merged = c.prs_opened THEN 'landed'
+    ELSE NULL
+  END AS delivery,
+  CASE
+    WHEN pl.status IS NOT 'done' OR COALESCE(c.prs_opened, 0) = 0 THEN NULL
+    WHEN COALESCE(c.prs_in_flight, 0) > 0 THEN c.prs_merged || '/' || c.prs_opened || ' slices merged, ' || c.prs_in_flight || ' converging'
+    WHEN c.prs_merged = c.prs_opened THEN c.prs_opened || '/' || c.prs_opened || ' slices merged'
+    ELSE NULL
+  END AS delivery_label
+FROM plans pl
+LEFT JOIN plan_delivery_counts c ON c.plan_key = pl.plan_key;
+
+CREATE VIEW plan_read_model AS
+SELECT
+  pl.plan_key AS plan_key,
+  pl.repo AS repo,
+  pl.issue_number AS issue_number,
+  pl.issue_url AS issue_url,
+  pl.title AS title,
+  pl.status AS status,
+  pl.task_count AS task_count,
+  pl.process_key AS process_key,
+  pl.outcome AS outcome,
+  pl.updated_at AS updated_at,
+  pl.epic_phase AS epic_phase,
+  pl.base_branch AS base_branch,
+  pl.wait_gate_label AS wait_gate_label,
+  pl.bound_artifacts AS bound_artifacts,
+  pl.promotion_pr AS promotion_pr,
+  pl.promotion_state AS promotion_state,
+  pl.list_bucket AS list_bucket,
+  pl.ack_open AS ack_open,
+  wl.wave_count AS wave_count,
+  wl.current_wave AS current_wave,
+  wl.wave_label AS wave_label,
+  d.delivery AS delivery,
+  d.delivery_label AS delivery_label
+FROM plans pl
+LEFT JOIN plan_wave_label wl ON wl.plan_key = pl.plan_key
+LEFT JOIN plan_delivery d ON d.plan_key = pl.plan_key;

package/db/migrations/062_merges_per_day_view.sql

@@ -0,0 +1,72 @@
+-- Merged-per-day throughput / burn-up as a derived SQL VIEW (epic #412, retiring the 051 flat table).
+--
+-- 051_merges_per_day.sql created the DENORMALISED `merges_per_day` read table (day / merged /
+-- cumulative / bar) that `pollMergesPerDay` (app/mergesPerDay.ts) recomputes each poll pass from the
+-- `merges` audit rows (004_merge.sql). Its comment cites the ONE reason it could not simply be a
+-- VIEW: "Urban's page datasource cannot read a SQL VIEW" (gateway.ts `schema()` whitelisted
+-- `type='table'` only). That constraint is GONE — nano-ide#424 made `gateway.schema()` introspect
+-- `type IN ('table','view')` and tag a view read-only, and #411 (059_plan_wave_summary.sql)
+-- established the layered-VIEW pattern. So the aggregate becomes what AGENTS.md always wanted
+-- ("Derivation over duplication"): a VIEW that is a single source of truth with NO write-path and no
+-- possibility of drift from the `merges` audit trail.
+--
+-- This migration is WAVE-0 / PURELY ADDITIVE: it adds the VIEW and the Velocity page is repointed
+-- onto it, but the `merges_per_day` TABLE and its `pollMergesPerDay` write-path are LEFT IN PLACE (a
+-- harmless duplicate) so the surface never goes stale while both coexist. A wave-1 cleanup task
+-- ("retire-projection-writepaths-cleanup") drops the table and deletes the write-path AFTER this
+-- merges.
+--
+-- The VIEW must reproduce the CURRENT projection EXACTLY, including two subtleties beyond the 051
+-- comment's canonical `SELECT date(at) AS day, COUNT(DISTINCT pr_key) …`:
+--   • the day is bucketed in the operator's LOCAL calendar day (issue #361) — `date(at, 'localtime')`,
+--     not UTC — matching `deriveMergesPerDay`, so a merge either side of a local midnight lands on the
+--     day the operator saw it;
+--   • `bar` is the SAME pre-formatted proportional block-character string the `prose` renderer draws
+--     today (the renderer has no per-cell templating / no chart node, so the bar must arrive
+--     ready-to-show): a run of `█` glyphs whose length is `max(1, round((merged / busiest) * 30))`
+--     (min one glyph for any non-zero day; the busiest day is 30 wide), i.e. exactly
+--     `barFor()`/`BAR_WIDTH`/`BAR_FULL` in app/mergesPerDay.ts.
+--
+-- Layered into TWO plain views so each is a `CREATE VIEW <name> AS SELECT … FROM …` with NO CTE and
+-- NO select-list subquery — which keeps them parseable by the static pages↔schema contract guard
+-- (scripts/pages-contract.test.ts), exactly as 059 layers its counts → summary:
+--
+--   • merges_per_day_counts — one row per local calendar day: `day` + `merged`
+--     (COUNT(DISTINCT pr_key) so a PR with several `merged` audit rows on one day — an
+--     already-merged short-circuit or a retry — counts once; `queued`/`blocked` rows are excluded).
+--   • merges_per_day_view   — the same rows PLUS the burn-up `cumulative`
+--     (`SUM(merged) OVER (ORDER BY day)` — a window function in the select list, allowed by the
+--     guard) and the pre-formatted `bar`. The bar length uses `MAX(merged) OVER ()` (the busiest
+--     day) as the scale; the block run is built with SQLite string funcs
+--     (`hex(zeroblob(n))` → 2n '0' chars → `substr` to n → `replace` to the `█` glyph), the same
+--     trick 059 uses for its progress bar. Both live in the SELECT list, not a subquery, so the
+--     guard can still read every output column.
+--
+-- Forward-only, additive (a new read model, no change to any base table). The runner wraps each file
+-- in its own transaction, so this file must NOT contain BEGIN/COMMIT.
+
+CREATE VIEW merges_per_day_counts AS
+SELECT
+  date(m.at, 'localtime') AS day,
+  COUNT(DISTINCT m.pr_key) AS merged
+FROM merges m
+WHERE m.outcome = 'merged'
+GROUP BY date(m.at, 'localtime');
+
+CREATE VIEW merges_per_day_view AS
+SELECT
+  c.day AS day,
+  c.merged AS merged,
+  SUM(c.merged) OVER (ORDER BY c.day) AS cumulative,
+  CASE
+    WHEN c.merged <= 0 OR MAX(c.merged) OVER () <= 0 THEN ''
+    ELSE replace(
+      substr(
+        hex(zeroblob(max(1, CAST(round((c.merged * 1.0 / MAX(c.merged) OVER ()) * 30.0) AS INTEGER)))),
+        1,
+        max(1, CAST(round((c.merged * 1.0 / MAX(c.merged) OVER ()) * 30.0) AS INTEGER))
+      ),
+      '0', '█'
+    )
+  END AS bar
+FROM merges_per_day_counts c;

package/db/migrations/064_lineage_thread_view.sql

@@ -0,0 +1,75 @@
+-- Lineage read-model: derive the view-expressible identity columns of `lineage_threads` (epic
+-- #412 — "Retire worker-maintained denormalized projections in favour of SQL VIEWs").
+--
+-- `lineage_threads` (037_lineage.sql) is a denormalised read table `pollLineage` (app/lineage.ts)
+-- rewrites every poll pass, stitching request → implementation → PR(s) → convergence → merge into
+-- one narrative per `root_request_key`. Its comment cited "Urban's datasource cannot read a SQL
+-- VIEW" as the sole reason to denormalise; nano-ide#424 removed that constraint (gateway.schema()
+-- now introspects `type IN ('table','view')`), so the parts that are plain rollups of data that
+-- ALREADY exists should be DERIVED, not duplicated (AGENTS.md "Derivation over duplication / no
+-- drift surfaces"), exactly as 059_plan_wave_summary.sql did for the plans wave/delivery rollups.
+--
+-- AUDIT — per column, is it a clean rollup or genuinely procedural?
+--
+--   VIEW-EXPRESSIBLE (pure structural function of which origin table the root matches — no frontier
+--   logic, no representative-PR selection, no formatting — so a plain parseable view reproduces them
+--   EXACTLY as `deriveLineage` does):
+--     • `kind`      — 'epic' when the root is a `plans.plan_key`, 'feature' when it is a
+--                     `feature_runs.feature_key`, else 'pr' (self-rooted human/webhook PR). The
+--                     epic-before-feature precedence mirrors `collectThreads`, which sets the plan
+--                     thread after the feature thread for the same key.
+--     • `issue_url` — the matched origin's `issue_url` (`plans`/`feature_runs`), NULL for a
+--                     self-rooted PR — exactly `deriveLineage`'s `origin.kind === "pr" ? null : …`.
+--     • `title`     — the matched origin's `title` for an epic/feature thread. A self-rooted PR's
+--                     title is the PROCEDURAL representative-PR pick, so it falls back to the
+--                     poller-written `lineage_threads.title` for kind 'pr' (see below).
+--
+--   PROCEDURAL (multi-stage frontier / ordering logic in the pure `deriveLineage`, which selects a
+--   representative PR — "first non-terminal by pr_key, else last by pr_key" — branches on origin
+--   kind + feature pre-hand-off, rolls epic fan-out up via `deriveDelivery`, and formats round /
+--   slice-count label strings; none of this is a plain no-CTE / no-select-list-subquery view, and
+--   forcing it would risk diverging from the tested derivation): `stage`, `stage_label`,
+--   `process_key`, `active`, plus the membership columns `pr_count` / `pr_keys` (which union a
+--   root's threaded PRs with its origin's own `pr_key` / `plan_tasks.pr_key` and dedupe across
+--   roots — not a clean grouped join) and the self-rooted `title`. These stay written by
+--   `pollLineage` for the wave-1 cleanup task to trim; this view PASSES THEM THROUGH from
+--   `lineage_threads` so the single Lineage grid keeps rendering identically.
+--
+-- The view is a plain `CREATE VIEW <name> AS SELECT … FROM …` — no CTE, no select-list subquery,
+-- every column aliased — so the static pages↔schema contract guard (scripts/pages-contract.test.ts)
+-- can introspect its output columns to whitelist the repointed page. CASE / COALESCE in the select
+-- list are fine (they are not subqueries).
+--
+-- Forward-only, additive: a new read model, no schema change to any base table, no DROP. The runner
+-- wraps each file in its own transaction, so this file must NOT contain BEGIN/COMMIT. This task owns
+-- the disjoint migration block 064-069; a single view suffices, so 065-069 are left unused.
+
+CREATE VIEW lineage_thread_view AS
+SELECT
+  lt.root_request_key AS root_request_key,
+  CASE
+    WHEN pl.plan_key IS NOT NULL THEN 'epic'
+    WHEN fr.feature_key IS NOT NULL THEN 'feature'
+    ELSE 'pr'
+  END AS kind,
+  CASE
+    WHEN pl.plan_key IS NOT NULL THEN pl.title
+    WHEN fr.feature_key IS NOT NULL THEN fr.title
+    ELSE lt.title
+  END AS title,
+  CASE
+    WHEN pl.plan_key IS NOT NULL THEN pl.issue_url
+    WHEN fr.feature_key IS NOT NULL THEN fr.issue_url
+    ELSE NULL
+  END AS issue_url,
+  lt.stage AS stage,
+  lt.stage_label AS stage_label,
+  lt.process_key AS process_key,
+  lt.pr_keys AS pr_keys,
+  lt.pr_count AS pr_count,
+  lt.active AS active,
+  lt.created_at AS created_at,
+  lt.updated_at AS updated_at
+FROM lineage_threads lt
+LEFT JOIN plans pl ON pl.plan_key = lt.root_request_key
+LEFT JOIN feature_runs fr ON fr.feature_key = lt.root_request_key;