@nanobpm/nano-workforce 0.88.0 → 0.89.0

package/app/plan.ts

@@ -89,6 +89,17 @@ export interface Plan {
   // view can show which phase the epic is IN rather than only the process-instance terminal status.
   // Display-only; NULL until the lifecycle first stamps it (grandfathers pre-#261 rows).
   epic_phase: string | null;
+  // Epic integration-branch → default-branch promotion (042_plan_promotion.sql, #299). When an epic
+  // targets a custom `epic/*` integration branch and every slice PR has merged (`delivery = landed`),
+  // the poller's `pollPromotion` pass opens exactly ONE `epic/* → <default>` promotion PR and drives
+  // it through the same convergence + merge protocol as every other PR (see app/promotion.ts).
+  //   • promotion_pr    — the `owner/repo#N` key of that promotion PR, or NULL until one is opened.
+  //                       PRIMARY idempotency key: a set value never re-opens a second PR.
+  //   • promotion_state — the epic-card progression 'ready' → 'open' → 'promoted', or NULL until the
+  //                       epic first becomes promotable (also NULL forever for a `main`-based epic,
+  //                       which has nothing to promote). Display-only; projected by the poller.
+  promotion_pr: string | null;
+  promotion_state: string | null;
   created_at: string;
   updated_at: string;
 }
