@nanobpm/nano-workforce 0.89.0 → 0.91.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.91.0](https://github.com/nanobpm/nano-workforce/compare/v0.90.0...v0.91.0) (2026-08-19)
+
+
+### Features
+
+* **tasks:** show subject title with repo/issue# as subtitle ([#308](https://github.com/nanobpm/nano-workforce/issues/308)) ([#311](https://github.com/nanobpm/nano-workforce/issues/311)) ([5771b38](https://github.com/nanobpm/nano-workforce/commit/5771b38abc33f4f88329d69c808214dfd42f5113))
+
+# [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/app/pollUserTasks.test.ts

@@ -78,6 +78,7 @@ test("pollUserTasks: projects feature / plan-review / trial-merge / PR-wait esca
         status: "escalated",
         process_key: "fp-10",
         issue_url: "https://github.com/o/r/issues/10",
+        title: "Add the framework selector",
         escalation_user_task_key: "ut-feat",
         escalation_question: "which framework?",
         blocked_user_task_key: null,
@@ -85,7 +86,7 @@ test("pollUserTasks: projects feature / plan-review / trial-merge / PR-wait esca
       },
     ],
     plans: [
-      { plan_key: "o/r#20", status: "dispatched", process_key: "pp-20", issue_url: "https://github.com/o/r/issues/20" },
+      { plan_key: "o/r#20", status: "dispatched", process_key: "pp-20", issue_url: "https://github.com/o/r/issues/20", title: "Broaden the epic scope" },
       { plan_key: "o/r#21", status: "done", process_key: "pp-21", issue_url: "https://github.com/o/r/issues/21" },
     ],
     plan_reviews: [
@@ -96,7 +97,7 @@ test("pollUserTasks: projects feature / plan-review / trial-merge / PR-wait esca
       { id: 1, plan_key: "o/r#20", wave: 0, result: "suite-failed", summary: "wave 0 red", resolved: 0 },
     ],
     pull_requests: [
-      { pr_key: "o/r#30", status: "escalated", process_key: "rp-30", url: "https://github.com/o/r/pull/30" },
+      { pr_key: "o/r#30", status: "escalated", process_key: "rp-30", url: "https://github.com/o/r/pull/30", title: "Resolve the reviews" },
     ],
     escalations: [{ id: 1, pr_key: "o/r#30", status: "open", question: "conflicting reviews" }],
   });
