@nanobpm/nano-workforce 0.56.0 → 0.57.0

package/openapi.yaml

@@ -361,9 +361,10 @@ components:
             per-request review-only override; defaults to false (the global auto-merge default applies).
     PlanStart:
       description: The start-plan-fanout request body. Names the target issue by EXACTLY ONE of
-        `issue` (an `owner/repo#123` reference) or `url` (a bare issue URL). Modeled as `oneOf`
-        named variants (Camunda REST v2 pattern) so an ambiguous or empty target is a 400 at the
-        edge, not a silent `issue ?? url` coalesce in the delegate.
+        `issue` (an `owner/repo#123` reference) or `url` (a bare issue URL), plus a REQUIRED
+        `baseBranch` (ADR 0003) the fleet branches off — a blank/absent base is a 400. Modeled as
+        `oneOf` named variants (Camunda REST v2 pattern) so an ambiguous or empty target is a 400 at
+        the edge, not a silent `issue ?? url` coalesce in the delegate.
       oneOf:
         - $ref: "#/components/schemas/PlanStartByIssue"
         - $ref: "#/components/schemas/PlanStartByUrl"
@@ -372,33 +373,77 @@ components:
       additionalProperties: false
       required:
         - issue
+        - baseBranch
       properties:
         issue:
           type: string
           description: "Issue reference: owner/repo#123."
         baseBranch:
           type: string
+          minLength: 1
+          maxLength: 255
+          pattern: '\S'
+          description: >-
+            REQUIRED target branch the fleet branches off and opens every PR against. Every epic
+            launch must name its base explicitly (ADR 0003): a blank/absent value is rejected with a
+            400, not silently coalesced to the repository default branch. Use it to land an entire
+            epic on a long-lived integration branch (e.g. `epic/agent-protocol`) so nothing reaches
+            the default branch — and any merge-to-default side effect, such as auto-publishing a
+            package — until you deliberately merge the integration branch. NOTE: this slice (B0)
+            only enforces that `baseBranch` is present and a plausible branch name; branch-existence
+            admission (auto-creating a missing `epic/*` base off the default branch HEAD, and
+            rejecting a missing non-`epic/*` base with a 400) is specified by ADR 0003 but NOT yet
+            enforced here — it lands in a later admission slice.
+        allowSharedBase:
+          type: boolean
+          description: >-
+            Reserved for a later ADR 0003 admission slice — NOT yet enforced in this slice (B0). When
+            implemented it will opt in to sharing a custom integration base branch with another
+            already-active plan: admission will otherwise reject (409) when another active plan already
+            targets the same repo + same custom base branch, to stop two epics interleaving commits on
+            one integration branch (the repository default branch is exempt from that guard). Accepted
+            by the schema today but currently has no runtime effect.
+        confirmDefaultBase:
+          type: boolean
           description: >-
-            Optional target branch the fleet branches off and opens every PR against, instead of the
-            repository's default branch. Use this to land an entire epic on a long-lived integration
-            branch (e.g. `epic/agent-protocol`) so nothing reaches the default branch — and any
-            merge-to-default side effect, such as auto-publishing a package — until you deliberately
-            merge the integration branch. Blank/omitted keeps the current behaviour (the repo
-            default branch).
+            Reserved for a later ADR 0003 admission slice — NOT yet enforced in this slice (B0). When
+            implemented it will be the required acknowledgement when `baseBranch` names the repository
+            default branch: targeting the default lands every task directly on it with no integration
+            buffer — and fires any merge-to-default side effect per task — so admission will reject
+            (400) unless confirmed with true (no effect for a non-default base). Accepted by the schema
+            today but currently has no runtime effect.
     PlanStartByUrl:
       type: object
       additionalProperties: false
       required:
         - url
+        - baseBranch
       properties:
         url:
           type: string
           description: A bare issue URL, when no `owner/repo#123` reference is supplied.
         baseBranch:
           type: string
+          minLength: 1
+          maxLength: 255
+          pattern: '\S'
+          description: >-
+            REQUIRED target branch the fleet branches off and opens every PR against. See
+            `PlanStartByIssue.baseBranch`.
+        allowSharedBase:
+          type: boolean
+          description: >-
+            Reserved for a later ADR 0003 admission slice — NOT yet enforced in this slice (B0).
+            Accepted by the schema today but currently has no runtime effect. When implemented it
+            will opt in to sharing a custom integration base branch with another already-active plan.
+            See `PlanStartByIssue.allowSharedBase`.
+        confirmDefaultBase:
+          type: boolean
           description: >-
