@nanobpm/nano-workforce 0.88.0 → 0.89.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.89.0](https://github.com/nanobpm/nano-workforce/compare/v0.88.1...v0.89.0) (2026-08-19)
+
+
+### Features
+
+* auto-open the epic integration-branch → default-branch promotion PR on landing ([#299](https://github.com/nanobpm/nano-workforce/issues/299)) ([#300](https://github.com/nanobpm/nano-workforce/issues/300)) ([24a8854](https://github.com/nanobpm/nano-workforce/commit/24a885484ae69bd654edd4d05fa198561e2db5dd))
+
+## [0.88.1](https://github.com/nanobpm/nano-workforce/compare/v0.88.0...v0.88.1) (2026-08-18)
+
+
+### Bug Fixes
+
+* scope user-task pollers to open tasks so they can't latch a COMPLETED task ([#297](https://github.com/nanobpm/nano-workforce/issues/297)) ([131a796](https://github.com/nanobpm/nano-workforce/commit/131a796dfaed8f9b2eb25526f6583b86b8d7b0df)), closes [#294](https://github.com/nanobpm/nano-workforce/issues/294)
+
 # [0.88.0](https://github.com/nanobpm/nano-workforce/compare/v0.87.0...v0.88.0) (2026-08-18)
 
 

package/app/contracts.ts

@@ -354,6 +354,14 @@ export const TYPE_CONTRACTS = {
       "The snake_case, agent-facing view of a blackboard entry — the HTTP-hook boundary shape every caller and agent consumes. Both the read and write halves import this ONE definition.",
     module: "app/blackboard.ts",
   },
+  PlanDep: {
+    category: "type",
+    name: "PlanDep",
+    owner: "app/plan.ts",
+    semantics:
+      "One INTER-epic dependency edge (issue #292): dependent epic `plan_key` waits for producer epic `depends_on_plan_key`, gated by the producer's `{ package, capability_ref }` capability descriptor. Set admission (S2), planner lowering (S3), and operator visibility (S4) all import this ONE row shape from app/plan.ts — no re-declared synonym.",
+    module: "app/plan.ts",
+  },
 } as const satisfies Record<string, TypeContract>;
 
 export const CAPABILITY_URL_CONTRACTS = {

package/app/feature.ts

@@ -181,10 +181,12 @@ export function deriveFeatureDelivery(prStatus: string | null): FeatureDeliveryR
 export const FEATURE_ESCALATION_ELEMENT = "feature-escalation";
 
 /** The parked `feature-escalation` user task, as `pollFeatureEscalations` observes it via
- * `searchUserTasks`: the completable user-task key the pages drive an attributed answer against.
+ *  `openUserTasks` (the open-task-scoped query — issue #294): the completable user-task key the pages
+ *  drive an attributed answer against. Scoping to `state:"CREATED"` is what keeps a looping run — which
+ *  holds COMPLETED prior-round tasks for the same element — from latching the pointer onto a dead task.
  *
  * The agent's `question` is NOT read from here — the WASM testkit engine does not surface a user
- * task's `zeebe:ioMapping`-mapped local variables through `searchUserTasks`, so relying on it would
+ * task's `zeebe:ioMapping`-mapped local variables through the user-task query, so relying on it would
  * make the question untestable. Instead the `record-feature-escalation` service task (feature.bpmn)
  * persists `question` onto the row at escalation entry — see `workers/record-feature-escalation`. */
 export interface FeatureEscalationParked {
@@ -240,8 +242,10 @@ export function deriveFeatureEscalationPatch(
  * `pollFeatureBlocked` reconciles it onto the read model. */
 export const FEATURE_BLOCKED_ELEMENT = "feature-blocked";
 
-/** The parked `feature-blocked` user task, as `pollFeatureBlocked` observes it via `searchUserTasks`:
- * the completable user-task key the pages drive an attributed acknowledgement against. */
+/** The parked `feature-blocked` user task, as `pollFeatureBlocked` observes it via `openUserTasks`
+ *  (the open-task-scoped query — issue #294): the completable user-task key the pages drive an
+ *  attributed acknowledgement against. Scoping to `state:"CREATED"` keeps a re-blocked run — which
+ *  holds COMPLETED prior-round tasks for the same element — from latching the pointer onto a dead task. */
 export interface FeatureBlockedParked {
   userTaskKey: string;
 }

package/app/featureBlocked.test.ts

@@ -49,12 +49,22 @@ function memData(): { data: DataLayer; stores: Record<string, any[]> } {
   return { data, stores };
 }
 
-/** A fake engine whose open user tasks are keyed by processInstanceKey (the only field
- *  pollFeatureBlocked queries on). */
-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 run 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
+ *  pollFeatureBlocked queries on). 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;
 }
 
@@ -133,3 +143,40 @@ test("pollFeatureBlocked: a parked non-blocked task (feature-escalation) does no
 
   assertEquals(stores.feature_runs[0].blocked_user_task_key, null);
 });
+
+// ── Defect-class guard (issue #294): a looping run holds MULTIPLE feature-blocked tasks ────────────
+// The blocked wait sits on a blocked→ack loop, so a re-blocked run holds a COMPLETED feature-blocked
+// task from a prior round alongside the live CREATED one; the engine returns the COMPLETED task first.
+// Scoping the query to open (CREATED) tasks records the live key, never the terminal one.
+test("pollFeatureBlocked: a looping run records the CREATED task, never the COMPLETED one", async () => {
+  const { data, stores } = memData();
+  stores.feature_runs = [
+    { feature_key: "o/r#6", status: "awaiting_operator", process_key: "600", blocked_user_task_key: null },
+  ];
+  const engine = fakeEngine({
+    "600": [
+      { userTaskKey: "ut-completed", elementId: "feature-blocked", state: "COMPLETED" },
+      { userTaskKey: "ut-live", elementId: "feature-blocked", state: "CREATED" },
+    ],
+  });
+
+  await pollFeatureBlocked(data, engine);
+
+  assertEquals(stores.feature_runs[0].blocked_user_task_key, "ut-live");
+});
+
+// Self-heal reached: a run past the blocked wait whose only feature-blocked task is COMPLETED must
+// clear the stale pointer (open-task query returns [] → `parked=null`), not latch it on the dead key.
+test("pollFeatureBlocked: a run whose only feature-blocked task is COMPLETED clears the stale pointer", async () => {
+  const { data, stores } = memData();
+  stores.feature_runs = [
+    { feature_key: "o/r#7", status: "awaiting_operator", process_key: "700", blocked_user_task_key: "ut-7" },
+  ];
+  const engine = fakeEngine({
+    "700": [{ userTaskKey: "ut-7", elementId: "feature-blocked", state: "COMPLETED" }],
+  });
+
+  await pollFeatureBlocked(data, engine);
+
+  assertEquals(stores.feature_runs[0].blocked_user_task_key, null);
+});

package/app/featureEscalation.test.ts

@@ -50,12 +50,22 @@ function memData(): { data: DataLayer; stores: Record<string, any[]> } {
   return { data, stores };
 }
 
-/** A fake engine whose open user tasks are keyed by processInstanceKey (the only field
- *  pollFeatureEscalations queries on). */
-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 run 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
+ *  pollFeatureEscalations queries on). 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;
 }
 