@@ -115,13 +116,17 @@ test("pollUserTasks: projects feature / plan-review / trial-merge / PR-wait esca
   assertEquals(Object.keys(byKey).sort(), ["ut-feat", "ut-plan", "ut-pr", "ut-trial"]);
   assertEquals(byKey["ut-feat"].kind_label, "Feature escalation");
   assertEquals(byKey["ut-feat"].question, "which framework?");
+  assertEquals(byKey["ut-feat"].subject_title, "Add the framework selector");
   assertEquals(byKey["ut-plan"].kind_label, "Plan review");
   assertEquals(byKey["ut-plan"].question, "scope too broad");
+  assertEquals(byKey["ut-plan"].subject_title, "Broaden the epic scope");
   assertEquals(byKey["ut-trial"].kind_label, "Trial merge");
   assertEquals(byKey["ut-trial"].question, "wave 0 red");
+  assertEquals(byKey["ut-trial"].subject_title, "Broaden the epic scope");
   assertEquals(byKey["ut-pr"].kind_label, "PR review");
   assertEquals(byKey["ut-pr"].subject_type, "pr");
   assertEquals(byKey["ut-pr"].question, "conflicting reviews");
+  assertEquals(byKey["ut-pr"].subject_title, "Resolve the reviews");
 });
 
 test("pollUserTasks: projects a merge-loop wait-merge-answer escalation into user_tasks as \"PR merge\"", async () => {

package/app/service.ts

@@ -1626,6 +1626,7 @@ export async function pollUserTasks(data: DataLayer, engine: EngineClient) {
               elementId: FEATURE_ESCALATION_ELEMENT,
               subjectType: "feature",
               subjectKey: run.feature_key,
+              subjectTitle: run.title,
               subjectUrl: run.issue_url,
               question: run.escalation_question,
               processKey: run.process_key,
@@ -1642,6 +1643,7 @@ export async function pollUserTasks(data: DataLayer, engine: EngineClient) {
               elementId: FEATURE_BLOCKED_ELEMENT,
               subjectType: "feature",
               subjectKey: run.feature_key,
+              subjectTitle: run.title,
               subjectUrl: run.issue_url,
               question: run.delivery_label,
               processKey: run.process_key,
@@ -1680,6 +1682,7 @@ export async function pollUserTasks(data: DataLayer, engine: EngineClient) {
                 elementId: PLAN_REVIEW_ELEMENT,
                 subjectType: "plan",
                 subjectKey: plan.plan_key,
+                subjectTitle: plan.title,
                 subjectUrl: plan.issue_url,
                 question,
                 processKey: plan.process_key,
@@ -1696,6 +1699,7 @@ export async function pollUserTasks(data: DataLayer, engine: EngineClient) {
                 elementId: TRIAL_MERGE_ELEMENT,
                 subjectType: "plan",
                 subjectKey: plan.plan_key,
+                subjectTitle: plan.title,
                 subjectUrl: plan.issue_url,
                 question,
                 processKey: plan.process_key,
@@ -1735,6 +1739,7 @@ export async function pollUserTasks(data: DataLayer, engine: EngineClient) {
               elementId: t.elementId,
               subjectType: "pr",
               subjectKey: pr.pr_key,
+              subjectTitle: pr.title,
               subjectUrl: pr.url,
               question,
               processKey: pr.process_key,

package/app/userTasks.test.ts

@@ -41,6 +41,7 @@ test("buildUserTaskRow: a plan-review task becomes a labelled row with its findi
     kind_label: "Plan review",
     subject_type: "plan",
     subject_key: "o/r#1",
+    subject_title: "o/r#1",
     subject_url: "https://github.com/o/r/issues/1",
     question: "cap reached: revise scope",
     process_key: "pk-1",
@@ -80,6 +81,28 @@ test("buildUserTaskRow: a blank userTaskKey or subjectKey yields null", () => {
   );
 });
 
+test("buildUserTaskRow: subject_title carries the subject title, trimmed, and coalesces to subject_key when absent/blank (issue #308)", () => {
+  const titled = buildUserTaskRow(
+    {
+      userTaskKey: "ut-t1",
+      elementId: PLAN_REVIEW_ELEMENT,
+      subjectType: "plan",
+      subjectKey: "o/r#1",
+      subjectTitle: "  Add the widget  ",
+    },
+    AT,
+  );
+  assertEquals(titled?.subject_title, "Add the widget");
+
+  for (const subjectTitle of [undefined, null, "   "]) {
+    const row = buildUserTaskRow(
+      { userTaskKey: "ut-t2", elementId: PLAN_REVIEW_ELEMENT, subjectType: "plan", subjectKey: "o/r#2", subjectTitle },
+      AT,
+    );
+    assertEquals(row?.subject_title, "o/r#2");
+  }
+});
+
 function row(key: string, extra: Partial<UserTaskRow> = {}): UserTaskRow {
   return {
     user_task_key: key,
@@ -87,6 +110,7 @@ function row(key: string, extra: Partial<UserTaskRow> = {}): UserTaskRow {
     kind_label: "Plan review",
     subject_type: "plan",
     subject_key: "o/r#1",
+    subject_title: "o/r#1",
     subject_url: null,
     question: null,
     process_key: null,

package/app/userTasks.ts

@@ -51,6 +51,10 @@ export interface UserTaskRow {
   kind_label: string;
   subject_type: string;
   subject_key: string;
+  /** The subject's human-readable title (`feature_runs`/`plans`/`pull_requests`.`title`), derived by
+   *  `pollUserTasks` from the subject row keyed on `subject_key` and coalesced to `subject_key` at
+   *  build time so the title-led grids never render a blank primary line (issue #308). */
+  subject_title: string;
   subject_url: string | null;
   question: string | null;
   process_key: string | null;
@@ -78,6 +82,10 @@ export interface UserTaskContext {
   elementId: string;
   subjectType: "feature" | "plan" | "pr";
   subjectKey: string;
+  /** The subject's human-readable title from its own row (`feature_runs`/`plans`/`pull_requests`.
+   *  `title`). Optional/blank tolerated — `buildUserTaskRow` coalesces it to `subjectKey` so the
+   *  projected `subject_title` is never blank. */
+  subjectTitle?: string | null;
   subjectUrl?: string | null;
   question?: string | null;
   processKey?: string | null;
@@ -93,12 +101,14 @@ export function buildUserTaskRow(ctx: UserTaskContext, at: string = now()): User
   const kindLabel = USER_TASK_KIND_LABELS[ctx.elementId];
   if (!userTaskKey || !subjectKey || !kindLabel) return null;
   const question = typeof ctx.question === "string" && ctx.question.trim() ? ctx.question.trim() : null;
+  const subjectTitle = typeof ctx.subjectTitle === "string" && ctx.subjectTitle.trim() ? ctx.subjectTitle.trim() : subjectKey;
   return {
     user_task_key: userTaskKey,
     element_id: ctx.elementId,
     kind_label: kindLabel,
     subject_type: ctx.subjectType,
     subject_key: subjectKey,
+    subject_title: subjectTitle,
     subject_url: ctx.subjectUrl ?? null,
     question,
     process_key: ctx.processKey ?? null,
@@ -124,6 +134,7 @@ function sameRow(a: UserTaskRow, b: UserTaskRow): boolean {
     a.kind_label === b.kind_label &&
     a.subject_type === b.subject_type &&
     a.subject_key === b.subject_key &&
+    a.subject_title === b.subject_title &&
     a.subject_url === b.subject_url &&
     a.question === b.question &&
     a.process_key === b.process_key

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/db/migrations/043_user_tasks_subject_title.sql

@@ -0,0 +1,24 @@
+-- Surface the subject's human-readable title as the primary identity on the Tasks
+-- grids (issue #308), mirroring the Features list. Every `user_tasks` row was keyed
+-- only by `subject_key` (`owner/repo#N`) — meaningful while you remember the number,
+-- opaque hours later. The Features list already leads with `{{title}}` and shows the
+-- key as a subtitle; the Tasks grids could only show the bare key.
+--
+-- The title is DERIVED (no new fetch): each escalation's subject already persists a
+-- title in a surviving table keyed by `subject_key` — `feature_runs.title`,
+-- `plans.title`, `pull_requests.title`. `pollUserTasks` reads it from the subject row
+-- already in scope this pass and coalesces to `subject_key` at write time so the
+-- column is ALWAYS non-blank — the grid's `{{subject_title}}` template then needs no
+-- fallback and a missing subject title still shows a usable identity.
+--
+-- Forward-only, additive (expand): nullable with no default, then backfilled in the
+-- same migration so the column is non-blank immediately — pre-#308 rows would otherwise
+-- grandfather in as NULL and the grid's `{{subject_title}}` primary line would render a
+-- blank/"null" identity for the window between deploy and the first `pollUserTasks` pass.
+-- The backfill coalesces existing rows to `subject_key` (matching the write-time coalesce
+-- in `pollUserTasks`, which re-derives the real title in place on the next poll — a
+-- completed task's row is deleted, not migrated). Idempotent: re-running is a no-op once
+-- set. Numbered after the current highest prefix on origin/main (042); the runner wraps
+-- each file in its own transaction, so this file must NOT contain BEGIN/COMMIT.
+ALTER TABLE user_tasks ADD COLUMN subject_title TEXT;
+UPDATE user_tasks SET subject_title = subject_key WHERE subject_title IS NULL OR trim(subject_title) = '';

package/package.json

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

package/pages/tasks.page.json

@@ -84,8 +84,12 @@
         },
         "columns": [
           {
-            "field": "subject_key",
-            "header": "Feature"
+            "field": "subject_title",
+            "template": "{{subject_title}}",
+            "header": "Item",
+            "subtitleField": "subject_key",
+            "truncate": true,
+            "linkField": "subject_url"
           },
           {
             "field": "subject_url",
@@ -141,8 +145,12 @@
         },
         "columns": [
           {
-            "field": "subject_key",
-            "header": "Epic"
+            "field": "subject_title",
+            "template": "{{subject_title}}",
+            "header": "Item",
+            "subtitleField": "subject_key",
+            "truncate": true,
+            "linkField": "subject_url"
           },
           {
             "field": "question",
@@ -202,8 +210,12 @@
         },
         "columns": [
           {
-            "field": "subject_key",
-            "header": "Epic"
+            "field": "subject_title",
+            "template": "{{subject_title}}",
+            "header": "Item",
+            "subtitleField": "subject_key",
+            "truncate": true,
+            "linkField": "subject_url"
           },
           {
             "field": "question",
@@ -264,8 +276,12 @@
         },
         "columns": [
           {
-            "field": "subject_key",
-            "header": "PR"
+            "field": "subject_title",
+            "template": "{{subject_title}}",
+            "header": "Item",
+            "subtitleField": "subject_key",
+            "truncate": true,
+            "linkField": "subject_url"
           },
           {
             "field": "kind_label",
@@ -343,8 +359,12 @@
         },
         "columns": [
           {
-            "field": "subject_key",
-            "header": "Feature"
+            "field": "subject_title",
+            "template": "{{subject_title}}",
+            "header": "Item",
+            "subtitleField": "subject_key",
+            "truncate": true,
+            "linkField": "subject_url"
           },
           {
             "field": "question",