@golden-frijoles/kit 0.26.2 → 0.27.0

package/dist/emit-epic-kickoff.mjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+// emit-epic-kickoff.mjs — print the finished, paste-ready EPIC-MODE kickoff for a groomed epic.
+//
+// ── Why this exists ──────────────────────────────────────────────────────────────────────────────────
+// Epic mode — one orchestrated run across a whole epic, sprint files as internal integration boundaries
+// — is the DEFAULT unit of work. But the only generator that existed was `emit-kickoff.mjs`, which emits
+// a single-sprint prompt, so every epic-mode kickoff was composed BY HAND. Hand-composed prompts are
+// exactly where a process contract erodes: the architecture-lock pass gets summarised away, the review
+// policy reverts to whatever the composing agent remembered, and nobody notices because the prompt still
+// looks complete. This is the sibling generator, and the two now split cleanly:
+//
+//   emit-epic-kickoff.mjs  → the DEFAULT. One prompt, whole epic, one orchestrator.
+//   emit-kickoff.mjs       → the EXCEPTION. A single-sprint epic, or a sprint whose outcome genuinely
+//                            changes the next sprint's scope (so the next kickoff can't be written yet).
+//
+// Same contract as its sibling: it resolves the epic by SEARCHING Roadmap/*/<slug>/ under the project root
+// (lib/kickoff-cli.mjs: --repo-root, else GF_PROJECT_ROOT, else the project around cwd), reads the epic README and EVERY sprint-N.md, substitutes into EPIC_KICKOFF_TEMPLATE (lib/epic-kickoff.mjs)
+// and prints to stdout. It writes no file — read + print, editorial control stays with the caller.
+//
+// The prompt POINTS at the process instead of restating it. WAYS-OF-WORKING → *Epic-mode builds* is the
+// one copy of the doctrine; an earlier template restated it verbatim and the two had already drifted on the
+// review policy. The test fails if a section the template names is missing, so the pointer can't dangle.
+// What stays in the prompt: the few non-negotiables that went missing when prompts were hand-composed, and
+// rules picked from THIS epic's docs (high risk, a migration, a flag) — see buildEpicRules.
+//
+// Usage, from the project root (the project's own `scripts/` copy wins, else the kit):
+//   npx -y @golden-frijoles/kit emit-epic-kickoff --epic <slug> [--repo-root <path>]
+//   npx -y @golden-frijoles/kit emit-epic-kickoff --list [--repo-root <path>]   # the epics a kickoff can start
+//                                       # (live-build-view S2.4): `scaffolded` or `in-progress`, build order first
+//
+// The kickoff's one home is `/build <slug>` (the plugin's mod runs groom's vendored copy of THIS file and fills the
+// prompt with its output); hosts without the mod run it through the kit. It is never saved to a file — the epic docs
+// are the state, regenerate it.
+//
+// One source, three homes (kickoff-generator-path C1): this file ships in the kit, a project spawned from the template
+// carries it in `scripts/`, and the groom skill holds a byte-identical copy in `vendor/` (render-hook-vendor.mjs).
+
+import { readFileSync, readdirSync, existsSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+
+// The builder, its parsers and the template text live in ONE file, `lib/epic-kickoff.mjs` (board-sinks-and-scrumban
+// D17): the Hub's Ready-to-build card carries the kickoff the extractor builds from that same file, so the card and
+// this CLI cannot print two different prompts. Re-exported for the spec.
+import { parseFrontmatter } from './emit-kickoff.mjs';
+import { parseArgs, resolveRepoRoot, findEpicDir } from './lib/kickoff-cli.mjs';
+import {
+  sprintNumFromFilename,
+  listSprintFiles,
+  buildSprintFileList,
+  compactStory,
+  buildSprintBreakdown,
+  buildEpicRules,
+  buildEpicKickoff,
+  parseEpicRisk,
+  epicKickoffFromDir,
+  EPIC_KICKOFF_TEMPLATE,
+} from './lib/epic-kickoff.mjs';
+import { wipWarning } from './lib/wip.mjs';
+export {
+  sprintNumFromFilename,
+  listSprintFiles,
+  buildSprintFileList,
+  compactStory,
+  buildSprintBreakdown,
+  buildEpicRules,
+  buildEpicKickoff,
+  parseEpicRisk,
+  EPIC_KICKOFF_TEMPLATE,
+};
+
+// ── filesystem helpers (thin, not unit-tested — exercised by the real run) ──────────────────
+
+function die(msg) {
+  console.error(`emit-epic-kickoff: ${msg}`);
+  process.exit(1);
+}
+
+const STARTABLE = ['scaffolded', 'in-progress'];
+
+/**
+ * The epics a kickoff can start, from each README's frontmatter: `{ slug, title, status, build_order }`, status
+ * scaffolded or in-progress, sorted by build_order (unordered last), then slug. Pure over `read`/`list` for the spec.
+ */
+export function listEpics(repoRoot, { read = (p) => readFileSync(p, 'utf8'), exists = existsSync, list = readdirSync } = {}) {
+  const roadmapDir = join(repoRoot, 'Roadmap');
+  if (!exists(roadmapDir)) return [];
+  const out = [];
+  for (const macro of list(roadmapDir)) {
+    if (!/^\d{2}-/.test(macro)) continue;
+    let slugs = [];
+    try {
+      slugs = list(join(roadmapDir, macro));
+    } catch {
+      continue;
+    }
+    for (const slug of slugs) {
+      const readme = join(roadmapDir, macro, slug, 'README.md');
+      if (!exists(readme)) continue;
+      const fm = parseFrontmatter(read(readme));
+      if (!STARTABLE.includes(fm.status)) continue;
+      const order = Number.parseInt(fm.build_order, 10);
+      out.push({ slug, title: String(fm.title ?? slug).replace(/^"(.*)"$/, '$1'), status: fm.status, build_order: Number.isFinite(order) ? order : null });
+    }
+  }
+  return out.sort((a, b) => (a.build_order ?? Infinity) - (b.build_order ?? Infinity) || a.slug.localeCompare(b.slug));
+}
+
+/** The list as printed: one epic per line, the slug first so it can be typed after `/build `. */
+export function formatEpicList(epics) {
+  if (!epics.length) return 'No scaffolded or in-progress epics under Roadmap/ — groom one first.';
+  return epics.map((e) => `${e.slug}  ${e.title}  (${e.status}${e.build_order !== null ? `, #${e.build_order}` : ''})`).join('\n');
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.list) {
+    process.stdout.write(`${formatEpicList(listEpics(resolveRepoRoot(args)))}\n`);
+    return;
+  }
+  if (!args.epic || args.epic === true) {
+    console.error('emit-epic-kickoff: missing required flag: --epic');
+    console.error('Run with --epic <slug> [--repo-root <path>]');
+    process.exit(1);
+  }
+
+  const slug = String(args.epic);
+  const repoRoot = resolveRepoRoot(args);
+  const found = findEpicDir(repoRoot, slug);
+  if (found.error) die(found.error);
+  const { macro, dir } = found;
+
+  const readmeText = readFileSync(join(dir, 'README.md'), 'utf8');
+  const frontmatter = parseFrontmatter(readmeText);
+  if (frontmatter.slug && frontmatter.slug !== slug) {
+    die(`Roadmap/${macro}/${slug}/README.md frontmatter slug "${frontmatter.slug}" != requested "${slug}"`);
+  }
+
+  let built;
+  try {
+    built = epicKickoffFromDir({ macro, slug, dir });
+  } catch (err) {
+    die(err.message);
+  }
+
+  // A single-sprint "epic" is the documented exception, not the default — say so instead of emitting a
+  // whole-epic orchestration prompt for one sprint's worth of work.
+  if (built.sprints.length === 1) {
+    process.stderr.write(
+      `⚠ "${slug}" has one sprint. Epic mode buys nothing here — the per-sprint kickoff is the right ` +
+        `tool: npx -y @golden-frijoles/kit emit-kickoff --epic ${slug} --sprint 1\n` +
+        `  (Emitting the epic-mode prompt anyway.)\n\n`
+    );
+  }
+
+  // S3.4 — scrumban's pull as advice: one line on stderr when Building is at its WIP limit; the kickoff still prints.
+  const wip = wipWarning({ root: repoRoot, excluding: slug });
+  if (wip) process.stderr.write(`${wip}\n\n`);
+
+  process.stdout.write(built.kickoff);
+}
+
+// realpath on both sides (D6): run through a symlinked path (npx's bin link, macOS /tmp → /private/tmp) a plain
+// compare is false and the script would exit 0 having printed nothing.
+const isMain = (() => {
+  try {
+    return !!process.argv[1] && realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]);
+  } catch {
+    return false;
+  }
+})();
+if (isMain) main();

