@golden-frijoles/kit 0.18.0 → 0.20.0

package/dist/lib/stage-facts.mjs

@@ -0,0 +1,166 @@
+// stage-facts.mjs — gather the git and GitHub facts the stage resolver reads, once per run (board-sinks-and-scrumban
+// D14).
+//
+// Three modes:
+//   live      one `git ls-remote --heads origin` and one `gh pr list --state all`, then the snapshot is rewritten.
+//             When either call fails (no network, no `gh`, no auth) it falls back to the snapshot and says why.
+//   snapshot  read `.golden-frijoles/board.json`. A missing or unreadable snapshot means no facts (docs only).
+//   docs      no facts at all — BUILD-ORDER.md (committed, so it may not hold anything that moves without a commit:
+//             lock C3) and fixtures.
+//
+// ── Why the snapshot holds FACTS, not stages ─────────────────────────────────────────────────────────────
+// A snapshot of computed stages would freeze the docs too: an offline client would keep showing a seed as To groom
+// after its pitch was written. Facts age; docs never do. So an offline run reads the docs as they are NOW and only
+// the branch and PR lists carry an age — which every stage read from them states (`… · snapshot@<iso>`).
+//
+// Zero deps — Node 18+.
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export const SNAPSHOT_PATH = join('.golden-frijoles', 'board.json');
+export const FACT_MODES = Object.freeze(['live', 'snapshot', 'docs']);
+const PR_LIMIT = 1000; // 223 PRs in this repo on 2026-10-01; one call, gh paginates.
+
+// git exports GIT_DIR and friends into hooks, and they override `cwd` (build-state.mjs found this the hard way).
+const GIT_ENV_TO_CLEAR = ['GIT_DIR', 'GIT_INDEX_FILE', 'GIT_WORK_TREE', 'GIT_COMMON_DIR', 'GIT_PREFIX'];
+function cleanEnv() {
+  const env = { ...process.env };
+  for (const k of GIT_ENV_TO_CLEAR) delete env[k];
+  return env;
+}
+
+/** `git ls-remote --heads` output → branch names. Pure. */
+export function parseLsRemote(text) {
+  return String(text || '')
+    .split('\n')
+    .map((line) => line.split('\t')[1] || '')
+    .filter((ref) => ref.startsWith('refs/heads/'))
+    .map((ref) => ref.slice('refs/heads/'.length));
+}
+
+/** `gh pr list --json number,headRefName,state,isDraft,url` → the resolver's PR shape. Pure. */
+export function normalizePrs(list) {
+  if (!Array.isArray(list)) throw new Error('gh pr list did not return an array');
+  return list.map((p) => ({
+    number: Number(p.number),
+    head: String(p.headRefName ?? ''),
+    state: String(p.state ?? '').toUpperCase(),
+    draft: Boolean(p.isDraft),
+    url: String(p.url ?? ''),
+  }));
+}
+
+function readSnapshot(root, read) {
+  try {
+    const data = JSON.parse(read(join(root, SNAPSHOT_PATH), 'utf8'));
+    if (!Array.isArray(data.branches) || !Array.isArray(data.prs) || !data.generated_at) return null;
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+/** Write the snapshot, and the directory's own ignore file when it is missing (the directory is never committed). */
+export function writeSnapshot(
+  root,
+  facts,
+  { write = writeFileSync, exists = existsSync, mkdir = mkdirSync } = {}
+) {
+  const file = join(root, SNAPSHOT_PATH);
+  mkdir(dirname(file), { recursive: true });
+  const ignore = join(dirname(file), '.gitignore');
+  if (!exists(ignore)) write(ignore, '# local roadmap facts and figures, never committed\n*\n');
+  write(file, `${JSON.stringify(facts, null, 2)}\n`);
+}
+
+/**
+ * The facts for one run.
+ * @returns `{ mode, branches, prs, origin, generated_at, note }` — `mode` is the mode actually used (a failed live
+ *          run reports `snapshot` or `docs`), `origin` is `snapshot@<iso>` when the facts were read from the file
+ *          (the resolver appends it to every git/GitHub source) and null otherwise, `note` says why a mode fell back.
+ */
+export function gatherFacts({
+  root,
+  mode = 'snapshot',
+  run = spawnSync,
+  read = readFileSync,
+  persist = writeSnapshot,
+  now = () => new Date(),
+} = {}) {
+  if (!FACT_MODES.includes(mode))
+    throw new Error(`unknown facts mode "${mode}" — one of ${FACT_MODES.join(' | ')}`);
+  const none = (note) => ({ mode: 'docs', branches: [], prs: [], origin: null, generated_at: null, note });
+  if (mode === 'docs') return none(null);
+
+  let note = null;
+  if (mode === 'live') {
+    const opts = { cwd: root, encoding: 'utf8', env: cleanEnv(), maxBuffer: 32 * 1024 * 1024 };
+    const ls = run('git', ['ls-remote', '--heads', 'origin'], { ...opts, timeout: 20_000 });
+    const gh =
+      ls.status === 0
+        ? run(
+            'gh',
+            [
+              'pr',
+              'list',
+              '--state',
+              'all',
+              '--limit',
+              String(PR_LIMIT),
+              '--json',
+              'number,headRefName,state,isDraft,url',
+            ],
+            { ...opts, timeout: 30_000 }
+          )
+        : null;
+    if (ls.status !== 0) note = `live facts unavailable: git ls-remote failed (${firstLine(ls)})`;
+    else if (gh.status !== 0) note = `live facts unavailable: gh pr list failed (${firstLine(gh)})`;
+    else {
+      try {
+        const facts = {
+          generated_at: now().toISOString(),
+          source: 'github',
+          branches: parseLsRemote(ls.stdout),
+          prs: normalizePrs(JSON.parse(gh.stdout)),
+        };
+        try {
+          persist(root, facts);
+        } catch {
+          // A read-only checkout still gets live facts; it just cannot leave a snapshot behind.
+        }
+        return {
+          mode: 'live',
+          branches: facts.branches,
+          prs: facts.prs,
+          origin: null,
+          generated_at: facts.generated_at,
+          note: null,
+        };
+      } catch (err) {
+        note = `live facts unavailable: ${err.message}`;
+      }
+    }
+  }
+
+  const snap = readSnapshot(root, read);
+  if (!snap) return none(note ?? 'no snapshot yet — run with --live once');
+  return {
+    mode: 'snapshot',
+    branches: snap.branches,
+    prs: snap.prs,
+    origin: `snapshot@${snap.generated_at}`,
+    generated_at: snap.generated_at,
+    note,
+  };
+}
+
+function firstLine(res) {
+  if (res.error) return res.error.code === 'ENOENT' ? 'not installed' : res.error.message;
+  return (
+    String(res.stderr || '')
+      .trim()
+      .split('\n')[0] || `exit ${res.status}`
+  ).slice(0, 160);
+}

package/dist/lib/stage.mjs

@@ -0,0 +1,168 @@
+// stage.mjs — the ONE place an initiative's stage is decided (board-sinks-and-scrumban D2, D13).
+//
+// Every roadmap client — the extractor that feeds the Hub and Notion, BUILD-ORDER.md, the CLI build view, the
+// kickoff's WIP advice — reads a stage computed here, so no two of them can compute it differently. Before this,
+// stage was written in five places in two vocabularies (seed `status:`, epic `status:`, `phase:`, a free-text
+// sprint `Status:` line, and inference the CLI mod skipped offline), and the clients disagreed.
+//
+// ── The rule (README § Architecture lock, D13) ───────────────────────────────────────────────────────────
+// 1. Off the board: `status: archived` (epic or seed) → stage null.
+// 2. Shipped: `status: shipped`. Docs win over a stale branch — 12 of the 13 work branches on origin on
+//    2026-10-01 were merged and never deleted (C7), including one of an epic that has shipped.
+// 3. Git and GitHub next. A branch is LIVE while its newest PR is open, or it has none; merged or closed means
+//    done or abandoned. Any live branch → the highest sprint's: an open, non-draft PR is QA, anything else is
+//    Building (a tie goes to Building: work is still happening). No live branch but a merged PR → QA (merged,
+//    close-out owed), unless a sprint AFTER the highest merged one is still Planned by its own docs: then Ready to
+//    build (paused between sprints).
+// 4. Docs last: raw → To groom · ready → Grooming · queued/scaffolded/in-progress → Ready to build.
+//    `in-progress` is never Building on its own word (D3): Building and QA are facts, never fields.
+//
+// Pure: facts come in as arguments (lib/stage-facts.mjs gathers them), so a fixture can pin every case.
+// Zero deps beyond the branch parser the build view already used.
+
+import { branchCandidates } from './work-branch.mjs';
+
+/** The six stages, in board order (D1 — locked by the product owner, 2026-10-01). */
+export const STAGES = Object.freeze(['To groom', 'Grooming', 'Ready to build', 'Building', 'QA', 'Shipped']);
+
+const DOCS_STAGE = {
+  raw: 'To groom',
+  ready: 'Grooming',
+  queued: 'Ready to build',
+  scaffolded: 'Ready to build',
+  'in-progress': 'Ready to build',
+};
+
+/**
+ * Which initiative a branch belongs to: the LONGEST reading of it that names a known slug (`known`), with a
+ * seed that carries `epic:` folded into that epic (`alias`: seed slug → epic slug). null when it names none.
+ */
+export function ownerOf(branch, known, alias = new Map()) {
+  for (const c of branchCandidates(branch)) {
+    if (known.has(c.slug)) return { slug: alias.get(c.slug) ?? c.slug, sprint: c.sprint };
+  }
+  return null;
+}
+
+/**
+ * Split run-wide facts into per-initiative facts. `branches` are origin branch names; `prs` are
+ * `{ number, head, state, draft, url }` with state OPEN | MERGED | CLOSED. A PR is attributed by its head
+ * branch NAME, so a merged PR whose branch was deleted still counts for its initiative.
+ * Returns Map slug → { branches: [{ name, sprint }], prs: [{ …pr, sprint }] }.
+ */
+export function attributeFacts({ branches = [], prs = [] } = {}, known, alias = new Map()) {
+  const out = new Map();
+  const slot = (slug) => {
+    if (!out.has(slug)) out.set(slug, { branches: [], prs: [] });
+    return out.get(slug);
+  };
+  for (const name of branches) {
+    const owner = ownerOf(name, known, alias);
+    if (owner) slot(owner.slug).branches.push({ name, sprint: owner.sprint });
+  }
+  for (const pr of prs) {
+    const owner = ownerOf(pr.head, known, alias);
+    if (owner) slot(owner.slug).prs.push({ ...pr, sprint: owner.sprint });
+  }
+  return out;
+}
+
+const rankOf = (sprint) => sprint ?? 1;
+const newest = (prs) =>
+  prs.reduce((best, pr) => (best === null || pr.number > best.number ? pr : best), null);
+
+/**
+ * The stage of one initiative.
+ *
+ * @param row      `{ grain: 'Epic' | 'Seed', status: <frontmatter status, lower-case, or null>, sprints?, sprints_total? }`
+ *                 — `sprints` is `[{ n, status }]` with each sprint's own docs status (Planned · In progress · …)
+ * @param gitFacts `{ branches: [{ name, sprint }] }` — this initiative's branches on origin
+ * @param prFacts  `{ prs: [{ number, head, state, draft, url, sprint }] }` — PRs from its branches, any state
+ * @param origin   appended to the source when the facts are not live (`snapshot@<iso>`), else null
+ * @returns `{ stage, source, pr }` — stage is one of STAGES or null (archived: off the board); `pr` is the PR
+ *          the stage was read from, or null.
+ */
+export function resolveStage(row, gitFacts = { branches: [] }, prFacts = { prs: [] }, origin = null) {
+  const status = row.status ? String(row.status).toLowerCase() : null;
+  const at = (source) => (origin ? `${source} · ${origin}` : source);
+
+  if (status === 'archived') return { stage: null, source: 'docs: status archived', pr: null };
+  if (status === 'shipped') return { stage: 'Shipped', source: 'docs: status shipped', pr: null };
+
+  const prs = prFacts.prs ?? [];
+  const live = (gitFacts.branches ?? [])
+    .map((b) => ({ ...b, pr: newest(prs.filter((p) => p.head === b.name)) }))
+    .filter((b) => b.pr === null || b.pr.state === 'OPEN');
+
+  if (live.length) {
+    const top = Math.max(...live.map((b) => rankOf(b.sprint)));
+    const atTop = live.filter((b) => rankOf(b.sprint) === top);
+    const ready = (b) => b.pr !== null && !b.pr.draft;
+    // A tie goes to the branch still being built: one ready PR does not make a sprint that is also being worked
+    // on in a sibling branch "in QA".
+    const pick = atTop.find((b) => !ready(b)) ?? atTop[0];
+    if (ready(pick)) return { stage: 'QA', source: at(`github: PR #${pick.pr.number} ready`), pr: pick.pr };
+    if (pick.pr) return { stage: 'Building', source: at(`github: PR #${pick.pr.number} draft`), pr: pick.pr };
+    return { stage: 'Building', source: at(`git: ${pick.name}`), pr: null };
+  }
+
+  const merged = prs.filter((p) => p.state === 'MERGED');
+  if (merged.length) {
+    const top = Math.max(...merged.map((p) => rankOf(p.sprint)));
+    const last = newest(merged.filter((p) => rankOf(p.sprint) === top));
+    // Paused between sprints only when a LATER sprint is still Planned by its own docs. Sprint numbers alone cannot
+    // tell: an epic may ship every sprint in one PR from `feat/<slug>` (scenarios-pm-operable, #98 — 10 of 10
+    // stories), which reads as "sprint 1" (lock run, 2026-10-01). Without sprint statuses, fall back to the count.
+    const later = (row.sprints ?? []).filter((sp) => sp.n > top);
+    const paused =
+      row.grain === 'Epic' &&
+      (Array.isArray(row.sprints)
+        ? later.some((sp) => sp.status === 'Planned')
+        : top < (Number(row.sprints_total) || 0));
+    if (!paused) return { stage: 'QA', source: at(`github: PR #${last.number} merged`), pr: last };
+    const next = later.find((sp) => sp.status === 'Planned');
+    return {
+      stage: 'Ready to build',
+      source: at(`github: PR #${last.number} merged, S${next ? next.n : top + 1} not started`),
+      pr: last,
+    };
+  }
+
+  // Docs last. An absent status reads as raw for a seed (the extractor's legacy tolerance) and as scaffolded for
+  // an epic (it has a README and sprint files, so it was scaffolded).
+  const key = status ?? (row.grain === 'Epic' ? 'scaffolded' : 'raw');
+  const stage = DOCS_STAGE[key] ?? 'Ready to build';
+  return { stage, source: `docs: status ${key}`, pr: null };
+}
+
+/** `build_order_num`, with a missing one sorting last rather than first. */
+const orderKey = (row) =>
+  Number.isFinite(row.build_order_num) ? row.build_order_num : Number.MAX_SAFE_INTEGER;
+
+/**
+ * Rows with a stage, grouped into the six columns in board order. Ready to build runs in build order (D1); Shipped
+ * runs newest first — by `shipped_at` (`shipped: 'recent'`, the default), or by build order, highest first
+ * (`shipped: 'build-order'`). The second exists for a COMMITTED view: `shipped_at` is a git date, and a depth-1 CI
+ * clone dates every row to its one commit, so a file sorted by it is not reproducible (build-order-guard went red on
+ * exactly that). Every other column runs in build order, then name. Rows whose stage is null (archived) or that are
+ * not initiatives (sprint rows) are left out — cards are initiatives (D7).
+ */
+export function groupByStage(rows, { shipped = 'recent' } = {}) {
+  const columns = Object.fromEntries(STAGES.map((s) => [s, []]));
+  for (const row of rows) {
+    if (row.grain === 'Sprint' || !row.stage || !(row.stage in columns)) continue;
+    columns[row.stage].push(row);
+  }
+  for (const stage of STAGES) {
+    columns[stage].sort((a, b) =>
+      stage !== 'Shipped'
+        ? orderKey(a) - orderKey(b) || String(a.name).localeCompare(String(b.name))
+        : shipped === 'build-order'
+          ? (Number.isFinite(b.build_order_num) ? b.build_order_num : -1) -
+              (Number.isFinite(a.build_order_num) ? a.build_order_num : -1) ||
+            String(a.name).localeCompare(String(b.name))
+          : String(b.shipped_at ?? '').localeCompare(String(a.shipped_at ?? '')) || orderKey(a) - orderKey(b)
+    );
+  }
+  return columns;
+}

package/dist/lib/work-branch.mjs

@@ -0,0 +1,51 @@
+// work-branch.mjs — read a work branch name as `<type>/<slug>[-s<N>][-words]` (board-sinks-and-scrumban D13).
+//
+// Moved here, unchanged, from build-state.mjs, where it was born (build-visualization-claude-mods S3). The stage
+// resolver (lib/stage.mjs) needs the SAME reading of a branch as the build view, and a second parser for one
+// naming convention is how two clients come to disagree about which epic a branch belongs to. build-state.mjs
+// re-exports both functions, so nothing that imported them from there had to change.
+//
+// Zero deps, no imports.
+
+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_.]+)*$/;
+
+/** 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 };
+}