@@ -178,3 +188,48 @@ test("pollFeatureEscalations: a parked non-escalation task (feature-blocked) doe
   assertEquals(stores.feature_runs[0].status, "running");
   assertEquals(stores.feature_runs[0].escalation_user_task_key, null);
 });
+
+// ── Defect-class guard (issue #294): a looping run holds MULTIPLE feature-escalation tasks ─────────
+// A run in an escalate→answer→implement→re-escalate loop holds a COMPLETED feature-escalation task
+// from a prior round alongside the live CREATED one. The engine returns the COMPLETED task first, so a
+// poller that reads UNFILTERED tasks and `.find`s by element latches onto the terminal key — pinning
+// the pointer at a dead task. Scoping the query to open (CREATED) tasks resolves the live one.
+test("pollFeatureEscalations: a looping run resolves the CREATED task, never the COMPLETED one", async () => {
+  const { data, stores } = memData();
+  stores.feature_runs = [
+    { feature_key: "o/r#7", status: "running", process_key: "700", escalation_question: null, escalation_user_task_key: null },
+  ];
+  // Engine returns the COMPLETED (prior-round) task FIRST, then the live CREATED one (issue #294).
+  const engine = fakeEngine({
+    "700": [
+      { userTaskKey: "ut-completed", elementId: "feature-escalation", state: "COMPLETED" },
+      { userTaskKey: "ut-live", elementId: "feature-escalation", state: "CREATED" },
+    ],
+  });
+
+  await pollFeatureEscalations(data, engine);
+
+  assertEquals(stores.feature_runs[0].status, "escalated");
+  // Must be the live CREATED task, not the COMPLETED prior-round one.
+  assertEquals(stores.feature_runs[0].escalation_user_task_key, "ut-live");
+});
+
+// Self-heal reached: once a run finally exits escalation for good, only a lingering COMPLETED
+// feature-escalation task remains. The open-task query returns [], so `parked=null` and the run
+// resets escalated→running — instead of a false-positive pointer built from the terminal task pinning
+// `status='escalated'` forever.
+test("pollFeatureEscalations: a run whose only feature-escalation task is COMPLETED self-heals to running", async () => {
+  const { data, stores } = memData();
+  stores.feature_runs = [
+    { feature_key: "o/r#8", status: "escalated", process_key: "800", escalation_question: "Q", escalation_user_task_key: "ut-8" },
+  ];
+  const engine = fakeEngine({
+    "800": [{ userTaskKey: "ut-8", elementId: "feature-escalation", state: "COMPLETED" }],
+  });
+
+  await pollFeatureEscalations(data, engine);
+
+  assertEquals(stores.feature_runs[0].status, "running");
+  assertEquals(stores.feature_runs[0].escalation_user_task_key, null);
+  assertEquals(stores.feature_runs[0].escalation_question, null);
+});

