@golden-frijoles/kit 0.19.0 → 0.20.0

package/dist/build-order.mjs

@@ -1,148 +1,117 @@
 #!/usr/bin/env node
-// build-order.mjs — render Roadmap/00-ideas/BUILD-ORDER.md from the SAME projection every roadmap
-// tool reads (roadmap-extract.mjs). One source of truth: seed frontmatter + epic/sprint
-// status lines. This file is GENERATED — never hand-edit BUILD-ORDER.md; run this instead.
+// build-order.mjs — render Roadmap/00-ideas/BUILD-ORDER.md in the six stages, from the SAME projection every roadmap
+// tool reads (roadmap-extract.mjs) and the ONE stage resolver (lib/stage.mjs). This file is GENERATED — never
+// hand-edit BUILD-ORDER.md; run this instead.
 //
-//   node scripts/build-order.mjs            # write Roadmap/00-ideas/BUILD-ORDER.md
+//   node scripts/build-order.mjs            # write Roadmap/00-ideas/BUILD-ORDER.md (docs only)
 //   node scripts/build-order.mjs --check    # exit 1 if the file is stale (for CI/precommit)
+//   node scripts/build-order.mjs --live     # print the full six-stage board with git/GitHub facts; writes nothing
 //
-// Why this exists: BUILD-ORDER.md used to be hand-maintained, so it drifted on every merge. Status
-// and ordering already live in seed frontmatter (the SSOT the Notion projection reads). This makes
-// the in-repo board a derived view that cannot drift.
+// ── Why the committed file is docs-only (board-sinks-and-scrumban lock C3) ───────────────────────────────
+// Building and QA are FACTS git and GitHub hold (a branch on origin, a ready PR), never fields in a doc. A committed
+// file that carried them would go stale on every PR event, and `--check` (build-order-guard, the nightly sync) would
+// turn every unrelated PR red. So the file holds what the docs alone decide — To groom, Grooming, Ready to build,
+// Shipped — and says where Building and QA live: `--live` here, the Hub board, and the build view. `--live` is the
+// same resolver with live facts, so it agrees with the Hub by construction.
 
 import { execFileSync } from 'node:child_process';
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
-import { EPIC_STATUS_ORDER, SEED_FUNNEL_STATUSES } from './lib/roadmap-status-buckets.mjs';
+import { STAGES, groupByStage } from './lib/stage.mjs';
 import { projectRoot } from './lib/project-root.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const REPO = projectRoot(); // D2
 const OUT = join(REPO, 'Roadmap', '00-ideas', 'BUILD-ORDER.md');
 const EXTRACTOR = join(__dirname, 'roadmap-extract.mjs');
