@nanobpm/nano-workforce 0.118.2 → 0.120.0

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+# [0.120.0](https://github.com/nanobpm/nano-workforce/compare/v0.119.0...v0.120.0) (2026-08-22)
+
+
+### Features
+
+* **lineage:** derive view-expressible lineage_threads columns via SQL VIEW ([#437](https://github.com/nanobpm/nano-workforce/issues/437)) ([f25c824](https://github.com/nanobpm/nano-workforce/commit/f25c824bf9c72c3757a58794065a5c86b208dbe0)), closes [nano-ide#424](https://github.com/nano-ide/issues/424) [nanobpm/nano-workforce#412](https://github.com/nanobpm/nano-workforce/issues/412)
+* **velocity:** back merged-per-day with a SQL VIEW, repoint Velocity page ([#412](https://github.com/nanobpm/nano-workforce/issues/412)) ([#436](https://github.com/nanobpm/nano-workforce/issues/436)) ([5be81e4](https://github.com/nanobpm/nano-workforce/commit/5be81e466f2593622ae837d6e63b00f0287c305d)), closes [nano-ide#424](https://github.com/nano-ide/issues/424) [#411](https://github.com/nanobpm/nano-workforce/issues/411) [#361](https://github.com/nanobpm/nano-workforce/issues/361)
+
+# [0.119.0](https://github.com/nanobpm/nano-workforce/compare/v0.118.2...v0.119.0) (2026-08-22)
+
+
+### Features
+
+* **epic-detail:** wave visualization + task→representation links ([#411](https://github.com/nanobpm/nano-workforce/issues/411)) ([#434](https://github.com/nanobpm/nano-workforce/issues/434)) ([cff11fe](https://github.com/nanobpm/nano-workforce/commit/cff11febc30c1fbe08ea385ef5cf36fae0ff2fe7)), closes [nano-ide#424](https://github.com/nano-ide/issues/424)
+
 ## [0.118.2](https://github.com/nanobpm/nano-workforce/compare/v0.118.1...v0.118.2) (2026-08-21)
 
 

package/app/lineage.ts

@@ -330,6 +330,31 @@ export interface LineageThreadRow {
 const lineageThreads = (data: DataLayer) =>
   data.table<LineageThreadRow>("lineage_threads", "root_request_key");
 
+/** Read-only handle on the `lineage_thread_view` VIEW (migration 064) the Lineage page now binds.
+ *  Same shape as `LineageThreadRow`: the view PASSES THROUGH the procedural frontier columns from
+ *  `lineage_threads` (`stage`/`stage_label`/`process_key`/`pr_keys`/`pr_count`/`active`/timestamps)
+ *  and DERIVES the view-expressible identity columns (`kind`, `issue_url`, and an epic/feature
+ *  thread's `title`) from the `plans`/`feature_runs` origin joins — the single source of truth,
+ *  eliminating those columns' drift surface (epic #412). A self-rooted PR's `title` falls back to
+ *  the poller-written value, since it is a procedural representative-PR pick. */
+const lineageThreadView = (data: DataLayer) =>
+  data.table<LineageThreadRow>("lineage_thread_view", "root_request_key");
+
+/** All lineage threads off the same `lineage_thread_view` VIEW the Lineage page binds, in this
+ *  module's own active-frontier-first, then-by-key stable order (matching {@link listLineage}) —
+ *  NOT the page datasource's `orderBy: updated_at desc` + tab-specific `active` filter, which the
+ *  page applies on top of this table. Additive: this reads the derived view rather than recomputing
+ *  via {@link collectThreads}, so it reflects the identity columns' single source of truth (origin
+ *  joins) while the frontier columns come through from the still-poller-written `lineage_threads`. */
+export async function listLineageView(data: DataLayer): Promise<LineageThreadRow[]> {
+  const rows = await lineageThreadView(data).all();
+  return rows.sort(
+    (a, b) =>
+      Number(b.active) - Number(a.active) ||
+      a.root_request_key.localeCompare(b.root_request_key),
+  );
+}
+
 function toLineagePr(row: PrRow): LineagePr {
   return {
     prKey: row.pr_key,

package/app/mergesPerDayView.test.ts

@@ -0,0 +1,166 @@
+// Coverage for the merged-per-day VIEW that retires the denormalised `merges_per_day` table
+// (epic #412; the read model originally shipped in issue #344 / 051_merges_per_day.sql).
+//
+// The whole point of #412 is that this aggregate — merged-per-day throughput + burn-up + a
+// pre-formatted proportional bar — is now a derived SQL VIEW (enabled by nano-ide#424) instead of a
+// worker-written flat table, so it is a single source of truth with no drift. This test therefore
+// exercises the REAL SQLite view (062_merges_per_day_view.sql applied to an in-memory DB, mirroring
+// migration053.test.ts / planWaveSummary.test.ts) and pins that it reproduces the previous
+// projection's EXACT values: the DISTINCT-per-day count, the ascending burn-up `cumulative`, and the
+// byte-for-byte pre-formatted `bar` string the Velocity `prose` renderer draws.
+//
+// `deriveMergesPerDay` (app/mergesPerDay.ts) is the pure function the retired `pollMergesPerDay`
+// write-path used, so it is the authoritative oracle for "what the table held". We assert the view
+// equals it over sample `merges` rows. Bucketing is local-calendar-day (issue #361 — the view uses
+// `date(at, 'localtime')`, which resolves against the host zone). To keep the SQLite `localtime`
+// bucketing and the JS oracle in lockstep WITHOUT mutating the process-global `process.env.TZ`
+// (which `node --test` runs concurrently across FILES, so a `TZ` flip could leak into the
+// timezone-specific assertions in app/mergesPerDay.test.ts), we drive the oracle with the SAME host
+// zone SQLite uses by omitting its `timeZone` argument — `deriveMergesPerDay(rows)` defaults to the
+// host zone. Both sides therefore bucket identically in any host zone, so no `day` string is
+// hard-coded.
+
+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 { deriveMergesPerDay, type MergeAuditRow } from "./mergesPerDay.ts";
+
+const MIGRATION = fileURLToPath(new URL("../db/migrations/062_merges_per_day_view.sql", import.meta.url));
+
+/** A DB with the `merges` audit shape (004_merge.sql, FK-free like migration053.test.ts) + the view. */
+function viewDb(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  db.exec(
+    `CREATE TABLE merges (
+       id INTEGER PRIMARY KEY AUTOINCREMENT, pr_key TEXT NOT NULL, outcome TEXT NOT NULL,
+       method TEXT, detail TEXT, at TEXT NOT NULL);`,
+  );
+  db.exec(readFileSync(MIGRATION, "utf8"));
+  return db;
+}
+
+function seed(db: DatabaseSync, rows: readonly MergeAuditRow[]): void {
+  const ins = db.prepare("INSERT INTO merges (pr_key, outcome, at) VALUES (?, ?, ?)");
+  for (const r of rows) ins.run(r.pr_key, r.outcome, r.at);
+}
+
+/** The view's rows as `[day, merged, cumulative, bar]`, ordered like the Velocity page (day asc). */
+function view(db: DatabaseSync): Array<[string, number, number, string]> {
+  return (
+    db.prepare("SELECT day, merged, cumulative, bar FROM merges_per_day_view ORDER BY day").all() as Array<
+      Record<string, unknown>
+    >
+  ).map((r) => [r.day as string, Number(r.merged), Number(r.cumulative), r.bar as string]);
+}
+
+const merged = (pr_key: string, at: string): MergeAuditRow => ({ pr_key, outcome: "merged", at });
+
+test("merges_per_day_view reproduces the retired projection exactly (count, burn-up, bar)", () => {
+  const db = viewDb();
+  const rows: MergeAuditRow[] = [
+    // day A: 4 distinct PRs (the busiest day → widest bar), including a duplicate merged row.
+    merged("o/r#1", "2026-01-01T01:00:00Z"),
+    merged("o/r#2", "2026-01-01T02:00:00Z"),
+    merged("o/r#3", "2026-01-01T03:00:00Z"),
+    merged("o/r#4", "2026-01-01T04:00:00Z"),
+    merged("o/r#4", "2026-01-01T05:00:00Z"), // retry / already-merged short-circuit → counts once
+    // day B: 1 PR → short but visible bar.
+    merged("o/r#5", "2026-01-02T10:00:00Z"),
+    // day C: 2 PRs.
+    merged("o/r#6", "2026-01-03T10:00:00Z"),
+    merged("o/r#7", "2026-01-03T11:00:00Z"),
+    // non-merged attempts must be ignored entirely.
+    { pr_key: "o/r#8", outcome: "queued", at: "2026-01-02T12:00:00Z" },
+    { pr_key: "o/r#9", outcome: "blocked", at: "2026-01-03T12:00:00Z" },
+  ];
+  seed(db, rows);
+
+  const expected = deriveMergesPerDay(rows).map(
+    (d) => [d.day, d.merged, d.cumulative, d.bar] as [string, number, number, string],
+  );
+  assertEquals(view(db), expected);
+});
+
+test("merges_per_day_view bar: full glyph run for the busiest day, min one glyph for a lone merge", () => {
+  const db = viewDb();
+  seed(db, [
+    merged("o/r#1", "2026-01-01T01:00:00Z"),
+    merged("o/r#2", "2026-01-01T02:00:00Z"),
+    merged("o/r#3", "2026-01-01T03:00:00Z"),
+    merged("o/r#4", "2026-01-01T04:00:00Z"),
+    merged("o/r#5", "2026-01-02T01:00:00Z"),
+  ]);
+  const rows = view(db);
+  const [a, b] = rows;
+  assertEquals(a[3], "█".repeat(30), "the busiest day fills the configured bar width (30)");
+  assert(a[3].length > b[3].length, "the busier day draws a longer bar");
+  assert([...b[3]].length >= 1, "a day with any merge draws at least one glyph");
+  assertEquals(view(db), deriveMergesPerDay([
+    merged("o/r#1", "2026-01-01T01:00:00Z"),
+    merged("o/r#2", "2026-01-01T02:00:00Z"),
+    merged("o/r#3", "2026-01-01T03:00:00Z"),
+    merged("o/r#4", "2026-01-01T04:00:00Z"),
+    merged("o/r#5", "2026-01-02T01:00:00Z"),
+  ]).map((d) => [d.day, d.merged, d.cumulative, d.bar]));
+});
+
+test("merges_per_day_view is empty when no merges are recorded", () => {
+  const db = viewDb();
+  seed(db, [{ pr_key: "o/r#1", outcome: "queued", at: "2026-01-01T01:00:00Z" }]);
+  assertEquals(view(db), []);
+});
+
+test("merges_per_day_view buckets on the LOCAL calendar day, matching deriveMergesPerDay (issue #361)", () => {
+  // The view's `date(at, 'localtime')` and the oracle's default zone both resolve against the host
+  // zone, so two merges either side of a local-day boundary bucket identically on both sides — no
+  // matter which host zone the suite runs under.
+  const db = viewDb();
+  const rows: MergeAuditRow[] = [
+    merged("o/r#1", "2026-01-01T23:30:00Z"),
+    merged("o/r#2", "2026-01-02T00:30:00Z"),
+  ];
+  seed(db, rows);
+  assertEquals(view(db), deriveMergesPerDay(rows).map((d) => [d.day, d.merged, d.cumulative, d.bar]));
+});
+
+// A tiny deterministic PRNG (mulberry32) so the property check runs the SAME audit rows every time —
+// non-determinism (`Math.random()`) would make a failure impossible to reproduce (see "no flaky
+// tests" in AGENTS.md). Seeded once with a fixed constant.
+function mulberry32(seed: number): () => number {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+test("merges_per_day_view reproduces the projection across many random audits (property check)", () => {
+  const db = viewDb();
+  const outcomes = ["merged", "merged", "merged", "queued", "blocked"];
+  const rand = mulberry32(0x9e3779b9); // fixed seed → the same 200 trials on every run.
+  for (let trial = 0; trial < 200; trial++) {
+    db.exec("DELETE FROM merges");
+    const rows: MergeAuditRow[] = [];
+    const n = 1 + Math.floor(rand() * 40);
+    for (let i = 0; i < n; i++) {
+      const day = 1 + Math.floor(rand() * 9);
+      const hh = String(Math.floor(rand() * 24)).padStart(2, "0");
+      rows.push({
+        pr_key: `o/r#${1 + Math.floor(rand() * 12)}`,
+        outcome: outcomes[Math.floor(rand() * outcomes.length)],
+        at: `2026-01-0${day}T${hh}:00:00Z`,
+      });
+    }
+    seed(db, rows);
+    assertEquals(
+      view(db),
+      deriveMergesPerDay(rows).map((d) => [d.day, d.merged, d.cumulative, d.bar]),
+      `random trial ${trial} diverged from the projection`,
+    );
+  }
+});

package/app/migration064.test.ts

@@ -0,0 +1,176 @@
+// Read-model guard for migration 064's `lineage_thread_view` VIEW (epic #412: retire the
+// worker-maintained `lineage_threads` denormalisation in favour of SQL VIEWs for the parts that are
+// clean rollups). Mirrors the derived-read-model test style of app/migration037.test.ts and
+// app/planWaveSummary.test.ts: apply the migration to a real in-memory SQLite DB and assert the
+// VIEW's output over sample rows — so this exercises the real view, not a re-implementation.
+//
+// The view DERIVES the view-expressible identity columns (`kind`, `issue_url`, and an epic/feature
+// thread's `title`) from the `plans` / `feature_runs` origin joins, and PASSES THROUGH the
+// procedural frontier columns (`stage`/`stage_label`/`process_key`/`pr_keys`/`pr_count`/`active`/
+// timestamps) from `lineage_threads`. It must reproduce EXACTLY what `pollLineage` wrote for the
+// migrated columns, so a future drop of those `lineage_threads` columns is behaviour-preserving.
+import { readFileSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+import { assertEquals } from "#test-assert";
+
+const MIGRATION = fileURLToPath(new URL("../db/migrations/064_lineage_thread_view.sql", import.meta.url));
+
+/** A DB with the base shapes the view reads (`lineage_threads`, `plans`, `feature_runs`) plus the
+ *  view applied. The `lineage_threads` schema also models `kind`/`issue_url`, which the view does
+ *  NOT read (it derives them from the `plans`/`feature_runs` origin joins) — they are kept here so
+ *  `addThread` can write exactly what `pollLineage` denormalises. */
+function viewDb(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  db.exec(
+    `CREATE TABLE lineage_threads (
+       root_request_key TEXT PRIMARY KEY, kind TEXT, title TEXT, issue_url TEXT, stage TEXT,
+       stage_label TEXT, process_key TEXT, pr_keys TEXT, pr_count INTEGER, active INTEGER,
+       created_at TEXT, updated_at TEXT);
+     CREATE TABLE plans (plan_key TEXT PRIMARY KEY, title TEXT, issue_url TEXT);
+     CREATE TABLE feature_runs (feature_key TEXT PRIMARY KEY, title TEXT, issue_url TEXT);`,
+  );
+  db.exec(readFileSync(MIGRATION, "utf8"));
+  return db;
+}
+
+/** Insert a `lineage_threads` row exactly as `pollLineage` denormalises one. */
+function addThread(
+  db: DatabaseSync,
+  row: {
+    root_request_key: string;
+    kind: string;
+    title: string | null;
+    issue_url: string | null;
+    stage: string;
+    stage_label: string | null;
+    process_key: string | null;
+    pr_keys: string | null;
+    pr_count: number;
+    active: number;
+  },
+): void {
+  db.prepare(
+    `INSERT INTO lineage_threads (root_request_key, kind, title, issue_url, stage, stage_label,
+       process_key, pr_keys, pr_count, active, created_at, updated_at)
+     VALUES (@root_request_key, @kind, @title, @issue_url, @stage, @stage_label, @process_key,
+       @pr_keys, @pr_count, @active, 't0', 't1')`,
+  ).run(row);
+}
+
+test("lineage_thread_view derives kind/issue_url/title for an epic thread from the plans origin", () => {
+  const db = viewDb();
+  db.prepare("INSERT INTO plans (plan_key, title, issue_url) VALUES (?, ?, ?)").run(
+    "o/r#2",
+    "Epic: retire projections",
+    "https://github.com/o/r/issues/2",
+  );
+  // pollLineage wrote the same identity values (denormalised) alongside the procedural frontier.
+  addThread(db, {
+    root_request_key: "o/r#2",
+    kind: "epic",
+    title: "Epic: retire projections",
+    issue_url: "https://github.com/o/r/issues/2",
+    stage: "converging",
+    stage_label: "3/5 slices merged, 2 converging",
+    process_key: "P-epic",
+    pr_keys: '["o/r#20","o/r#21"]',
+    pr_count: 5,
+    active: 1,
+  });
+
+  const v = db
+    .prepare("SELECT * FROM lineage_thread_view WHERE root_request_key = ?")
+    .get("o/r#2") as Record<string, unknown>;
+  // Derived from the plans join — identical to what the poller denormalised.
+  assertEquals(v.kind, "epic");
+  assertEquals(v.title, "Epic: retire projections");
+  assertEquals(v.issue_url, "https://github.com/o/r/issues/2");
+  // Procedural frontier columns pass through unchanged from lineage_threads.
+  assertEquals(v.stage, "converging");
+  assertEquals(v.stage_label, "3/5 slices merged, 2 converging");
+  assertEquals(v.process_key, "P-epic");
+  assertEquals(v.pr_keys, '["o/r#20","o/r#21"]');
+  assertEquals(v.pr_count, 5);
+  assertEquals(v.active, 1);
+});
+
+test("lineage_thread_view derives kind/issue_url/title for a feature thread from the feature_runs origin", () => {
+  const db = viewDb();
+  db.prepare("INSERT INTO feature_runs (feature_key, title, issue_url) VALUES (?, ?, ?)").run(
+    "o/r#1",
+    "Feature: add widget",
+    "https://github.com/o/r/issues/1",
+  );
+  addThread(db, {
+    root_request_key: "o/r#1",
+    kind: "feature",
+    title: "Feature: add widget",
+    issue_url: "https://github.com/o/r/issues/1",
+    stage: "merged",
+    stage_label: "Merged",
+    process_key: "P-feat",
+    pr_keys: '["o/r#10"]',
+    pr_count: 1,
+    active: 0,
+  });
+
+  const v = db
+    .prepare("SELECT * FROM lineage_thread_view WHERE root_request_key = ?")
+    .get("o/r#1") as Record<string, unknown>;
+  assertEquals(v.kind, "feature");
+  assertEquals(v.title, "Feature: add widget");
+  assertEquals(v.issue_url, "https://github.com/o/r/issues/1");
+  assertEquals(v.stage, "merged");
+  assertEquals(v.active, 0);
+});
+
+test("lineage_thread_view self-roots an origin-less PR: kind 'pr', NULL issue_url, title falls back to the poller value", () => {
+  const db = viewDb();
+  // No plans / feature_runs row for this root — it is a human/webhook PR that is its own root.
+  addThread(db, {
+    root_request_key: "o/r#30",
+    kind: "pr",
+    title: "hotfix: bump dep",
+    issue_url: null,
+    stage: "converging",
+    stage_label: "Converging (round 2)",
+    process_key: "P-pr",
+    pr_keys: '["o/r#30"]',
+    pr_count: 1,
+    active: 1,
+  });
+
+  const v = db
+    .prepare("SELECT * FROM lineage_thread_view WHERE root_request_key = ?")
+    .get("o/r#30") as Record<string, unknown>;
+  assertEquals(v.kind, "pr");
+  // issue_url is always NULL for a self-rooted PR, exactly as deriveLineage sets it.
+  assertEquals(v.issue_url, null);
+  // The PR title is the procedural representative-PR pick, so it comes through from lineage_threads.
+  assertEquals(v.title, "hotfix: bump dep");
+  assertEquals(v.stage_label, "Converging (round 2)");
+});
+
+test("lineage_thread_view reproduces the migrated columns for every thread the poller wrote", () => {
+  const db = viewDb();
+  db.prepare("INSERT INTO plans (plan_key, title, issue_url) VALUES ('o/r#2', 'Epic', 'u-epic')").run();
+  db.prepare("INSERT INTO feature_runs (feature_key, title, issue_url) VALUES ('o/r#1', 'Feat', 'u-feat')").run();
+  const rows = [
+    { root_request_key: "o/r#2", kind: "epic", title: "Epic", issue_url: "u-epic", stage: "converging", stage_label: "…", process_key: "a", pr_keys: "[]", pr_count: 2, active: 1 },
+    { root_request_key: "o/r#1", kind: "feature", title: "Feat", issue_url: "u-feat", stage: "merged", stage_label: "Merged", process_key: "b", pr_keys: "[]", pr_count: 1, active: 0 },
+    { root_request_key: "o/r#30", kind: "pr", title: "PR", issue_url: null, stage: "opened", stage_label: "Opened", process_key: null, pr_keys: "[]", pr_count: 1, active: 1 },
+  ];
+  for (const r of rows) addThread(db, r);
+
+  // The view's migrated columns must equal what pollLineage denormalised, for all three kinds.
+  for (const r of rows) {
+    const v = db
+      .prepare("SELECT kind, title, issue_url FROM lineage_thread_view WHERE root_request_key = ?")
+      .get(r.root_request_key) as Record<string, unknown>;
+    assertEquals(v.kind, r.kind);
+    assertEquals(v.title, r.title);
+    assertEquals(v.issue_url, r.issue_url);
+  }
+});

package/app/planWaveSummary.test.ts

@@ -0,0 +1,170 @@
+// Coverage for the Epic-detail wave visualization + task→representation links (issue #411).
+//
+// Two guards, mirroring the repo's split between a derived-read-model test (migration042.test.ts —
+// apply the migration to a real in-memory DB and assert its output) and a page-projection guard
+// (waitGateVisibility.test.ts — pure text assertions that the declarative page wires the surface):
+//
+//   1. The VIEW rollup over sample `plan_tasks` × `pull_requests` rows: the six-way per-wave count
+//      partition and the pre-formatted `bar` string. Because `plan_wave_summary` is a VIEW (the whole
+//      point of #411 — a single derived source of truth, enabled by nano-ide#424) this exercises the
+//      real SQLite view, not a re-implementation.
+//   2. The epic-detail page projects the wave banner, the per-wave summary section, and the
+//      task→representation links (PR url + processExplorer instance) on the wave-state grid.
+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";
+
+const MIGRATION = fileURLToPath(new URL("../db/migrations/059_plan_wave_summary.sql", import.meta.url));
+const PAGE = fileURLToPath(new URL("../pages/epic-detail.page.json", import.meta.url));
+
+/** A DB with the base `plan_tasks` / `pull_requests` shapes the views read, plus the views applied. */
+function viewDb(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  db.exec(
+    `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(readFileSync(MIGRATION, "utf8"));
+  return db;
+}
+
+function addTask(
+  db: DatabaseSync,
+  plan_key: string,
+  task_index: number,
+  status: string,
+  wave: number,
+  pr?: { pr_key: string; url: string; status: string; process_key: string },
+): void {
+  db.prepare(
+    "INSERT INTO plan_tasks (plan_key, task_index, task_id, status, pr_key, wave) VALUES (?, ?, ?, ?, ?, ?)",
+  ).run(plan_key, task_index, `t${task_index}`, status, pr?.pr_key ?? null, wave);
+  if (pr) {
+    db.prepare(
+      "INSERT INTO pull_requests (pr_key, url, status, process_key) VALUES (?, ?, ?, ?)",
+    ).run(pr.pr_key, pr.url, pr.status, pr.process_key);
+  }
+}
+
+test("plan_wave_summary partitions each wave's tasks and pre-formats the progress bar", () => {
+  const db = viewDb();
+  const plan = "o/r#1";
+  // Wave 0 — 5 tasks: 3 merged, 1 converging (in-flight), 1 blocked (no PR).
+  addTask(db, plan, 0, "opened", 0, { pr_key: "o/r#10", url: "https://gh/10", status: "merged", process_key: "P10" });
+  addTask(db, plan, 1, "opened", 0, { pr_key: "o/r#11", url: "https://gh/11", status: "merged", process_key: "P11" });
+  addTask(db, plan, 2, "opened", 0, { pr_key: "o/r#12", url: "https://gh/12", status: "merged", process_key: "P12" });
+  addTask(db, plan, 3, "opened", 0, { pr_key: "o/r#13", url: "https://gh/13", status: "converging", process_key: "P13" });
+  addTask(db, plan, 4, "blocked", 0);
+  // Wave 1 — an escalated slice (with a draft PR) and a skipped slice.
+  addTask(db, plan, 5, "escalated", 1, { pr_key: "o/r#14", url: "https://gh/14", status: "escalated", process_key: "P14" });
+  addTask(db, plan, 6, "skipped", 1);
+
+  const rows = db
+    .prepare("SELECT * FROM plan_wave_summary WHERE plan_key = ? ORDER BY wave")
+    .all(plan) as Array<Record<string, unknown>>;
+  assertEquals(rows.length, 2);
+
+  const w0 = rows[0];
+  assertEquals(w0.total, 5);
+  assertEquals(w0.merged, 3);
+  assertEquals(w0.in_flight, 1);
+  assertEquals(w0.blocked, 1);
+  assertEquals(w0.escalated, 0);
+  assertEquals(w0.skipped, 0);
+  // 3 filled + 2 empty glyphs (width = total), then the named non-zero categories.
+  assertEquals(w0.bar, "▓▓▓░░ 3/5 merged · 1 in-flight · 1 blocked");
+
+  const w1 = rows[1];
+  assertEquals(w1.total, 2);
+  assertEquals(w1.merged, 0);
+  assertEquals(w1.in_flight, 0);
+  assertEquals(w1.escalated, 1);
+  assertEquals(w1.skipped, 1);
+  assertEquals(w1.bar, "░░ 0/2 merged · 1 escalated · 1 skipped");
+});
+
+test("a merged PR wins over the task's own status, and unlevelized tasks are excluded", () => {
+  const db = viewDb();
+  const plan = "o/r#2";
+  // An escalated task whose PR nonetheless merged counts as merged, not escalated (PR wins).
+  addTask(db, plan, 0, "escalated", 0, { pr_key: "o/r#20", url: "https://gh/20", status: "merged", process_key: "P20" });
+  // A task with no wave yet (not levelized) must not appear in any wave row.
+  db.prepare(
+    "INSERT INTO plan_tasks (plan_key, task_index, task_id, status, wave) VALUES (?, ?, ?, ?, NULL)",
+  ).run(plan, 1, "t1", "pending");
+
+  const rows = db
+    .prepare("SELECT wave, total, merged, escalated FROM plan_wave_summary WHERE plan_key = ?")
+    .all(plan) as Array<Record<string, unknown>>;
+  assertEquals(rows.length, 1);
+  assertEquals(rows[0].wave, 0);
+  assertEquals(rows[0].total, 1);
+  assertEquals(rows[0].merged, 1);
+  assertEquals(rows[0].escalated, 0);
+});
+
+test("plan_wave_tasks carries each task's PR url + process_key link targets", () => {
+  const db = viewDb();
+  addTask(db, "o/r#3", 0, "opened", 0, { pr_key: "o/r#30", url: "https://gh/30", status: "converging", process_key: "P30" });
+  addTask(db, "o/r#3", 1, "blocked", 0); // no PR → null link targets
+
+  const rows = db
+    .prepare("SELECT task_id, pr_key, pr_url, process_key FROM plan_wave_tasks WHERE plan_key = ? ORDER BY task_index")
+    .all("o/r#3") as Array<Record<string, unknown>>;
+  assertEquals(rows[0].pr_url, "https://gh/30");
+  assertEquals(rows[0].process_key, "P30");
+  assertEquals(rows[1].pr_url, null);
+  assertEquals(rows[1].process_key, null);
+});
+
+test("epic-detail projects the wave banner, the per-wave summary, and task→representation links", () => {
+  const page = JSON.parse(readFileSync(PAGE, "utf8"));
+  const byId = (id: string) => page.nodes.find((n: { id: string }) => n.id === id);
+
+  // 1. The epic-level wave banner: a prose node reading wave_label + epic_phase off the derived
+  //    `plan_read_model` VIEW (epic #412 — retiring the worker-maintained plans.wave_label column;
+  //    the banner now reads the single-source-of-truth view instead of the raw `plans` table).
+  const banner = byId("wave-banner");
+  assert(banner, "epic detail must show the epic-level wave banner");
+  assertEquals(banner.props.data.table, "plan_read_model");
+  assert(
+    banner.props.data.filter.some((f: { field: string; eqParam?: boolean }) => f.field === "plan_key" && f.eqParam),
+    "the banner is scoped to this epic",
+  );
+  assert(/\{\{\s*wave_label\s*\}\}/.test(banner.props.header), "the banner surfaces the wave_label");
+  assert(/\{\{\s*epic_phase\s*\}\}/.test(banner.props.header), "the banner surfaces the epic phase");
+
+  // 2. The per-wave summary section: a grid over the derived VIEW, ordered by wave, with the bar.
+  const summary = byId("wave-summary");
+  assert(summary, "epic detail must show the per-wave progress summary");
+  assertEquals(summary.props.data.table, "plan_wave_summary");
+  assertEquals(summary.props.data.orderBy.field, "wave");
+  const summaryCols: string[] = summary.props.columns.map((c: { field: string }) => c.field);
+  for (const f of ["wave", "bar", "merged", "in_flight", "blocked", "escalated", "skipped", "total"]) {
+    assert(summaryCols.includes(f), `the summary grid shows ${f}`);
+  }
+
+  // 3. The wave-state grid links each in-flight task to its representation (PR + process instance).
+  const waveState = byId("wave-state");
+  assert(waveState, "epic detail must keep the wave-state grid");
+  assertEquals(waveState.props.data.table, "plan_wave_tasks");
+  const cols: Array<Record<string, unknown>> = waveState.props.columns;
+  const prCol = cols.find((c) => c.field === "pr_key");
+  assertEquals(prCol?.linkField, "pr_url", "the PR cell links to the GitHub PR url");
+  const statusCol = cols.find((c) => c.field === "status") as {
+    link?: { kind?: string; keyField?: string };
+  };
+  assertEquals(statusCol.link?.kind, "processExplorer", "the status cell links to the process instance");
+  assertEquals(statusCol.link?.keyField, "process_key");
+  // The existing tabs (Active / Skipped / All) and detail drawer must still be present.
+  assertEquals(waveState.props.tabs.length, 3);
+  const detailFields: string[] = waveState.props.detail.fields.map((f: { field: string }) => f.field);
+  for (const f of ["open_question", "answer", "draft_pr_key", "prompt"]) {
+    assert(detailFields.includes(f), `the detail drawer keeps ${f}`);
+  }
+});