package/app/github.test.ts

@@ -3,7 +3,7 @@
 // the merge-exclusion graph. Force the token transport and stub `globalThis.fetch`.
 import { test } from "node:test";
 import { assertEquals, assertRejects } from "#test-assert";
-import { BaseBranchMustExistError, coalesceTitle, ensureBaseBranch, fetchIssueTitle, fetchPrFiles, isNotAPullRequestError } from "./github.ts";
+import { BaseBranchMustExistError, coalesceTitle, createPullRequest, ensureBaseBranch, ensurePromotionPr, fetchIssueTitle, fetchPrFiles, isNotAPullRequestError, listPrsForHead } from "./github.ts";
 
 // A fake `fetch` that serves `pages` of file batches; each page N (1-based) returns `pages[N-1]`
 // files (named `f{index}`), setting a `Link: rel="next"` header whenever a later page exists.
@@ -335,3 +335,96 @@ test("coalesceTitle: skips a blank middle candidate to the next non-blank one",
   assertEquals(coalesceTitle("", "Prior title", "owner/repo#1"), "Prior title");
   assertEquals(coalesceTitle(null, "  ", "owner/repo#1"), "owner/repo#1");
 });
+
+// ── Epic promotion PR helpers (issue #299) ──────────────────────────────────
+// The promotion pass opens exactly one `epic/* → <default>` PR per landed epic. These unit tests
+// pin the GitHub token-transport primitives it relies on: reading PRs by head branch (idempotency
+// reconciliation), creating a PR, and the `ensurePromotionPr` reuse-vs-create decision.
+interface FakePulls {
+  repo: string;
+  // head branch → list of PRs opened from it
+  byHead: Map<string, { number: number; state: string; baseRef: string }[]>;
+  creates: { head: string; base: string; number: number }[];
+  next: number;
+}
+
+function pullsFetch(state: FakePulls) {
+  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;
+    if (method === "GET" && path === `/repos/${state.repo}/pulls`) {
+      const head = (u.searchParams.get("head") ?? "").split(":").pop() ?? "";
+      const list = state.byHead.get(head) ?? [];
+      return Promise.resolve(
+        jsonResponse(
+          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 };
+      const head = String(body.head ?? "");
+      const base = String(body.base ?? "");
+      const number = state.next++;
+      state.creates.push({ head, base, number });
+      const arr = state.byHead.get(head) ?? [];
+      arr.push({ number, state: "open", baseRef: base });
+      state.byHead.set(head, arr);
+      return Promise.resolve(jsonResponse({ number, html_url: `https://github.com/${state.repo}/pull/${number}` }, 201));
+    }
+    return Promise.resolve(new Response(`unexpected ${method} ${path}`, { status: 500 }));
+  };
+}
+
+async function withPulls<T>(state: FakePulls, fn: () => Promise<T>): Promise<T> {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevFetch = globalThis.fetch;
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  globalThis.fetch = pullsFetch(state) as typeof fetch;
+  try {
+    return await fn();
+  } finally {
+    globalThis.fetch = prevFetch;
+    if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+  }
+}
+
+function freshPulls(): FakePulls {
+  return { repo: "o/r", byHead: new Map(), creates: [], next: 500 };
+}
+
+test("listPrsForHead: returns the PRs opened from a head branch", async () => {
+  const state = freshPulls();
+  state.byHead.set("epic/x", [{ number: 12, state: "open", baseRef: "main" }]);
+  const list = await withPulls(state, () => listPrsForHead("o/r", "epic/x", "tok"));
+  assertEquals(list?.length, 1);
+  assertEquals(list?.[0].number, 12);
+  assertEquals(list?.[0].baseRef, "main");
+});
+
+test("createPullRequest: opens a PR and returns its number + url", async () => {
+  const state = freshPulls();
+  const pr = await withPulls(state, () => createPullRequest("o/r", "epic/x", "main", "T", "B", "tok"));
+  assertEquals(pr?.number, 500);
+  assertEquals(state.creates.length, 1);
+  assertEquals(state.creates[0].base, "main");
+});
+
+test("ensurePromotionPr: creates when none exists, then reuses on a re-run (idempotent)", async () => {
+  const state = freshPulls();
+  const first = await withPulls(state, () => ensurePromotionPr("o/r", "epic/x", "main", "T", "B", "tok"));
+  assertEquals(first?.created, true);
+  assertEquals(first?.number, 500);
+  const second = await withPulls(state, () => ensurePromotionPr("o/r", "epic/x", "main", "T", "B", "tok"));
+  assertEquals(second?.created, false);
+  assertEquals(second?.number, 500);
+  assertEquals(state.creates.length, 1);
+});