package/dist/emit-kickoff.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+// emit-kickoff.mjs — print the finished, paste-ready Stage-8 Claude Code kickoff for a groomed
+// sprint. Planning-only helper for the `groom` skill (Stage 8). The invariant preamble (the
+// orientation reads, plan-mode, escalate-don't-guess triggers, etc.) lives in
+// `templates/kickoff.md` — this script's whole point is that boilerplate stops being retyped by
+// hand per sprint; only the sprint-specific delta (epic title, sprint number + its own title,
+// story list) is read out of the epic's own docs and substituted in.
+//
+// Usage, from the project root (the project's own `scripts/` copy wins, else the kit):
+//   npx -y @golden-frijoles/kit emit-kickoff --epic <slug> --sprint N [--repo-root <path>]
+//
+// One source, three homes (kickoff-generator-path C1): this file ships in the kit, a project spawned from the template
+// carries it in `scripts/`, and the groom skill holds a byte-identical copy in `vendor/` (render-hook-vendor.mjs).
+// The template is read from this file's own directory, which is the kit root in all three.
+//
+// Resolves the epic dir by SEARCHING Roadmap/*/<slug>/ under the project root (lib/kickoff-cli.mjs) — the
+// macro-area prefix (e.g. "09-platform-infra") isn't knowable from the slug alone. Reads that
+// epic's README.md (frontmatter + H1 title) and sprint-<N>.md (H1 + `### Story N.M — <title>`
+// headings), then substitutes into templates/kickoff.md and prints the result to stdout.
+//
+// It does NOT write any file — this is a read + print tool, same "advisory, editorial control
+// stays with the caller" stance as the other groom/cross-agent scripts in this repo.
+
+import { readFileSync, existsSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { parseArgs, resolveRepoRoot, findEpicDir } from './lib/kickoff-cli.mjs';
+export { parseArgs };
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TPL = join(__dirname, 'templates');
+
+// ── pure helpers (exported for the co-located test) ─────────────────────────────────────────
+
+// The doc parsers live in the epic kickoff builder now (board-sinks-and-scrumban D17), so the per-sprint and epic
+// generators — and the Hub card's kickoff, which the extractor builds from the same file — read the doc format with
+// ONE set of parsers. Re-exported for this file's spec and for any caller that imported them from here.
+import {
+  sub,
+  parseFrontmatter,
+  stripFrontmatter,
+  parseEpicTitle,
+  parseSprintHeader,
+  parseStoryHeadings,
+  sprintBranch,
+  sprintBase,
+} from './lib/epic-kickoff.mjs';
+export { sub, parseFrontmatter, stripFrontmatter, parseEpicTitle, parseSprintHeader, parseStoryHeadings };
+
+export function buildStoryList(headings) {
+  if (!headings.length) return '(no `### Story N.M — <title>` headings found in the sprint doc)';
+  return headings.map((h) => `- ${h}`).join('\n');
+}
+
+export function buildKickoff({ macro, slug, sprintNum, epicTitle, sprintTitle, storyList, templateText }) {
+  return sub(templateText, {
+    MACRO: macro,
+    SLUG: slug,
+    N: String(sprintNum),
+    BRANCH: sprintBranch(slug, sprintNum),
+    BASE: sprintBase(slug, sprintNum),
+    EPIC_TITLE: epicTitle,
+    SPRINT_TITLE: sprintTitle,
+    STORY_LIST: storyList,
+  });
+}
+
+// ── filesystem helpers (thin, not unit-tested — exercised by the real run) ──────────────────
+
+function die(msg) {
+  console.error(`emit-kickoff: ${msg}`);
+  process.exit(1);
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const missing = ['epic', 'sprint'].filter((k) => !args[k] || args[k] === true);
+  if (missing.length) {
+    console.error(`emit-kickoff: missing required flag(s): ${missing.map((m) => '--' + m).join(', ')}`);
+    console.error('Run with --epic <slug> --sprint N [--repo-root <path>]');
+    process.exit(1);
+  }
+
+  const slug = String(args.epic);
+  const sprintNum = String(args.sprint);
+  if (!/^\d+$/.test(sprintNum)) die(`--sprint must be a number (got "${sprintNum}")`);
+  const repoRoot = resolveRepoRoot(args);
+
+  const found = findEpicDir(repoRoot, slug);
+  if (found.error) die(found.error);
+  const { macro, dir } = found;
+
+  const readmePath = join(dir, 'README.md');
+  const sprintPath = join(dir, `sprint-${sprintNum}.md`);
+  if (!existsSync(sprintPath)) die(`no sprint-${sprintNum}.md under Roadmap/${macro}/${slug}/`);
+
+  const readmeText = readFileSync(readmePath, 'utf8');
+  const sprintText = readFileSync(sprintPath, 'utf8');
+
+  const frontmatter = parseFrontmatter(readmeText);
+  if (frontmatter.slug && frontmatter.slug !== slug) {
+    die(`Roadmap/${macro}/${slug}/README.md frontmatter slug "${frontmatter.slug}" != requested "${slug}"`);
+  }
+
+  const epicTitle = parseEpicTitle(readmeText);
+  if (!epicTitle) die(`couldn't find an H1 title in Roadmap/${macro}/${slug}/README.md`);
+
+  const sprintHeader = parseSprintHeader(sprintText);
+  if (!sprintHeader) die(`couldn't parse the H1 of Roadmap/${macro}/${slug}/sprint-${sprintNum}.md (expected "# <epic title> — Sprint <N>: <sprint title>")`);
+
+  const storyHeadings = parseStoryHeadings(sprintText);
+  const storyList = buildStoryList(storyHeadings);
+
+  const templatePath = join(TPL, 'kickoff.md');
+  if (!existsSync(templatePath)) die(`missing template: ${templatePath}`);
+  const templateText = readFileSync(templatePath, 'utf8');
+
+  const out = buildKickoff({ macro, slug, sprintNum, epicTitle, sprintTitle: sprintHeader.sprintTitle, storyList, templateText });
+  process.stdout.write(out);
+}
+
+// realpath on both sides (D6): run through a symlinked path (npx's bin link, macOS /tmp → /private/tmp) a plain
+// compare is false and the script would exit 0 having printed nothing.
+const isMain = (() => {
+  try {
+    return !!process.argv[1] && realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]);
+  } catch {
+    return false;
+  }
+})();
+if (isMain) main();

