@nanobpm/nano-workforce 0.88.0 → 0.89.0

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
@@ -1410,7 +1498,7 @@ export async function pollFeatureEscalations(data: DataLayer, engine: EngineClie
   for (const run of candidates) {
     if (!run.process_key) continue;
     try {
-      const tasks = await engine.searchUserTasks({ processInstanceKey: run.process_key });
+      const tasks = await engine.openUserTasks({ processInstanceKey: run.process_key });
       const task = tasks.find((t) => t.elementId === FEATURE_ESCALATION_ELEMENT);
       const parked = task ? { userTaskKey: task.userTaskKey } : null;
       const patch = deriveFeatureEscalationPatch(run, parked);
@@ -1444,7 +1532,7 @@ export async function pollFeatureBlocked(data: DataLayer, engine: EngineClient)
   for (const run of await featureRuns(data).find({ status: "awaiting_operator" })) {
     if (!run.process_key) continue;
     try {
-      const tasks = await engine.searchUserTasks({ processInstanceKey: run.process_key });
+      const tasks = await engine.openUserTasks({ processInstanceKey: run.process_key });
       const task = tasks.find((t) => t.elementId === FEATURE_BLOCKED_ELEMENT);
       const parked = task ? { userTaskKey: task.userTaskKey } : null;
       const patch = deriveFeatureBlockedPatch(run, parked);
@@ -1577,7 +1665,7 @@ export async function pollUserTasks(data: DataLayer, engine: EngineClient) {
       planSeen.add(plan.plan_key);
       let tasks: { userTaskKey: string; elementId?: string }[];
       try {
-        tasks = await engine.searchUserTasks({ processInstanceKey: plan.process_key });
+        tasks = await engine.openUserTasks({ processInstanceKey: plan.process_key });
       } catch (err) {
         console.error(`[poller] user tasks (plan ${plan.plan_key}): ${err}`);
         continue;
@@ -1632,7 +1720,7 @@ export async function pollUserTasks(data: DataLayer, engine: EngineClient) {
       prSeen.add(pr.pr_key);
       let tasks: { userTaskKey: string; elementId?: string }[];
       try {
-        tasks = await engine.searchUserTasks({ processInstanceKey: pr.process_key });
+        tasks = await engine.openUserTasks({ processInstanceKey: pr.process_key });
       } catch (err) {
         console.error(`[poller] user tasks (pr ${pr.pr_key}): ${err}`);
         continue;
@@ -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/041_inter_epic_plan_deps.sql

@@ -0,0 +1,38 @@
+-- 041_inter_epic_plan_deps.sql — issue #292 slice S1: first-class INTER-epic dependency edge.
+--
+-- `plan_task_deps` (005_plan_deps.sql) records the INTRA-epic task DAG — edges that order tasks
+-- *within a single plan* into waves. There is no way today to say "epic B depends-on epic A": that
+-- the whole of epic B must wait until epic A has published a capability before B may fan out.
+--
+-- This table adds that second, coarser grain: one row per INTER-epic edge. `plan_key` is the
+-- dependent/consumer epic that waits; `depends_on_plan_key` is the producer epic it waits for. The
+-- edge also carries the GATING CONTRACT DESCRIPTOR the later capability probe (slice S3) needs to
+-- resolve which published `pkg@version` first carries the awaited capability: `package` is the
+-- producer's published package name, and `capability_ref` is the producer epic's issue handle used
+-- to resolve that version. This slice (S1) only lands the durable schema + typed read/write surface;
+-- admission (S2), lowering into a readiness gate (S3), and visibility (S4) build on it later.
+--
+-- Constraints mirror how `plan_task_deps` is constrained:
+--   • PRIMARY KEY (plan_key, depends_on_plan_key) — one edge per consumer→producer pair, so a
+--     re-submitted set cannot duplicate an edge.
+--   • CHECK (plan_key <> depends_on_plan_key) — an epic cannot depend on itself.
+--   • plan_key REFERENCES plans(plan_key) — the consumer is an admitted plan (as plan_task_deps FKs
+--     its plan_key). `depends_on_plan_key` is intentionally NOT FK-constrained: a batch admission
+--     (S2) may insert edges before every producer row exists, and the set validator enforces that
+--     every edge names a submitted epic. An index on plan_key backs the inbound read.
+--
+-- Numbered after the current highest prefix on origin/main (040); the runner wraps each file in its
+-- own transaction, so this file must NOT contain BEGIN/COMMIT.
+
+CREATE TABLE plan_deps (
+  plan_key            TEXT NOT NULL REFERENCES plans(plan_key),  -- dependent/consumer epic that waits
+  depends_on_plan_key TEXT NOT NULL,                             -- producer epic it waits for
+  package             TEXT NOT NULL,                             -- producer's published package name
+  capability_ref      TEXT NOT NULL,                             -- producer epic issue handle → pkg@version
+  created_at          TEXT NOT NULL,
+  PRIMARY KEY (plan_key, depends_on_plan_key),
+  CHECK (plan_key <> depends_on_plan_key)
+);
+
+CREATE INDEX idx_plan_deps_plan ON plan_deps(plan_key);
+CREATE INDEX idx_plan_deps_producer ON plan_deps(depends_on_plan_key);

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

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