@nanobpm/nano-workforce 0.88.1 → 0.90.0

package/app/promotion.test.ts

@@ -0,0 +1,56 @@
+// Pure derivation tests for epic promotion (issue #299). `app/promotion.ts` is the I/O-free core of
+// the "promote a landed epic's integration branch to the default branch" automation: the promotable
+// predicate, the epic-card state derivation, and the promotion PR title/body rendering. The poller
+// (`pollPromotion`) is exercised separately in `app/promotionPoll.test.ts`.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { derivePromotionState, isEpicIntegrationBranch, isPromotable, promotionPrBody, promotionPrTitle } from "./promotion.ts";
+
+test("isPromotable: landed on an epic/* base is promotable", () => {
+  assert(isPromotable({ delivery: "landed", base_branch: "epic/test-dsl" }));
+});
+
+test("isPromotable: a main-based epic has nothing to promote", () => {
+  assert(!isPromotable({ delivery: "landed", base_branch: "main" }));
+  assert(!isPromotable({ delivery: "landed", base_branch: null }));
+});
+
+test("isPromotable: a still-converging epic is never promoted, even on an epic/* base", () => {
+  assert(!isPromotable({ delivery: "converging", base_branch: "epic/x" }));
+  assert(!isPromotable({ delivery: null, base_branch: "epic/x" }));
+});
+
+test("isEpicIntegrationBranch: only epic/* branches match", () => {
+  assert(isEpicIntegrationBranch("epic/foo"));
+  assert(!isEpicIntegrationBranch("main"));
+  assert(!isEpicIntegrationBranch("feat/epic-ish"));
+  assert(!isEpicIntegrationBranch(null));
+});
+
+test("derivePromotionState: ready → open → promoted progression", () => {
+  assertEquals(derivePromotionState(false, false), "ready");
+  assertEquals(derivePromotionState(true, false), "open");
+  assertEquals(derivePromotionState(true, true), "promoted");
+});
+
+test("promotionPrTitle: names branch, target, and epic identity", () => {
+  assertEquals(
+    promotionPrTitle("epic/test-dsl", "main", "Assertion DSL"),
+    "Promote epic/test-dsl → main: Assertion DSL",
+  );
+});
+
+test("promotionPrBody: closes the epic issue and lists the merged slices", () => {
+  const body = promotionPrBody("epic/x", "main", "o/r#295", ["o/r#299", "o/r#304"]);
+  assert(body.includes("epic/x"));
+  assert(body.includes("main"));
+  assert(body.includes("Closes o/r#295"));
+  assert(body.includes("- o/r#299"));
+  assert(body.includes("- o/r#304"));
+});
+
+test("promotionPrBody: omits the slice list when there are none", () => {
+  const body = promotionPrBody("epic/x", "main", "o/r#295", []);
+  assert(body.includes("Closes o/r#295"));
+  assert(!body.includes("Merged slices:"));
+});

package/app/promotion.ts

