@golden-frijoles/kit 0.0.0 → 0.2.0

package/dist/lib/reporting-config.mjs

@@ -0,0 +1,266 @@
+// reporting-config.mjs — the ONE config seam for the reporting family (standup, weekly-recap, pmo-report).
+//
+// ── Why one file, and why it is committed ─────────────────────────────────────────────────────
+// The three reporting scripts were extracted from an origin project with its repo list, Telegram
+// target, smoke workflow and artifact-hosting URLs written straight into source. That is why they sat
+// dark for six weeks (plugin-audit-and-extraction D1/D2): there was no place for a consuming project to
+// put its own values, so porting meant either shipping someone else's targets or rewriting the logic.
+//
+// This module is that place. Every project-specific value the three scripts ACTUALLY read (locked
+// against the source, not against what they appear to read) lives in `reporting.config.json` at the repo
+// root. It is COMMITTED — none of it is a secret (the bot token stays in TELEGRAM_BOT_TOKEN), and a
+// routine's cloud sandbox is a fresh checkout every run, so a gitignored per-skill config.json never
+// survived to the next run anyway. The per-skill `config.json` files this replaces were exactly that trap.
+//
+// ── Public repos: reporting.config.local.json ─────────────────────────────────────────────────
+// A chat id is not a secret, but a PUBLIC repo should still not publish it. An optional, gitignored
+// `reporting.config.local.json` next to the committed file is merged over it (top-level keys replace;
+// `telegram` merges one level deep) — so the committed file carries the repos and signals and the local
+// file carries the chat. Routines keep using TELEGRAM_CHAT_ID, which needs neither.
+//
+// ── Fail loudly, never borrow ─────────────────────────────────────────────────────────────────
+// A missing or malformed file THROWS a ReportingConfigError that names the file. There is no default
+// repo list and no default chat: a reporting script that silently falls back to a baked-in target posts
+// one project's status into another project's channel. Optional sections are optional in the explicit
+// sense — absent means "this signal is off here", and the scripts say so rather than guessing.
+//
+// Zero deps — Node 18+.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { projectRoot } from './project-root.mjs';
+
+export const DEFAULT_ROOT = projectRoot(); // D2
+export const CONFIG_FILENAME = 'reporting.config.json';
+export const EXAMPLE_FILENAME = 'reporting.config.example.json';
+export const LOCAL_FILENAME = 'reporting.config.local.json';
+
+export const SURFACES = ['standup', 'weekly', 'pmo', 'merge'];
+const REPO_RE = /^[\w.-]+\/[\w.-]+$/;
+
+export class ReportingConfigError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ReportingConfigError';
+  }
+}
+
+/** Where the config lives. `REPORTING_CONFIG` overrides it (tests, or a project that keeps it elsewhere). */
+export function configPath({ root = DEFAULT_ROOT, env = process.env } = {}) {
+  return env.REPORTING_CONFIG ? resolve(root, env.REPORTING_CONFIG) : join(root, CONFIG_FILENAME);
+}
+
+function fail(path, msg) {
+  throw new ReportingConfigError(`${path}: ${msg}`);
+}
+
+function repoList(path, value, key) {
+  if (!Array.isArray(value)) fail(path, `"${key}" must be an array of "owner/name" strings`);
+  for (const r of value) {
+    if (typeof r !== 'string' || !REPO_RE.test(r))
+      fail(path, `"${key}" has an invalid repo "${r}" — expected "owner/name"`);
+  }
+  return value;
+}
+
+/**
+ * Pure — validate a parsed config object and return it normalized. Throws ReportingConfigError on any
+ * shape problem, naming the key. `path` is only used in the messages.
+ */
+export function validateReportingConfig(raw, path = CONFIG_FILENAME) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) fail(path, 'must be a JSON object');
+
+  const repos = repoList(path, raw.repos, 'repos');
+  if (!repos.length) fail(path, '"repos" is empty — list every repo the reports aggregate over');
+
+  const deployRepos = (raw.deployRepos ?? []).map((d, i) => {
+    if (!d || typeof d !== 'object' || typeof d.label !== 'string' || !d.label.trim()) {
+      fail(path, `"deployRepos[${i}]" needs a "label" (e.g. "Frontend") and a "repo"`);
+    }
+    repoList(path, [d.repo], `deployRepos[${i}].repo`);
+    return { label: d.label, repo: d.repo };
+  });
+
+  const telegram = raw.telegram ?? {};
+  if (!telegram || typeof telegram !== 'object' || Array.isArray(telegram))
+    fail(path, '"telegram" must be an object');
+  for (const k of ['chatId']) {
+    if (telegram[k] != null && typeof telegram[k] !== 'string' && typeof telegram[k] !== 'number')
+      fail(path, `"telegram.${k}" must be a string or number`);
+  }
+  const chatIds = telegram.chatIds ?? {};
+  for (const k of Object.keys(chatIds)) {
+    if (!SURFACES.includes(k))
+      fail(path, `"telegram.chatIds.${k}" is not a surface — use one of ${SURFACES.join(', ')}`);
+    if (typeof chatIds[k] !== 'string' && typeof chatIds[k] !== 'number')
+      fail(path, `"telegram.chatIds.${k}" must be a string or number`);
+  }
+
+  let smoke = null;
+  if (raw.smoke != null) {
+    if (typeof raw.smoke !== 'object' || Array.isArray(raw.smoke))
+      fail(path, '"smoke" must be an object {repo, workflow}');
+    repoList(path, [raw.smoke.repo], 'smoke.repo');
+    if (typeof raw.smoke.workflow !== 'string' || !raw.smoke.workflow)
+      fail(path, '"smoke.workflow" must name a workflow file');
+    smoke = { repo: raw.smoke.repo, workflow: raw.smoke.workflow };
+  }
+
+  let liveFlags = null;
+  if (raw.liveFlags != null) {
+    const cmd = raw.liveFlags.command;
+    if (!Array.isArray(cmd) || !cmd.length || cmd.some((c) => typeof c !== 'string')) {
+      fail(
+        path,
+        '"liveFlags.command" must be a non-empty argv array (e.g. ["node", "scripts/flags.mjs", "--list-on"])'
+      );
+    }
+    liveFlags = { command: cmd, cwd: raw.liveFlags.cwd || '.' };
+  }
+
+  // Where each repo is checked out locally (session-resume.mjs's git read), relative to the repo root.
+  const checkouts = raw.checkouts ?? {};
+  if (typeof checkouts !== 'object' || Array.isArray(checkouts))
+    fail(path, '"checkouts" must map "owner/name" to a local directory');
+  for (const [repo, dir] of Object.entries(checkouts)) {
+    if (!repos.includes(repo)) fail(path, `"checkouts.${repo}" is not one of "repos"`);
+    if (
+      typeof dir !== 'string' ||
+      !dir ||
+      dir.startsWith('/') ||
+      dir.includes('\\') ||
+      dir.split('/').includes('..')
+    ) {
+      fail(path, `"checkouts.${repo}" must be a relative directory inside the repo root`);
+    }
+  }
+
+  // What owed-ledger.mjs counts: who manual checks are owed to, and where the specs live.
+  const owed = raw.owed ?? {};
+  if (typeof owed !== 'object' || Array.isArray(owed))
+    fail(path, '"owed" must be an object {owners, specDirs}');
+  for (const k of ['owners', 'specDirs']) {
+    if (
+      owed[k] != null &&
+      (!Array.isArray(owed[k]) || owed[k].some((v) => typeof v !== 'string' || !v.trim()))
+    ) {
+      fail(path, `"owed.${k}" must be an array of non-empty strings`);
+    }
+  }
+  for (const d of owed.specDirs ?? []) {
+    if (d.startsWith('/') || d.includes('\\') || d.split('/').includes('..'))
+      fail(path, `"owed.specDirs" entry "${d}" must be relative, inside the repo`);
+  }
+
+  const stalePreviewAgeDays = raw.stalePreviewAgeDays ?? null;
+  if (stalePreviewAgeDays !== null && !(Number.isInteger(stalePreviewAgeDays) && stalePreviewAgeDays > 0)) {
+    fail(
+      path,
+      '"stalePreviewAgeDays" must be a positive integer, or absent to skip the stale-preview signal'
+    );
+  }
+  // The prune script has no default project (a defaulted name prunes someone else's project), so the
+  // signal needs one named here. Age without a project is a config error, not a silently-dark signal.
+  const vercelProject = raw.vercelProject ?? null;
+  if (vercelProject !== null && (typeof vercelProject !== 'string' || !/^[\w.-]+$/.test(vercelProject)))
+    fail(path, '"vercelProject" must be a Vercel project name');
+  if (stalePreviewAgeDays !== null && vercelProject === null)
+    fail(path, '"stalePreviewAgeDays" needs "vercelProject" — the Vercel project whose previews it counts');
+
+  const artifacts = raw.artifacts ?? {};
+  const docViewerUrl = artifacts.docViewerUrl ?? null;
+  if (docViewerUrl !== null && !/^https?:\/\//.test(docViewerUrl))
+    fail(path, '"artifacts.docViewerUrl" must be an http(s) URL');
+  const registry = artifacts.registry ?? null;
+  if (registry !== null) {
+    if (!/^https?:\/\//.test(registry.resolverBaseUrl || ''))
+      fail(path, '"artifacts.registry.resolverBaseUrl" must be an http(s) URL');
+    if (typeof registry.bucket !== 'string' || !registry.bucket)
+      fail(path, '"artifacts.registry.bucket" must name a bucket');
+  }
+
+  const prose = raw.prose ?? {};
+  const extraBannedToolNames = prose.extraBannedToolNames ?? [];
+  if (!Array.isArray(extraBannedToolNames) || extraBannedToolNames.some((t) => typeof t !== 'string')) {
+    fail(path, '"prose.extraBannedToolNames" must be an array of regex fragments');
+  }
+  // Compile each fragment NOW: a bad one would otherwise throw inside the prose guard at --post time.
+  for (const t of extraBannedToolNames) {
+    try {
+      new RegExp(`\\b${t}\\b`, 'i');
+    } catch (e) {
+      fail(path, `"prose.extraBannedToolNames" has an invalid regex fragment "${t}" (${e.message})`);
+    }
+  }
+
+  return {
+    repos,
+    deployRepos,
+    checkouts,
+    owed: { owners: owed.owners ?? null, specDirs: owed.specDirs ?? null },
+    telegram: { chatId: telegram.chatId ?? null, chatIds },
+    smoke,
+    liveFlags,
+    stalePreviewAgeDays,
+    vercelProject,
+    artifacts: { docViewerUrl, registry },
+    prose: { extraBannedToolNames },
+  };
+}
+
+/**
+ * Read + validate the project's reporting config. Throws ReportingConfigError — naming the file and how
+ * to create it — when it is absent. Never returns a default.
+ */
+export function loadReportingConfig({
+  root = DEFAULT_ROOT,
+  env = process.env,
+  read = readFileSync,
+  exists = existsSync,
+} = {}) {
+  const path = configPath({ root, env });
+  if (!exists(path)) {
+    throw new ReportingConfigError(
+      `${path} not found — the reporting scripts refuse to guess which repos to read or where to post.\n` +
+        `  Copy ${EXAMPLE_FILENAME} to ${CONFIG_FILENAME} at the repo root, fill it in, and commit it.`
+    );
+  }
+  const parse = (p) => {
+    try {
+      return JSON.parse(read(p, 'utf8'));
+    } catch (e) {
+      return fail(p, `is not valid JSON (${e.message})`);
+    }
+  };
+  let raw = parse(path);
+  const localPath = join(dirname(path), LOCAL_FILENAME);
+  if (exists(localPath)) raw = mergeLocal(raw, parse(localPath));
+  return validateReportingConfig(raw, path);
+}
+
+/** Pure — overlay the gitignored local file: top-level keys replace, `telegram` merges one level deep. */
+export function mergeLocal(base, local) {
+  if (!local || typeof local !== 'object' || Array.isArray(local)) return base;
+  const out = { ...base, ...local };
+  if (base?.telegram || local.telegram) {
+    out.telegram = {
+      ...(base?.telegram || {}),
+      ...(local.telegram || {}),
+      chatIds: { ...(base?.telegram?.chatIds || {}), ...(local.telegram?.chatIds || {}) },
+    };
+  }
+  return out;
+}
+
+/**
+ * The chat to post a surface to: the surface's own id, then the project-wide one, then TELEGRAM_CHAT_ID.
+ * Returns null when none is set — the caller must refuse to send rather than pick one.
+ */
+export function chatIdFor(config, surface, env = process.env) {
+  return config?.telegram?.chatIds?.[surface] || config?.telegram?.chatId || env.TELEGRAM_CHAT_ID || null;
+}
+
+/** "owner/name" → "name", the label the reports print. */
+export function shortRepo(repo) {
+  return repo.split('/')[1] || repo;
+}

package/dist/lib/roadmap-contract.mjs

@@ -0,0 +1,305 @@
+// roadmap-contract.mjs — THE machine-readable frontmatter contract for Roadmap epic docs, defined once
+// (build-visualization-claude-mods D8). doc-format.mjs enforces it, roadmap-backfill.mjs writes it and
+// build-state.mjs reads it; none of them restates a field list. Pure: zero I/O, zero dependencies.
+//
+// What it replaces: epic title/area/risk lived in a bold prose line, sprint files had NO frontmatter
+// at all, and a story's identity and user story were prose under a `### Story N.M —` heading that
+// came in six shapes across the corpus. A tool that scrapes those reports confidently while wrong.
+//
+// ── The shape ──────────────────────────────────────────────────────────────────────────────────────
+// Epic README frontmatter — the lifecycle `status:` (scaffolded|in-progress|shipped|archived, the
+// board's SSOT, untouched by this contract) plus:
+//   title · area · risk · type · phase · sprints_total · stories_total   (and the existing slug, build_order)
+// sprint-N.md frontmatter:
+//   epic · sprint · title · risk · phase · stories_total · stories
+// Each `stories:` entry (D1 — a list in the sprint frontmatter, one flat map per story):
+//   id · title · as_a · i_want · so_that · risk · status
+// The three user-story fields are the prose's own words, article included, so they render back as
+// "As <as_a>, I want <i_want>, so that <so_that>." — `as_a: a buyer's agent`, `as_a: the product owner`.
+//
+// ── Why the ladder is `phase:` and not `status:` (D6) ─────────────────────────────────────────────
+// An epic README's `status:` is the lifecycle every roadmap tool reads, and an unknown value there
+// hard-fails the extractor. On a sprint file, a frontmatter `status:` line would be captured by the
+// extractor's case-insensitive `^Status:` regex before the prose Status line, silently re-deriving
+// the board. So the executive ladder is its own field on both.
+//
+// ── The YAML subset ────────────────────────────────────────────────────────────────────────────────
+// Deliberately small, so a zero-dependency parser owns it completely: top-level `key: scalar` lines
+// (an unquoted value may carry a trailing ` # comment`), whole-line `#` comments at any indent, and a
+// top-level `key:` followed by a list of flat maps (`  - k: v` then `    k: v`). A scalar is `null`,
+// `~` or empty (→ null), `[]` (an empty list), an integer, a double-quoted JSON string, a single-quoted
+// YAML string, or a bare string; any of them may carry a trailing ` # comment`. Booleans and floats are
+// not in the subset (no contract field uses one). Anything else is a parse error, not guessed around.
+
+export const PHASES = ['Shaping', 'Locking architecture', 'Building', 'Verifying', 'In review', 'Shipped'];
+export const STORY_STATUSES = ['planned', 'in-progress', 'done'];
+export const RISKS = ['low', 'high'];
+export const TYPES = ['feature', 'spike', 'bug', 'chore'];
+
+export const EPIC_FIELDS = ['title', 'area', 'risk', 'type', 'phase', 'sprints_total', 'stories_total'];
+export const SPRINT_FIELDS = ['epic', 'sprint', 'title', 'risk', 'phase', 'stories_total', 'stories'];
+export const STORY_FIELDS = ['id', 'title', 'as_a', 'i_want', 'so_that', 'risk', 'status'];
+
+// A story id names its sprint: S<sprint>.<ordinal>. The commit convention D2 derives from uses it.
+export const STORY_ID_RE = /^S(\d+)\.(\d+)$/;
+
+// ── Parse ────────────────────────────────────────────────────────────────────────────────────────
+
+function parseScalar(raw, where) {
+  let v = raw.trim();
+  // A trailing ` # comment` is allowed after any value — quoted ones included, so a hand-edit that
+  // annotates a quoted title does not turn into a parse error.
+  const quoted = v.match(/^("(?:[^"\\]|\\.)*"|'(?:[^']|'')*')(?:\s+#.*)?$/);
+  if (quoted) v = quoted[1];
+  else {
+    const hash = v.search(/\s#/);
+    if (hash >= 0) v = v.slice(0, hash).trim();
+  }
+  if (v === '' || v === 'null' || v === '~') return null;
+  if (v === '[]') return [];
+  if (/^-?\d+$/.test(v)) return Number(v);
+  if (v.startsWith('"')) {
+    try {
+      return JSON.parse(v);
+    } catch {
+      throw new Error(`${where}: malformed double-quoted value ${v}`);
+    }
+  }
+  if (v.startsWith("'")) {
+    if (!/^'(?:[^']|'')*'$/.test(v)) throw new Error(`${where}: malformed single-quoted value ${v}`);
+    return v.slice(1, -1).replace(/''/g, "'");
+  }
+  return v;
+}
+
+/**
+ * Split a markdown doc into its frontmatter data and body.
+ * Returns { hasFrontmatter, data, body, raw, error } — `error` is a parse error message (the data is
+ * then partial); `raw` is the text between the fences.
+ */
+export function parseDocFrontmatter(md) {
+  const lines = md.split('\n');
+  if (lines[0].trim() !== '---') return { hasFrontmatter: false, data: {}, body: md, raw: null, error: null };
+  const end = lines.findIndex((l, i) => i > 0 && l.trim() === '---');
+  if (end === -1)
+    return { hasFrontmatter: false, data: {}, body: md, raw: null, error: 'unterminated frontmatter' };
+  const block = lines.slice(1, end);
+  const data = {};
+  let error = null;
+  let list = null; // the list currently being filled
+  let item = null; // the map currently being filled
+  try {
+    for (let i = 0; i < block.length; i++) {
+      const line = block[i];
+      const where = `frontmatter line ${i + 2}`;
+      if (line.trim() === '' || /^\s*#/.test(line)) continue;
+      const top = line.match(/^(\w+):(?:\s+(.*))?$/);
+      if (top) {
+        const [, key, rest = ''] = top;
+        if (
+          rest.trim() === '' &&
+          /^\s+-\s/.test(block.slice(i + 1).find((l) => l.trim() && !/^\s*#/.test(l)) || '')
+        ) {
+          list = data[key] = [];
+          item = null;
+        } else {
+          data[key] = parseScalar(rest, where);
+          list = null;
+          item = null;
+        }
+        continue;
+      }
+      const start = line.match(/^\s+-\s+(\w+):(?:\s+(.*))?$/);
+      if (start && list) {
+        item = {};
+        list.push(item);
+        item[start[1]] = parseScalar(start[2] || '', where);
+        continue;
+      }
+      const field = line.match(/^\s+(\w+):(?:\s+(.*))?$/);
+      if (field && item) {
+        item[field[1]] = parseScalar(field[2] || '', where);
+        continue;
+      }
+      throw new Error(`${where}: not in the contract's YAML subset: "${line.trim()}"`);
+    }
+  } catch (e) {
+    error = e.message;
+  }
+  return { hasFrontmatter: true, data, body: lines.slice(end + 1).join('\n'), raw: block.join('\n'), error };
+}
+
+// ── Serialize ────────────────────────────────────────────────────────────────────────────────────
+
+const BARE_SAFE = /^[A-Za-z0-9][A-Za-z0-9 _.,/()&+-]*$/;
+const RESERVED = new Set(['null', 'true', 'false', 'yes', 'no', 'on', 'off', '~']);
+
+/** One scalar in the subset's syntax: bare when unambiguous, else a double-quoted JSON string. */
+export function formatScalar(v) {
+  if (v === null || v === undefined) return 'null';
+  if (typeof v === 'number') return String(v);
+  const s = String(v);
+  if (BARE_SAFE.test(s) && !/^-?\d+$/.test(s) && !RESERVED.has(s.toLowerCase()) && !s.endsWith(' ')) return s;
+  return JSON.stringify(s);
+}
+
+/** `key: value` lines (and `key:` + a list of maps) for the given keys, in order. No fences. */
+export function serializeFields(data, keys) {
+  const out = [];
+  for (const key of keys) {
+    const v = data[key];
+    if (Array.isArray(v) && !v.length) {
+      out.push(`${key}: []`); // an empty list stays a list on the way back in
+    } else if (Array.isArray(v)) {
+      out.push(`${key}:`);
+      for (const entry of v) {
+        Object.keys(entry).forEach((k, i) =>
+          out.push(`${i === 0 ? '  - ' : '    '}${k}: ${formatScalar(entry[k])}`)
+        );
+      }
+    } else {
+      out.push(`${key}: ${formatScalar(v)}`);
+    }
+  }
+  return out.join('\n');
+}
+
+// ── Validate ─────────────────────────────────────────────────────────────────────────────────────
+// Each validator returns a list of { rule, detail } offenses — the shape doc-format.mjs reports.
+
+const isInt = (v) => Number.isInteger(v) && v >= 0;
+const oneOf = (v, set) => set.includes(v);
+
+/**
+ * An epic README's frontmatter. `ctx.sprintCount` / `ctx.storyCount`, when given, are cross-checked
+ * against the declared totals. An `archived` epic is frozen record and exempt from the new fields.
+ */
+export function validateEpicFrontmatter(parsed, ctx = {}) {
+  const offenses = [];
+  if (!parsed.hasFrontmatter) return offenses; // frontmatter-missing is doc-format's existing rule
+  if (parsed.error) return [{ rule: 'contract-parse', detail: parsed.error }];
+  const fm = parsed.data;
+  if (fm.status === 'archived') return offenses;
+  for (const key of EPIC_FIELDS) {
+    if (!(key in fm) || fm[key] === null)
+      offenses.push({ rule: 'contract-epic-field-missing', detail: `no \`${key}:\`` });
+  }
+  if (fm.phase != null && !oneOf(fm.phase, PHASES))
+    offenses.push({
+      rule: 'contract-phase-invalid',
+      detail: `phase: "${fm.phase}" is not one of ${PHASES.join(' | ')}`,
+    });
+  if (fm.risk != null && !oneOf(fm.risk, RISKS))
+    offenses.push({
+      rule: 'contract-risk-invalid',
+      detail: `risk: "${fm.risk}" is not one of ${RISKS.join(' | ')}`,
+    });
+  if (fm.type != null && !oneOf(fm.type, TYPES))
+    offenses.push({
+      rule: 'contract-type-invalid',
+      detail: `type: "${fm.type}" is not one of ${TYPES.join(' | ')}`,
+    });
+  for (const key of ['sprints_total', 'stories_total']) {
+    if (fm[key] != null && !isInt(fm[key]))
+      offenses.push({ rule: 'contract-total-invalid', detail: `${key}: "${fm[key]}" is not a whole number` });
+  }
+  if (isInt(fm.sprints_total) && isInt(ctx.sprintCount) && fm.sprints_total !== ctx.sprintCount)
+    offenses.push({
+      rule: 'contract-total-mismatch',
+      detail: `sprints_total: ${fm.sprints_total}, but the epic has ${ctx.sprintCount} sprint-N.md file(s)`,
+    });
+  if (isInt(fm.stories_total) && isInt(ctx.storyCount) && fm.stories_total !== ctx.storyCount)
+    offenses.push({
+      rule: 'contract-total-mismatch',
+      detail: `stories_total: ${fm.stories_total}, but its sprints declare ${ctx.storyCount} stories`,
+    });
+  return offenses;
+}
+
+/** A sprint-N.md's frontmatter. `ctx.n` is the file's sprint number, `ctx.slug` its epic's slug. */
+export function validateSprintFrontmatter(parsed, ctx = {}) {
+  if (!parsed.hasFrontmatter)
+    return [
+      {
+        rule: 'contract-sprint-frontmatter-missing',
+        detail: 'no --- frontmatter block at the top of the sprint file',
+      },
+    ];
+  if (parsed.error) return [{ rule: 'contract-parse', detail: parsed.error }];
+  const offenses = [];
+  const fm = parsed.data;
+  for (const key of SPRINT_FIELDS) {
+    if (!(key in fm) || (fm[key] === null && key !== 'stories'))
+      offenses.push({ rule: 'contract-sprint-field-missing', detail: `no \`${key}:\`` });
+  }
+  if (ctx.slug && fm.epic != null && fm.epic !== ctx.slug)
+    offenses.push({
+      rule: 'contract-sprint-epic-mismatch',
+      detail: `epic: "${fm.epic}", but the file is in "${ctx.slug}"`,
+    });
+  if (isInt(ctx.n) && fm.sprint != null && fm.sprint !== ctx.n)
+    offenses.push({
+      rule: 'contract-sprint-number-mismatch',
+      detail: `sprint: ${fm.sprint}, but the file is sprint-${ctx.n}.md`,
+    });
+  if (fm.phase != null && !oneOf(fm.phase, PHASES))
+    offenses.push({
+      rule: 'contract-phase-invalid',
+      detail: `phase: "${fm.phase}" is not one of ${PHASES.join(' | ')}`,
+    });
+  if (fm.risk != null && !oneOf(fm.risk, RISKS))
+    offenses.push({
+      rule: 'contract-risk-invalid',
+      detail: `risk: "${fm.risk}" is not one of ${RISKS.join(' | ')}`,
+    });
+
+  // A sprint with no stories says so with `stories: []`. A bare `stories:` (null) or a scalar is not a
+  // list, and would let `stories_total: 0` pass with nothing machine-readable behind it (found by the
+  // codex pass on golden-beans#156).
+  if ('stories' in fm && !Array.isArray(fm.stories)) {
+    offenses.push({
+      rule: 'contract-stories-invalid',
+      detail: '`stories:` must be a list of story maps (write `stories: []` for none)',
+    });
+    return offenses;
+  }
+  const stories = fm.stories || [];
+  if (fm.stories_total != null && (!isInt(fm.stories_total) || fm.stories_total !== stories.length))
+    offenses.push({
+      rule: 'contract-total-mismatch',
+      detail: `stories_total: ${fm.stories_total}, but \`stories:\` lists ${stories.length}`,
+    });
+  const seen = new Set();
+  stories.forEach((s, i) => {
+    const label = s.id ? `story ${s.id}` : `story #${i + 1}`;
+    for (const key of STORY_FIELDS) {
+      if (!(key in s))
+        offenses.push({ rule: 'contract-story-field-missing', detail: `${label}: no \`${key}:\`` });
+    }
+    const m = typeof s.id === 'string' ? s.id.match(STORY_ID_RE) : null;
+    if (!m)
+      offenses.push({
+        rule: 'contract-story-id-invalid',
+        detail: `${label}: id must look like S<sprint>.<n>`,
+      });
+    else if (isInt(ctx.n) && Number(m[1]) !== ctx.n)
+      offenses.push({
+        rule: 'contract-story-id-invalid',
+        detail: `${label}: id names sprint ${m[1]}, but the file is sprint-${ctx.n}.md`,
+      });
+    if (s.id && seen.has(s.id))
+      offenses.push({ rule: 'contract-story-id-duplicate', detail: `${label} appears twice` });
+    seen.add(s.id);
+    if ('risk' in s && !oneOf(s.risk, RISKS))
+      offenses.push({
+        rule: 'contract-risk-invalid',
+        detail: `${label}: risk "${s.risk}" is not one of ${RISKS.join(' | ')}`,
+      });
+    if ('status' in s && !oneOf(s.status, STORY_STATUSES))
+      offenses.push({
+        rule: 'contract-story-status-invalid',
+        detail: `${label}: status "${s.status}" is not one of ${STORY_STATUSES.join(' | ')}`,
+      });
+  });
+  return offenses;
+}

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

@@ -0,0 +1,20 @@
+// roadmap-status-buckets.mjs — the SSOT for epic-status buckets and the seed-funnel definition, shared
+// by scripts/build-order.mjs (Roadmap/00-ideas/BUILD-ORDER.md — the canonical in-repo board) and any
+// other view of the roadmap a project builds (a reporting hub's live views, a dashboard). A single
+// export means two views CANNOT independently drift on WHICH statuses count as "the funnel" or
+// "building now" — matching counts are enforced by construction, not by a regression test alone.
+//
+// Extracted in the origin project after a real bug: a hub view counted EVERY grain:'Seed' row as a
+// funnel member (including seeds that had since shipped/scaffolded/archived), while the board correctly
+// counted only Raw/Ready/Queued — the hub's funnel stat was silently overcounting.
+
+export const EPIC_STATUS_ORDER = ['In progress', 'Scaffolded', 'Shipped'];
+
+// Seeds not yet scaffolded = the funnel. A seed can also carry Shipped/Scaffolded/Archived (it
+// graduated into a real epic, or was retired) — those are NOT funnel members even though they're still
+// grain: 'Seed' rows in the projection.
+export const SEED_FUNNEL_STATUSES = new Set(['Raw', 'Ready', 'Queued']);
+
+export function isFunnelSeed(row) {
+  return row?.grain === 'Seed' && SEED_FUNNEL_STATUSES.has(row.status);
+}