@nanobpm/nano-workforce 0.55.0 → 0.57.0

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.55.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/cockpit/cockpit.css

@@ -131,6 +131,23 @@
 
 .cockpit-worker:hover { color: #58a6ff; }
 
+.cockpit-supply-process { color: var(--cockpit-muted); }
+
+.cockpit-correlation {
+  background: none;
+  border: none;
+  color: var(--cockpit-text);
+  cursor: pointer;
+  display: block;
+  font: inherit;
+  padding: 0;
+  text-align: left;
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.cockpit-correlation:hover { color: #58a6ff; }
+
 .cockpit-supply-liveness { color: var(--cockpit-muted); }
 
 .cockpit-supply-empty {

package/pages/cockpit/mount.js

@@ -33,8 +33,21 @@ function liveness(worker, staleAfterMs) {
   return worker.staleMs >= staleAfterMs ? "stale" : "live";
 }
 
-function workerView(worker, staleAfterMs) {
+function correlationLabel(c) {
+  const parts = [];
+  if (c.bpmnProcessId != null) parts.push(c.bpmnProcessId);
+  if (c.elementId != null) parts.push(c.elementId);
+  if (c.processInstanceKey != null) parts.push(`inst ${c.processInstanceKey}`);
+  if (c.planKey != null) parts.push(c.planKey);
+  return parts.length > 0 ? parts.join(" \u00b7 ") : `job ${c.jobKey}`;
+}
+
+function workerView(worker, staleAfterMs, byJobKey) {
   const jobKeys = [...(worker.jobKeys ?? [])].sort((a, b) => a.localeCompare(b));
+  const correlations = jobKeys
+    .map((jobKey) => byJobKey.get(jobKey))
+    .filter((c) => c != null)
+    .map((c) => ({ jobKey: c.jobKey, stream: c.stream, label: correlationLabel(c) }));
   return {
     instance: worker.instance,
     identity: worker.identity,
@@ -43,6 +56,7 @@ function workerView(worker, staleAfterMs) {
     host: worker.host ?? "\u2014",
     jobKeys,
     jobs: jobKeys.length,
+    correlations,
     liveness: liveness(worker, staleAfterMs),
     staleMs: worker.staleMs,
   };
@@ -50,9 +64,11 @@ function workerView(worker, staleAfterMs) {
 
 function supplyView(report, staleAfterMs) {
   const byInstance = (a, b) => a.instance.localeCompare(b.instance);
+  const byJobKey = new Map();
+  for (const c of report.correlations ?? []) byJobKey.set(c.jobKey, c);
   const leaves = (report.leaves ?? [])
     .map((leaf) => {
-      const workers = leaf.workers.map((w) => workerView(w, staleAfterMs)).sort(byInstance);
+      const workers = leaf.workers.map((w) => workerView(w, staleAfterMs, byJobKey)).sort(byInstance);
       return {
         token: leaf.token,
         workers,
@@ -61,7 +77,7 @@ function supplyView(report, staleAfterMs) {
       };
     })
     .sort((a, b) => a.token.localeCompare(b.token));
-  const workers = (report.workers ?? []).map((w) => workerView(w, staleAfterMs)).sort(byInstance);
+  const workers = (report.workers ?? []).map((w) => workerView(w, staleAfterMs, byJobKey)).sort(byInstance);
   return { leaves, workers, count: workers.length, live: workers.filter((w) => w.liveness === "live").length };
 }
 
@@ -100,6 +116,21 @@ function workerRow(doc, worker, onDrill) {
   const jobsCell = el(doc, "td", "cockpit-td cockpit-supply-jobs", worker.jobs === 0 ? "\u2014" : worker.jobKeys.join(", "));
   jobsCell.setAttribute("data-jobs", String(worker.jobs));
   row.appendChild(jobsCell);
+  const processCell = el(doc, "td", "cockpit-td cockpit-supply-process");
+  processCell.setAttribute("data-correlations", String(worker.correlations.length));
+  if (worker.correlations.length === 0) {
+    processCell.textContent = "\u2014";
+  } else {
+    for (const correlation of worker.correlations) {
+      const link = el(doc, "button", "cockpit-correlation", correlation.label);
+      link.setAttribute("type", "button");
+      link.setAttribute("data-job-key", correlation.jobKey);
+      link.setAttribute("data-stream", correlation.stream);
+      if (onDrill) link.addEventListener("click", () => onDrill(correlation.stream));
+      processCell.appendChild(link);
+    }
+  }
+  row.appendChild(processCell);
   const livenessCell = el(doc, "td", "cockpit-td cockpit-supply-liveness", worker.liveness);
   livenessCell.setAttribute("data-liveness", worker.liveness);
   row.appendChild(livenessCell);
@@ -116,7 +147,7 @@ function leafSection(doc, leaf, onDrill) {
   const table = el(doc, "table", "cockpit-supply-table");
   const thead = el(doc, "thead", "cockpit-supply-thead");
   const head = el(doc, "tr", "cockpit-supply-head");
-  for (const label of ["worker", "family", "host", "jobs", "liveness"]) head.appendChild(el(doc, "th", "cockpit-th", label));
+  for (const label of ["worker", "family", "host", "jobs", "process / plan", "liveness"]) head.appendChild(el(doc, "th", "cockpit-th", label));
   thead.appendChild(head);
   table.appendChild(thead);
   const tbody = el(doc, "tbody", "cockpit-supply-tbody");

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": "!" } },

package/resources/agent-guide.md

@@ -97,13 +97,49 @@ PR is then enrolled into its own convergence loop (§1).
 ```bash
 curl -sS -X POST __BASE__/actions/start/plan-fanout \
   -H 'content-type: application/json' \
-  -d '{ "issue": "owner/repo#123" }'
+  -d '{ "issue": "owner/repo#123", "baseBranch": "epic/agent-protocol" }'
 ```
 
-The body is flat: `issue` (or `url`) — `owner/repo#123` or an issue URL. Starting a
+The body is flat: `issue` (or `url`) — `owner/repo#123` or an issue URL — plus a REQUIRED
+`baseBranch` (ADR 0003), the branch the fleet branches off and opens every PR against; a
+blank/absent base is rejected with a 400. Starting a
 plan is idempotent on the plan key; an already-running plan short-circuits. The
 response (202) echoes the `planKey` and engine `processKey`.
 
+### Base-branch admission (ADR 0003)
+
+`startPlanFanout` admits the base through one fail-fast gate before any task fans out.
+Four ordered rules govern which base is accepted:
+
+1. **Required + explicit.** `baseBranch` is mandatory — a blank/absent value is a `400`
+   (`MissingBaseBranchError`), and an implausible name is a `400` (`InvalidBaseBranchError`).
+   There is no silent "land on the default branch" fallback.
+2. **Create-if-missing, `epic/*` only.** A missing `epic/*` base is **auto-created** off the
+   repository default branch's HEAD (idempotently — an existing branch is never reset). A
+   missing base that is **not** `epic/*` is a clean `400` (`BaseBranchMustExistError`): a typo
+   can't silently spawn a wrong-rooted branch, so any non-`epic/*` base must already exist.
+3. **Confirm-default.** Naming the repository **default branch** as the base requires
+   `confirmDefaultBase: true`, else `400` (`DefaultBaseNotConfirmedError`). This is a
+   deliberate acknowledgement that every task lands directly on the default branch with no
+   integration buffer, and any merge-to-default side effect fires per task.
+4. **Shared-base guard.** If another **active** epic (status not `done`/`failed`/`abandoned`)
+   already targets the **same repo + same custom base**, admission is a `409` (`SharedBaseError`)
+   unless you pass `allowSharedBase: true`. The default branch is exempt — many epics target it
+   concurrently without colliding.
+
+So the body may also carry two optional booleans — `confirmDefaultBase` and `allowSharedBase` —
+each a "warn you can't skip" for its rule:
+
+```bash
+curl -sS -X POST __BASE__/actions/start/plan-fanout \
+  -H 'content-type: application/json' \
+  -d '{ "issue": "owner/repo#123", "baseBranch": "main", "confirmDefaultBase": true }'
+```
+
+Grandfathered: in-flight plans launched before this admission gate (with a `null` base branch)
+keep running unchanged — the requirement is enforced at admission of **new** launches, not by a
+database constraint.
+
 Track a plan the same way you track PRs — its `process_key` is an engine instance you
 can inspect in §5, and the PRs it opens show up in `/status` as ordinary convergence
 loops.