@golden-frijoles/kit 0.19.0 → 0.21.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,14 @@ 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';
+import { buildRows } from './roadmap-extract.mjs';
+import { gatherFacts } from './lib/stage-facts.mjs';
+import { groupByStage } from './lib/stage.mjs';
+import { getKey } from './lib/config.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 +77,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) =>
@@ -276,18 +243,17 @@ function readJournalLocal(git) {
   return { entries: [], ref: null };
 }
 
-function ghOpenPr(root, branch) {
-  try {
-    const out = execFileSync(
-      'gh',
-      ['pr', 'list', '--head', branch, '--state', 'open', '--json', 'number,url', '--limit', '1'],
-      { cwd: root, encoding: 'utf8', timeout: 8000, stdio: ['ignore', 'pipe', 'ignore'] }
-    );
-    const [pr] = JSON.parse(out);
-    return { ok: true, pr: pr || null };
-  } catch {
-    return { ok: false, pr: null };
-  }
+/**
+ * The open PR for `branch`, read from the run's facts (board-sinks-and-scrumban S3.1): the ONE `gh pr list` the facts
+ * made already holds every PR, so the build view asks GitHub nothing more. `ok` is whether those facts are live.
+ */
+export function prFromFacts(facts, branch) {
+  const open = (facts?.prs ?? []).filter((p) => p.head === branch && p.state === 'OPEN');
+  const pr = open.reduce((best, p) => (best === null || p.number > best.number ? p : best), null);
+  // Only LIVE facts may lift the status to In review: a failed online gather that fell back to the snapshot must not
+  // claim a PR from hours ago (before this, a failed gh call meant no lift; fresh review, #227).
+  const live = facts?.mode === 'live';
+  return { ok: live, pr: live && pr ? { number: pr.number, url: pr.url } : null };
 }
 
 const notInFlight = (reason, extra = {}) => ({ in_flight: false, reason, ...extra });
@@ -298,6 +264,48 @@ export function namesSlug(text, slug) {
   return new RegExp(`(^|[^A-Za-z0-9-])${esc}($|[^A-Za-z0-9-])`).test(String(text));
 }
 
+/** "just now", "12m ago", "3h ago", "2 days ago" — how old the facts behind a stage are. */
+export function ageOf(iso, now = new Date()) {
+  const ms = now.getTime() - new Date(iso).getTime();
+  if (!Number.isFinite(ms)) return null;
+  const m = Math.floor(ms / 60_000);
+  if (m < 1) return 'just now';
+  if (m < 60) return `${m}m ago`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ago`;
+  const d = Math.floor(h / 24);
+  return d === 1 ? 'yesterday' : `${d} days ago`;
+}
+
+/**
+ * The stage of what is in flight, and the board around it (board-sinks-and-scrumban S3.1, D2/D14). The stage is the
+ * EXTRACTOR's row for this initiative — the same `buildRows()` the Hub's push and BUILD-ORDER.md read — so the build
+ * view cannot say a different word than the board. `dates: false` keeps it inside the hook's budget (~50 ms).
+ */
+export function boardState({ root, facts, state, now = new Date() }) {
+  const rows = buildRows({ facts: facts ?? undefined, root, dates: false });
+  const slug = state.in_flight ? (state.epic?.slug ?? state.seed?.slug ?? null) : null;
+  const row = slug ? rows.find((r) => r.grain !== 'Sprint' && r.slug === slug) : null;
+  const cols = groupByStage(rows);
+  const next = cols['Ready to build'][0] ?? null;
+  const hub = getKey('board.hubUrl', { root });
+  const hubUrl = typeof hub === 'string' && /^https:\/\//.test(hub) ? hub.replace(/\/+$/, '') : null;
+  return {
+    stage: row ? row.stage : null,
+    stage_source: row ? row.stage_source : null,
+    stage_age:
+      facts?.mode === 'live' ? 'just now' : facts?.generated_at ? ageOf(facts.generated_at, now) : null,
+    facts_mode: facts?.mode ?? 'docs',
+    board: {
+      building: cols.Building.length,
+      qa: cols.QA.length,
+      ready: cols['Ready to build'].length,
+      next: next ? { name: next.name, slug: next.slug, build_order: next.build_order_num ?? null } : null,
+      url: hubUrl ? `${hubUrl}/board${slug && row ? `?card=${encodeURIComponent(slug)}` : ''}` : null,
+    },
+  };
+}
+
 /**
  * Resolve the build state. Every external read is injectable so the tests drive real fixture repos with
  * a fake `gh`: { root, offline, git, gh }. It NEVER throws — it runs once per turn inside a CLI hook, and
@@ -305,14 +313,31 @@ export function namesSlug(text, slug) {
  * `elsewhere: false` skips the other-worktrees / open-epics scan (used when resolving those worktrees).
  */
 export function resolveBuildState(opts = {}) {
+  // board-sinks-and-scrumban S3.1 — ONE facts gather per run: the snapshot offline (the hook never goes online), else
+  // one `git ls-remote` + one `gh pr list`, which also refreshes the snapshot. Injectable for the spec.
+  let facts = null;
+  if (opts.board !== false) {
+    try {
+      facts = (opts.gather ?? gatherFacts)({ root: opts.root, mode: opts.offline ? 'snapshot' : 'live' });
+    } catch {
+      facts = null;
+    }
+  }
   let state;
   try {
-    state = resolve_(opts);
+    state = resolve_({ ...opts, facts });
   } catch (err) {
     state = notInFlight(
       `the resolver could not read this checkout (${err && err.message ? err.message : err})`
     );
   }
+  if (opts.board !== false) {
+    try {
+      Object.assign(state, boardState({ root: opts.root, facts, state, now: opts.now ?? new Date() }));
+    } catch {
+      // A roadmap this extractor cannot read (an out-of-enum status) leaves the view without a stage, never blank.
+    }
+  }
   if (opts.elsewhere === false) return state;
   try {
     state.elsewhere = elsewhere_({ root: opts.root, git: opts.git || makeGit(opts.root), state });
@@ -363,7 +388,7 @@ function elsewhere_({ root, git, state }) {
     if (!w.branch || w.bare || w.prunable || samePath(w.path, top) || !existsSync(w.path)) continue;
     if (!branchCandidates(w.branch).length) continue; // main, release branches: nothing to resolve
     if (resolved++ >= MAX_WORKTREES) break;
-    const s = resolveBuildState({ root: w.path, offline: true, elsewhere: false });
+    const s = resolveBuildState({ root: w.path, offline: true, elsewhere: false, board: false });
     if (!s.in_flight || DONE_LIFECYCLES.includes(s.lifecycle)) continue;
     const item = s.epic
       ? { kind: 'epic', slug: s.epic.slug, title: s.epic.title }
@@ -438,7 +463,8 @@ function seedState({ root, git, gh, offline, branch, seed, match }) {
   };
 }
 
-function resolve_({ root, offline = false, git = makeGit(root), gh = ghOpenPr } = {}) {
+function resolve_({ root, offline = false, git = makeGit(root), facts = null, gh } = {}) {
+  gh = gh ?? ((_root, branch) => prFromFacts(facts, branch));
   if (tryGit(git, ['rev-parse', '--is-inside-work-tree']) !== 'true')
     return notInFlight('not inside a git checkout (or git is not installed)');
   const branch = tryGit(git, ['symbolic-ref', '-q', '--short', 'HEAD']);
@@ -642,9 +668,40 @@ function elsewhereLines(state, pad) {
  * work in other worktrees appears as one `Also` line when this checkout is building, and as the list
  * itself when it isn't.
  */
+/**
+ * The stage, said with where it came from and how old that is (board-sinks-and-scrumban S3.1): "Building · from git:
+ * feat/x · facts from the snapshot, 3h ago". The written `phase:` stays only as a detail (D12). Without a stage (the
+ * roadmap could not be read) it falls back to the old written-phase status, labelled as such.
+ */
+export function statusValue(state) {
+  if (!state.stage) return state.status || `unknown${state.warning ? ` — ${state.warning}` : ''}`;
+  const source = String(state.stage_source || '').replace(/ · snapshot@\S+$/, '');
+  const age =
+    state.facts_mode === 'live'
+      ? 'live'
+      : state.facts_mode === 'snapshot'
+        ? `snapshot, ${state.stage_age ?? 'age unknown'}`
+        : 'docs only, no snapshot yet';
+  const phase =
+    state.phase_written && state.phase_written !== state.stage ? ` · phase ${state.phase_written}` : '';
+  return `${state.stage} · from ${source} (${age})${phase}`;
+}
+
+/** The board around this work in one line, and the link to it when `board.hubUrl` is set (S3.1). */
+function boardLines(state, pad) {
+  const b = state.board;
+  if (!b) return [];
+  const next = b.next
+    ? ` · next to pull: ${clip(b.next.name, 40)}${b.next.build_order !== null ? ` (#${b.next.build_order})` : ''}`
+    : '';
+  const counts = `Building ${b.building} · QA ${b.qa} · Ready to build ${b.ready}${next}`;
+  return [`${pad('Board')}${counts}`, ...(b.url ? [`${pad('')}↗ ${b.url}`] : [])];
+}
+
 export function renderLines(state) {
   const pad = (label) => `  ${label.padEnd(9)}`;
-  if (!state.in_flight) return [`No epic in flight — ${state.reason}`, ...elsewhereLines(state, pad)];
+  if (!state.in_flight)
+    return [`No epic in flight — ${state.reason}`, ...elsewhereLines(state, pad), ...boardLines(state, pad)];
   const others = state.elsewhere?.worktrees?.length || 0;
   const also = others
     ? [
@@ -664,8 +721,9 @@ export function renderLines(state) {
       HEADINGS[seed.type] || 'Currently working on',
       `${pad(label)}${seed.title}${meta ? `    ${meta}` : ''}`,
       `${pad('Seed')}${seed.path}`,
-      `${pad('Status')}${state.status || 'unknown'}`,
+      `${pad('Status')}${statusValue(state)}`,
       ...also,
+      ...boardLines(state, pad),
     ];
   }
   const { epic, story, progress } = state;
@@ -686,8 +744,8 @@ export function renderLines(state) {
   const storyPart = `Story ${progress.story ?? '?'} of ${progress.stories}`;
   const sprintPart = `Sprint ${progress.sprint ?? '?'} of ${progress.sprints}`;
   lines.push(`${pad('Progress')}${storyPart} · ${sprintPart}`);
-  lines.push(`${pad('Status')}${state.status || `unknown${state.warning ? ` — ${state.warning}` : ''}`}`);
-  return [...lines, ...also];
+  lines.push(`${pad('Status')}${statusValue(state)}`);
+  return [...lines, ...also, ...boardLines(state, pad)];
 }
 
 // realpath on both sides: a plugin or checkout reached through a symlink (macOS /tmp → /private/tmp) would

package/dist/lib/board-text.mjs

@@ -0,0 +1,50 @@
+// board-text.mjs — the six-stage board as terminal text (board-sinks-and-scrumban S3.2, `roadmap-extract --sink terminal`).
+//
+// The terminal sink: the same rows the Hub renders, grouped by the same function (`groupByStage`), said in plain text.
+// Shipped is the long column, so it shows a count and the most recent few; every other column lists every card.
+//
+// Pure — the caller passes the rows and how fresh their facts are.
+
+import { STAGES, groupByStage } from './stage.mjs';
+
+const SHIPPED_SHOWN = 5;
+
+function cardLine(row) {
+  const meta = [
+    row.grain === 'Seed' ? 'seed' : null,
+    row.type,
+    row.risk ? `risk ${String(row.risk).toLowerCase()}` : null,
+    Number.isFinite(row.build_order_num) ? `#${row.build_order_num}` : null,
+  ]
+    .filter(Boolean)
+    .join(' · ');
+  return `  · ${row.name}${meta ? ` — ${meta}` : ''}`;
+}
+
+/**
+ * @param rows   the extractor's rows
+ * @param facts  `{ mode, origin }` from lib/stage-facts.mjs — said in the header, so a reader knows how old Building/QA are
+ */
+export function renderBoardText(rows, facts = { mode: 'docs' }) {
+  const columns = groupByStage(rows);
+  const fresh =
+    facts.mode === 'live'
+      ? 'live from git and GitHub'
+      : facts.mode === 'snapshot'
+        ? `from the ${String(facts.origin ?? 'snapshot').replace('@', ' of ')}`
+        : 'from the docs alone — Building and QA need git/GitHub facts (--live)';
+  const out = [`Board — six stages, ${fresh}`, ''];
+  for (const stage of STAGES) {
+    const list = columns[stage];
+    out.push(`${stage} (${list.length})`);
+    const shown = stage === 'Shipped' ? list.slice(0, SHIPPED_SHOWN) : list;
+    for (const row of shown) out.push(cardLine(row));
+    if (stage === 'Shipped' && list.length > shown.length)
+      out.push(`  … and ${list.length - shown.length} more`);
+    if (list.length === 0) out.push('  —');
+    out.push('');
+  }
+  const next = columns['Ready to build'][0];
+  out.push(next ? `Next to pull: ${next.name}` : 'Nothing is ready to pull.');
+  return `${out.join('\n')}\n`;
+}

package/dist/lib/config-registry.mjs

@@ -50,6 +50,23 @@ export const REGISTRY = Object.freeze([
     choices: ['terminal', 'golden-frijoles', 'notion'],
     question: 'Where should the board live?',
   },
+  // board-sinks-and-scrumban D22 — scrumban's pull, as advice: the kickoff warns when Building is at its limit, the Hub
+  // board says when a column is over. `null` = no limits, so nothing warns until a project sets them.
+  {
+    key: 'board.wip',
+    module: 'Plan',
+    askWhen: 'never-yet',
+    default: null,
+    question: 'How many initiatives may be Building and in QA at once (e.g. { "Building": 2, "QA": 3 })? Advice only.',
+  },
+  // The project's Hub base (https://…/hub/<slug>): the build view links each card to it. `null` = no link, no error.
+  {
+    key: 'board.hubUrl',
+    module: 'Plan',
+    askWhen: 'never-yet',
+    default: null,
+    question: "Your project's Golden Frijoles Hub URL (https://goldenfrijoles.com/hub/<project>), for the build view's board link?",
+  },
   {
     key: 'verify.depth',
     module: 'Build',