@nanobpm/nano-workforce 0.89.0 → 0.90.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.90.0](https://github.com/nanobpm/nano-workforce/compare/v0.89.0...v0.90.0) (2026-08-19)
+
+
+### Features
+
+* **convergence:** surface epic / cross-slice lineage on the PR-row detail ([#307](https://github.com/nanobpm/nano-workforce/issues/307)) ([7010b88](https://github.com/nanobpm/nano-workforce/commit/7010b88889529aec173c552bab2a1e7b881ba9da)), closes [nanobpm/nano-workforce#304](https://github.com/nanobpm/nano-workforce/issues/304)
+
 # [0.89.0](https://github.com/nanobpm/nano-workforce/compare/v0.88.1...v0.89.0) (2026-08-19)
 
 

package/app/lineage.test.ts

@@ -75,7 +75,7 @@ test("feature: an escalated run surfaces the escalation stage", () => {
 
 test("epic: rolls up N slice PRs and stays active while any is in flight", () => {
   const t = deriveLineage(
-    { kind: "epic", key: "o/r#9", title: "Big epic", issueUrl: "u", status: "done", processKey: "e1" },
+    { kind: "epic", key: "o/r#9", title: "Big epic", issueUrl: "u", status: "done", processKey: "e1", epicPhase: "Implementing (wave 2/3)" },
     [
       pr({ prKey: "o/r#10", status: "merged" }),
       pr({ prKey: "o/r#11", status: "converging", processKey: "c11" }),
@@ -85,6 +85,7 @@ test("epic: rolls up N slice PRs and stays active while any is in flight", () =>
   assertEquals(t.kind, "epic");
   assertEquals(t.stage, "converging");
   assertEquals(t.stageLabel, "1/3 slices merged, 1 converging");
+  assertEquals(t.epicPhaseLabel, "Implementing (wave 2/3)", "an epic thread carries its stamped epic_phase down to member PRs");
   assertEquals(t.processKey, "c11");
   assertEquals(t.prCount, 3);
   assert(t.active);
@@ -92,17 +93,18 @@ test("epic: rolls up N slice PRs and stays active while any is in flight", () =>
 
 test("epic: all slices merged settles as merged", () => {
   const t = deriveLineage(
-    { kind: "epic", key: "o/r#9", title: "Big epic", issueUrl: "u", status: "done", processKey: "e1" },
+    { kind: "epic", key: "o/r#9", title: "Big epic", issueUrl: "u", status: "done", processKey: "e1", epicPhase: null },
     [pr({ prKey: "o/r#10", status: "merged" }), pr({ prKey: "o/r#11", status: "merged" })],
   );
   assertEquals(t.stage, "merged");
   assertEquals(t.stageLabel, "2/2 slices merged");
+  assertEquals(t.epicPhaseLabel, "2/2 slices merged", "a grandfathered epic (no epic_phase) falls back to its delivery-rollup stage label");
   assert(!t.active);
 });
 
 test("epic: mixed terminal (none in flight, not all merged) is resolved, not landed", () => {
   const t = deriveLineage(
-    { kind: "epic", key: "o/r#9", title: "E", issueUrl: "u", status: "done", processKey: "e1" },
+    { kind: "epic", key: "o/r#9", title: "E", issueUrl: "u", status: "done", processKey: "e1", epicPhase: "Finalizing" },
     [pr({ prKey: "o/r#10", status: "merged" }), pr({ prKey: "o/r#11", status: "abandoned" })],
   );
   assertEquals(t.stage, "resolved");
@@ -111,13 +113,23 @@ test("epic: mixed terminal (none in flight, not all merged) is resolved, not lan
 
 test("epic: planning with no PRs yet", () => {
   const t = deriveLineage(
-    { kind: "epic", key: "o/r#9", title: "E", issueUrl: "u", status: "planning", processKey: "e1" },
+    { kind: "epic", key: "o/r#9", title: "E", issueUrl: "u", status: "planning", processKey: "e1", epicPhase: "Planning" },
     [],
   );
   assertEquals(t.stage, "planning");
   assert(t.active);
 });
 
+test("feature/self-rooted threads carry no epic phase label", () => {
+  const feat = deriveLineage(
+    { kind: "feature", key: "o/r#1", title: "X", issueUrl: "u", status: "converging", processKey: "f1" },
+    [pr({ prKey: "o/r#2", status: "converging" })],
+  );
+  assertEquals(feat.epicPhaseLabel, null, "a feature PR is not an epic slice");
+  const self = deriveLineage({ kind: "pr", key: "o/r#5" }, [pr({ prKey: "o/r#5", status: "converging" })]);
+  assertEquals(self.epicPhaseLabel, null, "a self-rooted PR is not an epic slice");
+});
+
 // ── self-rooted (human/webhook) PR ───────────────────────────────────────────────────────────
 
 test("pr: a human/webhook PR with no origin is its own root", () => {
@@ -174,7 +186,7 @@ test("pollLineage: projects feature, epic, and self-rooted threads onto lineage_
     { feature_key: "o/r#1", title: "Feature", issue_url: "u1", status: "converging", process_key: "f1", pr_key: "o/r#100" },
   ];
   stores.plans = [
-    { plan_key: "o/r#2", title: "Epic", issue_url: "u2", status: "done", process_key: "e1" },
+    { plan_key: "o/r#2", title: "Epic", issue_url: "u2", status: "done", process_key: "e1", epic_phase: "Implementing (wave 1/2)" },
   ];
   stores.plan_tasks = [
     { id: 1, plan_key: "o/r#2", pr_key: "o/r#200" },
@@ -212,6 +224,14 @@ test("pollLineage: projects feature, epic, and self-rooted threads onto lineage_
   assertEquals(human?.stage, "merged");
   assertEquals(human?.active, 0);
 
+  // Epic-phase projection (#304): each epic slice PR gets its parent epic's phase label; the feature
+  // and self-rooted PRs (not epic slices) are left NULL, so their PR-row detail shows no epic panel.
+  const prById = (k: string) => stores.pull_requests.find((r: any) => r.pr_key === k);
+  assertEquals(prById("o/r#200").epic_phase_label, "Implementing (wave 1/2)", "epic slice S1 carries the epic phase");
+  assertEquals(prById("o/r#201").epic_phase_label, "Implementing (wave 1/2)", "epic slice S2 carries the epic phase");
+  assertEquals(prById("o/r#100").epic_phase_label ?? null, null, "a feature PR is not an epic slice");
+  assertEquals(prById("o/r#300").epic_phase_label ?? null, null, "a self-rooted PR is not an epic slice");
+
   // Idempotent: a second pass with no state change writes nothing new (same row count, same ts).
   const before = stores.lineage_threads.map((r: LineageThreadRow) => r.updated_at);
   await pollLineage(data);

package/app/lineage.ts

@@ -56,6 +56,10 @@ export type LineageOrigin =
       issueUrl: string | null;
       status: string;
       processKey: string | null;
+      // The epic's derived domain phase (`plans.epic_phase`, 038_plan_epic_phase.sql) — e.g.
+      // "Implementing (wave 3/5)". NULL for pre-#261 epics that never stamped a phase; the thread
+      // then falls back to its delivery-rollup `stageLabel` for the projected `epicPhaseLabel`.
+      epicPhase: string | null;
     }
   | {
       // A human/webhook PR with no originating request: its own root.
@@ -73,6 +77,12 @@ export interface LineageThread {
   stage: LineageStage;
   /** Human narrative rollup for the timeline (e.g. "Converging (round 2)", "3/5 slices merged, …"). */
   stageLabel: string;
+  /** The epic-phase/stage label projected onto each member PR's `pull_requests.epic_phase_label`, so
+   *  the Convergence PR-row detail can show an epic slice its parent epic's phase (issue #304). For an
+   *  epic thread it is the epic's `epic_phase` (e.g. "Implementing (wave 3/5)"), falling back to the
+   *  delivery-rollup `stageLabel` when the epic never stamped a phase. NULL for feature/self-rooted
+   *  threads — their member PRs are not epic slices, so the epic panel stays empty for them. */
+  epicPhaseLabel: string | null;
   /** The active-frontier process instance (for the processExplorer link), best-effort. */
   processKey: string | null;
   prKeys: string[];
@@ -238,6 +248,12 @@ export function deriveLineage(origin: LineageOrigin, prsIn: readonly LineagePr[]
   }
 
   const active = !TERMINAL_STAGES.includes(stage);
+  // Epic slices carry their parent epic's phase down to the PR-row detail (issue #304): prefer the
+  // epic's own stamped `epic_phase`, falling back to the delivery-rollup `stageLabel` for a
+  // grandfathered epic that never stamped one. Feature/self-rooted threads are not epics, so their
+  // member PRs get no epic label.
+  const epicPhaseLabel =
+    origin.kind === "epic" ? (origin.epicPhase ?? stageLabel) : null;
   return {
     rootRequestKey: origin.key,
     kind: origin.kind,
@@ -245,6 +261,7 @@ export function deriveLineage(origin: LineageOrigin, prsIn: readonly LineagePr[]
     issueUrl: origin.kind === "pr" ? null : origin.issueUrl,
     stage,
     stageLabel,
+    epicPhaseLabel,
     processKey,
     prKeys,
     prCount: prKeys.length,
@@ -287,6 +304,9 @@ interface PrRow {
   process_key: string | null;
   outcome: string | null;
   root_request_key: string | null;
+  // Epic-phase projection this module maintains (issue #304, migration 043): the parent epic's phase
+  // label for an epic slice PR, NULL otherwise. Read here only to keep the write idempotent.
+  epic_phase_label: string | null;
 }
 
 const prRows = (data: DataLayer) => data.table<PrRow>("pull_requests", "pr_key");
@@ -324,7 +344,9 @@ function toLineagePr(row: PrRow): LineagePr {
 
 /** Assemble the origin + PR set for every root from the live gateway rows, then derive each thread.
  * Reused by both `getLineage` (single root, on demand) and `pollLineage` (all roots, projected). */
-async function collectThreads(data: DataLayer): Promise<Map<string, LineageThread>> {
+async function collectThreads(
+  data: DataLayer,
+): Promise<{ threads: Map<string, LineageThread>; allPrs: PrRow[] }> {
   const allPrs = await prRows(data).all();
   const prByKey = new Map<string, PrRow>();
   for (const pr of allPrs) prByKey.set(pr.pr_key, pr);
@@ -388,7 +410,7 @@ async function collectThreads(data: DataLayer): Promise<Map<string, LineageThrea
     threads.set(rootKey, deriveLineage({ kind: "pr", key: rootKey }, prs.map(toLineagePr)));
   }
 
-  return threads;
+  return { threads, allPrs };
 }
 
 /** Union the PRs a feature root owns: those threaded to it + its own denormalised `pr_key`. */
@@ -446,6 +468,7 @@ function epicOrigin(plan: Plan): LineageOrigin {
     issueUrl: plan.issue_url,
     status: plan.status,
     processKey: plan.process_key,
+    epicPhase: plan.epic_phase,
   };
 }
 
@@ -455,7 +478,7 @@ export async function getLineage(
   data: DataLayer,
   rootRequestKey: string,
 ): Promise<LineageThread | null> {
-  const threads = await collectThreads(data);
+  const { threads } = await collectThreads(data);
   return threads.get(rootRequestKey) ?? null;
 }
 
@@ -463,7 +486,7 @@ export async function getLineage(
  * deterministic order (the projection has no per-thread timestamp to sort on, and equal-`active`
  * ties would otherwise be nondeterministic across passes). */
 export async function listLineage(data: DataLayer): Promise<LineageThread[]> {
-  const threads = await collectThreads(data);
+  const { threads } = await collectThreads(data);
   return [...threads.values()].sort(
     (a, b) => Number(b.active) - Number(a.active) || a.rootRequestKey.localeCompare(b.rootRequestKey),
   );
@@ -474,8 +497,9 @@ export async function listLineage(data: DataLayer): Promise<LineageThread[]> {
  * when the projection actually changes. Best-effort; per-root failures are isolated. */
 export async function pollLineage(data: DataLayer): Promise<void> {
   let threads: Map<string, LineageThread>;
+  let allPrs: PrRow[];
   try {
-    threads = await collectThreads(data);
+    ({ threads, allPrs } = await collectThreads(data));
   } catch (err) {
     console.error(`[poller] lineage collect: ${err}`);
     return;
@@ -534,4 +558,35 @@ export async function pollLineage(data: DataLayer): Promise<void> {
       console.error(`[poller] lineage ${thread.rootRequestKey}: ${err}`);
     }
   }
+  await projectEpicPhaseLabels(data, threads, allPrs);
+}
+
+/** Denormalise each epic thread's phase label down onto its member PRs' `pull_requests.epic_phase_label`
+ * (issue #304), so the Convergence PR-row detail can show an escalated slice its parent epic's phase
+ * without a cross-join to `plans` / `lineage_threads`. Every PR belongs to exactly one thread, so a
+ * PR whose thread is a feature/self-root is cleared to NULL — no stale epic label survives if a PR is
+ * re-rooted. Idempotent: writes only the rows whose label actually changed. Mirrors the write-time
+ * projection convention (`delivery_label`, `epic_phase`). Best-effort; failures are isolated. */
+async function projectEpicPhaseLabels(
+  data: DataLayer,
+  threads: Map<string, LineageThread>,
+  allPrs: PrRow[],
+): Promise<void> {
+  // Desired label per member PR: an epic thread stamps its `epicPhaseLabel`, every other thread NULL.
+  const desired = new Map<string, string | null>();
+  for (const thread of threads.values()) {
+    for (const key of thread.prKeys) desired.set(key, thread.epicPhaseLabel);
+  }
+  // Reuse the PR rows `collectThreads` already read this pass rather than re-scanning the whole
+  // `pull_requests` table — the projection only writes the rows whose label actually changed.
+  const table = prRows(data);
+  for (const pr of allPrs) {
+    const want = desired.get(pr.pr_key) ?? null;
+    if ((pr.epic_phase_label ?? null) === want) continue; // steady state — no write
+    try {
+      await table.update(pr.pr_key, { epic_phase_label: want });
+    } catch (err) {
+      console.error(`[poller] lineage epic-phase ${pr.pr_key}: ${err}`);
+    }
+  }
 }

package/app/migration043.test.ts

@@ -0,0 +1,62 @@
+// Regression guard for migration 043's epic_phase_label backfill (issue #304). The Convergence
+// PR-row detail surfaces an epic slice's parent-epic phase via `pull_requests.epic_phase_label`. The
+// column is maintained going forward by `pollLineage` (`projectEpicPhaseLabels`), but pre-existing
+// rows must be backfilled at deploy time so the epic panel is populated before the first poll pass:
+// an epic slice PR (its `root_request_key` is an epic `plans.plan_key`) takes that epic's
+// `plans.epic_phase`; a feature/self-rooted PR (no matching plan) stays NULL — no empty epic panel.
+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";
+
+function migratedDb(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  // Minimal pre-043 shape: pull_requests WITH root_request_key (037) but WITHOUT epic_phase_label
+  // (043 ADD COLUMNs it), plus the plans table the backfill joins on for the epic phase.
+  db.exec(`
+    CREATE TABLE pull_requests (pr_key TEXT PRIMARY KEY, repo TEXT, number INTEGER, url TEXT,
+      status TEXT, root_request_key TEXT, created_at TEXT, updated_at TEXT);
+    CREATE TABLE plans (plan_key TEXT PRIMARY KEY, epic_phase TEXT);
+  `);
+  const ins = (k: string, root: string) =>
+    db
+      .prepare(
+        `INSERT INTO pull_requests (pr_key, repo, number, url, status, root_request_key, created_at, updated_at)
+         VALUES (?, 'o/r', 1, 'u', 'converging', ?, 't', 't')`,
+      )
+      .run(k, root);
+  ins("o/r#20", "o/r#2"); // epic slice of a phased epic
+  ins("o/r#21", "o/r#3"); // epic slice of a grandfathered epic (epic_phase NULL)
+  ins("o/r#30", "o/r#30"); // self-rooted (human/webhook) PR — root is its own key, no plan
+  ins("o/r#40", "o/r#1"); // feature-rooted PR — root is a feature key, no matching plan
+  db.prepare("INSERT INTO plans (plan_key, epic_phase) VALUES ('o/r#2', 'Implementing (wave 3/5)')").run();
+  db.prepare("INSERT INTO plans (plan_key, epic_phase) VALUES ('o/r#3', NULL)").run();
+
+  const sql = readFileSync(
+    fileURLToPath(new URL("../db/migrations/043_pr_epic_phase.sql", import.meta.url)),
+    "utf8",
+  );
+  db.exec(sql);
+  return db;
+}
+
+test("migration 043 backfills epic slice PRs with their epic's phase and leaves non-epic PRs NULL", () => {
+  const db = migratedDb();
+  const labelOf = (k: string) =>
+    (
+      db.prepare("SELECT epic_phase_label AS l FROM pull_requests WHERE pr_key = ?").get(k) as {
+        l: string | null;
+      }
+    ).l;
+
+  // An epic slice roots on its epic's plan_key, so it inherits that epic's stamped phase.
+  assertEquals(labelOf("o/r#20"), "Implementing (wave 3/5)");
+  // A slice of a grandfathered epic (epic_phase NULL) stays NULL — the poller reconciles the
+  // delivery-rollup fallback on its next pass; the migration only seeds the stamped phase.
+  assertEquals(labelOf("o/r#21"), null);
+  // A self-rooted PR has no matching plan → no epic panel.
+  assertEquals(labelOf("o/r#30"), null);
+  // A feature-rooted PR has no matching plan → no epic panel.
+  assertEquals(labelOf("o/r#40"), null);
+});

package/db/migrations/043_pr_epic_phase.sql

@@ -0,0 +1,36 @@
+-- 043_pr_epic_phase.sql — issue #304: surface epic / cross-slice lineage on the Convergence
+-- PR-row detail. An operator triaging a PR (especially an escalation) needs to see, at the point of
+-- decision, that the PR is a slice of an epic and which phase that epic is in — without navigating to
+-- the Lineage page. The sibling-slice roster is already expressible in page JSON today (a `plan_tasks`
+-- child grid joined `pull_requests.root_request_key → plan_tasks.plan_key`), but the epic's PHASE
+-- lives on `plans.epic_phase` (038) / `lineage_threads.stage_label` (037), NOT on `pull_requests`, so
+-- a `detail.field` cannot read it directly.
+--
+-- This migration adds the one missing projection column the read model needs:
+--
+--   • `pull_requests.epic_phase_label` — the parent epic's phase label for an epic slice PR (e.g.
+--     "Implementing (wave 3/5)"), NULL for a feature/self-rooted PR that is not an epic slice.
+--     Written idempotently on the SAME lineage poll path that maintains the lineage projection
+--     (`app/lineage.ts` `pollLineage` → `projectEpicPhaseLabels`), mirroring the existing write-time
+--     projection convention (`plans.epic_phase`, `plans.delivery_label`, `feature_runs.delivery_label`).
+--     The poller prefers the epic's stamped `epic_phase`, falling back to the thread's delivery-rollup
+--     stage label for a grandfathered epic that never stamped one, and clears the column to NULL if a
+--     PR is ever re-rooted off an epic — so no stale epic label can survive.
+--
+-- Forward-only, additive (expand): a nullable TEXT column with no default, display-only, that never
+-- gates control flow. Numbered after the current highest prefix (042). The runner wraps each file in
+-- its own transaction, so this file must NOT contain BEGIN/COMMIT.
+ALTER TABLE pull_requests ADD COLUMN epic_phase_label TEXT;
+
+-- Backfill pre-existing rows so the epic panel is populated at deploy time, not only after the first
+-- poll pass writes it. An epic slice PR is one whose `root_request_key` is an epic `plans.plan_key`
+-- (submitPr threads the epic origin key onto every slice PR, and migration 037 backfilled legacy
+-- rows the same way); stamp it with that epic's `plans.epic_phase`. A feature/self-rooted PR has no
+-- matching plan, so it stays NULL — no empty epic panel for a non-epic PR. Idempotent, and the poller
+-- reconciles the delivery-rollup fallback (for a plan whose `epic_phase` is NULL) on its next pass.
+UPDATE pull_requests SET epic_phase_label = (
+    SELECT p.epic_phase FROM plans p WHERE p.plan_key = pull_requests.root_request_key
+  )
+  WHERE EXISTS (
+    SELECT 1 FROM plans p WHERE p.plan_key = pull_requests.root_request_key
+  );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.89.0",
+  "version": "0.90.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/home.page.json

@@ -257,9 +257,62 @@
             {
               "field": "outcome",
               "label": "Outcome"
+            },
+            {
+              "field": "epic_phase_label",
+              "label": "Epic phase"
             }
           ],
           "children": [
+            {
+              "title": "Epic",
+              "source": "app",
+              "table": "plans",
+              "parentField": "root_request_key",
+              "childField": "plan_key",
+              "columns": [
+                {
+                  "field": "title",
+                  "header": "Epic root",
+                  "truncate": true,
+                  "linkField": "issue_url"
+                },
+                {
+                  "field": "epic_phase",
+                  "header": "Phase"
+                }
+              ]
+            },
+            {
+              "title": "Epic slices",
+              "source": "app",
+              "table": "plan_tasks",
+              "parentField": "root_request_key",
+              "childField": "plan_key",
+              "orderBy": {
+                "field": "task_index",
+                "dir": "asc"
+              },
+              "columns": [
+                {
+                  "field": "task_id",
+                  "header": "Slice"
+                },
+                {
+                  "field": "title",
+                  "header": "Title",
+                  "truncate": true
+                },
+                {
+                  "field": "status",
+                  "header": "Status"
+                },
+                {
+                  "field": "pr_key",
+                  "header": "PR"
+                }
+              ]
+            },
             {
               "title": "Rounds",
               "source": "app",