@@ -0,0 +1,84 @@
+// Epic promotion derivation (issue #299): the pure, I/O-free core of the "promote a landed epic's
+// integration branch to the default branch" automation. Extracted from `service.ts` (mirroring how
+// `deriveDelivery` lives in `delivery.ts`) so the promotion predicate + state derivation + PR
+// title/body rendering are unit-testable without a data layer or GitHub transport.
+//
+// The gap this closes: when an epic targets a custom `epic/*` integration branch, its slices PR
+// *into* that branch. Once every slice merges (`plans.delivery = landed`, projected by
+// `pollDelivery`), the epic is delivered ON the integration branch — but nothing opens the final
+// `epic/* → <default>` promotion PR. `pollPromotion` (app/service.ts) uses these helpers to open
+// exactly one such PR per landed epic and drive it through the same convergence + merge protocol.
+
+/** The epic-card promotion progression for a landed epic (issue #299 point 3), denormalised onto
+ * `plans.promotion_state`:
+ *   • `ready`    — landed on an `epic/*` base; the promotion PR has not been opened yet.
+ *   • `open`     — the promotion PR is open and converging toward merge.
+ *   • `promoted` — the promotion PR merged; the epic is delivered on the default branch. */
+export type PromotionState = "ready" | "open" | "promoted";
+
+/** The subset of a plan the promotion derivation reads. */
+export interface PromotablePlan {
+  /** The derived delivery signal (`deriveDelivery`): only a `landed` epic is ever promotable. */
+  delivery: string | null;
+  /** The epic's target integration branch, e.g. `epic/test-dsl`. NULL / non-`epic/*` ⇒ nothing to
+   * promote (a `main`-based epic's slices already landed on the default branch). */
+  base_branch: string | null;
+}
+
+/** Whether `branch` is an auto-created `epic/*` integration branch (mirrors github.ts's
+ * `isEpicBranch` — kept local so this module stays pure/dependency-free). */
+export function isEpicIntegrationBranch(branch: string | null): branch is string {
+  return !!branch && branch.startsWith("epic/");
+}
+
+/** Whether an epic is eligible for auto-promotion: its fan-out has LANDED (every slice PR merged —
+ * the `deriveDelivery` `landed` predicate, which already encodes `prsInFlight == 0 && prsMerged ==
+ * prsOpened && prsOpened > 0`, so a still-converging epic is never promoted) AND it targets a custom
+ * `epic/*` integration branch. A `main`-based epic (slices went straight to the default branch) has
+ * nothing to promote. */
+export function isPromotable(plan: PromotablePlan): boolean {
+  return plan.delivery === "landed" && isEpicIntegrationBranch(plan.base_branch);
+}
+
+/** Derive the promotion-state projection for a promotable epic from whether its promotion PR exists
+ * yet and whether that PR has merged. Pure; the poller writes the result onto `plans.promotion_state`.
+ *   • no PR yet            → `ready`
+ *   • PR exists, unmerged  → `open`
+ *   • PR merged            → `promoted` */
+export function derivePromotionState(hasPr: boolean, prMerged: boolean): PromotionState {
+  if (prMerged) return "promoted";
+  if (hasPr) return "open";
+  return "ready";
+}
+
+/** The title for an epic's promotion PR: names the integration branch, the target it promotes into,
+ * and the epic's human identity. */
+export function promotionPrTitle(base: string, target: string, epicTitle: string): string {
+  return `Promote ${base} → ${target}: ${epicTitle}`;
+}
+
+/** Render the promotion PR body: a short explanation, the parent epic issue (as `Closes` so the
+ * epic closes when the promotion lands — the epic is only truly delivered once its integration
+ * branch reaches the default branch), and the list of merged slice PRs it carries. `slicePrKeys`
+ * are `owner/repo#N` keys; a `Depends-on:` is deliberately NOT emitted — the slices have already
+ * merged into the integration branch, so the promotion PR has no live dependency. */
+export function promotionPrBody(
+  base: string,
+  target: string,
+  issueRef: string,
+  slicePrKeys: readonly string[],
+): string {
+  const lines = [
+    `Automated promotion of the landed epic integration branch \`${base}\` into \`${target}\`.`,
+    "",
+    `Every slice of this epic has merged into \`${base}\`; this PR delivers the whole epic to ` +
+      `\`${target}\`. It converges and merges through the standard review + merge protocol.`,
+    "",
+    `Closes ${issueRef}`,
+  ];
+  if (slicePrKeys.length > 0) {
+    lines.push("", "Merged slices:");
+    for (const key of slicePrKeys) lines.push(`- ${key}`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/app/promotionPoll.test.ts

@@ -0,0 +1,255 @@
+// Integration tests for the epic promotion poller pass (issue #299). `pollPromotion` is the missing
+// counterpart to `ensureBaseBranch`: once an epic has LANDED on its custom `epic/*` integration
+// branch (every slice PR merged → `plans.delivery = landed`), it opens exactly ONE `epic/* →
+// <default>` promotion PR and enrolls it into the convergence + merge loop. These tests exercise the
+// issue's red/green plan against an in-memory data layer + a stubbed GitHub (token) transport + a
+// recording engine: open exactly one PR, never a duplicate on re-run, never for a converging epic,
+// and never for a `main`-based epic.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { DataLayer, EngineClient } from "@nanobpm/urban";
+import { resetDefaultBranchCache } from "./github.ts";
+import { pollPromotion } from "./service.ts";
+
+// In-memory record gateway (all/get/find/insert/update/delete), mirroring app/delivery.test.ts but
+// with `delete` (submitPr's `registerDependencies` clears the PR's dep set on submit).
+function memData(): { data: DataLayer; stores: Record<string, any[]> } {
+  const stores: Record<string, any[]> = {};
+  function tbl(name: string, pk = "id") {
+    const rows = (stores[name] ??= [] as any[]);
+    const match = (r: any, where: any) => Object.entries(where).every(([k, v]) => r[k] === v);
+    return {
+      async all() {
+        return rows.slice();
+      },
+      async get(id: any) {
+        return rows.find((r) => r[pk] === id);
+      },
+      async find(where: any = {}) {
+        return rows.filter((r) => match(r, where));
+      },
+      async insert(row: any) {
+        rows.push({ ...row });
+        return row[pk];
+      },
+      async update(id: any, patch: any) {
+        const r = rows.find((row) => row[pk] === id);
+        if (r) Object.assign(r, patch);
+      },
+      async delete(id: any) {
+        for (let i = rows.length - 1; i >= 0; i--) if (rows[i][pk] === id) rows.splice(i, 1);
+      },
+    };
+  }
+  const data = { table: (n: string, pk?: string) => tbl(n, pk) } as any as DataLayer;
+  return { data, stores };
+}
+
+// A recording engine stub: every `submitPr` starts a convergence instance via `createInstance`.
+function recordingEngine(): { engine: EngineClient; instances: any[] } {
+  const instances: any[] = [];
+  const engine = {
+    async createInstance(req: any) {
+      instances.push(req);
+      return { processInstanceKey: `pi-${instances.length}` };
+    },
+  } as any as EngineClient;
+  return { engine, instances };
+}
+
+// A fake GitHub repo model served over the token transport. Tracks the default branch and the PRs
+// keyed by head branch; records every create so a test can assert exactly-once.
+interface FakeRepo {
+  repo: string;
+  defaultBranch: string;
+  prsByHead: Map<string, { number: number; state: string; baseRef: string }[]>;
+  creates: { head: string; base: string; title: string; number: number }[];
+  nextNumber: number;
+}
+
+function githubFetch(state: FakeRepo) {
+  return (url: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    const u = new URL(String(url));
+    const method = (init?.method ?? "GET").toUpperCase();
+    const path = u.pathname;
+    const json = (obj: unknown, status = 200) =>
+      Promise.resolve(new Response(JSON.stringify(obj), { status, headers: { "content-type": "application/json" } }));
+
+    if (method === "GET" && path === `/repos/${state.repo}`) {
+      return json({ default_branch: state.defaultBranch });
+    }
+    if (method === "GET" && path === `/repos/${state.repo}/pulls`) {
+      // listPrsForHead: ?head=owner:branch
+      const head = (u.searchParams.get("head") ?? "").split(":").pop() ?? "";
+      const list = state.prsByHead.get(head) ?? [];
+      return json(
+        list.map((p) => ({
+          number: p.number,
+          html_url: `https://github.com/${state.repo}/pull/${p.number}`,
+          state: p.state,
+          base: { ref: p.baseRef },
+        })),
+      );
+    }
+    if (method === "POST" && path === `/repos/${state.repo}/pulls`) {
+      // biome-ignore lint/plugin: test fixture parsing an external body shape
+      const body = JSON.parse(String(init?.body ?? "{}")) as { head?: string; base?: string; title?: string };
+      const head = String(body.head ?? "");
+      const number = state.nextNumber++;
+      state.creates.push({ head, base: String(body.base ?? ""), title: String(body.title ?? ""), number });
+      const arr = state.prsByHead.get(head) ?? [];
+      arr.push({ number, state: "open", baseRef: String(body.base ?? "") });
+      state.prsByHead.set(head, arr);
+      return json({ number, html_url: `https://github.com/${state.repo}/pull/${number}` }, 201);
+    }
+    return Promise.resolve(new Response(`unexpected ${method} ${path}`, { status: 500 }));
+  };
+}
+
+async function withGithub<T>(state: FakeRepo, fn: () => Promise<T>): Promise<T> {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevFetch = globalThis.fetch;
+  const prevToken = process.env.GITHUB_TOKEN;
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  // Leave GITHUB_TOKEN empty so submitPr's best-effort PR-meta enrichment is skipped (no fetch),
+  // while pollPromotion's own GitHub calls use the explicit "tok" argument.
+  delete process.env.GITHUB_TOKEN;
+  globalThis.fetch = githubFetch(state) as typeof fetch;
+  resetDefaultBranchCache();
+  try {
+    return await fn();
+  } finally {
+    globalThis.fetch = prevFetch;
+    resetDefaultBranchCache();
+    if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+    if (prevToken === undefined) delete process.env.GITHUB_TOKEN;
+    else process.env.GITHUB_TOKEN = prevToken;
+  }
+}
+
+function freshRepo(defaultBranch = "main"): FakeRepo {
+  return { repo: "o/r", defaultBranch, prsByHead: new Map(), creates: [], nextNumber: 500 };
+}
+
+test("pollPromotion: a landed epic on an epic/* base opens exactly one epic/*→default PR", async () => {
+  const { data, stores } = memData();
+  const { engine, instances } = recordingEngine();
+  stores.plans = [
+    { plan_key: "o/r#295", repo: "o/r", title: "Assertion DSL", status: "done", base_branch: "epic/test-dsl", delivery: "landed", promotion_pr: null, promotion_state: null },
+  ];
+  stores.plan_tasks = [
+    { id: 1, plan_key: "o/r#295", pr_key: "o/r#299" },
+    { id: 2, plan_key: "o/r#295", pr_key: "o/r#304" },
+  ];
+  stores.pull_requests = [
+    { pr_key: "o/r#299", status: "merged" },
+    { pr_key: "o/r#304", status: "merged" },
+  ];
+  const state = freshRepo();
+
+  await withGithub(state, () => pollPromotion(data, engine, "tok"));
+
+  assertEquals(state.creates.length, 1);
+  assertEquals(state.creates[0].head, "epic/test-dsl");
+  assertEquals(state.creates[0].base, "main");
+  assertEquals(stores.plans[0].promotion_pr, "o/r#500");
+  assertEquals(stores.plans[0].promotion_state, "open");
+  // The promotion PR was enrolled into the convergence loop (a real PR, not an auto-merge).
+  assertEquals(instances.length, 1);
+  assertEquals(instances[0].variables.prKey, "o/r#500");
+  const prRow = stores.pull_requests.find((p) => p.pr_key === "o/r#500");
+  assert(prRow, "promotion PR row registered by submitPr");
+});
+
+test("pollPromotion: re-running is idempotent — no duplicate promotion PR", async () => {
+  const { data, stores } = memData();
+  const { engine } = recordingEngine();
+  stores.plans = [
+    { plan_key: "o/r#295", repo: "o/r", title: "Assertion DSL", status: "done", base_branch: "epic/test-dsl", delivery: "landed", promotion_pr: null, promotion_state: null },
+  ];
+  stores.plan_tasks = [{ id: 1, plan_key: "o/r#295", pr_key: "o/r#299" }];
+  stores.pull_requests = [{ pr_key: "o/r#299", status: "merged" }];
+  const state = freshRepo();
+
+  await withGithub(state, async () => {
+    await pollPromotion(data, engine, "tok");
+    await pollPromotion(data, engine, "tok");
+    await pollPromotion(data, engine, "tok");
+  });
+
+  assertEquals(state.creates.length, 1, "exactly one promotion PR across three passes");
+  assertEquals(stores.plans[0].promotion_pr, "o/r#500");
+});
+
+test("pollPromotion: a still-converging epic opens no promotion PR", async () => {
+  const { data, stores } = memData();
+  const { engine } = recordingEngine();
+  stores.plans = [
+    { plan_key: "o/r#296", repo: "o/r", title: "WIP", status: "done", base_branch: "epic/wip", delivery: "converging", promotion_pr: null, promotion_state: null },
+  ];
+  stores.plan_tasks = [{ id: 1, plan_key: "o/r#296", pr_key: "o/r#310" }];
+  stores.pull_requests = [{ pr_key: "o/r#310", status: "converging" }];
+  const state = freshRepo();
+
+  await withGithub(state, () => pollPromotion(data, engine, "tok"));
+
+  assertEquals(state.creates.length, 0);
+  assertEquals(stores.plans[0].promotion_pr, null);
+  assertEquals(stores.plans[0].promotion_state, null);
+});
+
+test("pollPromotion: a main-based epic has nothing to promote", async () => {
+  const { data, stores } = memData();
+  const { engine } = recordingEngine();
+  stores.plans = [
+    { plan_key: "o/r#297", repo: "o/r", title: "Direct", status: "done", base_branch: "main", delivery: "landed", promotion_pr: null, promotion_state: null },
+  ];
+  stores.plan_tasks = [{ id: 1, plan_key: "o/r#297", pr_key: "o/r#320" }];
+  stores.pull_requests = [{ pr_key: "o/r#320", status: "merged" }];
+  const state = freshRepo();
+
+  await withGithub(state, () => pollPromotion(data, engine, "tok"));
+
+  assertEquals(state.creates.length, 0);
+  assertEquals(stores.plans[0].promotion_pr, null);
+  assertEquals(stores.plans[0].promotion_state, null);
+});
+
+test("pollPromotion: reuses an existing PR from the integration branch (crash-recovery idempotency)", async () => {
+  const { data, stores } = memData();
+  const { engine } = recordingEngine();
+  stores.plans = [
+    { plan_key: "o/r#295", repo: "o/r", title: "Assertion DSL", status: "done", base_branch: "epic/test-dsl", delivery: "landed", promotion_pr: null, promotion_state: null },
+  ];
+  stores.plan_tasks = [{ id: 1, plan_key: "o/r#295", pr_key: "o/r#299" }];
+  stores.pull_requests = [{ pr_key: "o/r#299", status: "merged" }];
+  const state = freshRepo();
+  // A prior pass created the PR on GitHub but crashed before persisting `promotion_pr`.
+  state.prsByHead.set("epic/test-dsl", [{ number: 777, state: "open", baseRef: "main" }]);
+
+  await withGithub(state, () => pollPromotion(data, engine, "tok"));
+
+  assertEquals(state.creates.length, 0, "existing PR reused, not duplicated");
+  assertEquals(stores.plans[0].promotion_pr, "o/r#777");
+  assertEquals(stores.plans[0].promotion_state, "open");
+});
+
+test("pollPromotion: projects `promoted` once the promotion PR merges", async () => {
+  const { data, stores } = memData();
+  const { engine } = recordingEngine();
+  stores.plans = [
+    { plan_key: "o/r#295", repo: "o/r", title: "Assertion DSL", status: "done", base_branch: "epic/test-dsl", delivery: "landed", promotion_pr: "o/r#500", promotion_state: "open" },
+  ];
+  stores.plan_tasks = [{ id: 1, plan_key: "o/r#295", pr_key: "o/r#299" }];
+  stores.pull_requests = [
+    { pr_key: "o/r#299", status: "merged" },
+    { pr_key: "o/r#500", status: "merged" },
+  ];
+  const state = freshRepo();
+
+  await withGithub(state, () => pollPromotion(data, engine, "tok"));
+
+  assertEquals(state.creates.length, 0);
+  assertEquals(stores.plans[0].promotion_state, "promoted");
+});

package/app/service.ts

@@ -17,6 +17,8 @@ import {
   classifyMergeability,
   coalesceTitle,
   ensureFreshHeadRun,
+  ensurePromotionPr,
+  fetchDefaultBranch,
   fetchPrHead,
   fetchPrMeta,
   fetchPrReviews,
@@ -32,6 +34,7 @@ import { mergeLanes, readExclusions } from "./mergeExclusion.ts";
 import { freshHeadRunAction, headRunPresenceCount, loadMergeProtocol } from "./mergeProtocol.ts";
 import { type PrLaneDecision, planPrLane, taskDependencyDepths } from "./mergeTrain.ts";
 import { planReviews, plans, planTaskDeps, planTasks } from "./plan.ts";
+import { derivePromotionState, isPromotable, promotionPrBody, promotionPrTitle } from "./promotion.ts";
 import { clampNudgeMinutes, reviewWaitTimeout } from "./reviewWait.ts";
 import { trialMergeAudits } from "./trialMerge.ts";
 import {
@@ -1347,6 +1350,91 @@ export async function pollDelivery(data: DataLayer) {
   }
 }
 
+/** Idempotent promotion pass (issue #299): open — and then track — the `epic/* → <default>`
+ * promotion PR for every epic that has LANDED on a custom integration branch. This is the missing
+ * counterpart to `ensureBaseBranch`: that creates the `epic/*` branch slices merge into; this
+ * delivers the fully-landed branch to the default branch. Runs AFTER `pollDelivery` so it reads the
+ * freshly-projected `delivery = landed` signal.
+ *
+ * Per promotable plan (`isPromotable`: `delivery = landed` AND base is `epic/*`):
+ *   • No promotion PR yet → open ONE `epic/* → <default>` PR (idempotent against a remote head-branch
+ *     lookup, so a crash between GitHub-create and the `promotion_pr` write can't duplicate it),
+ *     record `promotion_pr`, mark `promotion_state = open`, and enroll it into the convergence + merge
+ *     loop via `submitPr` (a real PR that must go green + converge before it merges — never an
+ *     auto-merge). If the PR can't be opened this pass (no default branch resolvable, no transport),
+ *     leave it at `promotion_state = ready` and retry next pass.
+ *   • Promotion PR already recorded → project `promotion_state` from its live status
+ *     (`merged → promoted`, else `open`); if its `pull_requests` row is absent (a prior `submitPr`
+ *     failed / DB desync) re-enroll it (idempotent).
+ *
+ * A `main`-based epic (base is not `epic/*`) is never promotable — its slices already landed on the
+ * default branch, so there is nothing to promote. Best-effort + per-plan isolated. */
+export async function pollPromotion(data: DataLayer, engine: EngineClient, token: string) {
+  // Preload every PR status once per pass (mirrors pollDelivery — avoids an N+1 `prs(data).get`).
+  const statusByPrKey = new Map<string, string>();
+  for (const pr of await prs(data).all()) statusByPrKey.set(pr.pr_key, pr.status);
+  for (const plan of await plans(data).all()) {
+    if (!isPromotable(plan)) continue;
+    const base = plan.base_branch;
+    if (!base) continue; // narrowed by isPromotable, but keep the type-checker honest
+    try {
+      // Already opened → project state from the promotion PR's live status, and re-enroll it if its
+      // convergence row went missing (a prior submit failed, or the app/engine store desynced).
+      if (plan.promotion_pr) {
+        const prStatus = statusByPrKey.get(plan.promotion_pr) ?? null;
+        const nextState = derivePromotionState(true, prStatus === "merged");
+        if (plan.promotion_state !== nextState) {
+          await plans(data).update(plan.plan_key, { promotion_state: nextState, updated_at: now() });
+        }
+        if (prStatus === null) {
+          const parsed = parsePr(plan.promotion_pr);
+          if (parsed) await submitPr(data, engine, parsed);
+        }
+        continue;
+      }
+      // Not opened yet: this epic is ready to promote. Resolve the target (default) branch; without
+      // it we can't open the PR this pass, so surface `ready` and retry.
+      const target = await fetchDefaultBranch(plan.repo, token);
+      if (!target || target === base) {
+        // `target === base` is a defensive guard (an `epic/*` base can't be the default), but never
+        // open a branch-into-itself PR. Either way, mark ready and retry.
+        if (plan.promotion_state !== "ready") {
+          await plans(data).update(plan.plan_key, { promotion_state: "ready", updated_at: now() });
+        }
+        continue;
+      }
+      const tasks = await planTasks(data).find({ plan_key: plan.plan_key });
+      const slicePrKeys = tasks.map((t) => t.pr_key).filter((k): k is string => !!k);
+      const epicTitle = coalesceTitle(plan.title, plan.plan_key);
+      const title = promotionPrTitle(base, target, epicTitle);
+      const body = promotionPrBody(base, target, plan.plan_key, slicePrKeys);
+      const result = await ensurePromotionPr(plan.repo, base, target, title, body, token);
+      if (!result) {
+        // No transport this pass — surface ready-to-promote and retry.
+        if (plan.promotion_state !== "ready") {
+          await plans(data).update(plan.plan_key, { promotion_state: "ready", updated_at: now() });
+        }
+        continue;
+      }
+      const promotionPrKey = `${plan.repo}#${result.number}`;
+      // Persist the idempotency key + state BEFORE enrolling, so a submit failure can never lead a
+      // later pass to open a second PR (it will see `promotion_pr` set and only re-enroll).
+      await plans(data).update(plan.plan_key, {
+        promotion_pr: promotionPrKey,
+        promotion_state: "open",
+        updated_at: now(),
+      });
+      const parsed = parsePr(promotionPrKey);
+      if (parsed) await submitPr(data, engine, parsed);
+      console.log(
+        `[poller] promotion PR ${result.created ? "opened" : "reused"} ${promotionPrKey} (${base} -> ${target})`,
+      );
+    } catch (err) {
+      console.error(`[poller] promotion ${plan.plan_key}: ${err}`);
+    }
+  }
+}
+
 /** Reconcile each in-flight FEATURE run against its handed-off PR (fix: Feature history stuck at
  * `converging`). A feature run ends its own process with `status = converging` and its PR's live
  * outcome (merged / converged / abandoned) thereafter lives only on the `pull_requests` row keyed
@@ -1699,6 +1787,7 @@ export async function pollOnce(
   await pollReviews(data, engine, token);
   await pollMerges(data, engine, token);
   await pollDelivery(data);
+  await pollPromotion(data, engine, token);
   await pollFeatureDelivery(data);
   await pollLineage(data);
   await pollFeatureEscalations(data, engine);

package/db/migrations/042_plan_promotion.sql

@@ -0,0 +1,31 @@
+-- 042_plan_promotion.sql — issue #299: automate the epic integration-branch → default-branch
+-- promotion PR once an epic LANDS on its custom `epic/*` integration branch.
+--
+-- Today an epic that targets a custom `epic/*` integration branch fans slices out that PR *into*
+-- that branch; once every slice merges (`plans.delivery = landed`, projected by 029), the epic is
+-- delivered on the integration branch but NOTHING opens the final `epic/* → <default>` promotion
+-- PR — the operator has to notice, find the branch, and raise it by hand. This migration adds the
+-- durable read/idempotency surface the poller's new `pollPromotion` pass needs to open (and then
+-- track) exactly one promotion PR per landed epic, reusing the same convergence + merge protocol as
+-- every other PR:
+--
+--   • promotion_pr    — the `owner/repo#N` key of the promotion PR the poller opened for this epic,
+--                       or NULL until one exists. This is the PRIMARY idempotency key: a pass that
+--                       finds it set never opens a second PR (the poller also reconciles against a
+--                       remote head-branch lookup, so a crash between GitHub-create and this write
+--                       can never duplicate the PR either).
+--   • promotion_state — the epic-card progression for the landed→delivered arc (issue #298's
+--                       "keep landed epics visible until acknowledged"): one of
+--                         'ready'    — landed on an `epic/*` base, promotion PR not yet opened.
+--                         'open'     — the promotion PR is open and converging toward merge.
+--                         'promoted' — the promotion PR merged; the epic is delivered on the
+--                                      default branch.
+--                       NULL until the epic first becomes promotable (grandfathers pre-#299 rows
+--                       and every `main`-based epic, which has nothing to promote).
+--
+-- Additive/derived only: no change to the plan lifecycle (`status`) — both columns are projected
+-- idempotently by the poller, mirroring the `delivery` / `delivery_label` read-model columns (029).
+-- Numbered after the current highest prefix on origin/main (041); the runner wraps each file in its
+-- own transaction, so this file must NOT contain BEGIN/COMMIT.
+ALTER TABLE plans ADD COLUMN promotion_pr TEXT;
+ALTER TABLE plans ADD COLUMN promotion_state TEXT;

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.88.1",
+  "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/epic-detail.page.json

@@ -61,6 +61,7 @@
           { "field": "epic_phase", "header": "Phase" },
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
           { "field": "delivery", "header": "Delivery" },
+          { "field": "promotion_state", "header": "Promotion" },
           { "field": "wave_label", "header": "Wave" },
           { "field": "task_count", "header": "Tasks" },
           { "field": "updated_at", "header": "Updated", "width": "9rem" }
@@ -72,6 +73,7 @@
             { "field": "issue_number", "label": "Issue number" },
             { "field": "base_branch", "label": "Base branch (blank = repo default)" },
             { "field": "delivery_label", "label": "Delivery rollup (slices merged / converging)" },
+            { "field": "promotion_pr", "label": "Promotion PR (epic/* → default branch)" },
             { "field": "outcome", "label": "Outcome" }
           ]
         }

package/pages/epic.page.json

@@ -79,6 +79,7 @@
           { "field": "epic_phase", "header": "Phase" },
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
           { "field": "delivery", "header": "Delivery" },
+          { "field": "promotion_state", "header": "Promotion" },
           { "field": "base_branch", "header": "Base branch" },
           { "field": "wave_label", "header": "Wave" },
           { "field": "task_count", "header": "Tasks" },