package/app/github.ts

@@ -1091,3 +1091,153 @@ export async function ensureBaseBranch(
   const created = await createBranchRef(repo, branch, defaultSha, token);
   return created ? "created" : "exists";
 }
+
+// ── Epic promotion PR (issue #299) ──────────────────────────────────────────
+// Once an epic's slices have all merged into its `epic/*` integration branch, the poller opens a
+// single `epic/* → <default>` promotion PR to deliver the epic. These helpers are the GitHub side
+// of that: discover an already-open promotion PR (idempotency against a crash between create and
+// the DB write) and, when none exists, create it.
+
+/** A pull request discovered for a head branch — the subset the promotion idempotency check reads. */
+export interface HeadPr {
+  number: number;
+  url: string;
+  state: string;
+  baseRef: string | null;
+}
+
+/** List the PRs (any state) whose HEAD branch is `headBranch` on `repo`. Used to reconcile the
+ * promotion PR idempotently: an `epic/*` integration branch is only ever the HEAD of its promotion
+ * PR (slices target it as their BASE), so any result is that promotion PR. Returns `null` when no
+ * transport is usable (idle — the caller retries next pass). */
+export async function listPrsForHead(
+  repo: string,
+  headBranch: string,
+  token: string,
+): Promise<HeadPr[] | null> {
+  if (await useGh()) {
+    const out = await runGh([
+      "pr",
+      "list",
+      "--repo",
+      repo,
+      "--head",
+      headBranch,
+      "--state",
+      "all",
+      "--json",
+      "number,url,state,baseRefName",
+      "--limit",
+      "20",
+    ]);
+    // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+    const arr = JSON.parse(out) as { number?: number; url?: string; state?: string; baseRefName?: string | null }[];
+    return arr.map((p) => ({
+      number: Number(p.number),
+      url: p.url ?? "",
+      state: (p.state ?? "").toLowerCase(),
+      baseRef: p.baseRefName ?? null,
+    }));
+  }
+  if (!token) return null;
+  const owner = repo.split("/")[0];
+  const r = await fetch(
+    `https://api.github.com/repos/${repo}/pulls?state=all&head=${encodeURIComponent(`${owner}:${headBranch}`)}&per_page=20`,
+    { headers: { authorization: `Bearer ${token}`, accept: "application/vnd.github+json" } },
+  );
+  if (!r.ok) throw new Error(`github ${r.status} ${r.statusText}`.trim());
+  // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+  const arr = (await r.json()) as { number?: number; html_url?: string; state?: string; base?: { ref?: string | null } }[];
+  return arr.map((p) => ({
+    number: Number(p.number),
+    url: p.html_url ?? "",
+    state: (p.state ?? "").toLowerCase(),
+    baseRef: p.base?.ref ?? null,
+  }));
+}
+
+/** The identity of a freshly-created (or reused) PR. */
+export interface CreatedPr {
+  number: number;
+  url: string;
+}
+
+/** Open a pull request from `headBranch` into `baseBranch` on `repo`. Returns the new PR's
+ * number + URL, or `null` when no transport is usable (idle — the caller retries next pass). Throws
+ * on a genuine create failure so the caller logs and retries rather than silently losing the PR. */
+export async function createPullRequest(
+  repo: string,
+  headBranch: string,
+  baseBranch: string,
+  title: string,
+  body: string,
+  token: string,
+): Promise<CreatedPr | null> {
+  if (await useGh()) {
+    const out = await runGh([
+      "pr",
+      "create",
+      "--repo",
+      repo,
+      "--base",
+      baseBranch,
+      "--head",
+      headBranch,
+      "--title",
+      title,
+      "--body",
+      body,
+    ]);
+    // `gh pr create` prints the new PR's URL on stdout; parse its number from the canonical path.
+    const url = out.trim().split(/\s+/).pop() ?? "";
+    const m = url.match(/\/pull\/(\d+)/);
+    if (!m) throw new Error(`could not parse a PR number from \`gh pr create\` output: ${out.trim()}`);
+    return { number: Number(m[1]), url };
+  }
+  if (!token) return null;
+  const r = await fetch(`https://api.github.com/repos/${repo}/pulls`, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${token}`,
+      accept: "application/vnd.github+json",
+      "content-type": "application/json",
+    },
+    body: JSON.stringify({ title, head: headBranch, base: baseBranch, body }),
+  });
+  if (!r.ok) throw new Error(`github ${r.status} ${r.statusText}: ${(await r.text()).slice(0, 300)}`.trim());
+  // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+  const j = (await r.json()) as { number?: number; html_url?: string };
+  return { number: Number(j.number), url: j.html_url ?? "" };
+}
+
+/** The outcome of `ensurePromotionPr`: the promotion PR's number + URL and whether THIS call
+ * created it (`created: false` ⇒ an existing one was reused, keeping the open idempotent). */
+export interface EnsurePromotionPrResult extends CreatedPr {
+  created: boolean;
+}
+
+/** Idempotently guarantee the `headBranch → baseBranch` promotion PR exists on `repo`. First
+ * reconciles against GitHub — an `epic/*` integration branch is only ever the HEAD of its own
+ * promotion PR, so ANY open/merged PR from it IS that promotion PR and is reused (this closes the
+ * window where a crash between GitHub-create and the DB write would otherwise duplicate the PR).
+ * Only when none exists is a new one created. Returns `null` when no transport is usable. */
+export async function ensurePromotionPr(
+  repo: string,
+  headBranch: string,
+  baseBranch: string,
+  title: string,
+  body: string,
+  token: string,
+): Promise<EnsurePromotionPrResult | null> {
+  const existing = await listPrsForHead(repo, headBranch, token);
+  if (existing === null) return null; // no transport → retry next pass
+  // Prefer a PR that already targets the intended base; otherwise reuse any PR from this branch
+  // (the head is unique to the promotion PR, so this can only be it).
+  const reuse = existing.find((p) => p.baseRef === baseBranch) ?? existing[0];
+  if (reuse && Number.isFinite(reuse.number) && reuse.number > 0) {
+    return { number: reuse.number, url: reuse.url, created: false };
+  }
+  const created = await createPullRequest(repo, headBranch, baseBranch, title, body, token);
+  if (!created) return null;
+  return { ...created, created: true };
+}

package/app/migration041.test.ts

@@ -0,0 +1,79 @@
+// Regression guard for migration 041 (issue #292 slice S1): the durable constraints on the INTER-epic
+// `plan_deps` table. The app-layer accessors (app/planDeps.test.ts) enforce self-edge / duplicate
+// rejection for the in-memory data layer; this test proves the SCHEMA itself is the backstop — the
+// migration applies cleanly, a self-edge trips the CHECK, a duplicate consumer→producer pair trips
+// the PRIMARY KEY, and the consumer `plan_key` foreign-keys to an admitted plan.
+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:");
+  db.exec("PRAGMA foreign_keys = ON;");
+  // Minimal `plans` shape the migration's FK references.
+  db.exec("CREATE TABLE plans (plan_key TEXT PRIMARY KEY);");
+  for (const k of ["o/r#1", "o/r#2", "o/r#3"]) {
+    db.prepare("INSERT INTO plans (plan_key) VALUES (?)").run(k);
+  }
+  const sql = readFileSync(
+    fileURLToPath(new URL("../db/migrations/041_inter_epic_plan_deps.sql", import.meta.url)),
+    "utf8",
+  );
+  db.exec(sql);
+  return db;
+}
+
+const insert = (db: DatabaseSync, planKey: string, dependsOn: string) =>
+  db
+    .prepare(
+      `INSERT INTO plan_deps (plan_key, depends_on_plan_key, package, capability_ref, created_at)
+       VALUES (?, ?, '@nanobpm/p', ?, 't')`,
+    )
+    .run(planKey, dependsOn, dependsOn);
+
+test("migration 041 applies cleanly and records a valid inter-epic edge", () => {
+  const db = migratedDb();
+  insert(db, "o/r#2", "o/r#1");
+  const row = db
+    .prepare("SELECT plan_key, depends_on_plan_key, package FROM plan_deps WHERE plan_key = ?")
+    .get("o/r#2") as { plan_key: string; depends_on_plan_key: string; package: string };
+  assertEquals(row.plan_key, "o/r#2");
+  assertEquals(row.depends_on_plan_key, "o/r#1");
+  assertEquals(row.package, "@nanobpm/p");
+});
+
+test("migration 041 CHECK rejects a self-edge", () => {
+  const db = migratedDb();
+  let threw = false;
+  try {
+    insert(db, "o/r#1", "o/r#1");
+  } catch {
+    threw = true;
+  }
+  assertEquals(threw, true);
+});
+
+test("migration 041 PRIMARY KEY rejects a duplicate consumer→producer edge", () => {
+  const db = migratedDb();
+  insert(db, "o/r#2", "o/r#1");
+  let threw = false;
+  try {
+    insert(db, "o/r#2", "o/r#1");
+  } catch {
+    threw = true;
+  }
+  assertEquals(threw, true);
+});
+
+test("migration 041 FK ties the consumer plan_key to an admitted plan", () => {
+  const db = migratedDb();
+  let threw = false;
+  try {
+    insert(db, "o/r#404", "o/r#1");
+  } catch {
+    threw = true;
+  }
+  assertEquals(threw, true);
+});

package/app/migration042.test.ts

@@ -0,0 +1,51 @@
+// Regression guard for migration 042 (issue #299): the promotion columns on `plans`. Proves the
+// migration applies cleanly onto the pre-#299 `plans` shape and that a landed epic can record its
+// promotion PR + state.
+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-#299 `plans` shape the migration extends (only the columns this test touches).
+  db.exec(
+    "CREATE TABLE plans (plan_key TEXT PRIMARY KEY, base_branch TEXT, delivery TEXT, delivery_label TEXT);",
+  );
+  db.prepare("INSERT INTO plans (plan_key, base_branch, delivery) VALUES (?, ?, ?)").run(
+    "o/r#295",
+    "epic/test-dsl",
+    "landed",
+  );
+  const sql = readFileSync(
+    fileURLToPath(new URL("../db/migrations/042_plan_promotion.sql", import.meta.url)),
+    "utf8",
+  );
+  db.exec(sql);
+  return db;
+}
+
+test("migration 042 applies cleanly and adds nullable promotion columns", () => {
+  const db = migratedDb();
+  const row = db
+    .prepare("SELECT promotion_pr, promotion_state FROM plans WHERE plan_key = ?")
+    .get("o/r#295") as { promotion_pr: string | null; promotion_state: string | null };
+  // Grandfathered: both columns default to NULL on the existing row.
+  assertEquals(row.promotion_pr, null);
+  assertEquals(row.promotion_state, null);
+});
+
+test("migration 042 lets a landed epic record its promotion PR + state", () => {
+  const db = migratedDb();
+  db.prepare("UPDATE plans SET promotion_pr = ?, promotion_state = ? WHERE plan_key = ?").run(
+    "o/r#500",
+    "open",
+    "o/r#295",
+  );
+  const row = db
+    .prepare("SELECT promotion_pr, promotion_state FROM plans WHERE plan_key = ?")
+    .get("o/r#295") as { promotion_pr: string; promotion_state: string };
+  assertEquals(row.promotion_pr, "o/r#500");
+  assertEquals(row.promotion_state, "open");
+});