package/dist/lib/kickoff-cli.mjs

@@ -0,0 +1,76 @@
+// kickoff-cli.mjs — the argv, project-root and epic-lookup half both kickoff generators share
+// (kickoff-generator-path C2).
+//
+// `emit-epic-kickoff.mjs` and `emit-kickoff.mjs` run in THREE places, the same bytes in each:
+//   • a project's own `scripts/` (copied from the template),
+//   • the kit's `dist/` (`npx -y @golden-frijoles/kit emit-epic-kickoff …`, far from the project),
+//   • the groom skill's `vendor/` inside the plugin (the build-view mod's `/build`, and groom's Stage 8).
+// `projectRoot()` answers the first two. For the third it answers `groom/`, which holds no Roadmap/, so the root takes
+// one more rung (see `resolveRepoRoot`). The epic lookup lived twice, byte-for-byte, in the two CLIs; it lives here.
+//
+// Zero deps; no side effects at import.
+
+import { existsSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { findProjectRoot, projectRoot } from './project-root.mjs';
+
+/** `--key value` pairs; a flag with no value (or followed by another flag) is `true`. */
+export function parseArgs(argv) {
+  const a = {};
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t.startsWith('--')) {
+      const key = t.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith('--')) { a[key] = true; }
+      else { a[key] = next; i++; }
+    }
+  }
+  return a;
+}
+
+/**
+ * The project whose Roadmap/ the kickoff is built from, first match wins:
+ *   1. `--repo-root <path>` (the mod always passes it),
+ *   2. `GF_PROJECT_ROOT` (`gf-kit --root` sets it), taken as given: a person named it,
+ *   3. `projectRoot()` when it holds a Roadmap/ (a project's own `scripts/`, or the installed kit's walk from cwd),
+ *      — a copied set answers its own parent, so the template's own copy here answers `skills/template/` (whose
+ *        skeleton Roadmap/ has no epics); that is project-root.mjs's copied-mode rule, and no doc runs that copy,
+ *   4. the nearest directory holding Roadmap/ or .git, walking up from cwd (the plugin's vendored copy),
+ *   5. cwd.
+ * Pure over its options for the spec.
+ */
+export function resolveRepoRoot(
+  args,
+  { env = process.env, cwd = process.cwd(), exists = existsSync, project = () => projectRoot({ env, cwd, exists }) } = {}
+) {
+  const flag = args['repo-root'];
+  if (flag && flag !== true) return resolve(cwd, String(flag));
+  if (env.GF_PROJECT_ROOT) return resolve(cwd, env.GF_PROJECT_ROOT);
+  const root = project();
+  if (exists(join(root, 'Roadmap'))) return root;
+  return findProjectRoot(cwd, { exists }) ?? resolve(cwd);
+}
+
+/**
+ * Search Roadmap/*\/<slug>/ under repoRoot — the macro-area prefix isn't knowable from the slug alone.
+ * Returns `{ macro, dir }`, or `{ error }` naming what was searched (zero hits, or more than one).
+ */
+export function findEpicDir(repoRoot, slug, { exists = existsSync, list = readdirSync } = {}) {
+  const roadmapDir = join(repoRoot, 'Roadmap');
+  if (!exists(roadmapDir)) return { error: `no Roadmap/ dir under "${repoRoot}" (pass --repo-root <path>)` };
+  let macros;
+  try {
+    macros = list(roadmapDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
+  } catch (e) {
+    return { error: `couldn't read ${roadmapDir}: ${e.message}` };
+  }
+  const hits = macros.filter((m) => exists(join(roadmapDir, m, slug, 'README.md')));
+  if (hits.length === 0) {
+    return { error: `no epic found for slug "${slug}" under any Roadmap/*/ dir in "${repoRoot}" (searched: ${macros.join(', ') || '(none)'})` };
+  }
+  if (hits.length > 1) {
+    return { error: `ambiguous slug "${slug}" — found under multiple macro-areas: ${hits.map((m) => `Roadmap/${m}/${slug}`).join(', ')}` };
+  }
+  return { macro: hits[0], dir: join(roadmapDir, hits[0], slug) };
+}

package/dist/lib/wip.mjs

@@ -0,0 +1,40 @@
+// wip.mjs — scrumban's pull, as advice at the moment of pulling (board-sinks-and-scrumban S3.4, D9, D22).
+//
+// `emit-epic-kickoff` asks this before it prints a kickoff: if Building is already at its limit (`board.wip.Building` in
+// golden-frijoles.config.json), it says so in ONE line that names the limit and the cards in Building — and the kickoff
+// is printed anyway. A WIP limit here is advice, never a gate (D9): the person pulling may have a good reason.
+//
+// Building is counted from the SAME rows every client reads (`buildRows`, the stage resolver), with the facts in the
+// local snapshot — no network at kickoff time, and the age of those facts is said in the warning.
+
+import { buildRows } from '../roadmap-extract.mjs';
+import { gatherFacts } from './stage-facts.mjs';
+import { getKey } from './config.mjs';
+
+/**
+ * The warning line, or null when there is no limit, Building is under it, or the roadmap cannot be read (advice must
+ * never break the kickoff it decorates). `excluding` is the epic being pulled — it is not yet Building.
+ */
+export function wipWarning({ root, excluding = null, gather = gatherFacts } = {}) {
+  try {
+    const wip = getKey('board.wip', { root });
+    const limit = wip && Number.isInteger(wip.Building) && wip.Building > 0 ? wip.Building : null;
+    if (limit === null) return null;
+    const facts = gather({ root, mode: 'snapshot' });
+    const building = buildRows({ facts, root, dates: false }).filter(
+      (r) => r.grain !== 'Sprint' && r.stage === 'Building' && r.slug !== excluding
+    );
+    if (building.length < limit) return null;
+    const age =
+      facts.mode === 'snapshot'
+        ? ` (facts from ${facts.origin.replace('@', ' of ')})`
+        : ' (docs only: no snapshot of git facts yet)';
+    const names = building.map((r) => r.name).join('; ');
+    return (
+      `⚠ WIP: Building is ${building.length > limit ? 'over' : 'at'} its limit of ${limit} — ${names}${age}. ` +
+      `Pulling this starts one more; finish or hand one off first, or go ahead knowingly. The kickoff follows.`
+    );
+  } catch {
+    return null;
+  }
+}

package/dist/templates/kickoff.md

@@ -0,0 +1,26 @@
+Start by pushing this sprint's branch, before anything else — it is what moves the card to Building on the board:
+`git switch -c {{BRANCH}} {{BASE}} && git push -u origin {{BRANCH}}` (stacked on the previous sprint; branch from
+`origin/main` instead once that sprint has merged. Resuming? `git switch {{BRANCH}}`).
+
+Read AGENTS.md, Roadmap/WAYS-OF-WORKING.md and Roadmap/LEARNINGS.md. Skim team memory.
+Then read Roadmap/{{MACRO}}/{{SLUG}}/README.md and Roadmap/{{MACRO}}/{{SLUG}}/sprint-{{N}}.md.
+
+You're building Sprint {{N}} of "{{EPIC_TITLE}}". Enter plan mode, confirm the plan as user stories with me,
+then build one story at a time per WAYS-OF-WORKING. If you're one of
+several builders running in parallel, work in your own isolated `git worktree`, not the shared root checkout.
+Reuse before rebuild (see "What already exists"). Escalate rather than guess: stop and hand back on any trigger in
+the ONE list, WAYS-OF-WORKING → *Escalate, don't guess* — default to escalate when unsure. Commit per story with path-limited adds
+(`git add <your files>` + `git commit -- <those paths>`, never `git add -A` — a shared worktree races the
+index). Follow this project's own copy/localization conventions (see AGENTS.md). Add one api spec per testable story; name the
+QA/smoke stage and state any browser smoke owed to me. When the deterministic gate (tsc + build + Playwright
+api) is green, open a draft PR declaring the risk tier, then flip it ready-for-review — and write the SPRINT
+SMOKE WALKTHROUGH (below) into sprint-{{N}}.md before you call the sprint done.
+Review (WAYS-OF-WORKING → Review & merge): CI always; then run
+`node scripts/review-route.mjs --builder <who-wrote-it> <PR#>` and take what it prints — one external
+general pass, a security lens when the changed paths trigger it, and the fresh `pr-reviewer` subagent, in
+the scope `scripts/review-config.json` sets. A family never reviews its own diff, so don't pick `--agent`
+by hand; a capped family is routed past with `--exclude <family>`, and if only one can run it runs both
+prompts and you say so in the PR body. You merge your own PR on a green gate once findings are resolved.
+
+Sprint {{N}} of "{{EPIC_TITLE}}" — "{{SPRINT_TITLE}}" — stories:
+{{STORY_LIST}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@golden-frijoles/kit",
-  "version": "0.26.2",
+  "version": "0.27.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": {