@golden-frijoles/kit 0.20.0 → 0.21.0

package/dist/build-state.mjs

@@ -59,6 +59,10 @@ 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));
 
@@ -239,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 });
@@ -261,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
@@ -268,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 });
@@ -326,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 }
@@ -401,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']);
@@ -605,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
     ? [
@@ -627,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;
@@ -649,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',

package/dist/roadmap-extract.mjs

@@ -5,6 +5,9 @@
 //   node scripts/roadmap-extract.mjs --live       # gather git/GitHub facts now (one ls-remote, one gh call)
 //   node scripts/roadmap-extract.mjs --docs-only  # no facts at all — what the committed BUILD-ORDER.md reads
 //   … --live --require-live                        # exit 3 instead of falling back (what a publisher passes)
+//   node scripts/roadmap-extract.mjs --sink terminal  # the six-stage board as text (live facts unless told otherwise)
+//   node scripts/roadmap-extract.mjs --sink hub       # push the board to the Hub (GROWTH_ENGINE_URL + the project key, see roadmap-push)
+//   node scripts/roadmap-extract.mjs --sink notion    # run the optional Notion sync copied beside this file
 //
 // ── One extractor (board-sinks-and-scrumban D15) ─────────────────────────────────────────────────────────
 // This file is THE projection, byte-identical in every project's scripts/ and in the kit. It used to have a fork in
@@ -57,35 +60,37 @@
 //   Legacy freeform lines are still mapped best-effort below.
 
 import { readFileSync, readdirSync, existsSync, statSync, writeSync, realpathSync } from 'node:fs';
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { projectRoot } from './lib/project-root.mjs';
 import { attributeFacts, resolveStage } from './lib/stage.mjs';
 import { gatherFacts } from './lib/stage-facts.mjs';
 import { epicKickoffFromDir, sprintBranch } from './lib/epic-kickoff.mjs';
+import { renderBoardText } from './lib/board-text.mjs';
+import { pushRoadmap, reportPush } from './roadmap-push.mjs';
 
-const REPO = projectRoot(); // D2
-const ROADMAP = join(REPO, 'Roadmap');
-const SEEDS = join(ROADMAP, '00-ideas', 'seeds');
+const REPO = projectRoot(); // D2 — the CLI's default root; buildRows takes its own
 
 // Area labels are DERIVED from the project's own macro-section folders (`Roadmap/NN-slug/` → "NN Slug Title-Cased"),
 // never hardcoded: a hardcoded map was another product's area list and mislabeled every line it touched. A number
 // with no folder yet (a seed for a future area) falls back to the raw number.
-const AREA_NAMES = existsSync(ROADMAP)
-  ? Object.fromEntries(
-      readdirSync(ROADMAP)
-        .filter((d) => /^\d{2}-/.test(d) && statSync(join(ROADMAP, d)).isDirectory())
-        .map((d) => {
-          const [, num, slug] = d.match(/^(\d{2})-(.+)$/);
-          const label = slug
-            .split('-')
-            .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
-            .join(' ');
-          return [num, `${num} ${label}`];
-        })
-    )
-  : {};
+export function areaNames(roadmapDir) {
+  if (!existsSync(roadmapDir)) return {};
+  return Object.fromEntries(
+    readdirSync(roadmapDir)
+      .filter((d) => /^\d{2}-/.test(d) && statSync(join(roadmapDir, d)).isDirectory())
+      .map((d) => {
+        const [, num, slug] = d.match(/^(\d{2})-(.+)$/);
+        const label = slug
+          .split('-')
+          .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+          .join(' ');
+        return [num, `${num} ${label}`];
+      })
+  );
+}
+
 const SEED_STATUS_LABEL = {
   raw: 'Raw',
   ready: 'Ready',
@@ -129,12 +134,12 @@ function parseFrontmatter(md) {
   return fm;
 }
 
-function readSeeds() {
-  if (!existsSync(SEEDS)) return [];
-  return readdirSync(SEEDS)
+function readSeeds(seedsDir) {
+  if (!existsSync(seedsDir)) return [];
+  return readdirSync(seedsDir)
     .filter((f) => f.endsWith('.md'))
     .map((f) => {
-      const fm = parseFrontmatter(readFileSync(join(SEEDS, f), 'utf8'));
+      const fm = parseFrontmatter(readFileSync(join(seedsDir, f), 'utf8'));
       seedStatusLabel(fm.status, `Roadmap/00-ideas/seeds/${f}`); // hard-fail on an invalid enum value
       seedAppetite(fm.appetite, `Roadmap/00-ideas/seeds/${f}`); // hard-fail on an invalid appetite
       return { ...fm, _file: `Roadmap/00-ideas/seeds/${f}` };
@@ -172,11 +177,11 @@ export function seedAppetite(appetite, file = 'seed') {
   return appetite;
 }
 
-function listEpicDirs() {
+function listEpicDirs(roadmapDir) {
   const out = [];
-  for (const macro of readdirSync(ROADMAP)) {
+  for (const macro of readdirSync(roadmapDir)) {
     if (!/^[0-9]{2}-/.test(macro)) continue; // macro-section folders only
-    const macroPath = join(ROADMAP, macro);
+    const macroPath = join(roadmapDir, macro);
     if (!statSync(macroPath).isDirectory()) continue;
     for (const slug of readdirSync(macroPath)) {
       const epicPath = join(macroPath, slug);
@@ -337,10 +342,10 @@ export function buildOrderNum(v) {
 
 // When a row ENTERED its current status: the last commit whose diff touched the status-bearing line, else the
 // file's last commit, else today (a brand-new uncommitted scaffold entered its status now). Docs + git stay the SSOT.
-function gitDate(args) {
+function gitDate(root, args) {
   try {
     return execFileSync('git', ['log', '-1', '--format=%as', ...args], {
-      cwd: REPO,
+      cwd: root,
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'ignore'],
     }).trim();
@@ -348,10 +353,10 @@ function gitDate(args) {
     return '';
   }
 }
-function statusDate(relFile, statusLineRegex) {
+function statusDate(root, relFile, statusLineRegex) {
   return (
-    (statusLineRegex && gitDate([`-G${statusLineRegex}`, '--', relFile])) ||
-    gitDate(['--', relFile]) ||
+    (statusLineRegex && gitDate(root, [`-G${statusLineRegex}`, '--', relFile])) ||
+    gitDate(root, ['--', relFile]) ||
     new Date().toISOString().slice(0, 10)
   );
 }
@@ -454,13 +459,22 @@ const prOf = (pr) =>
  * Build the rows. `facts` is what lib/stage-facts.mjs gathered (`{ branches, prs, origin }`); the default is no
  * facts, so an import — doc-hygiene, pmo-report, a spec — never touches the network or the snapshot.
  */
-export function buildRows({ facts = { branches: [], prs: [], origin: null } } = {}) {
-  const seeds = readSeeds();
+export function buildRows({
+  facts = { branches: [], prs: [], origin: null },
+  root = REPO,
+  dates = true,
+} = {}) {
+  const ROADMAP = join(root, 'Roadmap');
+  const AREA_NAMES = areaNames(ROADMAP);
+  // `dates: false` skips the per-row `git log` (one per doc) — the build view runs inside a 5-second hook budget and
+  // reads no date; every other field is the same either way.
+  const when = (rel, re) => (dates ? statusDate(root, rel, re) : null);
+  const seeds = readSeeds(join(ROADMAP, '00-ideas', 'seeds'));
   const seedByEpic = new Map();
   for (const s of seeds) if (s.epic) seedByEpic.set(s.epic, s);
 
   const rows = [];
-  const epicDirs = listEpicDirs();
+  const epicDirs = listEpicDirs(ROADMAP);
 
   // Which initiative each branch and PR belongs to (D13): epic slugs and funnel-seed slugs are the names a branch can
   // carry; a seed that carries `epic:` names that epic.
@@ -508,7 +522,7 @@ export function buildRows({ facts = { branches: [], prs: [], origin: null } } =
       sprints: sprints.map((sp) => ({ n: sp.n, status: sp.status })), // each sprint's OWN docs status, not floored
       sprints_total: sprints.length,
     });
-    const statusDay = statusDate(readmePath, '^status:');
+    const statusDay = when(readmePath, '^status:');
     let kickoff = null;
     if (stage === 'Ready to build') {
       try {
@@ -562,7 +576,7 @@ export function buildRows({ facts = { branches: [], prs: [], origin: null } } =
         slug: `${e.slug}--s${sp.n}`,
         grain: 'Sprint',
         status: sp.status,
-        status_date: statusDate(`Roadmap/${epicKey}/sprint-${sp.n}.md`, '^(\\*\\*)?Status:'),
+        status_date: when(`Roadmap/${epicKey}/sprint-${sp.n}.md`, '^(\\*\\*)?Status:'),
         area,
         priority,
         type: 'Sprint',
@@ -580,7 +594,7 @@ export function buildRows({ facts = { branches: [], prs: [], origin: null } } =
   // Seed rows: only seeds with no scaffolded epic (epic == null)
   for (const s of seeds.filter((x) => !x.epic)) {
     const { stage, source: stageSource, pr } = stageFor(s.slug, { grain: 'Seed', status: s.status });
-    const statusDay = statusDate(s._file, '^status:');
+    const statusDay = when(s._file, '^status:');
     const name = s.title || s.slug;
     rows.push({
       name,
@@ -601,7 +615,7 @@ export function buildRows({ facts = { branches: [], prs: [], origin: null } } =
       build_order_num: buildOrderNum(s.build_order),
       doc_link: s._file,
       epic_slug: null,
-      goal: firstParagraph(readFileSync(join(REPO, s._file), 'utf8'), [
+      goal: firstParagraph(readFileSync(join(root, s._file), 'utf8'), [
         'Problem',
         'Why',
         'Outcome & signal',
@@ -619,6 +633,17 @@ export function buildRows({ facts = { branches: [], prs: [], origin: null } } =
   return rows;
 }
 
+/** The sinks one projector feeds (board-sinks-and-scrumban S3.2): no `--sink` prints the rows as JSON. */
+export const SINKS = Object.freeze(['terminal', 'hub', 'notion']);
+
+/** `--sink <name>` / `--sink=<name>` → the name, `''` for a bare `--sink`, or null when absent. */
+export function sinkFrom(argv) {
+  const eq = argv.find((a) => a.startsWith('--sink='));
+  if (eq) return eq.slice('--sink='.length);
+  const i = argv.indexOf('--sink');
+  return i === -1 ? null : (argv[i + 1] ?? '');
+}
+
 /** `--live` · `--offline` (the default) · `--docs-only` → a facts mode. The last one given wins. */
 export function factsModeFrom(argv) {
   let mode = 'snapshot';
@@ -643,18 +668,57 @@ const isMain = (() => {
   }
 })();
 if (isMain) {
-  const mode = factsModeFrom(process.argv.slice(2));
+  const argv = process.argv.slice(2);
+  const sink = sinkFrom(argv);
+  if (sink !== null && !SINKS.includes(sink)) {
+    process.stderr.write(`roadmap-extract: --sink takes one of ${SINKS.join(' | ')} (got "${sink}")\n`);
+    process.exit(2);
+  }
+  // A sink shows or sends the board, so it wants Building and QA: live facts unless a mode was asked for.
+  const explicit = argv.some((a) => a === '--live' || a === '--offline' || a === '--docs-only');
+  const mode = sink !== null && !explicit ? 'live' : factsModeFrom(argv);
   const facts = gatherFacts({ root: REPO, mode });
   // A FAILED --live run says why on stderr (the rows say where their facts came from in every stage_source). An
   // offline run with no snapshot is the normal case for the six callers that spawn this with no flags — one of them
   // in the pre-commit hook — so it stays quiet.
   if (facts.note && mode === 'live') process.stderr.write(`roadmap-extract: ${facts.note}\n`);
-  // --require-live: a publisher (roadmap-push in CI) must never send a board whose live facts silently fell back. A
-  // fresh CI checkout has no snapshot, so the fallback is docs-only — every Building/QA card would drop to its docs
-  // stage on the public Hub and the unchanged-board check would store it as a new version. Fail instead.
-  if (process.argv.includes('--require-live') && facts.mode !== 'live') {
-    process.stderr.write('roadmap-extract: --require-live, and live facts could not be gathered — nothing printed.\n');
+  // --require-live: a publisher must never send a board whose live facts silently fell back (a fresh CI checkout has
+  // no snapshot, so the fallback is docs-only: every Building/QA card would drop to its docs stage on the Hub and the
+  // unchanged-board check would store it as a new version). The Hub sink implies it whenever it asked for live facts.
+  const requireLive = argv.includes('--require-live') || (sink === 'hub' && mode === 'live');
+  if (requireLive && facts.mode !== 'live') {
+    process.stderr.write(
+      'roadmap-extract: live facts could not be gathered — nothing printed or pushed. ' +
+        '(The Hub sink needs git and an authenticated `gh`; pass --docs-only to push the docs-only stages.)\n'
+    );
     process.exit(3);
   }
-  writeSync(1, JSON.stringify(buildRows({ facts }), null, 2) + '\n');
+  const rows = buildRows({ facts });
+  if (sink === null) writeSync(1, JSON.stringify(rows, null, 2) + '\n');
+  else if (sink === 'terminal') writeSync(1, renderBoardText(rows, facts));
+  else if (sink === 'hub')
+    process.exitCode = reportPush(await pushRoadmap(rows, { root: REPO }), rows.length);
+  else {
+    // Notion is opt-in (template/optional/notion/): a project that wants it copies roadmap-to-notion.mjs beside this.
+    // Beside this file when it IS the project's copy; the project's scripts/ when this runs from the kit (fresh review, #227).
+    const notion = [
+      join(dirname(fileURLToPath(import.meta.url)), 'roadmap-to-notion.mjs'),
+      join(REPO, 'scripts', 'roadmap-to-notion.mjs'),
+    ].find((p) => existsSync(p));
+    if (!notion) {
+      process.stderr.write(
+        'roadmap-extract: no roadmap-to-notion.mjs beside this script or in the project\'s scripts/ — the Notion sink is opt-in: copy ' +
+          'template/optional/notion/roadmap-to-notion.mjs into scripts/ and set NOTION_TOKEN + NOTION_DB_ID.\n'
+      );
+      process.exit(2);
+    }
+    const r = spawnSync(
+      process.execPath,
+      [notion, '--sync', `--${mode === 'live' ? 'live' : mode === 'docs' ? 'docs-only' : 'offline'}`],
+      {
+        stdio: 'inherit',
+      }
+    );
+    process.exitCode = r.status ?? 1;
+  }
 }

package/dist/roadmap-push.mjs

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+// roadmap-push.mjs — push a project's roadmap extract to a Growth Engine as a report artifact (the Hub).
+//
+// board-sinks-and-scrumban S3.2 — this file ships in the kit (`npx -y @golden-frijoles/kit roadmap-push`, or
+// `roadmap-extract --sink hub`, which calls `pushRoadmap()` in-process), byte-identical in every project's scripts/.
+// So a stranger feeds the hosted board with the same rail this repo uses.
+//
+// pod-report · Sprint 1, Story 1.1. golden-beans is tenant #0: it dogfoods the same client-pushes
+// rail a customer uses, through the same public endpoint, with the same kind of API key. There is
+// no privileged internal path — if this script works, a customer's does too.
+//
+//   node scripts/roadmap-push.mjs                       # push to $GROWTH_ENGINE_URL
+//   node scripts/roadmap-push.mjs --dry-run             # print the envelope, send nothing
+//   node scripts/roadmap-push.mjs --url http://localhost:3000
+//
+// Env: GROWTH_ENGINE_URL (default http://localhost:3000) and the project's ingest key: SELF_PROJECT_API_KEY FIRST (it only
+// ever means this project's own key), else the SDK's GROWTH_ENGINE_API_KEY. Not the other way round — see apiKeyFrom.
+// A missing key is a CLEAN SKIP (exit 0), not a failure — see the note in the CI step.
+
+import { spawnSync } from 'node:child_process';
+import { writeSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getKey } from './lib/config.mjs';
+import { projectRoot } from './lib/project-root.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// The PROJECT, not this file's parent: installed from the kit, this file lives in node_modules (golden-frijoles-plugin D2).
+const REPO_ROOT = projectRoot();
+
+// Must match apps/web/lib/roadmap-artifact-schema.ts's ROADMAP_SCHEMA_VERSION. Duplicated rather
+// than imported because this is a zero-dependency .mjs script and that module is TypeScript behind
+// a Next.js path alias — a spec asserts the two agree so the duplication cannot silently drift.
+export const ROADMAP_SCHEMA_VERSION = 1;
+
+function git(args, root = REPO_ROOT) {
+  const r = spawnSync('git', args, { cwd: root, encoding: 'utf8' });
+  return r.status === 0 ? (r.stdout || '').trim() : null;
+}
+
+/**
+ * Build the push envelope from the extract rows.
+ *
+ * Pure and exported so a unit test pins the contract without running git, spawning the generator or
+ * touching the network — the envelope is the thing the server validates, so it is the thing worth
+ * testing.
+ */
+export function buildEnvelope(items, { commit, ref, generatedAt, board = null } = {}) {
+  return {
+    schemaVersion: ROADMAP_SCHEMA_VERSION,
+    generatedAt: generatedAt ?? new Date().toISOString(),
+    source: {
+      // null, never undefined: JSON.stringify DROPS undefined keys, and a silently absent field is
+      // harder to diagnose server-side than an explicit null.
+      commit: commit ?? null,
+      ref: ref ?? null,
+    },
+    items,
+    // board-sinks-and-scrumban D21 — optional and additive; absent rather than null when there is nothing in it,
+    // so the server's unchanged-board check (D16) never sees a difference that carries no information.
+    ...(board ? { board } : {}),
+  };
+}
+
+/**
+ * The https base a card's repo-relative doc links resolve against, from the `origin` remote:
+ * `git@github.com:o/r.git` or `https://github.com/o/r(.git)` → `https://github.com/o/r/blob/<branch>/`.
+ * null for any other host — a link the Hub cannot build is better left out than guessed.
+ */
+export function repoBlobBase(remoteUrl, branch = 'main') {
+  const m = String(remoteUrl || '')
+    .trim()
+    .match(
+      /^(?:git@github\.com:|https:\/\/(?:[^@/]+@)?github\.com\/)([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?\/?$/
+    );
+  if (!m || !/^[A-Za-z0-9_./-]+$/.test(branch)) return null;
+  return `https://github.com/${m[1]}/${m[2]}/blob/${branch}/`;
+}
+
+/** The envelope's `board` block: the WIP limits from config (D22) and the repo base for doc links. null when empty. */
+export function buildBoard({ wip, repo }) {
+  const limits = {};
+  for (const stage of ['Building', 'QA']) {
+    const n = wip?.[stage];
+    if (Number.isInteger(n) && n > 0) limits[stage] = n;
+  }
+  const board = {};
+  if (Object.keys(limits).length) board.wip = limits;
+  if (repo) board.repo = repo;
+  return Object.keys(board).length ? board : null;
+}
+
+/**
+ * Rows from `roadmap-extract.mjs --live` — the ONE extractor (board-sinks-and-scrumban D15), with git and GitHub facts
+ * gathered now, so the pushed stages are the ones the event that triggered this run produced. Dies loudly on empty
+ * output (LEARNINGS: treat empty as failure).
+ */
+export function readExtract(run = spawnSync) {
+  // --require-live: a failed git/GitHub gather turns the run red rather than publishing a docs-only board.
+  const r = run('node', [resolve(__dirname, 'roadmap-extract.mjs'), '--live', '--require-live'], {
+    cwd: REPO_ROOT,
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  if (r.status !== 0) {
+    throw new Error(`roadmap-extract.mjs --live failed: ${(r.stderr || '').trim().split('\n').pop()}`);
+  }
+  const out = (r.stdout || '').trim();
+  if (!out) throw new Error('roadmap-extract.mjs --live produced no output — treating empty as failure.');
+  const items = JSON.parse(out);
+  if (!Array.isArray(items) || items.length === 0) {
+    throw new Error('extract returned no rows — refusing to push an empty roadmap.');
+  }
+  return items;
+}
+
+/** The project's ingest key: `SELF_PROJECT_API_KEY` first, else the SDK's `GROWTH_ENGINE_API_KEY`. */
+// ⚠️ ORDER MATTERS (fresh review, #227): a repo that ALSO syncs data from another project can hold that other project's
+// key in `GROWTH_ENGINE_API_KEY` (the SDK's name for "the engine key"), so preferring it would push this roadmap into
+// someone else's project from any shell that has it exported. `SELF_PROJECT_API_KEY` — the name that only ever means
+// "this project's own key" — wins; a project that never sets it uses the SDK's name.
+export const apiKeyFrom = (env = process.env) =>
+  env.SELF_PROJECT_API_KEY || env.GROWTH_ENGINE_API_KEY || null;
+
+/** The envelope for `items` as pushed from the checkout at `root`: provenance, the WIP limits, the repo base. */
+export function envelopeFor(items, root = REPO_ROOT) {
+  const defaultBranch = (
+    git(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], root) || 'origin/main'
+  ).replace(/^origin\//, '');
+  return buildEnvelope(items, {
+    commit: git(['rev-parse', 'HEAD'], root),
+    ref: git(['rev-parse', '--abbrev-ref', 'HEAD'], root),
+    board: buildBoard({
+      wip: getKey('board.wip', { root }),
+      repo: repoBlobBase(git(['remote', 'get-url', 'origin'], root), defaultBranch),
+    }),
+  });
+}
+
+/**
+ * Push rows to the engine. Returns `{ ok, skipped, status, text }` and writes nothing to stdout itself — the CLI and
+ * `roadmap-extract --sink hub` say what happened in their own words. No key is a clean skip, never an error.
+ */
+export async function pushRoadmap(
+  items,
+  {
+    root = REPO_ROOT,
+    baseUrl = process.env.GROWTH_ENGINE_URL || 'http://localhost:3000',
+    apiKey = apiKeyFrom(),
+    fetchFn = fetch,
+  } = {}
+) {
+  if (!apiKey) return { ok: true, skipped: true, status: null, text: '' };
+  let res;
+  try {
+    res = await fetchFn(`${String(baseUrl).replace(/\/$/, '')}/api/v1/roadmap/push`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${apiKey}` },
+      body: JSON.stringify(envelopeFor(items, root)),
+      signal: AbortSignal.timeout(30_000),
+    });
+  } catch (err) {
+    // An unreachable engine is a failed push with its reason — never a stack trace (fresh review, #227).
+    return { ok: false, skipped: false, status: null, text: `could not reach ${baseUrl}: ${err.message}` };
+  }
+  return { ok: res.ok, skipped: false, status: res.status, text: await res.text() };
+}
+
+/** The CLI's report for one push result. Exported so `roadmap-extract --sink hub` says it the same way. */
+export function reportPush(result, count) {
+  if (result.skipped) {
+    // Clean skip, not a failure: a repo without the key must not turn every CI run red over an observability-grade
+    // nicety — same stance as the Telegram workflow.
+    process.stderr.write(
+      'SELF_PROJECT_API_KEY (or GROWTH_ENGINE_API_KEY) not set — skipping the roadmap push cleanly.\n' +
+        `  ${count} rows were generated and discarded. Set the project's ingest key to enable this.\n`
+    );
+    return 0;
+  }
+  if (!result.ok) {
+    // The server's own error body names WHICH field failed and whether it was a version or a shape problem.
+    process.stderr.write(`✗ roadmap push failed (${result.status}): ${result.text}\n`);
+    return 1;
+  }
+  writeSync(1, `✓ roadmap pushed (${count} rows): ${result.text}\n`);
+  return 0;
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const urlFlag = args.indexOf('--url');
+  const baseUrl =
+    (urlFlag !== -1 ? args[urlFlag + 1] : undefined) ||
+    process.env.GROWTH_ENGINE_URL ||
+    'http://localhost:3000';
+  const items = readExtract();
+  if (args.includes('--dry-run')) {
+    writeSync(1, `${JSON.stringify(envelopeFor(items), null, 2)}\n`);
+    return;
+  }
+  process.exitCode = reportPush(await pushRoadmap(items, { baseUrl }), items.length);
+}
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  main().catch((err) => {
+    process.stderr.write(`✗ ${err.message}\n`);
+    process.exit(1);
+  });
+}

package/dist/session-resume.mjs

@@ -52,6 +52,7 @@ import { fileURLToPath } from 'node:url';
 import { dirname, join, resolve } from 'node:path';
 import { listPulls, getPullMergeability, getStatusRollup } from './lib/gh-rest.mjs';
 import { readLogFromBranch } from './lib/log-branch.mjs';
+import { gatherFacts } from './lib/stage-facts.mjs';
 import {
   parseJournal,
   lastNEntries,
@@ -858,6 +859,7 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
     homeDir = process.env.HOME,
     now,
     resolveReposFn = resolveRepos,
+    gatherFactsFn = gatherFacts,
   } = deps;
 
   let args;
@@ -875,6 +877,15 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
   try {
     const { repos, note: reposNote } = resolveReposFn({ root: args.root, spawn });
     if (reposNote) warn(`⚠ session-resume: ${reposNote}`);
+    // board-sinks-and-scrumban S3.1 — refresh the board snapshot (.golden-frijoles/board.json) once per session start.
+    // The build view's hook never goes online, so this is what keeps the age it prints short. Best-effort: a failed
+    // gather keeps the old snapshot, and the build view says how old that one is.
+    try {
+      const facts = gatherFactsFn({ root: args.root, mode: 'live', run: spawn });
+      if (facts.note) warn(`⚠ session-resume: board snapshot not refreshed — ${facts.note}`);
+    } catch {
+      // never block a resume on the board
+    }
     const repoStates = repos.map((r) => ({
       repo: r.repo,
       dir: r.dir,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@golden-frijoles/kit",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "The scripts the Golden Frijoles skills run, packaged so they work in any repo: planning, build-order, reporting and verification rails. Zero dependencies.",
   "type": "module",
   "bin": {