+const LIVE = process.argv.includes('--live');
 
 function extract() {
-  const json = execFileSync('node', [EXTRACTOR], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  const json = execFileSync('node', [EXTRACTOR, LIVE ? '--live' : '--docs-only'], {
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+    stdio: ['ignore', 'pipe', 'inherit'],
+  });
   return JSON.parse(json);
 }
 
-// SSOT = each epic README's frontmatter `status:` field (00-ideas/README). The extractor resolves it
-// into r.status (frontmatter-authoritative, prose/retro fallback) and also emits r.status_derived (the
-// fallback derivation) so this board can flag an advisory drift when the two disagree. No seed read
-// here — a scaffolded epic's seed is funnel-only; the epic README owns its status.
-
-// Epic status → bucket. Sprints are folded into their epic via sprint_progress; seeds are the funnel.
-// The bucket KEYS/ORDER and the seed-funnel status set live in scripts/lib/roadmap-status-buckets.mjs —
-// shared with any other view of the roadmap (a reporting hub, a dashboard) so it can never independently
-// drift from this board's counts. Emoji/title here are this board's own presentation.
-const EPIC_BUCKET_META = {
-  'In progress': { emoji: '🏗️', title: 'Building now' },
-  Scaffolded: { emoji: '📋', title: 'Ready to build (scaffolded, not started)' },
-  Shipped: { emoji: '✅', title: 'Shipped' },
+// What each stage means, in the words the board uses (the seed's table, locked 2026-10-01).
+const STAGE_NOTE = {
+  'To groom': 'seeds with no pitch yet',
+  Grooming: 'a pitch is waiting at the approval gate',
+  'Ready to build': 'scaffolded (or a fixed-scope seed), in build order — pull from the top',
+  Building: 'a work branch is on origin',
+  QA: 'a PR is ready for review, or merged and waiting for its close-out',
+  Shipped: 'merged, deployed and closed',
 };
-const EPIC_BUCKETS = EPIC_STATUS_ORDER.map((key) => ({ key, ...EPIC_BUCKET_META[key] }));
-const SEED_FUNNEL = SEED_FUNNEL_STATUSES;
+const LIVE_ONLY = new Set(['Building', 'QA']);
 
 function line(r) {
-  const bits = [`[${r.name}](../../${r.doc_link.replace(/^Roadmap\//, '')})`];
+  // BUILD-ORDER.md lives in Roadmap/00-ideas/, so an epic README is ONE folder up — `../../` resolved to the repo
+  // root and 404'd every epic link on GitHub (seed board-link-depth, absorbed by board-sinks-and-scrumban S1.5).
+  const link = r.grain === 'Seed' ? `seeds/${r.slug}.md` : `../${r.doc_link.replace(/^Roadmap\//, '')}`;
   const meta = [];
+  if (r.build_order_num != null) meta.push(`#${r.build_order_num}`);
   if (r.area) meta.push(r.area);
+  if (r.grain === 'Seed') meta.push(`seed · ${r.type}`);
   if (r.sprint_progress) meta.push(r.sprint_progress);
   if (r.risk) meta.push(`risk: ${r.risk}`);
-  if (r.priority) meta.push(r.priority);
-  return `- ${bits[0]}${meta.length ? ` — ${meta.join(' · ')}` : ''}`;
+  if (r.appetite) meta.push(`appetite ${r.appetite}`);
+  // A queued seed without an underwriter is funded-but-unowned — advisory, loud on the board.
+  const warn =
+    r.grain === 'Seed' && r.status === 'Queued' && !r.underwritten_by
+      ? ' — ⚠️ no underwriter (set `underwritten_by:` at the betting table)'
+      : '';
+  return `- [${r.name}](${link}) — ${meta.join(' · ')} · _${r.stage_source}_${warn}`;
 }
 
 function render(rows) {
-  const epics = rows.filter((r) => r.grain === 'Epic');
-  const seeds = rows.filter((r) => r.grain === 'Seed');
+  // Shipped by build order, never by `shipped_at`: that is a git date, and a depth-1 CI clone would reorder the file.
+  const columns = groupByStage(rows, { shipped: 'build-order' });
   const now = new Date().toISOString().slice(0, 10);
-
-  // Epic status is authoritative from the README frontmatter (the extractor resolved it into e.status).
-  // Advisory drift = the prose/retro derivation (e.status_derived) disagreeing with that authoritative
-  // status — usually a close-out that forgot to set `status:`, or a stale README. Non-gating signal.
-  const drift = [];
-  for (const e of epics) {
-    if (e.status_derived && e.status_derived !== e.status) {
-      drift.push({ name: e.name, frontmatter: e.status, derived: e.status_derived });
-    }
-  }
-  render._drift = drift;
-
   const out = [];
   out.push('<!-- GENERATED FILE — do not edit by hand.');
   out.push('     Regenerate:  node scripts/build-order.mjs');
-  out.push("     Status SSOT: each epic README's frontmatter `status:` field (set at epic close). Funnel");
-  out.push('     ordering: seed frontmatter (priority). Both projected via scripts/roadmap-extract.mjs. -->');
-  out.push('');
-  out.push('# Build order — generated status board');
-  out.push('');
-  out.push(
-    `> **Generated ${now} — do not hand-edit.** Epic status SSOT = the epic \`README.md\` frontmatter`
-  );
   out.push(
-    '> `status:` field (set at epic close). To change what this shows, edit that field (or a seed for the'
+    "     Stage: scripts/lib/stage.mjs, from each initiative's frontmatter (docs only in this file; the"
   );
   out.push(
-    '> funnel), then run `node scripts/build-order.mjs`. This board and the Notion "Marketplace Roadmap"'
+    '     live board with git/GitHub facts is `node scripts/build-order.mjs --live` and the Hub). -->'
   );
-  out.push('> DB are both *derived views* — never hand-edit the board.');
   out.push('');
-
-  for (const b of EPIC_BUCKETS) {
-    const list = epics
-      .filter((e) => e.status === b.key)
-      .sort((a, z) => (a.area || '').localeCompare(z.area || '') || a.name.localeCompare(z.name));
-    out.push(`## ${b.emoji} ${b.title} (${list.length})`);
-    out.push('');
-    out.push(list.length ? list.map(line).join('\n') : '_None._');
-    out.push('');
-  }
-
-  const funnel = seeds
-    .filter((s) => SEED_FUNNEL.has(s.status))
-    .sort((a, z) => (a.priority || 'zzz').localeCompare(z.priority || 'zzz') || a.name.localeCompare(z.name));
-  out.push(`## ⬜ Funnel — seeds not yet scaffolded (${funnel.length})`);
+  out.push('# Build order — the six stages');
   out.push('');
-  out.push(
-    funnel.length
-      ? funnel
-          .map((s) => {
-            const meta = [s.status, s.type, s.appetite ? `appetite ${s.appetite}` : null, s.priority]
-              .filter(Boolean)
-              .join(' · ');
-            // A queued seed without an underwriter is funded-but-unowned — advisory drift, loud on the board.
-            const warn =
-              s.status === 'Queued' && !s.underwritten_by
-                ? ' — ⚠️ no underwriter (set `underwritten_by:` at the betting table)'
-                : '';
-            return `- [${s.name}](seeds/${s.slug}.md)${meta ? ` — ${meta}` : ''}${warn}`;
-          })
-          .join('\n')
-      : '_None._'
-  );
+  out.push(`> **Generated ${now} — do not hand-edit.** One stage per initiative, decided in one place`);
+  out.push('> (`scripts/lib/stage.mjs`): To groom · Grooming · Ready to build · Building · QA · Shipped.');
+  if (LIVE) {
+    out.push('> **Live:** Building and QA come from git and GitHub as of this run. Printed, never written.');
+  } else {
+    out.push('> This committed file reads the docs alone, so **Building and QA are not here** — they are facts git');
+    out.push('> and GitHub hold. For the live board run `node scripts/build-order.mjs --live`, or open the Hub board.');
+  }
   out.push('');
-
-  if (drift.length) {
-    out.push(`## ⚠️ Status drift — README frontmatter vs sprint/retro-derived (${drift.length})`);
+  for (const stage of STAGES) {
+    const list = columns[stage];
+    if (LIVE_ONLY.has(stage) && !LIVE) {
+      out.push(`## ${stage} — live only`);
+      out.push('');
+      out.push(
+        `_${STAGE_NOTE[stage]}. Not in this committed file: \`node scripts/build-order.mjs --live\` or the Hub board._`
+      );
+      out.push('');
+      continue;
+    }
+    out.push(`## ${stage} (${list.length})`);
     out.push('');
-    out.push('These epics’ authoritative README-frontmatter `status:` disagrees with what the sprint/retro');
-    out.push('derivation infers. The board trusts the **frontmatter**; a mismatch usually means a close-out');
-    out.push(
-      'forgot to set `status:` (or the README is stale). Reconcile the README, then this advisory clears.'
-    );
+    out.push(`_${STAGE_NOTE[stage]}._`);
     out.push('');
-    out.push('| Epic | frontmatter (used) | sprint/retro-derived |');
-    out.push('|---|---|---|');
-    for (const d of drift) out.push(`| ${d.name} | ${d.frontmatter} | ${d.derived} |`);
+    out.push(list.length ? list.map(line).join('\n') : '_None._');
     out.push('');
   }
-
+  const cards = STAGES.reduce((n, s) => n + columns[s].length, 0);
   out.push('---');
-  out.push(
-    `_Epics: ${epics.length} · seeds in funnel: ${funnel.length} · status drift: ${drift.length}. Regenerate with \`node scripts/build-order.mjs\`._`
-  );
+  out.push(`_${cards} initiatives on the board. Regenerate with \`node scripts/build-order.mjs\`._`);
   out.push('');
   return out.join('\n');
 }
@@ -163,7 +132,10 @@ if (unfunded.length) {
 
 const content = render(rows);
 
-if (process.argv.includes('--check')) {
+if (LIVE) {
+  // Printed, never written: the committed file must stay docs-only (lock C3).
+  process.stdout.write(content);
+} else if (process.argv.includes('--check')) {
   const current = existsSync(OUT) ? readFileSync(OUT, 'utf8') : '';
   // Ignore the "Generated <date>" line when comparing so a date-only diff isn't "stale".
   const norm = (s) => s.replace(/^> \*\*Generated \d{4}-\d{2}-\d{2} /m, '> **Generated DATE ');

package/dist/build-state.mjs

@@ -58,11 +58,10 @@ import { fileURLToPath } from 'node:url';
 import { dirname, join, resolve } from 'node:path';
 import { PHASES, parseDocFrontmatter } from './lib/roadmap-contract.mjs';
 import { parseJournal, JOURNAL_BRANCH, JOURNAL_PATH } from './lib/session-journal.mjs';
+import { branchCandidates, parseBranch } from './lib/work-branch.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-const BRANCH_PREFIX_RE = /^(?:feat|fix|chore|spike|bug|docs)\/(.+)$/;
-const SLUG_RE = /^[A-Za-z0-9][A-Za-z0-9_.]*(?:-[A-Za-z0-9_.]+)*$/;
 const SEEDS_DIR = ['Roadmap', '00-ideas', 'seeds'];
 const MAX_WORKTREES = 8; // resolved per refresh — a pile of stale agent worktrees must not stall the view
 const MAX_ELSEWHERE_LINES = 4;
@@ -74,45 +73,9 @@ export function storyIdsIn(text) {
   return [...String(text).matchAll(STORY_IN_TEXT_RE)].map((m) => `S${Number(m[1])}.${Number(m[2])}`);
 }
 
-/** A sprint token right after the slug: `s3`, `sprint3`, or `sprint` `3` → 3; else null. */
-function sprintAt(rest) {
-  const m = String(rest[0] ?? '').match(/^s(?:print)?(\d+)$/);
-  if (m) return Number(m[1]);
-  return rest[0] === 'sprint' && /^\d+$/.test(rest[1] ?? '') ? Number(rest[1]) : null;
-}
-
-/**
- * Every reading of a work branch as `<slug>[-s<N>][-anything]`, LONGEST slug first:
- * `feat/foo-s4-licences` → foo-s4-licences, foo-s4, foo (sprint 4). The resolver takes the first reading
- * whose slug names an epic (or a seed) on disk. [] for a branch that isn't a work branch.
- */
-export function branchCandidates(branch) {
-  const m = String(branch || '').match(BRANCH_PREFIX_RE);
-  if (!m || !SLUG_RE.test(m[1]) || m[1].includes('..')) return [];
-  const tokens = m[1].split('-');
-  const out = [];
-  for (let i = tokens.length; i >= 1; i--) {
-    out.push({
-      slug: tokens.slice(0, i).join('-'),
-      sprint: sprintAt(tokens.slice(i)),
-      exact: i === tokens.length,
-    });
-  }
-  return out;
-}
-
-/**
- * The syntactic reading alone, no disk: `feat/foo-s3` → { slug: 'foo', sprint: 3 },
- * `feat/foo-s3-extra` → { slug: 'foo', sprint: 3 }; null for a branch that is not a work branch.
- */
-export function parseBranch(branch) {
-  const cands = branchCandidates(branch);
-  if (!cands.length) return null;
-  const withSprint = cands.find((c) => c.sprint !== null);
-  return withSprint
-    ? { slug: withSprint.slug, sprint: withSprint.sprint }
-    : { slug: cands[0].slug, sprint: null };
-}
+// The branch parser lives in lib/work-branch.mjs now (board-sinks-and-scrumban D13), so the stage resolver reads a
+// branch exactly as this view does. Re-exported: callers and the spec import them from here.
+export { branchCandidates, parseBranch };
 
 function makeGit(root) {
   return (args) =>

package/dist/lib/epic-kickoff.mjs

@@ -0,0 +1,268 @@
+// epic-kickoff.mjs — the epic-mode kickoff, as one pure builder (board-sinks-and-scrumban D17).
+//
+// It used to live only in the groom skill (`emit-epic-kickoff.mjs` + `templates/epic-kickoff.md`), which the kit does
+// not ship and an installed extractor cannot import (lock C11). The Hub's "Ready to build" card has to carry the same
+// kickoff the CLI prints — a kickoff composed twice is the exact drift `emit-epic-kickoff` was written to end — so
+// the builder, the parsers it reads the docs with and the template text all live here, in the ONE source
+// (`template/scripts/`). The groom skill imports a byte-identical copy that `skills/scripts/render-hook-vendor.mjs`
+// writes into `groom/vendor/` and checks in CI; the extractor imports this file directly.
+//
+// The parsers moved here from `emit-kickoff.mjs` unchanged; that file re-exports them, so the per-sprint generator
+// and this one still read the doc format with ONE set of parsers.
+//
+// Zero deps beyond node:fs/node:path (for `epicKickoffFromDir`, the only function that touches the disk).
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+// Same substitution approach as scaffold-epic.mjs's `sub()` — {{PLACEHOLDER}} → value, leaves
+// unknown placeholders untouched (so a missing var surfaces loudly in the printed output).
+export const sub = (str, vars) => str.replace(/\{\{(\w+)\}\}/g, (_, k) => (k in vars ? vars[k] : `{{${k}}}`));
+
+// Parses the epic README's YAML-ish frontmatter block (the two `---` fence lines and simple
+// `key: value` lines between them — no nested structures, matches what scaffold-epic.mjs emits).
+export function parseFrontmatter(text) {
+  const lines = text.split('\n');
+  if (lines[0].trim() !== '---') return {};
+  const end = lines.findIndex((l, i) => i > 0 && l.trim() === '---');
+  if (end === -1) return {};
+  const out = {};
+  for (const line of lines.slice(1, end)) {
+    const m = line.match(/^(\w+):\s*(.*)$/);
+    // Strip a YAML inline comment (whitespace + `#` … to end-of-line) before
+    // trimming: frontmatter routinely annotates values, e.g.
+    // `status: in-progress   # AUTHORITATIVE …`. Without this, a comment on
+    // the `slug:` line would make `frontmatter.slug !== slug` a false mismatch
+    // and crash the run on otherwise-fine data. Only an UNquoted value is
+    // parsed here (these frontmatters never quote), so this can't eat a `#`
+    // inside a quoted string.
+    if (m) out[m[1]] = m[2].replace(/\s+#.*$/, '').trim();
+  }
+  return out;
+}
+
+// Strips a leading `---`…`---` frontmatter fence, if present, returning only the body. Frontmatter
+// commonly carries trailing `# comment` annotations on its own lines (e.g. `status: in-progress   #
+// AUTHORITATIVE epic status …`, or a bare `# note` line) — those must never be mistaken for the H1,
+// so every H1 search below runs against this stripped body, not the raw file text.
+export function stripFrontmatter(text) {
+  const lines = text.split('\n');
+  if (lines[0].trim() !== '---') return text;
+  const end = lines.findIndex((l, i) => i > 0 && l.trim() === '---');
+  if (end === -1) return text;
+  return lines.slice(end + 1).join('\n');
+}
+
+// The epic README's H1 is `# Epic: <title>` — strip the `Epic: ` prefix. Searches only the body
+// AFTER the frontmatter fence (see stripFrontmatter) so a `# `-led YAML comment can't win first.
+export function parseEpicTitle(text) {
+  const m = stripFrontmatter(text).match(/^#\s+(.+)$/m);
+  if (!m) return null;
+  const raw = m[1].trim();
+  return raw.replace(/^Epic:\s*/, '');
+}
+
+// The sprint doc's H1 is `# <epic title> — Sprint <N>: <sprint title>`. The separator accepts a
+// hyphen, en-dash, or em-dash ([-–—]) — an author typing a plain "-" must not crash the generator.
+export function parseSprintHeader(text) {
+  const m = stripFrontmatter(text).match(/^#\s+(.+?)\s+[-–—]\s+Sprint\s+(\d+):\s+(.+)$/m);
+  if (!m) return null;
+  return { epicTitle: m[1].trim(), sprintNum: m[2], sprintTitle: m[3].trim() };
+}
+
+// Story headings are `### Story N.M — <title>` — return the full heading text (minus `### `). The
+// separator accepts a hyphen, en-dash, or em-dash ([-–—]): the em-dash-only regex this replaced
+// silently dropped every story typed with a plain "-", producing a complete-looking kickoff with
+// NO stories at all — the worst failure shape (silent, plausible-looking output).
+export function parseStoryHeadings(text) {
+  const out = [];
+  const re = /^###\s+(Story\s+\d+\.\d+\s+[-–—]\s+.+)$/gm;
+  let m;
+  while ((m = re.exec(text))) out.push(m[1].trim());
+  return out;
+}
+
+// `sprint-3.md` → 3. Returns null for anything that isn't a sprint file, so a stray doc in the epic dir
+// (a NOTES.md, an image) can't be mistaken for a sprint.
+export function sprintNumFromFilename(name) {
+  const m = name.match(/^sprint-(\d+)\.md$/);
+  return m ? Number(m[1]) : null;
+}
+
+// Every sprint file in the epic dir, NUMERICALLY sorted. Numeric, not lexicographic: a 10-sprint epic
+// would otherwise order sprint-10 between sprint-1 and sprint-2, and the whole point of epic mode is that
+// the sprints are an ordered assembly line. Stacked branches make a wrong order actively harmful.
+export function listSprintFiles(names) {
+  return names
+    .map((name) => ({ name, num: sprintNumFromFilename(name) }))
+    .filter((s) => s.num !== null)
+    .sort((a, b) => a.num - b.num);
+}
+
+// The comma-separated file list for the orientation line.
+export function buildSprintFileList(sprints) {
+  if (!sprints.length) return '(no sprint-N.md files found)';
+  return sprints.map((s) => s.name).join(', ');
+}
+
+// `Story 1.1 — Persist intent ✅ #12. **Decided …**` → `1.1 Persist intent`, clipped. The breakdown is a
+// checklist for the orchestrator and the product owner; the sprint files carry the detail.
+export function compactStory(heading) {
+  const m = String(heading).match(/^Story\s+(\d+\.\d+)\s+[-–—]\s+(.+)$/);
+  if (!m) return String(heading);
+  const title = m[2]
+    .replace(/\s+✅.*$/, '')
+    .replace(/\*\*/g, '')
+    .trim();
+  return `${m[1]} ${title.length > 70 ? `${title.slice(0, 69)}…` : title}`;
+}
+
+// The per-sprint breakdown at the foot of the prompt: one line per sprint, its stories inline. This is the
+// only part that genuinely varies per epic, and it is deliberately the LAST thing in the prompt — the
+// contract above it is invariant, so two kickoffs diff to their scope.
+export function buildSprintBreakdown(sprints) {
+  if (!sprints.length) return '(no sprint files found — scaffold the epic first)';
+  return sprints
+    .map((s) => {
+      const stories = s.stories.length
+        ? s.stories.map(compactStory).join(' · ')
+        : '(no `### Story N.M — <title>` headings found in this sprint doc)';
+      const clean = s.title ? s.title.replace(/^S\d+\s*[—–:-]?\s*/, '') : '';
+      const title = clean ? ` · ${clean}` : '';
+      return `- **S${s.num}${title}** (${s.name}): ${stories}`;
+    })
+    .join('\n');
+}
+
+// Rules that apply to THIS epic only, picked from its docs. A false positive costs one line; a missing one
+// is the incident each rule came from, so the patterns lean inclusive.
+const MIGRATION_RE = /\bmigrations?\b|supabase\/migrations|\bALTER TABLE\b|\bCREATE TABLE\b/i;
+// A flag KEY (`checkout.stripe_enabled`) or a flag write — not the words "kill-switch" / "flag", which every
+// scaffolded README's Definition of Done carries whether or not a flag was planned.
+const FLAG_RE = /\b[a-z][a-z0-9_]*\.[a-z0-9_]+_enabled\b|\bgf flags (?:create|set|on)\b/;
+
+// "No new table, no migration" is the most common way a doc mentions one — strip negated mentions first.
+const NEGATED_RE =
+  /\b(?:no|without|zero|not an?|nor an?)\s+(?:new\s+)?(?:db\s+|database\s+|schema\s+)?migrations?\b/gi;
+
+export function buildEpicRules({ risk, texts }) {
+  const all = texts.join('\n').replace(NEGATED_RE, '');
+  const rules = [];
+  if (String(risk).toUpperCase() === 'HIGH')
+    rules.push(
+      '- **High risk:** the fresh `pr-reviewer` pass is mandatory on every PR, on top of the routed external passes.'
+    );
+  if (MIGRATION_RE.test(all))
+    rules.push(
+      '- **Migration:** apply it BEFORE merging (merging deploys), verify live, merge, then confirm the deploy.'
+    );
+  if (FLAG_RE.test(all))
+    rules.push(
+      '- **Flag:** create it in Golden Frijoles in every env and ACTIVATE it; `gf flags get <key>` must show production.'
+    );
+  return rules.length ? `\nFor this epic:\n${rules.join('\n')}\n` : '';
+}
+
+export function buildEpicKickoff({ macro, slug, epicTitle, risk, sprints, templateText, texts = [] }) {
+  return sub(templateText, {
+    EPIC_RULES: buildEpicRules({ risk, texts }),
+    MACRO: macro,
+    SLUG: slug,
+    EPIC_TITLE: epicTitle,
+    RISK: risk,
+    SPRINT_COUNT: String(sprints.length),
+    SPRINT_FILE_LIST: buildSprintFileList(sprints),
+    SPRINT_BREAKDOWN: buildSprintBreakdown(sprints),
+  });
+}
+
+// The epic README header line carries `**Risk:** <low|high>`; the frontmatter doesn't. Falls back to
+// 'high' — the WAYS-OF-WORKING rule is "when unsure, treat it as high", and a kickoff that under-declares
+// risk is the one that skips the mandatory fresh-reviewer pass.
+export function parseEpicRisk(text) {
+  const m = text.match(/\*\*Risk:\*\*\s*([A-Za-z]+)/);
+  return m ? m[1].toLowerCase() : 'high';
+}
+
+/**
+ * A sprint's branch, STACKED (WAYS-OF-WORKING → *Epic-mode builds*: `feat/<slug>` → `-s2` → …): sprint 1 is the epic
+ * branch itself, sprint N is `feat/<slug>-s<N>`. One function, so the per-sprint kickoff, the Notion sprint card and
+ * the stage resolver's branch reading (`lib/work-branch.mjs`: `-s<N>` is sprint N, no suffix is sprint 1) agree.
+ */
+export const sprintBranch = (slug, n) => (Number(n) <= 1 ? `feat/${slug}` : `feat/${slug}-s${Number(n)}`);
+/** What sprint N branches FROM: main for sprint 1, else the previous sprint's branch (stacked; main once it merged). */
+export const sprintBase = (slug, n) =>
+  Number(n) <= 1 ? 'origin/main' : `origin/${sprintBranch(slug, Number(n) - 1)}`;
+
+// The prompt POINTS at the process instead of restating it (WAYS-OF-WORKING → *Epic-mode builds* is the one copy of
+// the doctrine). Its FIRST step pushes the epic branch (S1.4): Building is a git fact the moment work starts, not a
+// status somebody remembers to write — the push is what moves the card on the board (README § lock, D13).
+export const EPIC_KICKOFF_TEMPLATE = `Start by pushing the epic branch, before anything else — it is what moves this card to Building on the board:
+\`git switch -c feat/{{SLUG}} origin/main && git push -u origin feat/{{SLUG}}\` (resuming? \`git switch feat/{{SLUG}}\`).
+
+Build this epic in ONE orchestrated run: "{{EPIC_TITLE}}" ({{SPRINT_COUNT}} sprints, risk {{RISK}}).
+Docs: Roadmap/{{MACRO}}/{{SLUG}}/README.md and {{SPRINT_FILE_LIST}}. The sprint files are integration, review
+and rollback boundaries inside this run, not separate sessions.
+
+The process is Roadmap/WAYS-OF-WORKING.md → *Epic-mode builds*, *Review & merge* and *Escalate, don't guess*,
+under AGENTS.md. Read those, the epic docs, and the Roadmap/LEARNINGS.md entries that touch this area. Start
+with \`node scripts/session-resume.mjs\`.
+
+Non-negotiable for this run:
+1. **Lock first.** Write \`D1…Dn\` and each sprint's build contract into the epic README, verified against
+   live code and live data, before any builder starts. Scope the live system disproves gets corrected out loud.
+   Then run \`node scripts/intent-reader.mjs --epic {{SLUG}}\` once: off by default (one line, nothing waits); on,
+   one other family reads the pitch and any failure is a single \`reader skipped\` line. Never wait on it.
+2. **Stack** \`feat/{{SLUG}}\` → \`-s2\` → …, one PR per sprint, merged in order. Worktree or in place: decide
+   per *Epic-mode builds*.
+3. **Review** every PR through \`node scripts/review-route.mjs --builder <who-wrote-it> <PR#>\` (one general
+   pass, plus the security lens when the paths trigger it); each finding is fixed or answered before merge.
+4. **Merge on green** — pre-authorized, except a new category of production mutation: ask that once.
+5. **Done means shipped** — deployed and verified live, each sprint's smoke walkthrough in its sprint file,
+   then the epic Definition of Done.
+{{EPIC_RULES}}
+## Sprints
+
+{{SPRINT_BREAKDOWN}}
+`;
+
+/**
+ * The epic kickoff for the epic in `dir` (`Roadmap/<macro>/<slug>/`), read from its README and every sprint file.
+ * Throws (never exits) on a missing H1 or no sprint files: the CLI turns that into its own message, and the
+ * extractor leaves the card without a kickoff rather than failing the whole projection.
+ */
+export function epicKickoffFromDir({
+  macro,
+  slug,
+  dir,
+  read = (p) => readFileSync(p, 'utf8'),
+  list = readdirSync,
+}) {
+  const readmeText = read(join(dir, 'README.md'));
+  const epicTitle = parseEpicTitle(readmeText);
+  if (!epicTitle) throw new Error(`couldn't find an H1 title in Roadmap/${macro}/${slug}/README.md`);
+  const found = listSprintFiles(list(dir));
+  if (!found.length)
+    throw new Error(`no sprint-N.md files under Roadmap/${macro}/${slug}/ — scaffold the epic first`);
+  const sprints = found.map(({ name, num }) => {
+    const text = read(join(dir, name));
+    const header = parseSprintHeader(text);
+    return { name, num, text, title: header ? header.sprintTitle : null, stories: parseStoryHeadings(text) };
+  });
+  return {
+    sprints,
+    readmeText,
+    kickoff: buildEpicKickoff({
+      macro,
+      slug,
+      epicTitle,
+      risk: parseEpicRisk(readmeText).toUpperCase(),
+      sprints,
+      templateText: EPIC_KICKOFF_TEMPLATE,
+      texts: [readmeText, ...sprints.map((s) => s.text)],
+    }),
+  };
+}
+
+/** True when `dir` holds an epic README — a convenience for callers that search macro folders. */
+export const isEpicDir = (dir) => existsSync(join(dir, 'README.md'));

package/dist/lib/roadmap-status-buckets.mjs

@@ -18,3 +18,7 @@ export const SEED_FUNNEL_STATUSES = new Set(['Raw', 'Ready', 'Queued']);
 export function isFunnelSeed(row) {
   return row?.grain === 'Seed' && SEED_FUNNEL_STATUSES.has(row.status);
 }
+
+// The six stages (board-sinks-and-scrumban D1/D2) live in lib/stage.mjs; re-exported here so the old buckets and
+// the new stages have one home. The buckets above stay for the readers that still group by `status`.
+export { STAGES } from './stage.mjs';