@nanobpm/nano-workforce 0.118.2 → 0.119.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [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/planWaveSummary.test.ts

@@ -0,0 +1,168 @@
+// 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 `plans`.
+  const banner = byId("wave-banner");
+  assert(banner, "epic detail must show the epic-level wave banner");
+  assertEquals(banner.props.data.table, "plans");
+  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}`);
+  }
+});

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/package.json

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

package/pages/epic-detail.page.json

@@ -82,6 +82,51 @@
         "variant": "sub"
       }
     },
+    {
+      "type": "prose",
+      "id": "wave-banner",
+      "props": {
+        "refreshMs": 5000,
+        "measure": 80,
+        "empty": "No plan recorded for this epic yet.",
+        "data": {
+          "kind": "datasource",
+          "source": "app",
+          "table": "plans",
+          "orderBy": { "field": "updated_at", "dir": "desc" },
+          "filter": [{ "field": "plan_key", "eqParam": true }]
+        },
+        "header": "Wave {{wave_label}} · {{epic_phase}}",
+        "body": "delivery_label"
+      }
+    },
+    {
+      "type": "dataGrid",
+      "id": "wave-summary",
+      "props": {
+        "title": "Wave progress",
+        "rowKey": "wave",
+        "refreshMs": 5000,
+        "empty": "No waves yet — this epic hasn't been levelized into waves.",
+        "data": {
+          "kind": "datasource",
+          "source": "app",
+          "table": "plan_wave_summary",
+          "orderBy": { "field": "wave", "dir": "asc" },
+          "filter": [{ "field": "plan_key", "eqParam": true }]
+        },
+        "columns": [
+          { "field": "wave", "header": "Wave" },
+          { "field": "bar", "header": "Progress", "width": "40%" },
+          { "field": "merged", "header": "Merged" },
+          { "field": "in_flight", "header": "In flight" },
+          { "field": "blocked", "header": "Blocked" },
+          { "field": "escalated", "header": "Escalated" },
+          { "field": "skipped", "header": "Skipped" },
+          { "field": "total", "header": "Total" }
+        ]
+      }
+    },
     {
       "type": "dataGrid",
       "id": "epic-plan",
@@ -161,7 +206,7 @@
         "data": {
           "kind": "datasource",
           "source": "app",
-          "table": "plan_tasks",
+          "table": "plan_wave_tasks",
           "orderBy": { "field": "wave", "dir": "asc" },
           "filter": [
             { "field": "plan_key", "eqParam": true },
@@ -192,8 +237,8 @@
           { "field": "wave", "header": "Wave" },
           { "field": "task_id", "header": "Task" },
           { "field": "title", "header": "Title" },
-          { "field": "status", "header": "Status" },
-          { "field": "pr_key", "header": "PR" },
+          { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
+          { "field": "pr_key", "header": "PR", "linkField": "pr_url" },
           { "field": "summary", "header": "Summary" },
           { "field": "updated_at", "header": "Updated", "format": "datetime" }
         ],

package/scripts/pages-contract.test.ts

@@ -49,6 +49,54 @@ function parseSchema(sql: string, schema: Map<string, Set<string>>): void {
     cols.add(m[2]);
     schema.set(m[1], cols);
   }
+  // CREATE VIEW [IF NOT EXISTS] <name> AS SELECT <select-list> FROM …
+  //
+  // A page datasource can bind a VIEW as well as a base table (nano-ide#424), so a view's OUTPUT
+  // columns must join the whitelist exactly like a table's. A view has no `PRAGMA`-visible column
+  // list in this static parse, so we read them off its SELECT projection: take the select-list up
+  // to the first top-level `FROM`, split it on top-level commas, and record each item's output name
+  // (its `AS <alias>`, or the trailing identifier of a bare `t.col` / `col`). This is why the
+  // repo's views (see 059_plan_wave_summary.sql) alias every projected column and avoid select-list
+  // subqueries — it keeps this purely-textual contract guard able to see their columns.
+  const viewRe = /CREATE\s+VIEW\s+(?:IF\s+NOT\s+EXISTS\s+)?["`]?(\w+)["`]?\s+AS\s+SELECT\s+/gi;
+  while ((m = viewRe.exec(sql)) !== null) {
+    const selectList = topLevelSelectList(sql, viewRe.lastIndex);
+    if (selectList === null) continue;
+    const cols = schema.get(m[1]) ?? new Set<string>();
+    for (const frag of splitTopLevel(selectList)) {
+      const col = viewColumnName(frag);
+      if (col) cols.add(col);
+    }
+    schema.set(m[1], cols);
+  }
+}
+
+// The select-list of a view: the text between `SELECT` (its end at `start`) and the first top-level
+// `FROM` keyword (one at paren depth 0 — a `FROM` inside a function/subquery doesn't end the list).
+function topLevelSelectList(s: string, start: number): string | null {
+  let depth = 0;
+  for (let i = start; i < s.length; i++) {
+    const c = s[i];
+    if (c === "(") depth++;
+    else if (c === ")") depth--;
+    else if (depth === 0 && (c === "F" || c === "f")) {
+      // whole-word FROM with a non-identifier char (or string start) on each side
+      if (/from/i.test(s.slice(i, i + 4)) && !/\w/.test(s[i - 1] ?? " ") && !/\w/.test(s[i + 4] ?? " ")) {
+        return s.slice(start, i);
+      }
+    }
+  }
+  return null;
+}
+
+// The output name of one select-list item: its `AS <alias>` if present, else the trailing
+// identifier of a bare `table.column` / `column` reference.
+function viewColumnName(frag: string): string | null {
+  const trimmed = frag.trim();
+  const asMatch = trimmed.match(/\bAS\s+["`]?(\w+)["`]?\s*$/i);
+  if (asMatch) return asMatch[1];
+  const bare = trimmed.match(/(\w+)\s*$/);
+  return bare ? bare[1] : null;
 }
 
 // Return the text inside the parentheses whose opener is at `openIdx`, honouring nesting.