-            Optional target branch the fleet branches off and opens every PR against, instead of the
-            repository's default branch. See `PlanStartByIssue.baseBranch`.
+            Reserved for a later ADR 0003 admission slice — NOT yet enforced in this slice (B0).
+            Accepted by the schema today but currently has no runtime effect. When implemented it
+            will be the required acknowledgement when `baseBranch` names the repository default
+            branch. See `PlanStartByIssue.confirmDefaultBase`.
     MessageResult:
       type: object
       description: The result of publishing a message / answering an escalation. Shape varies by message

package/operations/startAndMessage.test.ts

@@ -12,6 +12,7 @@ import { noopLog } from "../test/log.ts";
 import startConvergenceLoop from "./startConvergenceLoop.ts";
 import startPlanFanout from "./startPlanFanout.ts";
 import postMessage from "./postMessage.ts";
+import { resetDefaultBranchCache } from "../app/github.ts";
 
 const app = { log: noopLog() } as any as AppApi;
 
@@ -72,13 +73,60 @@ function withGithubOff(run: () => Promise<void>): Promise<void> {
   const prevTok = process.env["GITHUB_TOKEN"];
   process.env["NANO_PR_GITHUB_TRANSPORT"] = "token"; // no token → meta fetch is skipped
   delete process.env["GITHUB_TOKEN"];
+  resetDefaultBranchCache(); // start cold so a prior warmed cache can't mask the no-transport path
   return run().finally(() => {
+    resetDefaultBranchCache();
     if (prev !== undefined) process.env["NANO_PR_GITHUB_TRANSPORT"] = prev;
     else delete process.env["NANO_PR_GITHUB_TRANSPORT"];
     if (prevTok !== undefined) process.env["GITHUB_TOKEN"] = prevTok;
   });
 }
 