@@ -138,6 +149,87 @@ export interface PlanTaskDep {
 export const planTaskDeps = (data: DataLayer) =>
   data.table<PlanTaskDep>("plan_task_deps", "plan_key");
 
+/** One INTER-epic dependency edge in the plan-set DAG (issue #292, slice S1): the epic `plan_key`
+ * waits for the producer epic `depends_on_plan_key` to publish a capability before it may fan out.
+ *
+ * This is the coarser sibling of {@link PlanTaskDep} (which orders TASKS *within* one epic into
+ * waves). A `PlanDep` orders whole EPICS relative to each other. The edge additionally carries the
+ * gating contract descriptor the capability probe (slice S3) resolves against:
+ *   • `package` — the producer epic's published package name, and
+ *   • `capability_ref` — the producer epic's issue handle, used to resolve which published
+ *     `pkg@version` FIRST carries the awaited capability (late-bound into the dependent's build).
+ * Keyed on `plan_key` (the dependent) so a single delete clears a dependent's whole inbound edge set
+ * — mirroring how `plan_task_deps` is keyed on `plan_key`. See db/migrations/041_inter_epic_plan_deps.sql
+ * for the durable constraints (one edge per consumer→producer pair; no self-edge). */
+export interface PlanDep {
+  plan_key: string;
+  depends_on_plan_key: string;
+  package: string;
+  capability_ref: string;
+  created_at: string;
+}
+export const planDeps = (data: DataLayer) => data.table<PlanDep>("plan_deps", "plan_key");
+
+/** The fields an admission caller supplies for one inter-epic edge; `created_at` is stamped here. */
+export type PlanDepInput = Omit<PlanDep, "created_at">;
+
+/** Record one inter-epic dependency edge, enforcing the schema's two invariants at the app layer too
+ * (the durable table backstops both, but the in-memory test data layer does not): an epic may not
+ * depend on itself, and a consumer→producer edge is recorded at most once. A duplicate re-submission
+ * is a no-op that returns the existing row rather than throwing, so batch admission (S2) stays
+ * idempotent; a self-edge is a programming/validation error and throws. */
+export async function recordPlanDep(data: DataLayer, edge: PlanDepInput): Promise<PlanDep> {
+  if (edge.plan_key === edge.depends_on_plan_key) {
+    throw new Error(
+      `plan_deps: self-edge rejected — epic ${edge.plan_key} cannot depend on itself`,
+    );
+  }
+  const table = planDeps(data);
+  const match = { plan_key: edge.plan_key, depends_on_plan_key: edge.depends_on_plan_key };
+  const existing = (await table.find(match))[0];
+  if (existing) return existing;
+  const row: PlanDep = { ...edge, created_at: now() };
+  try {
+    await table.insert(row);
+    return row;
+  } catch (err) {
+    // A concurrent caller may have inserted the same consumer→producer pair between our find and
+    // our insert (classic check-then-insert race); the composite PRIMARY KEY is the durable
+    // backstop that rejects the loser. Honour the "duplicate re-submission is a no-op" contract by
+    // re-reading and returning the winning row rather than surfacing the constraint error. Only a
+    // genuine non-collision failure (the pair still absent after the re-read) is re-raised.
+    const raced = (await table.find(match))[0];
+    if (raced) return raced;
+    throw err;
+  }
+}
+
+/** All INBOUND edges for `planKey` — i.e. every producer epic this dependent waits on. Empty for a
+ * root epic (no inter-epic dependencies). */
+export function inboundPlanDeps(data: DataLayer, planKey: string): Promise<PlanDep[]> {
+  return planDeps(data).find({ plan_key: planKey });
+}
+
+/** Every inter-epic edge whose dependent is in `planKeys` — the whole DAG for a submitted plan set.
+ * Reads per-key (not a table scan) so it composes with the same equality-filtered data layer the
+ * unit tests exercise. Producers outside the set are still returned as edge fields; the set
+ * validator (S3) is what rejects an edge naming an unsubmitted epic. */
+export async function planDepsForSet(data: DataLayer, planKeys: string[]): Promise<PlanDep[]> {
+  const seen = new Set<string>();
+  const out: PlanDep[] = [];
+  // De-duplicate the keys first so a repeated key (retries / accidental repeats) does not trigger a
+  // redundant per-key inbound read; the edge de-dup below still guards against any overlap.
+  for (const key of new Set(planKeys)) {
+    for (const edge of await inboundPlanDeps(data, key)) {
+      const id = `${edge.plan_key}\u0000${edge.depends_on_plan_key}`;
+      if (seen.has(id)) continue;
+      seen.add(id);
+      out.push(edge);
+    }
+  }
+  return out;
+}
+
 /** One adversarial plan-review round (006_plan_review.sql): the `senior:plan-review` agent's
  * verdict on the plan before fan-out. Append-only within a plan run; the current round is
  * `count(plan_reviews)`. Re-planning a finished issue clears the prior rows (see startPlan) so

package/app/planDeps.test.ts

@@ -0,0 +1,192 @@
+// Red/green regression for the INTER-epic dependency edge (PlanDep) data layer — issue #292 slice S1.
+//
+// This slice adds `plan_deps` (db/migrations/041_inter_epic_plan_deps.sql) and its typed read/write
+// surface in app/plan.ts, mirroring the intra-epic `plan_task_deps` accessors. The durable table
+// enforces "one edge per consumer→producer pair" (PRIMARY KEY) and "no self-edge" (CHECK); these
+// tests pin the app-layer accessors that admission (S2) and the planner (S3) build on, driven against
+// the same in-memory data layer the rest of app/plan's tests use.
+import { test } from "node:test";
+import { assertEquals, assertRejects } from "#test-assert";
+import {
+  inboundPlanDeps,
+  type PlanDep,
+  planDepsForSet,
+  recordPlanDep,
+} from "./plan.ts";
+
+// Minimal in-memory data layer, matching the helper style in app/plan.test.ts: equality-filtered
+// `find`, append `insert`, and a `delete(planKey)` that clears every row keyed on `plan_key` (so a
+// re-seed of a plan's inbound edge set is one delete, exactly as `plan_task_deps` is cleared).
+function memData() {
+  const rows: any[] = [];
+  const key = "plan_key";
+  const table = {
+    get: (k: any) => Promise.resolve(rows.find((r) => r[key] === k) ?? null),
+    find: (q: any) =>
+      Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+    insert: (r: any) => {
+      rows.push(r);
+      return Promise.resolve(r);
+    },
+    count: (q: any) =>
+      Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v)).length),
+    delete: (k: any) => {
+      for (let i = rows.length - 1; i >= 0; i--) if (rows[i][key] === k) rows.splice(i, 1);
+      return Promise.resolve();
+    },
+  };
+  return {
+    rows,
+    data: { table: () => table } as any,
+  };
+}
+
+const EDGE = {
+  plan_key: "owner/repo#2",
+  depends_on_plan_key: "owner/repo#1",
+  package: "@nanobpm/producer",
+  capability_ref: "owner/repo#1",
+};
+
+test("recordPlanDep persists an edge with a stamped created_at", async () => {
+  const { data, rows } = memData();
+  const row = await recordPlanDep(data, EDGE);
+  assertEquals(rows.length, 1);
+  assertEquals(row.plan_key, "owner/repo#2");
+  assertEquals(row.depends_on_plan_key, "owner/repo#1");
+  assertEquals(row.package, "@nanobpm/producer");
+  assertEquals(row.capability_ref, "owner/repo#1");
+  assertEquals(typeof row.created_at, "string");
+  assertEquals(row.created_at.length > 0, true);
+});
+
+test("recordPlanDep rejects a self-edge (an epic cannot depend on itself)", async () => {
+  const { data, rows } = memData();
+  await assertRejects(() =>
+    recordPlanDep(data, { ...EDGE, plan_key: "owner/repo#1", depends_on_plan_key: "owner/repo#1" }),
+  );
+  assertEquals(rows.length, 0);
+});
+
+test("recordPlanDep is idempotent on a duplicate edge (no second row)", async () => {
+  const { data, rows } = memData();
+  const first = await recordPlanDep(data, EDGE);
+  const again = await recordPlanDep(data, { ...EDGE, package: "@nanobpm/ignored-on-dupe" });
+  assertEquals(rows.length, 1);
+  // The existing row wins — a re-submission does not overwrite nor append.
+  assertEquals(again.created_at, first.created_at);
+  assertEquals(again.package, "@nanobpm/producer");
+});
+
+test("recordPlanDep treats a concurrent PK collision as idempotent (no throw)", async () => {
+  // Simulate the check-then-insert race the durable composite PRIMARY KEY backstops: a sibling
+  // caller wins between our find and our insert, so `find` sees nothing but `insert` collides.
+  const rows: any[] = [];
+  const key = "plan_key";
+  let raceArmed = true;
+  const table = {
+    get: (k: any) => Promise.resolve(rows.find((r) => r[key] === k) ?? null),
+    find: (q: any) =>
+      Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+    insert: (r: any) => {
+      // On the first insert, a concurrent writer has already landed the same pair: append the
+      // rival row and reject this one with a UNIQUE/PK constraint error, as SQLite would.
+      if (raceArmed) {
+        raceArmed = false;
+        rows.push({ ...r, package: "@nanobpm/winner", created_at: "1999-01-01T00:00:00.000Z" });
+        return Promise.reject(new Error("UNIQUE constraint failed: plan_deps.plan_key"));
+      }
+      rows.push(r);
+      return Promise.resolve(r);
+    },
+    count: (q: any) =>
+      Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v)).length),
+    delete: (k: any) => {
+      for (let i = rows.length - 1; i >= 0; i--) if (rows[i][key] === k) rows.splice(i, 1);
+      return Promise.resolve();
+    },
+  };
+  const data = { table: () => table } as any;
+
+  const row = await recordPlanDep(data, EDGE);
+  // The rival row is returned rather than the constraint error surfacing, and no duplicate lands.
+  assertEquals(rows.length, 1);
+  assertEquals(row.package, "@nanobpm/winner");
+  assertEquals(row.created_at, "1999-01-01T00:00:00.000Z");
+});
+
+test("recordPlanDep re-raises a non-collision insert failure", async () => {
+  // A genuine failure (the pair is still absent after the re-read) must not be swallowed.
+  const table = {
+    get: () => Promise.resolve(null),
+    find: () => Promise.resolve([] as any[]),
+    insert: () => Promise.reject(new Error("disk I/O error")),
+    count: () => Promise.resolve(0),
+    delete: () => Promise.resolve(),
+  };
+  const data = { table: () => table } as any;
+  await assertRejects(() => recordPlanDep(data, EDGE), Error, "disk I/O error");
+});
+
+test("inboundPlanDeps returns every producer a dependent waits on; empty for a root", async () => {
+  const { data } = memData();
+  await recordPlanDep(data, EDGE);
+  await recordPlanDep(data, { ...EDGE, depends_on_plan_key: "owner/repo#3", capability_ref: "owner/repo#3" });
+
+  const inbound = await inboundPlanDeps(data, "owner/repo#2");
+  assertEquals(inbound.length, 2);
+  assertEquals(
+    inbound.map((e: PlanDep) => e.depends_on_plan_key).sort(),
+    ["owner/repo#1", "owner/repo#3"],
+  );
+
+  const root = await inboundPlanDeps(data, "owner/repo#1");
+  assertEquals(root.length, 0);
+});
+
+test("planDepsForSet returns the whole DAG for a submitted set, de-duplicated", async () => {
+  const { data } = memData();
+  // #3 -> #1, #3 -> #2, #2 -> #1 : a small DAG across three epics.
+  await recordPlanDep(data, {
+    plan_key: "owner/repo#3",
+    depends_on_plan_key: "owner/repo#1",
+    package: "@nanobpm/a",
+    capability_ref: "owner/repo#1",
+  });
+  await recordPlanDep(data, {
+    plan_key: "owner/repo#3",
+    depends_on_plan_key: "owner/repo#2",
+    package: "@nanobpm/b",
+    capability_ref: "owner/repo#2",
+  });
+  await recordPlanDep(data, {
+    plan_key: "owner/repo#2",
+    depends_on_plan_key: "owner/repo#1",
+    package: "@nanobpm/a",
+    capability_ref: "owner/repo#1",
+  });
+
+  const edges = await planDepsForSet(data, ["owner/repo#1", "owner/repo#2", "owner/repo#3"]);
+  assertEquals(edges.length, 3);
+  // A root (#1) contributes no inbound edges; passing overlapping keys never double-counts an edge.
+  const overlapped = await planDepsForSet(data, ["owner/repo#3", "owner/repo#3"]);
+  assertEquals(overlapped.length, 2);
+});
+
+test("planDepsForSet reads each key once even when planKeys repeats", async () => {
+  // Prove the key de-dup: a repeated key must not drive a redundant inbound read.
+  const findKeys: string[] = [];
+  const table = {
+    get: () => Promise.resolve(null),
+    find: (q: any) => {
+      findKeys.push(q.plan_key);
+      return Promise.resolve([] as any[]);
+    },
+    insert: (r: any) => Promise.resolve(r),
+    count: () => Promise.resolve(0),
+    delete: () => Promise.resolve(),
+  };
+  const data = { table: () => table } as any;
+  await planDepsForSet(data, ["owner/repo#3", "owner/repo#3", "owner/repo#4", "owner/repo#3"]);
+  assertEquals(findKeys.sort(), ["owner/repo#3", "owner/repo#4"]);
+});

package/app/pollUserTasks.test.ts

@@ -51,12 +51,22 @@ function memData(seed: Record<string, any[]> = {}): { data: DataLayer; stores: R
   return { data, stores };
 }
 
-/** A fake engine whose open user tasks are keyed by processInstanceKey (the only field the poller
- *  queries on for plan / PR instances). */
-function fakeEngine(byInstance: Record<string, { userTaskKey: string; elementId?: string }[]>): EngineClient {
+/** A single engine-reported user task in the fixture. `state` mirrors the engine lifecycle; it
+ *  defaults to `"CREATED"` (the only open/answerable state) so existing fixtures read as live tasks.
+ *  A looping instance holds multiple tasks for one element (COMPLETED from prior rounds + the live one). */
+type FakeTask = { userTaskKey: string; elementId?: string; state?: "CREATED" | "COMPLETED" | "CANCELED" };
+
+/** A fake engine whose user tasks are keyed by processInstanceKey (the only field the poller queries on
+ *  for plan / PR instances). It models the real engine's two accessors from ONE fixture so a test
+ *  genuinely exercises the lifecycle-state filtering: `searchUserTasks` returns tasks in ANY state
+ *  (COMPLETED first, as the live API does — issue #294), while `openUserTasks` pins `state:"CREATED"`. */
+function fakeEngine(byInstance: Record<string, FakeTask[]>): EngineClient {
+  const all = (filter?: { processInstanceKey?: string }) =>
+    filter?.processInstanceKey ? (byInstance[filter.processInstanceKey] ?? []) : [];
   return {
-    searchUserTasks: (filter?: { processInstanceKey?: string }) =>
-      Promise.resolve(filter?.processInstanceKey ? (byInstance[filter.processInstanceKey] ?? []) : []),
+    searchUserTasks: (filter?: { processInstanceKey?: string }) => Promise.resolve(all(filter)),
+    openUserTasks: (filter?: { processInstanceKey?: string }) =>
+      Promise.resolve(all(filter).filter((t) => (t.state ?? "CREATED") === "CREATED")),
   } as unknown as EngineClient;
 }
 
@@ -172,3 +182,50 @@ test("pollUserTasks: skips terminal plans and PRs without a process key", async
 
   assertEquals(stores.user_tasks ?? [], []);
 });
+
+// ── Defect-class guard (issue #294): a looping instance holds MULTIPLE tasks for one element ───────
+// The plan-review (review→revise→review) and PR-wait (escalate→answer→re-escalate) elements sit on a
+// loop, so a looping instance holds a COMPLETED task from a prior round alongside the live CREATED one,
+// and the engine returns the COMPLETED one first. Scoping the query to open (CREATED) tasks projects
+// only the live completable key onto `user_tasks`, never a terminal one the page could not complete.
+test("pollUserTasks: a looping plan/PR projects only the CREATED task, never the COMPLETED one", async () => {
+  const { data, stores } = memData({
+    plans: [{ plan_key: "o/r#50", status: "dispatched", process_key: "pp-50", issue_url: "https://github.com/o/r/issues/50" }],
+    plan_reviews: [{ plan_key: "o/r#50", epoch: 0, round: 0, approved: 0, findings: "scope too broad", created_at: "2025-01-01T00:00:00.000Z" }],
+    pull_requests: [{ pr_key: "o/r#51", status: "escalated", process_key: "rp-51", url: "https://github.com/o/r/pull/51" }],
+    escalations: [{ id: 1, pr_key: "o/r#51", status: "open", question: "conflicting reviews" }],
+  });
+  // Each looping instance returns its COMPLETED prior-round task FIRST, then the live CREATED one.
+  const engine = fakeEngine({
+    "pp-50": [
+      { userTaskKey: "ut-plan-completed", elementId: "plan-review-decision", state: "COMPLETED" },
+      { userTaskKey: "ut-plan-live", elementId: "plan-review-decision", state: "CREATED" },
+    ],
+    "rp-51": [
+      { userTaskKey: "ut-pr-completed", elementId: "wait-answer", state: "COMPLETED" },
+      { userTaskKey: "ut-pr-live", elementId: "wait-answer", state: "CREATED" },
+    ],
+  });
+
+  await pollUserTasks(data, engine);
+
+  const keys = (stores.user_tasks ?? []).map((r) => r.user_task_key).sort();
+  // Only the live CREATED keys — the COMPLETED prior-round tasks must never surface a dead affordance.
+  assertEquals(keys, ["ut-plan-live", "ut-pr-live"]);
+});
+
+// Self-heal reached: an instance whose only task for an element is COMPLETED yields no open task, so
+// its row is removed (open-task query returns []), rather than pinning a dead completable pointer.
+test("pollUserTasks: an instance whose only task is COMPLETED surfaces no row", async () => {
+  const { data, stores } = memData({
+    plans: [{ plan_key: "o/r#52", status: "dispatched", process_key: "pp-52", issue_url: "https://github.com/o/r/issues/52" }],
+    plan_reviews: [{ plan_key: "o/r#52", epoch: 0, round: 0, approved: 0, findings: "scope too broad", created_at: "2025-01-01T00:00:00.000Z" }],
+  });
+  const engine = fakeEngine({
+    "pp-52": [{ userTaskKey: "ut-plan-completed", elementId: "plan-review-decision", state: "COMPLETED" }],
+  });
+
+  await pollUserTasks(data, engine);
+
+  assertEquals(stores.user_tasks ?? [], []);
+});

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`;
+}