@golden-frijoles/kit 0.2.0 → 0.3.0

package/dist/init.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+// init.mjs — `gf-kit init`: adopt any repo by writing the Roadmap/ skeleton (golden-frijoles-plugin S3.2, D2).
+//
+//   node scripts/init.mjs             # write the skeleton into projectRoot(); never overwrite a file
+//
+// ── Why ───────────────────────────────────────────────────────────────────────────────────────
+// A stranger who pastes the install prompt into an EXISTING repo gets the plugin, but `groom` needs
+// somewhere to write on day one — `Roadmap/README.md`, `WAYS-OF-WORKING.md`, `LEARNINGS.md`, and the
+// `00-ideas/` funnel. `gf-kit init` is that one step: it writes the same skeleton a project spawned
+// from `template/` already has, into any repo, copied or installed (D2's two roots).
+//
+// ── Where the skeleton's SOURCE lives ─────────────────────────────────────────────────────────
+// INSTALLED: `kitRoot()/skeleton/` — `scripts/build-kit.mjs` copies `template/<each SKELETON path>`
+// into `kit/dist/skeleton/`, reading the very list exported below, so there is one list, not two.
+// COPIED: `kitRoot()/../` — when this file runs as `template/scripts/init.mjs` (this repo's own dev
+// checkout) that is `template/`, the skeleton's real source; when it runs as a spawned project's own
+// `scripts/init.mjs`, that is the project's own root, which already has every file, so every write is
+// a no-op `skipped … (exists)` — never a broken read.
+//
+// ── The one rule ──────────────────────────────────────────────────────────────────────────────
+// It NEVER overwrites a file that already exists (it prints `skipped <path> (exists)`), so it is safe
+// to run on a partially-adopted repo. It writes nothing outside `Roadmap/`. Its own exit code is 0
+// whether it wrote anything or not — "already adopted" is success, not a no-op failure.
+//
+// ── Two guards found by cross-review on #47 ───────────────────────────────────────────────────
+// (1) COPIED mode, source === destination: `skeletonRoot()` in copied mode is `kitRoot()/..`, the
+// SAME directory `projectRoot()` resolves to (this repo's own dev checkout runs exactly this way).
+// So `join(source, rel)` and `join(project, rel)` are the identical path — reproduced by deleting
+// one SKELETON file from a template/ checkout and running `node scripts/init.mjs`: the destination
+// "doesn't exist" (it was deleted), so the copy proceeds, and the SOURCE (the same path) doesn't
+// exist either — `copyFileSync` throws ENOENT instead of a clean skip. A stranger in installed mode
+// never hits this (source and project are genuinely different directories there), but the repo's
+// own dev loop and any future copied-mode caller can. Treated as `skipped`, same as "exists" — the
+// file not being copyable from itself is not a failure this tool should crash on.
+// (2) INSTALLED mode, project root resolves to `$HOME`: `projectRoot()` walks up to the nearest
+// `Roadmap/` or `.git`. A non-git folder under a dotfiles repo tracked at `$HOME` (a common setup)
+// has no closer match, so the walk lands on `$HOME` itself — and writing `Roadmap/` there would
+// scatter the skeleton across the operator's actual home directory. Refused outright.
+//
+// Zero deps — Node 18+.
+
+import { copyFileSync, existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { isInstalled, kitRoot, projectRoot } from './lib/project-root.mjs';
+
+/**
+ * The Roadmap skeleton `gf-kit init` writes, relative both to its source root (template/, or
+ * kit/dist/skeleton/ once built) and to the project it writes into. ONE list: `build-kit.mjs` reads
+ * this export to populate `kit/dist/skeleton/`, so there is no second copy of the file names to drift.
+ */
+export const SKELETON = [
+  'Roadmap/README.md',
+  'Roadmap/WAYS-OF-WORKING.md',
+  'Roadmap/LEARNINGS.md',
+  'Roadmap/00-ideas/README.md',
+  'Roadmap/00-ideas/seeds/.gitkeep',
+  'Roadmap/00-ideas/audits/.gitkeep',
+];
+
+/** Where the skeleton's SOURCE files live: `kitRoot()/skeleton` when installed, `kitRoot()/..` when copied. */
+export function skeletonRoot({ root = kitRoot(), installed = isInstalled({ root }) } = {}) {
+  return installed ? join(root, 'skeleton') : join(root, '..');
+}
+
+/**
+ * Write the skeleton into `project`, never overwriting. Pure given its injected fs functions.
+ * Returns `{ wrote, skipped }`, each a list of the SKELETON-relative paths.
+ */
+export function initSkeleton({
+  project = projectRoot(),
+  source = skeletonRoot(),
+  files = SKELETON,
+  exists = existsSync,
+  mkdir = mkdirSync,
+  copy = copyFileSync,
+  log = () => {},
+} = {}) {
+  const wrote = [];
+  const skipped = [];
+  for (const rel of files) {
+    const dest = join(project, rel);
+    if (exists(dest)) {
+      skipped.push(rel);
+      log(`skipped ${rel} (exists)`);
+      continue;
+    }
+    const from = join(source, rel);
+    // Copied mode's source and destination roots can be the identical directory (see the header) —
+    // a source that is the destination, or that simply isn't there, is a skip, never a crash. The
+    // destination not existing (checked above) does NOT imply the source exists: they can be the
+    // same absent path.
+    if (from === dest || !exists(from)) {
+      skipped.push(rel);
+      log(`skipped ${rel} (${from === dest ? 'source is the destination' : 'source is absent'})`);
+      continue;
+    }
+    mkdir(dirname(dest), { recursive: true });
+    copy(from, dest);
+    wrote.push(rel);
+    log(`wrote ${rel}`);
+  }
+  return { wrote, skipped };
+}
+
+/**
+ * True when `project` resolves to the operator's own home directory — the one place `gf-kit init`
+ * must never write, even though `projectRoot()`'s walk-up can legitimately land there (a non-git
+ * folder under a dotfiles repo tracked at `$HOME`). Pure given its injected `home`.
+ */
+export function isHomeDirectory({ project = projectRoot(), home = homedir() } = {}) {
+  return resolve(project) === resolve(home);
+}
+
+function main() {
+  const project = projectRoot();
+  if (isHomeDirectory({ project })) {
+    console.error(
+      `gf-kit init: refusing to run — the resolved project root is your home directory (${project}).\n` +
+        '  This usually means no Roadmap/ or .git was found between the current directory and $HOME,\n' +
+        '  and $HOME itself is a git repo (a dotfiles checkout, for example). Run this from inside a\n' +
+        '  real project — a directory with its own .git — or pass --root explicitly.'
+    );
+    return 2;
+  }
+  const { wrote, skipped } = initSkeleton({ project, log: (line) => console.log(line) });
+  console.log(`gf-kit init: ${wrote.length} written, ${skipped.length} already present.`);
+  return 0;
+}
+
+const isMain = process.argv[1] && process.argv[1].endsWith('init.mjs');
+if (isMain) process.exitCode = main();

package/dist/lib/golden-onboarding.mjs

@@ -156,6 +156,31 @@ export function compareVersions(a, b) {
   return left.pre < right.pre ? -1 : 1;
 }
 
+/**
+ * The ONE install prompt a stranger pastes into their agent (golden-frijoles-plugin S3.3/S3.4, D6/D8/X10).
+ *
+ * This is a CONSTANT, not this repo's business to author: golden-beans `apps/web/lib/install-prompt.ts`
+ * is the SOURCE (`export const INSTALL_PROMPT`), and it names only `github.com` /
+ * `raw.githubusercontent.com` URLs and no site URL — so unlike `getSiteUrl()`-backed strings there, it
+ * needs no per-environment origin and is safe to transcribe byte-for-byte. This is that transcription,
+ * exactly as golden-beans' `CopyPromptCard` renders it on the closing CTA, `/install` and onboarding.
+ * `scripts/check-onboarding-parity.mjs` asserts this string appears VERBATIM in the repo README.md and
+ * the `golden-frijoles` umbrella SKILL.md — a one-word drift fails it. Never hand-edit this without the
+ * source (golden-beans `apps/web/lib/install-prompt.ts`) changing first.
+ *
+ * Text: the audit's §3.1 prompt (`Roadmap/00-ideas/audits/golden-frijoles-unification-2026-09-23.md`,
+ * golden-beans checkout), verbatim, its soft-wrapped blockquote lines joined into the one paragraph it
+ * renders as.
+ */
+export const INSTALL_PROMPT =
+  "Install the golden-frijoles plugin. If you're in Claude Code, run `claude plugin marketplace add " +
+  'golden-frijoles/skills`, then `claude plugin install golden-frijoles@golden-frijoles`. If you\'re in ' +
+  'another agent, run `npx skills add golden-frijoles/skills --skill \'*\'` and select your ' +
+  'agent. Use one installation method. You can read the skill directly at ' +
+  'https://github.com/golden-frijoles/skills/blob/main/plugins/golden-frijoles/skills/golden-frijoles/SKILL.md ' +
+  '(raw: https://raw.githubusercontent.com/golden-frijoles/skills/main/plugins/golden-frijoles/skills/golden-frijoles/SKILL.md). ' +
+  'Then use the golden-frijoles skill when working on this project, and start with its setup.';
+
 /**
  * The value of `name` in a dotenv file, or null.
  *

package/dist/skeleton/Roadmap/00-ideas/README.md

@@ -0,0 +1,85 @@
+# 00-ideas — the idea funnel
+
+The front of the pipeline: raw ideas → scoped seeds → scaffolded epics. Lifecycle is tracked in
+**frontmatter on each seed**, not in folder names.
+
+```
+00-ideas/
+├── README.md         ← you are here
+├── BUILD-ORDER.md    ← GENERATED status board (run `node scripts/build-order.mjs`) — do NOT hand-edit
+├── seeds/            ← every idea/scope seed, flat, one .md each (with frontmatter)
+└── audits/           ← UX/UI (or equivalent) audit findings (reference material, NOT seeds)
+```
+
+## Seed frontmatter (the lifecycle source)
+
+Every file in `seeds/` starts with this block:
+
+```yaml
+---
+title: "Example feature idea"
+slug: example-feature-idea          # kebab; matches the filename
+status: raw                          # raw | ready | queued | scaffolded | in-progress | shipped | archived
+area: "01"                           # macro-section number, matching Roadmap/README.md's table
+type: feature                        # feature | spike | chore | epic
+priority: null                       # a wave/priority label, or null
+appetite: null                       # S | M | L — the budget, set at shaping; REQUIRED before `queued`
+underwritten_by: null                # wave that pays for this (a Roadmap/bets/<wave>.md), or null
+risk: low                            # low | high
+epic: null                           # path to the scaffolded epic, or null until scaffolded
+build_order: null                    # BUILD-ORDER id, or null
+updated: <date>
+---
+```
+
+### status — definitions
+
+| status | meaning |
+|---|---|
+| `raw` | unrefined idea, no scope yet |
+| `ready` | Definition-of-Ready scope doc written |
+| `queued` | accepted into `BUILD-ORDER.md` (⬜) |
+| `scaffolded` | epic + sprint docs created (`epic:` set; poster 🚧) |
+| `in-progress` | building (some sprint stories ticked) |
+| `shipped` | epic done (epic ✅ + RETROSPECTIVE; poster ✅) |
+| `archived` | dropped or superseded |
+
+The enum should be **enforced, not advisory** — wire `scripts/build-order.mjs` (and any Notion/board
+sync you add) to hard-fail on a present-but-unrecognized `status:` value, rather than falling back
+silently to a derived status. A silent fallback makes drift undetectable exactly where it matters.
+
+### Who owns `status` (seed vs. epic-README frontmatter)
+
+One field is authoritative at each stage — they never both drive the board:
+
+- **Before an epic exists** (`epic: null`) → the **seed's** `status` (`raw`/`ready`/`queued`) is
+  authoritative; you set it by hand or the `groom` skill sets it. This is what the BUILD-ORDER
+  **funnel** shows.
+- **Once `epic:` is set** → the **epic README's frontmatter `status:` is the SSOT** (set at epic
+  close: `scaffolded` → `in-progress` → `shipped`). The seed is now **funnel-only** — its `status:` is
+  no longer read for the board, so it can't drift it. **`BUILD-ORDER.md` is a generated view — never
+  hand-edit it; change the README `status:` and run `node scripts/build-order.mjs`.**
+
+### appetite & underwriting — the economics fields
+
+`appetite` (S | M | L) is the **budget the idea is worth**, fixed at shaping *before* the solution
+is designed — sessions + an implied token band, never a time estimate (see WAYS-OF-WORKING →
+*Betting & appetite*). `underwritten_by` names the **wave that pays for it** (a
+`Roadmap/bets/<wave>.md` file), set at the betting table. `null` means nobody has paid for it yet —
+fine in the funnel, impossible on the board: `build-order.mjs` **hard-fails** a `queued` seed with
+no `appetite`, and flags a missing `underwritten_by` as drift. Like `status`, `appetite` is an
+enforced enum — a present-but-unrecognized value fails the board, it never falls back silently.
+
+## How seeds flow (no file moves)
+
+1. **Capture** — drop a raw idea as `seeds/<slug>.md` with `status: raw` (the `groom` skill does this
+   from a brain-dump).
+2. **Scope** — `groom` fills out the Definition-of-Ready (appetite included) and flips
+   `status: ready`.
+3. **Queue** — bet on it at a wave boundary (`appetite:` + `underwritten_by:` set, the wave's
+   `Roadmap/bets/` file records what it displaced); `status: queued`.
+4. **Scaffold** — on approval, `groom` runs its own `scaffold-epic.mjs` (ships inside the `groom`
+   skill, `golden-frijoles` plugin) to create the epic/sprint docs, then sets the seed's `epic:` +
+   `status: scaffolded`. **No file ever moves between folders** — the frontmatter carries the state.
+
+Filenames are kebab-case and match `slug`. Audits live in `audits/`, never in `seeds/`.

package/dist/skeleton/Roadmap/LEARNINGS.md

@@ -0,0 +1,164 @@
+# Learnings — operating notes for every build
+
+**Read this at the start of every session.** It's the distilled, cross-cutting wisdom from past
+epics' retrospectives — the things that would have saved the last agent time. The full story of any
+item lives in its epic's `RETROSPECTIVE.md`; this file keeps only the *transferable* rule.
+
+**How this file stays useful (Definition of Done, epic):** at epic close, promote any durable,
+generalizable learning from your `RETROSPECTIVE.md` into the right section below — a one-liner + a
+*why* + the date/source. **Dedupe** (sharpen the existing line, don't append a near-duplicate). If a
+rule here is now wrong, fix or delete it. Keep it short — a long digest is an unread digest.
+
+**TEMPLATE NOTE:** the entries below are a curated, generalized subset carried over from the origin
+project (`dobby-foundation`'s own extraction) — the tooling/process gotchas that don't depend on any
+particular stack. As you build this project, your own entries will accumulate here; keep the same
+one-liner + why + date shape.
+
+---
+
+## Multi-agent & async deploy coordination
+*If several agents work in parallel on their own branches, against repos that deploy independently.*
+
+- **`main` moves under you.** Before opening a PR — and again if it sits open — **merge latest `main`
+  into your branch**. Tell-tale: CI fails on a spec/check for something you never touched → a sibling
+  agent landed something on `main` and your preview (if you have one) predates it. **A re-run alone
+  won't fix it** — the mismatch is structural; only `git merge origin/main` + push clears it. Confirm
+  with `git log HEAD..origin/main`.
+  **Corollary — the stale-vs-fresh mismatch can hit your own NEW code too, not just an untouched
+  check, when a sibling PR changes a shared file's CONVENTIONS (a lint rule, not a feature).** The
+  diagnostic tell: check whether a FAILING assertion is about a rule/convention that changed, not just
+  a feature/data mismatch.
+- **Announce cross-cutting or direct-to-`main` changes**, and prefer a PR even for "engine" features.
+  Anything touching shared surface — a root layout/middleware file, global styles, `package.json`/deps,
+  a new sibling worktree — can break every other open PR.
+- **Don't yank a shared branch out from under another agent.** If the repo's working tree is on
+  someone else's branch, do your change in an isolated `git worktree` instead of switching it.
+  **Corollary — checking CI status and merging a PR need no local checkout at all.** `gh pr checks <N>`
+  and `gh pr merge <N>` operate against the pushed remote branch via the GitHub API; they don't care
+  what's checked out locally.
+- **Before building a story, grep whether a sibling PR already fixed the identical root cause.** Two
+  epics approved the same day can target the same bug from different scope docs. Check
+  `git log --oneline -- <the file the story's root-cause names>` + `gh pr list` during research, not
+  assumed.
+- **Risk tier decides who merges**: low-risk → the reviewer/agent may merge on green CI; anything
+  touching money / auth / DB / shared infra → the product owner merges. When unsure, treat as high.
+  **Corollary — an explicit "merge on green" authorization changes who decides to pause and check in,
+  not whether the review layers themselves still run.** "Merge on green" is permission to proceed
+  through the established gate without re-asking at each step, not permission to skip the gate.
+  **Corollary — a "merge on green" given for one PR does not carry forward to a LATER PR in the same
+  session/epic, even a similarly-scoped one**, and a builder's own plan can promise a review step the
+  standing authorization never touched. Re-check whether a standing "merge on green" was given for
+  *this* PR/story, not just somewhere earlier in the conversation.
+- **When your branch is BEHIND `main`, the two-dot `git diff main..HEAD` lies — read the three-dot.**
+  Two-dot compares tips directly, so it folds in the *inverse* of every commit `main` gained since you
+  branched (a sibling epic's new files show up as "deletions" in your diff — alarming and wrong).
+  Review with **three-dot `git diff main...HEAD`** (merge-base→HEAD = only your changes), and **merge
+  `origin/main` into the branch before merging the PR** so the merged tree is what actually ships.
+- **A squash-merged sprint branch is a dead end — start the next sprint on a FRESH branch off `main`.**
+  A squash-merged PR's individual commits aren't on `main` (only the one squash commit is), so
+  continuing that branch for the next sprint re-introduces a messy duplicate diff and can't
+  fast-forward. Branch clean off `origin/main` for each new sprint.
+- **To verify "is the prior sprint serving?", reason off `origin/main` — never the working tree — and
+  read PR *state*, not branch commits.** Local app checkouts routinely sit on *other* agents'
+  branches, so on-disk files lie about `main`, and a squash-merged sprint's individual commits
+  genuinely aren't on `main`. Confirm with `gh pr view <#> --json state,mergeCommit` or `git fetch`
+  then `git grep <x> origin/main` — an `ls`/working-tree read is not evidence about `main`.
+- **Concurrent planning commits in a shared worktree collide the git index.** Fix: (1) **path-limited
+  commits** — `git add <your files>` + `git commit -- <those paths>`, never `git add -A`; (2) for
+  parallel planning, give each session its own worktree, or appoint a single **scribe** for shared
+  files (like `BUILD-ORDER.md`).
+- **A subagent/fork that dies mid-task from a shared session rate-limit still returns a `result` — that
+  text is its last tool-call narration, not a trustworthy completion claim.** After any subagent/fork
+  batch — especially one large enough to plausibly share a rate-limit, or any showing a failed status —
+  re-derive actual file state directly (grep the real repo) and run the language's type-checker/build
+  before treating the batch as complete.
+
+## Tooling gotchas
+- **A script with a co-located pure-logic test file MUST guard its `main()` call with an `isMain`
+  check.** Importing a script that calls `main()` unconditionally at module scope re-executes the
+  whole script for real (shell-outs, notifications, git pushes, all of it) the moment a test file
+  loads it for its pure helpers: `const isMain = process.argv[1] && …; if (isMain) main()`.
+- **Run the repo binaries directly when `npm`/`npx` chokes.** A sibling worktree that reuses the same
+  `package.json` name as the main checkout breaks npm **workspace resolution** at the monorepo root.
+  Use the binary path directly (`node /…/node_modules/typescript/bin/tsc --noEmit`,
+  `/…/node_modules/.bin/{next,playwright}`). New worktrees should use a unique package name or be
+  excluded from the root `workspaces` glob.
+- **A worktree needing its own `npm install` forces worktree-local binaries for everything, including
+  test runners.** A fresh `git worktree` resolves most tooling fine via walk-up to the root
+  `node_modules`, but if any dependency needs a local install (e.g. a CSS framework's PostCSS plugin
+  resolution), that install adds a worktree-local copy of your test framework too — switch to the
+  **worktree-local** binary path, or you'll hit "two different versions" / "No tests found" errors.
+- **`gh pr merge --delete-branch` fails when a worktree holds `main`.** The merge still succeeds on
+  GitHub; only the local branch-delete errors. Verify with `gh pr view <n> --json state`.
+- **A server-side `process.env.X ?? \`https://${req.headers.get('host')}\`` fallback is a real
+  production landmine, distinct from client-bundle build-time-inlining bugs.** The trap is the
+  Host-header fallback when the env var is unset: a bare container run without an explicit runtime env
+  var can get a literal `0.0.0.0:PORT` or similar garbage as the `Host` header, and the fallback
+  happily builds a broken URL from it — dangerous on any redirect-URL-building code path (OAuth
+  callbacks, payment-provider return URLs). Fix: one shared `resolveOrigin()`-style helper that
+  rejects obviously-wrong hosts and **throws instead of silently building a broken URL** — a loud
+  failure beats a dead redirect.
+- **A unit-tested pure helper can't live in the same file as code that imports a framework/runtime-only
+  module** (e.g. a Next.js `next/cache` import, or an auth SDK's server-only entrypoint). A generic
+  test runner that can't load that module throws an opaque, unrelated-looking error the moment it
+  imports the file at all — even if the pure function itself never touches the framework-only code.
+  Keep the pure logic in its own zero-import file; let the framework-touching wrapper import *it*.
+- **Swapping a framework-generated artifact for a hand-rolled route breaks specs on exact format.**
+  Converting a typed/generated file (robots.txt, sitemap, OG image, metadata) to a hand-rolled
+  equivalent can silently change output details (header casing, field order) that an existing spec
+  asserted on. When you replace anything a framework generates, diff the *exact bytes* the old one
+  emitted and grep the suite for any spec asserting that surface.
+- **CI sometimes just doesn't schedule a workflow for a PR.** Seen occasionally on `opened`; close/
+  reopen doesn't always fix it — an empty-commit push (a real `synchronize` event) does. Don't merge
+  on an absent gate: re-trigger, and lean on the local gate + a green preview as the real signal.
+- **`node --test <dir>` (bare directory) can silently fail to discover tests depending on your Node
+  version** — it may try to load the directory as a module instead of globbing it. Use an explicit
+  glob: `node --test 'scripts/lib/*.test.mjs'`.
+- **A "resolve the PR from the current branch" tool must read PR `state`** — a list/view call can
+  return MERGED/CLOSED PRs too, especially for a reused branch name whose PR already merged. Treat
+  `state !== 'OPEN'` as "no open PR for this branch" and pair it with a stale-HEAD guard
+  (`git rev-parse HEAD` vs the PR's `headRefOid` → warn + require an explicit override) so the first
+  run always reviews the current diff.
+- **A hosted CLI-authenticated integration (Vercel-style env-var management, similar platforms) can
+  silently store or report EMPTY values** through a convenience CLI command even when the underlying
+  API call "succeeds." Verify by value **length** where you can't read the value directly (a scoped
+  read token may be needed), not just by exit code.
+- **A "sensitive"/write-only secret is confirmable by presence/type but not by value** — you can check
+  it exists and which environment it targets, but not its actual content, from a CLI or API. Read the
+  provider's dashboard, or have the app surface the cause on use (missing key → a specific, classifiable
+  error) instead of guessing.
+- **Driving a young foreign CLI: run `<cli> --help` first, pin the version, and design for degrade —
+  never build against a documented flag from memory.** A less-mature CLI can have surprising interface
+  shapes (no JSON output mode, arguments only via argv not stdin, or vice versa) that don't match a
+  more mainstream CLI's conventions. Smoke-test by running it against something real and reading the
+  actual output before scripting around it.
+  **A young foreign CLI can silently break its own contract on a MINOR version bump** — a print mode
+  that used to always emit something can start exiting 0 with empty output on a real failure. Treat
+  **empty output as failure** (not success), and make any version-pin check **fail loud** so a
+  contract break gets caught, not silently absorbed.
+  **A CLI authed by an interactive/OAuth login is NOT free to run in CI** — confirm a portable
+  non-interactive credential path AND its cost before automating it in a runner; some CLIs have no
+  headless auth at all, which may mean an advisory/local-only tool stays local-only rather than
+  becoming a CI job.
+- **`process.exit()` truncates piped stdout — flush synchronously, or you ship a tool that works to a
+  file but crashes in a pipe.** A script that does `console.log(json); process.exit(0)` can produce
+  valid output when redirected to a file (sync writes) but truncated output down a pipe, because the
+  async stdout write hasn't drained when exit fires. Use a synchronous write before `process.exit`, or
+  exit in the write callback. Test a tool the way it's actually invoked (pipe, not just file redirect).
+- **Git background auto-maintenance can race a burst of rapid commits and leave stale `*.lock`
+  files**, producing intermittent "cannot lock ref" errors. Clear locks recursively
+  (`find .git -name '*.lock'`) and run a rapid-commit batch with `git -c gc.auto=0 commit …` so
+  auto-maintenance can't re-trigger mid-sequence.
+- **A delta-only reporting tool must special-case a missing/wiped baseline as a bounded no-op, never as
+  "everything happened."** Diffing current state against an empty/`null` previous snapshot makes every
+  historical item look "new" — guard for a missing baseline with ONE bounded summary (counts only)
+  instead of enumerating full history, and keep a message-length safety net regardless of the guard.
+- **A script with both scheduled state-tracking delivery and on-demand artifact generation must keep
+  the artifact mode stateless.** Reusing a stateful window/log rail for an on-demand report mode risks
+  silently advancing state a scheduled run depends on — keep on-demand modes explicitly
+  non-state-mutating and lock that with a test.
+
+## Working efficiently
+- **Running a whole multi-sprint epic in one session is the main context-cost driver.** The durable
+  state (the plan file, sprint docs, team memory) makes re-entry cheap by design — compact at each
+  sprint/PR boundary, and for big epics consider a fresh session per sprint.

package/dist/skeleton/Roadmap/README.md

@@ -0,0 +1,67 @@
+# <TEMPLATE FILL-IN: Project Name> — Product Roadmap & Feature Poster
+
+> **Mission:** <TEMPLATE FILL-IN: one or two sentences — what this product does and for whom.>
+
+This folder is the **product source of truth**. It speaks in plain product language for product,
+design, and business — **no engineering or tech specs here** (those live in `tasks/` and team memory).
+
+---
+
+## How this roadmap is organized
+
+```
+Roadmap/
+├── README.md                ← you are here · the product poster (all features)
+├── WAYS-OF-WORKING.md       ← how we plan, build, ship (scrum cadence) + tooling
+├── LEARNINGS.md             ← the cross-cutting retro digest, read at every session start
+├── SESSION-KICKOFFS.md      ← thin-pointer prompt cheat sheet for starting a session
+├── 00-ideas/                ← the idea funnel (seeds, audits, the generated BUILD-ORDER.md)
+└── <Macro-section>/         ← a product domain (a journey, not a component)
+    ├── README.md            ← what this area is, for whom, current features
+    └── <Epic>/              ← a meaningful body of work
+        ├── README.md        ← the epic's product overview
+        ├── sprint-N.md      ← the sprint's user stories (As a… I want… so that…)
+        └── RETROSPECTIVE.md ← what we learned
+```
+
+**Levels:** `Roadmap → Macro-section → Epic → Sprint → User Story`. Each user story is a small,
+independently shippable slice of value.
+
+---
+
+## The macro-sections (product domains)
+
+<!-- TEMPLATE FILL-IN: list your project's product domains here, one per macro-section folder
+     (e.g. `01-onboarding-and-auth`, `02-core-workflow`, ...). Number them so BUILD-ORDER.md and
+     epic paths sort predictably. One macro-section should be reserved for platform/infra work
+     that isn't user-facing product — see the convention below. -->
+
+| # | Macro-section | Covers |
+|---|---|---|
+| 01 | <TEMPLATE FILL-IN> | <TEMPLATE FILL-IN> |
+| 09 | Platform & Infra | Engineering/observability work that isn't a user-facing product domain — deploy pipeline, dev tooling, cross-cutting process (this convention — reserving `09` for platform/infra — is a deliberate carry-over from the origin project; keep the number stable so tooling that reads it doesn't need per-project config). |
+
+---
+
+## Feature map
+
+<!-- TEMPLATE FILL-IN: one `### <NN> · <Macro-section name>` heading per row above, each listing
+     shipped/in-progress features with a status marker. Convention: ✅ means enforced in code, not
+     merely intended — partial/aspirational is 🚧. Don't let this page lag a shipped epic; updating
+     it is part of the epic Definition of Done (see WAYS-OF-WORKING.md). -->
+
+### 01 · <TEMPLATE FILL-IN: macro-section name>
+- 🚧 <TEMPLATE FILL-IN: first feature/epic, one line>
+
+---
+
+## Recent highlights
+
+<!-- TEMPLATE FILL-IN: newest-first log of shipped epics, one bullet each, dated. Added at every
+     epic close (WAYS-OF-WORKING.md's epic Definition of Done). Example shape:
+- **2026-01-01** — `<epic-slug>` shipped: <one-line what changed and why it matters>.
+-->
+
+## License
+
+<TEMPLATE FILL-IN: if this repo is private/internal, say so; otherwise state the license.>

package/dist/skeleton/Roadmap/WAYS-OF-WORKING.md

@@ -0,0 +1,233 @@
+<!-- GENERATED FILE — do not edit by hand.
+     Source: Roadmap/WAYS-OF-WORKING.template.md + Roadmap/fill-ins.yml
+     Regenerate: node scripts/render-ways-of-working.mjs   (CI checks it with --check)
+     Shared process text belongs in the .template.md; this project's own belongs in fill-ins.yml. -->
+# Ways of Working
+
+How the product owner and Claude (builder) ship product together. Small slices, plan first, ship
+the moment each slice works — and each slice is a piece of the final product, never a test of it.
+
+## Roles and the unit of work
+
+The **product owner** sets direction, approves plans, tests each shipped slice and makes the consequential
+calls (architecture forks, infra, money). **Claude** researches, proposes the plan as user stories,
+builds, verifies, ships and documents.
+
+Everything is sliced into **user stories** — the smallest independently testable, shippable value: *As a
+\<role\>, I want \<capability\>, so that \<outcome\>*, plus **acceptance checks the product owner can
+run**. Stories roll up into sprints, sprints into an epic, epics into a macro-section. Before building,
+check whether existing features plus communication already deliver the outcome — surface that lighter
+path first; `groom` gates on it (Stage 2.5).
+
+## The cadence
+
+```
+Plan → branch + scaffold docs → build story → verify → QA/smoke → PR → review → merge (= deploy) → close
+```
+
+1. **Plan.** Non-trivial work goes through plan mode as user stories, approved before code, naming its
+   QA/smoke stage. Reference end-states are inspiration, never signed-off scope.
+2. **Branch + scaffold.** One branch per epic (`feat/<slug>`, or `fix/…`, `chore/…`) off the latest
+   `main`, in each repo you touch. Scaffold the epic `README.md` + `sprint-N.md` *before* any code, so
+   the product owner sees scope as it grows, and keep them current (✅ ticks, commit refs).
+3. **Build one story at a time.** Reuse before rebuild. Commit per story, **path-limited**.
+4. **Verify + QA.** The deterministic gate — typecheck, lint, build, the suite — is green **before**
+   merge, run by the building agent, not only by CI. **TEMPLATE FILL-IN — your deploy rail:** whether a branch gets a preview and how the gate reaches it, what merging to `main` builds, and — if there is no per-branch preview — who does the post-merge browser half.
+5. **PR → review → merge.** Declare a risk tier, run the review the policy asks for, resolve or answer
+   every finding, merge on green. **Merging to `main` is the production deploy.** Delete the branch.
+6. **Close.** Sprint close: the sprint-wrap summary. Epic close: the Definition of Done below.
+
+## Epic-mode builds — the default for a scaffolded epic
+
+A whole epic in one orchestrated session is the normal unit of work; sprint docs are integration and
+rollback boundaries *inside* it (a per-sprint session stays valid for a one-sprint epic, or when a sprint's
+outcome genuinely changes the next one's scope). Six things make it work, and the first is the leverage:
+
+1. **Lock the architecture before any builder starts** — numbered decisions `D1…Dn` in the epic README
+   plus a per-sprint **"Build contract (locked by the architect before the builder started)"**, each
+   verified **against live code and live data**. Builders *cite* them; a paraphrased contract drifts
+   permissive. The lock must **disprove scope** (an acceptance criterion describing a guard, table or flag
+   the live system lacks is fiction — saying so is a success), **query the live data** (row counts decide
+   what is safe: a schema fork that is free while a table is empty is only free then), **name every
+   deviation** in the README, and **say where each contract lives, once** — import the rule, never
+   restate it.
+2. **Stack the branches** — `feat/<slug>` → `-s2` → `-s3`, one PR per sprint (a single PR only when the
+   sprints don't split along a review boundary), merged in order; sprints share hot files, so stack or
+   pay. **Never delete a base branch while a stacked PR is open** — GitHub closes that PR for good.
+3. **Route models by risk, invert for review** — the contract-defining sprint to the stronger model, the
+   mechanical ones to the faster, the riskiest PR's fresh reviewer to the strongest; state the routing in
+   the epic README. Findings route back to the original builder, whose context makes fixes cheap.
+4. **Merges are pre-authorized on green** in a named run: that removes the round-trip, not the gate or the
+   review layers, and never extends to a new category of production mutation (TLS/IAM/secrets, money or
+   entitlement writes, a new external dependency) — name those in one focused question.
+5. **Generate the kickoff, don't compose it** — `node skills/groom/emit-epic-kickoff.mjs --epic <slug>`
+   (the `groom` skill) reads the epic README and every sprint file and prints the orchestrator prompt.
+   Hand-composing it is how the architecture lock gets summarised away and the review policy silently
+   reverts to whatever the composing agent remembered.
+6. **Derive state, journal intent** — at session start run `node scripts/session-resume.mjs` (it ships in
+   the template's `scripts/`; a project spawned from it has both scripts): it
+   re-derives branches, worktrees, open PRs and migration drift live across the project's repos and leads
+   with what is surprising. Journal each locked decision with `node scripts/session-note.mjs --kind
+   decision "<text>"` — one intent line, nothing derived. A killed worker's agent is resumed with a
+   one-paragraph state recap (its actual `git status`/`diff`), not re-spawned cold.
+
+*Done* means **shipped**, not merged: a merged PR that has not deployed, a migration written but not
+applied, a flag that exists only in code are none of them done. With a migration: apply it **before**
+merging, verify live, merge, then confirm the deploy succeeded.
+
+## Betting & appetite
+
+Appetite is denominated in **sessions** — with agents the binding constraints are product-owner attention
+and session context. Fixed appetite, variable scope.
+
+| Appetite | Buys | Circuit breaker |
+|---|---|---|
+| **S** | one builder session; fixed scope (a bug, a chore, a clear story) | escalate-don't-guess — no hard breaker |
+| **M** | one wave: an architect session + builder fan-out + review rounds | appetite exhausted → stop, back to shaping |
+| **L** | a multi-wave epic | per-wave: each wave is re-bet at the boundary |
+
+Four rules: **an exhausted bet returns to shaping**, never extends in flight; **nothing reaches
+`status: queued` without an `appetite:` and an `underwritten_by:` wave**; **bets are placed at wave
+boundaries** into `Roadmap/bets/<wave>.md`, three lines each, recording what they displaced; and **uphill
+work stays on the strongest model**. Not every ask earns the betting table — `groom` sorts shaped bets
+from fixed scope (appetite S, straight to a builder) and reactive/ops work. Why it works this way:
+[`references/shapeup/`](https://github.com/golden-frijoles/skills/blob/main/template/references/shapeup/README.md).
+
+## Review & merge
+
+The deterministic gate is the gate. Everything else is judgment, and it is reads that answer **different
+questions** — not more reviewers of the same kind.
+
+```
+CI (deterministic gate)            — does it build, typecheck, pass the suite?   BLOCKS merge
+  → fresh pr-reviewer subagent     — context independence: did not hold the diff
+  → one external cross-family pass — family independence: different blind spots
+  → + a lean security lens         — when the diff touches a security path
+  → the builder merges on green
+```
+
+**Which PRs**: `scripts/review-config.json` → `reviewScope` — `every-pr` (all non-trivial PRs;
+`--skip-trivial` drops docs-only and tiny diffs) or `security-paths-only`. The **security lens** is
+triggered by a `securityPaths` glob or a `risk: high` body in either scope — paths, not judgement, so a
+builder can add it but never skip it.
+
+**Who reviews** is printed by `node scripts/review-route.mjs --builder <who> <PR#>`, never picked by hand:
+the highest-preference family that did **not** build the diff takes the general pass, the next takes the
+security lens (`codex → agy → vibe → claude`; a capped family falls through with `--exclude`). One family
+left runs both prompts and says so in the PR body; none left means the layer is **DARK**, said out loud.
+
+**A silent reviewer is a FAILED run, not a clean one**: the run asserts the reply carries real review
+structure, posts `pending` before the CLI is even checked, pins the reviewed sha, and otherwise prints the
+full reply, exits non-zero and fails the PR's `cross-review/<lens>` status. Both readers share one prompt
+(`scripts/cross-review.prompt.md`): one pass, a `file:line` citation or the finding is not posted, at most
+3 nits, skip what CI enforces, Blocking/Should-fix only on a re-review. `/security-review` is available
+locally as a pre-push self-check, never a gate. Why this shape:
+[`references/review-stack.md`](https://github.com/golden-frijoles/skills/blob/main/template/references/review-stack.md).
+
+**Every finding is fixed or answered on the PR; neither pass authorizes anything.** **HIGH** = money
+(payments, checkout, fulfillment), auth and authorization boundaries, tenancy, DB migrations, shared infra;
+**LOW** = the rest; unsure means HIGH. The **builder merges their own PR at every
+risk tier** once CI is green and findings are resolved — the tier selects the review
+scope, not the merge authority. Roll back with `git revert` on `main`.
+
+**A deterministic floor runs underneath, free and without an LLM:** GitHub secret scanning with push protection, and CodeQL default setup on any repo with app code. The lens finds logic flaws; the scanners find known patterns and leaked credentials.
+
+## Escalate, don't guess — the ONE trigger list
+
+Stop and hand back to the planning tier — rather than inventing an answer — on any of:
+
+> **money (payments, checkout, fulfillment) · auth and authorization boundaries · tenancy · DB migrations ·
+> shared infra · plan ambiguity · a decision the plan doesn't cover · 2+ failed attempts at the same
+> problem.**
+
+Default to escalate when unsure. This is a **model-routing** trigger, not a merge gate. Everywhere else
+that needs this list references it here; there is no second copy.
+
+## Permissions — what an agent may do unattended
+
+`.claude/settings.json` carries a committed `permissions` block: **allow** = verb classes only (never a
+literal past command, and never one that destroys uncommitted work — an allowed command skips the
+auto-mode classifier); **deny** = the irreversible-by-rule (CLI deploys, migration replays, force pushes and
+protected-branch deletes, `rm -r`, whole-tree staging, edits to generated files, and the few repo scripts
+that write production secrets from inside an allowed `node scripts/*`); **ask** = production secrets, env
+writes and a service deploy. Deny and ask rules are carried in **three spellings** — bare,
+assignment-prefixed and `env`-prefixed — because a leading assignment escapes a bare rule, and an escaped
+*ask* is not a stricter outcome but a silent downgrade to the classifier.
+Every deny/ask rule cites what it enforces in `.claude/permissions-ledger.json`, and
+`node scripts/permissions-smoke.mjs` fails on an uncited rule, a stale ledger entry, a literal allow or a
+missing baseline guardrail.
+
+**Three actions get one focused question before you take them** — about irreversibility, not review: a
+destructive or hard-to-reverse change to live data; real money or a third party's metered resource;
+production secrets/IAM/DNS/TLS. The `ask` rules make that prompt automatic for the commands that do it.
+
+**Auto mode is a USER setting** (`~/.claude/settings.json`): the same line in
+a project file is ignored *and* masks the user default, so the smoke fails on it. A deny rule matches the
+command an agent normally writes — it is not a sandbox: a leading assignment with an expansion
+(`PATH=/x:$PATH vercel deploy`) was observed escaping a bare rule, so the critical rules carry an
+expansion-safe form and the auto-mode classifier is the second floor.
+
+## Definitions of Done
+
+**A story can start** when its "as a / I want / so that" is clear, its acceptance check is testable, and
+it ships on its own.
+
+**A story is done** when acceptance criteria are confirmed working; typecheck, lint and build are clean;
+the real behaviour is **smoke-tested** end to end (never "build passes, therefore done" — an untestable
+gap is stated in the PR, not glossed); **every new spec has been observed failing once** via a deliberate
+mutation, so it is not a tautology; and the sprint doc is ticked.
+
+**An epic is done** when `node scripts/epic-dod.mjs --check <macro/slug>` passes — it derives the
+mechanical half (sprints merged, README `status: shipped`, sprint statuses ticked with refs, a real
+retrospective, no leftover branch) — **and** the judgment items below are true:
+
+- [ ] The **product poster** reflects what is now live (✅ = enforced in code).
+- [ ] **`RETROSPECTIVE.md`** says what actually happened, and its durable learnings are promoted into
+      `Roadmap/LEARNINGS.md` — sharpen the existing line, don't append a near-duplicate.
+- [ ] **Each sprint has a smoke walkthrough** a person can follow blind, with real URLs; money/auth steps
+      are flagged by name as owed to the product owner.
+- [ ] **Team memory** (and its index, if your tooling keeps one) records the epic.
+
+## Automated QA
+
+The harness grows by **one spec per browser-/API-testable story** — coverage accretes with the work. Two
+layers: an **`api` project** that is the deterministic gate (no browser binaries, runs on every PR, green
+before merge), and an opt-in **`browser` project** for rendered UI an API call can't see (nightly or on
+demand, never the gate). A browser spec replaces a browser smoke previously owed to the product owner.
+
+## Documentation map
+
+**`Roadmap/`** is the product source of truth in plain language (macro-section → epic → sprint → story,
+plus the poster); **`LEARNINGS.md`** is the cross-epic digest, read at session start and fed at every
+close; **`Roadmap/00-ideas/`** is the funnel — `seeds/` (lifecycle in frontmatter, never folder-shuffled),
+`audits/`, and the **generated** `BUILD-ORDER.md` (`node scripts/build-order.mjs`, never hand-edited).
+**Status SSOT = each epic README's frontmatter `status:`**; the board and any external projection are
+derived views. **`Roadmap/bets/`** holds one file per wave; **`tasks/`** is the engineering delivery log.
+
+## Conventions
+
+- **Gitflow.** Branch off `main`, commit per story, PR → merge. Never commit feature work straight to
+  `main`; never force-push a shared branch; merge latest `main` in before opening the PR.
+- **Path-limited commits.** `git add <specific files>` then `git commit -- <those paths>` — never
+  `git add -A`. Several agents share a checkout, so whole-tree staging commits a sibling's in-flight
+  work. The deny list enforces it; parallel planners take their own `git worktree` or appoint one scribe
+  for shared files like `BUILD-ORDER.md`.
+- **Docs track code — verified, not generalized.** A canonical rule must reflect what the code actually
+  does, checked against it — and a scoped learning is not globalized into a site-wide rule. On the poster
+  ✅ means enforced in code, 🚧 partial or aspirational. Run a light drift audit periodically.
+- **Parallel agents and async deploys.** `main` moves under you: merge latest `main` into a long-running
+  branch; when repos deploy at different speeds, merge the data-producing repo first and make the consumer
+  degrade gracefully.
+- **Worker death is a normal case.** Each builder on its own worktree; a killed worker's uncommitted tree
+  is evidence, not garbage; **verify by re-deriving repo state, never by trusting a completion report** —
+  a rate-limited subagent still returns a plausible-sounding result. Compact at sprint/PR boundaries; for a
+  big epic consider a fresh session per sprint.
+- Commit messages end with the `Co-Authored-By: Claude` trailer.
+- **Language.** Docs, comments and PR descriptions are in **English**. **TEMPLATE FILL-IN:** if your user-facing copy has its own policy (a default plus a bilingual allow-list), state it here and in `AGENTS.md`.
+
+## Tooling
+
+**TEMPLATE FILL-IN:** list this project's authenticated CLI access and what each is used for — at minimum **git/gh** (branches, PRs, merges) and **node/npm** (typecheck, lint, build, dev server), plus your deploy, database and container CLIs.
+
+Actions that touch live production, real money, or paid infrastructure are surfaced to the product owner
+before running.

package/package.json

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