+// Force the token transport with a stubbed `globalThis.fetch` that serves a minimal in-memory
+// github model, so `admitPlan` (which now calls `ensureBaseBranch` + `fetchDefaultBranch`) can run
+// without touching the network. The default branch is `main`; an epic/* base is auto-created off it.
+function withGithubStub(run: () => Promise<void>): Promise<void> {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevTok = process.env["GITHUB_TOKEN"];
+  const prevFetch = globalThis.fetch;
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  process.env["GITHUB_TOKEN"] = "tok";
+  resetDefaultBranchCache(); // isolate: don't inherit or leak the owner/repo default-branch entry
+  const branches = new Map<string, string>([["main", "mainsha"]]);
+  globalThis.fetch = ((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) =>
+      new Response(JSON.stringify(obj), { status, headers: { "content-type": "application/json" } });
+    if (method === "GET" && path === "/repos/owner/repo") return Promise.resolve(json({ default_branch: "main" }));
+    const refPrefix = "/repos/owner/repo/git/ref/heads/";
+    if (method === "GET" && path.startsWith(refPrefix)) {
+      const branch = decodeURIComponent(path.slice(refPrefix.length));
+      const sha = branches.get(branch);
+      if (sha === undefined) return Promise.resolve(new Response("Not Found", { status: 404 }));
+      return Promise.resolve(json({ ref: `refs/heads/${branch}`, object: { sha } }));
+    }
+    if (method === "POST" && path === "/repos/owner/repo/git/refs") {
+      // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+      const body = JSON.parse(String(init?.body ?? "{}")) as { ref?: string; sha?: string };
+      const branch = String(body.ref ?? "").replace(/^refs\/heads\//, "");
+      if (branches.has(branch)) return Promise.resolve(json({ message: "Reference already exists" }, 422));
+      branches.set(branch, String(body.sha ?? ""));
+      return Promise.resolve(json({ ref: body.ref }, 201));
+    }
+    return Promise.resolve(new Response(`unexpected ${method} ${path}`, { status: 500 }));
+  }) as typeof fetch;
+  return run().finally(() => {
+    resetDefaultBranchCache();
+    globalThis.fetch = prevFetch;
+    if (prevMode !== undefined) process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+    else delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    if (prevTok !== undefined) process.env["GITHUB_TOKEN"] = prevTok;
+    else delete process.env["GITHUB_TOKEN"];
+  });
+}
+
 test("startConvergenceLoop → 400 (not 500) on a missing request body", async () => {
   const res = await startConvergenceLoop(input(undefined), app);
   const r = res as any;
@@ -133,6 +181,15 @@ test("startPlanFanout → 400 on an invalid baseBranch (not persisted/rendered)"
   assertEquals(typeof r.body.error, "string");
 });
 
+test("startPlanFanout → 400 on a missing baseBranch (not persisted/rendered)", async () => {
+  // A blank/absent baseBranch must be rejected at the edge as a 400 (MissingBaseBranchError),
+  // never silently coalesced to the repository default branch (ADR 0003, B0).
+  const res = await startPlanFanout(input({ issue: "owner/repo#123" }), app);
+  const r = res as any;
+  assertEquals(r.status, 400);
+  assertEquals(typeof r.body.error, "string");
+});
+
 test("startConvergenceLoop narrows the `url` variant (no `pr` key)", async () => {
   await withGithubOff(async () => {
     const { app: capApp } = captureApp();
@@ -142,9 +199,12 @@ test("startConvergenceLoop narrows the `url` variant (no `pr` key)", async () =>
 });
 
 test("startPlanFanout narrows the `url` variant (no `issue` key)", async () => {
-  await withGithubOff(async () => {
+  await withGithubStub(async () => {
     const { app: capApp } = captureApp();
-    const res = await startPlanFanout(input({ url: "https://github.com/owner/repo/issues/12" }), capApp);
+    const res = await startPlanFanout(
+      input({ url: "https://github.com/owner/repo/issues/12", baseBranch: "epic/agent-protocol" }),
+      capApp,
+    );
     assertEquals((res as any).status, 202);
   });
 });

package/operations/startPlanFanout.admission.integration.test.ts

@@ -0,0 +1,263 @@
+// Integration coverage for the base-branch ADMISSION gate (ADR 0003) driven through the operation
+// EDGE — `startPlanFanout` → `admitPlan` → HTTP status. The unit tests in app/plan.test.ts already
+// prove `admitPlan`'s decision matrix in isolation; this file proves the COMPOSED behaviour at the
+// door: each admission rule maps to the correct HTTP status (400 / 409) and each accept path reaches
+// the 202 fan-out. It runs the real delegate against an in-memory app/data/engine and a faked github
+// transport (token mode + stubbed `globalThis.fetch`) — no network, deterministic on a single run.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { resetDefaultBranchCache } from "../app/github.ts";
+import { noopLog } from "../test/log.ts";
+import startPlanFanout from "./startPlanFanout.ts";
+
+// ── in-memory github model ───────────────────────────────────────────────────
+// A minimal fake of the GitHub REST surface `admitPlan` touches: the repo-meta GET (default branch),
+// the ref GET (branch existence, returning a synthetic per-branch head sha) and the ref-create POST.
+// `default_branch` is `main`; a missing `epic/*` base is auto-created off the default branch's head
+// sha (which `admitPlan` reads via the ref GET, so here that is `main-sha`). `creates` records the
+// full ref-create POST body (`ref` + `sha`) so a test can assert a branch was (or was NOT) created
+// AND that the create payload points the new ref at the resolved base sha, not a stale/blank value.
+interface GithubState {
+  repo: string;
+  defaultBranch: string;
+  branches: Set<string>;
+  creates: { ref: string; sha: string }[];
+}
+
+function githubFetch(state: GithubState) {
+  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) =>
+      new Response(JSON.stringify(obj), { status, headers: { "content-type": "application/json" } });
+    if (method === "GET" && path === `/repos/${state.repo}`) {
+      return Promise.resolve(json({ default_branch: state.defaultBranch }));
+    }
+    const refPrefix = `/repos/${state.repo}/git/ref/heads/`;
+    if (method === "GET" && path.startsWith(refPrefix)) {
+      const branch = decodeURIComponent(path.slice(refPrefix.length));
+      if (!state.branches.has(branch)) return Promise.resolve(new Response("Not Found", { status: 404 }));
+      return Promise.resolve(json({ ref: `refs/heads/${branch}`, object: { sha: `${branch}-sha` } }));
+    }
+    if (method === "POST" && path === `/repos/${state.repo}/git/refs`) {
+      // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+      const body = JSON.parse(String(init?.body ?? "{}")) as { ref?: string; sha?: string };
+      const ref = String(body.ref ?? "");
+      const sha = String(body.sha ?? "");
+      const branch = ref.replace(/^refs\/heads\//, "");
+      if (state.branches.has(branch)) return Promise.resolve(json({ message: "Reference already exists" }, 422));
+      state.creates.push({ ref, sha });
+      state.branches.add(branch);
+      return Promise.resolve(json({ ref }, 201));
+    }
+    return Promise.resolve(new Response(`unexpected ${method} ${path}`, { status: 500 }));
+  };
+}
+
+async function withGithub<T>(state: GithubState, fn: () => Promise<T>): Promise<T> {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevTok = process.env["GITHUB_TOKEN"];
+  const prevFetch = globalThis.fetch;
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  process.env["GITHUB_TOKEN"] = "tok";
+  resetDefaultBranchCache(); // isolate: don't inherit or leak another test's default-branch entry
+  globalThis.fetch = githubFetch(state) as typeof fetch;
+  try {
+    return await fn();
+  } finally {
+    resetDefaultBranchCache();
+    globalThis.fetch = prevFetch;
+    if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+    if (prevTok === undefined) delete process.env["GITHUB_TOKEN"];
+    else process.env["GITHUB_TOKEN"] = prevTok;
+  }
+}
+
+// ── in-memory app (data + engine) ────────────────────────────────────────────
+// A generic table over an array, matching the DataLayer surface `startPlan`/`findActivePlansByBase`
+// use (get/find/insert/update/delete). `seedPlans` pre-loads the `plans` table so the shared-base
+// guard has active rows to find. `started` records each engine.createInstance call so an accept path
+// can be asserted to have fanned out.
+function makeApp(seedPlans: Record<string, unknown>[] = []) {
+  const tables = new Map<string, Record<string, unknown>[]>();
+  tables.set("plans", [...seedPlans]);
+  const started: { processDefinitionId: string; variables?: Record<string, unknown> }[] = [];
+  const table = (name: string, key: string) => {
+    const rows = tables.get(name) ?? (() => {
+      const fresh: Record<string, unknown>[] = [];
+      tables.set(name, fresh);
+      return fresh;
+    })();
+    return {
+      get: (k: unknown) => Promise.resolve(rows.find((r) => r[key] === k) ?? null),
+      find: (q: Record<string, unknown>) =>
+        Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+      insert: (r: Record<string, unknown>) => {
+        rows.push(r);
+        return Promise.resolve(r);
+      },
+      update: (k: unknown, patch: Record<string, unknown>) => {
+        const row = rows.find((r) => r[key] === k);
+        if (row) Object.assign(row, patch);
+        return Promise.resolve(row);
+      },
+      delete: (k: unknown) => {
+        const i = rows.findIndex((r) => r[key] === k);
+        if (i >= 0) rows.splice(i, 1);
+        return Promise.resolve();
+      },
+    };
+  };
+  const app = {
+    data: { table },
+    engine: {
+      createInstance: (req: { processDefinitionId: string; variables?: Record<string, unknown> }) => {
+        started.push(req);
+        return Promise.resolve({ processInstanceKey: "PI-1" });
+      },
+    },
+    log: noopLog(),
+  } as any as AppApi;
+  return { app, started };
+}
+
+function input(body: unknown) {
+  return {
+    req: { method: "POST", path: "/", query: new URLSearchParams(), headers: new Headers(), text: async () => "" } as any,
+    params: {},
+    query: {},
+    body,
+  };
+}
+
+function freshGithub(repo: string, extraBranches: string[] = []): GithubState {
+  return { repo, defaultBranch: "main", branches: new Set(["main", ...extraBranches]), creates: [] };
+}
+
+// ── Rule 1 — required + explicit ──────────────────────────────────────────────
+
+// Rule 1 rejects both a MISSING baseBranch field and an explicit blank/whitespace
+// one — the latter is a distinct edge input that must not slip past as a "present"
+// value. Table-drive both so the required-and-explicit rule is covered end to end.
+for (const [label, body] of [
+  ["missing field", { issue: "owner/repo#1" }],
+  ["empty string", { issue: "owner/repo#1", baseBranch: "" }],
+  ["whitespace only", { issue: "owner/repo#1", baseBranch: "   " }],
+] as const) {
+  test(`edge: ${label} baseBranch → 400`, async () => {
+    const gh = freshGithub("owner/repo");
+    await withGithub(gh, async () => {
+      const { app, started } = makeApp();
+      const res = (await startPlanFanout(input(body), app)) as any;
+      assertEquals(res.status, 400);
+      assertEquals(typeof res.body.error, "string");
+      assertEquals(started.length, 0); // rejected before any fan-out
+      assertEquals(gh.creates, []); // no ref created on a rejected input
+    });
+  });
+}
+
+// ── Rule 2 — create-if-missing (epic/* guard), synchronously at the edge ──────
+
+test("edge: non-epic/* base that does not exist → 400 (BaseBranchMustExistError path)", async () => {
+  // A typo'd, non-epic/* base is NOT auto-created — admitPlan throws BaseBranchMustExistError
+  // synchronously, which the delegate maps to a clean 400 at the door (not a late per-task failure).
+  const gh = freshGithub("owner/repo"); // "release-9" absent, not epic/* → must-exist
+  await withGithub(gh, async () => {
+    const { app, started } = makeApp();
+    const res = (await startPlanFanout(input({ issue: "owner/repo#2", baseBranch: "release-9" }), app)) as any;
+    assertEquals(res.status, 400);
+    assertEquals(typeof res.body.error, "string");
+    assertEquals(started.length, 0);
+    assertEquals(gh.creates, []); // never created
+  });
+});
+
+test("edge: missing epic/* base → created off default HEAD, then 202", async () => {
+  const gh = freshGithub("owner/repo"); // epic/new absent → auto-created off main
+  await withGithub(gh, async () => {
+    const { app, started } = makeApp();
+    const res = (await startPlanFanout(input({ issue: "owner/repo#3", baseBranch: "epic/new" }), app)) as any;
+    assertEquals(res.status, 202);
+    // Created off the resolved base sha: the ref-create payload names epic/new AND points it at the
+    // default branch's head sha (`main-sha` here), proving the create body carries the base sha.
+    assertEquals(gh.creates, [{ ref: "refs/heads/epic/new", sha: "main-sha" }]);
+    assertEquals(started.length, 1);
+  });
+});
+
+// ── Rule 3 — confirm-default ──────────────────────────────────────────────────
+
+test("edge: target == default branch WITHOUT confirmDefaultBase → 400", async () => {
+  const gh = freshGithub("owner/repo"); // base "main" IS the default
+  await withGithub(gh, async () => {
+    const { app, started } = makeApp();
+    const res = (await startPlanFanout(input({ issue: "owner/repo#4", baseBranch: "main" }), app)) as any;
+    assertEquals(res.status, 400);
+    assertEquals(typeof res.body.error, "string");
+    assertEquals(started.length, 0);
+  });
+});
+
+test("edge: target == default branch WITH confirmDefaultBase → 202", async () => {
+  const gh = freshGithub("owner/repo");
+  await withGithub(gh, async () => {
+    const { app, started } = makeApp();
+    const res = (await startPlanFanout(
+      input({ issue: "owner/repo#5", baseBranch: "main", confirmDefaultBase: true }),
+      app,
+    )) as any;
+    assertEquals(res.status, 202);
+    assertEquals(started.length, 1);
+  });
+});
+
+// ── Rule 4 — shared-base guard ────────────────────────────────────────────────
+
+test("edge: active plan on the same CUSTOM base WITHOUT allowSharedBase → 409", async () => {
+  const gh = freshGithub("owner/repo", ["epic/shared"]); // base exists → ensureBaseBranch no-ops
+  await withGithub(gh, async () => {
+    // A DIFFERENT active plan already targets epic/shared on this repo.
+    const { app, started } = makeApp([
+      { plan_key: "owner/repo#98", repo: "owner/repo", base_branch: "epic/shared", status: "planning" },
+    ]);
+    const res = (await startPlanFanout(input({ issue: "owner/repo#6", baseBranch: "epic/shared" }), app)) as any;
+    assertEquals(res.status, 409);
+    assertEquals(typeof res.body.error, "string");
+    assertEquals(started.length, 0);
+  });
+});
+
+test("edge: same CUSTOM base WITH allowSharedBase → 202", async () => {
+  const gh = freshGithub("owner/repo", ["epic/shared"]);
+  await withGithub(gh, async () => {
+    const { app, started } = makeApp([
+      { plan_key: "owner/repo#98", repo: "owner/repo", base_branch: "epic/shared", status: "planning" },
+    ]);
+    const res = (await startPlanFanout(
+      input({ issue: "owner/repo#7", baseBranch: "epic/shared", allowSharedBase: true }),
+      app,
+    )) as any;
+    assertEquals(res.status, 202);
+    assertEquals(started.length, 1);
+  });
+});
+
+test("edge: two plans sharing the DEFAULT branch → 202 (default is exempt from the shared-base guard)", async () => {
+  const gh = freshGithub("owner/repo"); // base "main" == default → exempt
+  await withGithub(gh, async () => {
+    // An active plan already targets main; a second one is still admitted (confirmed default).
+    const { app, started } = makeApp([
+      { plan_key: "owner/repo#97", repo: "owner/repo", base_branch: "main", status: "planning" },
+    ]);
+    const res = (await startPlanFanout(
+      input({ issue: "owner/repo#8", baseBranch: "main", confirmDefaultBase: true }),
+      app,
+    )) as any;
+    assertEquals(res.status, 202);
+    assertEquals(started.length, 1);
+  });
+});

package/operations/startPlanFanout.ts

@@ -10,7 +10,16 @@
 // ONE of `issue` or `url` — so an empty or ambiguous target is a 400 at the edge; this delegate just
 // narrows the validated variant and keeps the issue-FORMAT parse guard (schema can't express it).
 
-import { InvalidBaseBranchError, normalizeBaseBranch, parseIssue, startPlan } from "../app/plan.ts";
+import { BaseBranchMustExistError } from "../app/github.ts";
+import {
+  admitPlan,
+  DefaultBaseNotConfirmedError,
+  InvalidBaseBranchError,
+  MissingBaseBranchError,
+  parseIssue,
+  SharedBaseError,
+  startPlan,
+} from "../app/plan.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 export default defineOperation("startPlanFanout", async ({ body }, app) => {
@@ -26,16 +35,29 @@ export default defineOperation("startPlanFanout", async ({ body }, app) => {
     app.log.warn("start-plan rejected: unparseable issue reference", { raw });
     return { status: 400, body: { error: "could not parse issue (use owner/repo#123 or an issue URL)" } };
   }
-  // Optional epic base branch: the branch the fleet branches off and opens every PR against instead
-  // of the repo default. Present on both oneOf variants; blank/absent keeps the default-branch
-  // behaviour. It is later interpolated into the authoritative implementer prompt (with `git`/`gh`
-  // shell snippets), so validate/normalise it HERE — a non-blank value that isn't a plausible git
-  // branch name is a 400 at the edge, never persisted or rendered. `normalizeBaseBranch` blank → null.
-  const baseBranch = "baseBranch" in body && typeof body.baseBranch === "string" ? body.baseBranch : null;
-  let normalizedBase: string | null;
+  // Epic base branch (ADR 0003): admit the launch through the fail-fast `admitPlan` gate BEFORE any
+  // fan-out. It composes the four ordered admission rules — required+explicit, create-if-missing
+  // (epic/* guard, run synchronously so a typo is a clean edge 400), confirm-default, and
+  // shared-base — and returns the normalized base. Errors map to specific HTTP statuses at the edge.
+  const rawBase = "baseBranch" in body && typeof body.baseBranch === "string" ? body.baseBranch : null;
+  const allowSharedBase = "allowSharedBase" in body && body.allowSharedBase === true;
+  const confirmDefaultBase = "confirmDefaultBase" in body && body.confirmDefaultBase === true;
+  const token = process.env.GITHUB_TOKEN ?? "";
+  let normalizedBase: string;
   try {
-    normalizedBase = normalizeBaseBranch(baseBranch);
+    normalizedBase = await admitPlan(app.data, parsed.repo, rawBase, token, {
+      allowSharedBase,
+      confirmDefaultBase,
+      selfPlanKey: parsed.planKey,
+    });
   } catch (err) {
+    if (err instanceof MissingBaseBranchError) {
+      app.log.warn("start-plan rejected: missing base branch");
+      return {
+        status: 400,
+        body: { error: "baseBranch is required (name the integration branch, e.g. epic/agent-protocol)" },
+      };
+    }
     if (err instanceof InvalidBaseBranchError) {
       app.log.warn("start-plan rejected: invalid base branch", { baseBranch: err.value });
       return {
@@ -43,13 +65,50 @@ export default defineOperation("startPlanFanout", async ({ body }, app) => {
         body: { error: "invalid baseBranch (must be a plausible git branch name, e.g. epic/agent-protocol)" },
       };
     }
+    if (err instanceof BaseBranchMustExistError) {
+      app.log.warn("start-plan rejected: base branch does not exist", { baseBranch: err.branch });
+      return {
+        status: 400,
+        body: {
+          error:
+            `baseBranch "${err.branch}" does not exist and is not an epic/* branch, so it is not ` +
+            `auto-created — create it first, or use the epic/* convention`,
+        },
+      };
+    }
+    if (err instanceof DefaultBaseNotConfirmedError) {
+      app.log.warn("start-plan rejected: default base not confirmed", { baseBranch: err.branch });
+      return {
+        status: 400,
+        body: {
+          error:
+            `baseBranch "${err.branch}" is the repository default branch — every task would land ` +
+            `directly on it with no integration branch. Re-submit with confirmDefaultBase: true to proceed`,
+        },
+      };
+    }
+    if (err instanceof SharedBaseError) {
+      app.log.warn("start-plan rejected: shared base branch", { baseBranch: err.branch });
+      return {
+        status: 409,
+        body: {
+          error:
+            `baseBranch "${err.branch}" is already in use by another active epic. Re-submit with ` +
+            `allowSharedBase: true to stack on it, or name a distinct epic/* branch`,
+        },
+      };
+    }
     throw err;
   }
   const result = await startPlan(app.data, app.engine, parsed, normalizedBase);
+  const alreadyRunning = "alreadyRunning" in result && result.alreadyRunning === true;
   app.log.info("plan fan-out started", {
     planKey: parsed.planKey,
-    baseBranch: normalizedBase ?? "(default branch)",
-    alreadyRunning: "alreadyRunning" in result && result.alreadyRunning === true,
+    // The base the caller requested. When `alreadyRunning`, `startPlan` short-circuits before this
+    // base takes effect (it may not match the in-flight plan's persisted base), so name it as the
+    // request — not the effective base — to keep the log honest.
+    requestedBaseBranch: normalizedBase,
+    alreadyRunning,
   });
   return { status: 202, body: result };
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.56.0",
+  "version": "0.57.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.page.json

@@ -38,7 +38,9 @@
         "action": { "path": "/app/api/actions/start/plan-fanout", "body": "{{form}}" },
         "fields": [
           { "key": "issue", "label": "owner/repo#123 or a GitHub issue URL", "type": "text" },
-          { "key": "baseBranch", "label": "Base branch (blank = repo default; e.g. epic/agent-protocol to land the whole epic on an integration branch)", "type": "text" }
+          { "key": "baseBranch", "label": "Base branch (REQUIRED; e.g. epic/agent-protocol to land the whole epic on an integration branch). A missing epic/* branch is auto-created off default HEAD; a non-epic/* branch must already exist.", "type": "text" },
+          { "key": "confirmDefaultBase", "label": "Confirm landing on the default branch \u2014 required only when the base above IS the repository default (every task lands directly on it, with any merge-to-default side effect firing per task)", "type": "checkbox" },
+          { "key": "allowSharedBase", "label": "Allow sharing a custom integration branch with another active epic \u2014 required only when another in-flight epic already targets this same custom base", "type": "checkbox" }
         ]
       }
     },
@@ -70,6 +72,7 @@
         "columns": [
           { "field": "plan_key", "header": "Epic", "link": { "kind": "page", "page": "epic-detail", "keyField": "plan_key" } },
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
+          { "field": "base_branch", "header": "Base branch" },
           { "field": "wave_label", "header": "Wave" },
           { "field": "task_count", "header": "Tasks" },
           { "field": "open_plan_findings", "header": "Attention", "badge": { "tone": "danger", "label": "!" } },