@golden-frijoles/kit 0.33.0 → 0.35.0

package/dist/lib/cross-agent-cli.mjs

@@ -54,10 +54,10 @@ export const AGENT_BIN = {
 // Harmless here since AGY_MODEL/AGY_FALLBACK_MODEL below are always valid, listed model names (checked via
 // `agy models`), but it means a future typo in either constant would silently review with the WRONG model
 // instead of failing loud — watch for that if either constant is ever edited.
-// agy-doctor: last verified 2026-10-06 against 1.3.0.
+// agy-doctor: last verified 2026-10-07 against 1.3.1.
 //   ^ machine-managed marker — `node scripts/cross-agent-doctor.mjs agy --fix` rewrites it (with the constant
 //   below) after a green live contract probe. Don't hand-edit the marker's shape.
-export const AGY_PINNED = '1.3.0';
+export const AGY_PINNED = '1.3.1';
 
 // agy's `--print` mode prints NOTHING unless `--model` names a model — and, crucially, it ALSO prints
 // nothing (exit 0, empty stdout — the error lands only in agy's log, see --log-file) when the model is

package/dist/lib/roadmap-contract.mjs

@@ -140,6 +140,25 @@ export function validateResultFields(fm) {
   return offenses;
 }
 
+// one-epic-page D11 — the epic's flag, decided at groom Stage 6b and copied into the README by the scaffold. The SDK's
+// flag-key grammar (`FLAG_KEY` in apps/web/lib/flag-admin-operation.ts). Optional: `flag_key: null` (no flag) is the
+// default and never an error; a value that is not a key is named, never pushed (the extract sends null for it).
+export const FLAG_KEY_RE = /^[a-z][a-z0-9_.-]{0,127}$/;
+
+/** `flag_key:` → offenses (`contract-flag-key-invalid`). Absent or null is fine. */
+export function validateFlagKey(fm) {
+  const v = fm.flag_key;
+  if (v === undefined || v === null) return [];
+  // The string "null" fits the grammar but means "no flag": named here as the push schema refuses it (codex, #297).
+  if (typeof v === 'string' && v !== 'null' && FLAG_KEY_RE.test(v)) return [];
+  return [
+    {
+      rule: 'contract-flag-key-invalid',
+      detail: `flag_key: "${v}" is not a flag key (a lowercase letter, then a-z 0-9 _ . -; at most 128) — or null`,
+    },
+  ];
+}
+
 // live-build-view D10 — `locked_at:` is stamped by `scripts/epic-phase.mjs lock` when the architecture lock is written;
 // the build view reads its absence as "Locking architecture". Optional (no epic before it has one), an ISO date-time
 // string when present: the command writes `"2026-10-03T20:34:34Z"` (quoted, so the frontmatter parser keeps the colons).
@@ -355,6 +374,7 @@ export function validateEpicFrontmatter(parsed, ctx = {}) {
   }
   offenses.push(...validateFinopsFields(fm));
   offenses.push(...validateResultFields(fm));
+  offenses.push(...validateFlagKey(fm));
   offenses.push(...validateLockedAt(fm));
   if (isInt(fm.sprints_total) && isInt(ctx.sprintCount) && fm.sprints_total !== ctx.sprintCount)
     offenses.push({

package/dist/roadmap-extract.mjs

@@ -73,6 +73,7 @@ import {
   FINOPS_NUMERIC_FIELDS,
   RESULT_DAY_FIELDS,
   RESULT_FIELDS,
+  FLAG_KEY_RE,
   RESULT_NUMERIC_FIELDS,
   VERDICTS,
 } from './lib/roadmap-contract.mjs';
@@ -161,6 +162,21 @@ export function resultFields(fm, shippedAt) {
   return out;
 }
 
+/**
+ * one-epic-page D11 — an epic's flag: `flag_key` off its README frontmatter (the SDK's key grammar, else null — the
+ * contract names a bad one) and `flag_note`, the README's own `**Flag:** …` line, which is where an epic with no flag
+ * says why. Both null when absent; nothing is inferred from prose about a flag the frontmatter does not name.
+ */
+export function flagFields(fm, readme) {
+  const raw = typeof fm.flag_key === 'string' ? fm.flag_key.trim() : '';
+  // A QUOTED `flag_key: "null"` (or `~`) arrives as a string, and "null" fits the key grammar — so the blank
+  // spellings are refused before the pattern is asked. (Unquoted `null` is already null from this file's reader.)
+  const blank = raw === '' || raw === 'null' || raw === '~';
+  const line = /^\*\*Flag:\*\*[ \t]*(.+)$/m.exec(readme ?? '');
+  const note = line ? line[1].replace(/[*`]/g, '').trim().slice(0, 280) : '';
+  return { flag_key: !blank && FLAG_KEY_RE.test(raw) ? raw : null, flag_note: note || null };
+}
+
 function parseFrontmatter(md) {
   if (!md.startsWith('---')) return {};
   const end = md.indexOf('\n---', 3);
@@ -583,6 +599,7 @@ export function buildRows({
       }
     }
 
+    const readme = readFileSync(join(e.path, 'README.md'), 'utf8');
     // Epic row
     rows.push({
       name: epicTitle(e.path, e.slug),
@@ -605,7 +622,7 @@ export function buildRows({
       build_order_num: buildOrderNum(buildOrder),
       doc_link: readmePath,
       epic_slug: null,
-      goal: firstParagraph(readFileSync(join(e.path, 'README.md'), 'utf8'), ['Why', 'Goal', 'Problem']),
+      goal: firstParagraph(readme, ['Why', 'Goal', 'Problem']),
       sprints: boardSprints.map((sp) => ({ n: sp.n, title: sp.title, done: sp.done, total: sp.total })),
       links: {
         readme: readmePath,
@@ -618,6 +635,7 @@ export function buildRows({
       shipped_at: stage === 'Shipped' ? statusDay : null,
       ...finopsFields(epicFm),
       ...resultFields(epicFm, stage === 'Shipped' ? statusDay : null),
+      ...flagFields(epicFm, readme),
     });
 
     // Sprint rows (one per sprint-N.md), related to the Epic by slug. boardSprints already carries

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

@@ -76,13 +76,13 @@ enforced enum — a present-but-unrecognized value fails the board, it never fal
    from a brain-dump).
 2. **Scope** — `groom` fills out the Definition-of-Ready (appetite included) and flips
    `status: ready`.
-3. **Fund + scaffold, in one answer** — the approval gate is the betting table. On "approve", `groom`
+3. **Fund + scaffold, in one answer** — the approval gate is the betting table. On "Approve the plan", `groom`
    runs its own `fund.mjs` (a row in the month's `Roadmap/bets/wave-YYYY-MM.md`, created on first use,
    recording what the bet displaced; `underwritten_by:`; a `build_order` placed with `--next` or
    `--after <slug>`, renumbering only the queue) and then `scaffold-epic.mjs` (the epic/sprint docs; the
    seed gets `epic:` + `status: scaffolded`), committed together. Both ship inside the `groom` skill,
    `golden-frijoles` plugin. A fixed-scope seed scaffolds from its slug alone, its acceptance criteria
-   becoming sprint 1's stories. "Approve, don't fund" leaves the seed `ready` and scaffolds nothing.
+   becoming sprint 1's stories. "Park it" leaves the seed `ready` and scaffolds nothing.
    **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/WAYS-OF-WORKING.md

@@ -93,10 +93,11 @@ and session context. Fixed appetite, variable scope.
 | **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; **the approval gate is the
-betting table** — approving a pitch in `groom` funds it in the same answer (`fund.mjs`: a row in the month's
-cycle file `Roadmap/bets/wave-YYYY-MM.md` recording what it displaced, `underwritten_by:`, and a build
-position), in the same commit as the scaffold, while "approve, don't fund" leaves it `ready` and scaffolds
-nothing; **nothing scaffolded is unfunded** — `build-order.mjs` fails a live bet with no `underwritten_by:`;
+betting table** — **Approve the plan** in `groom`'s Plan gate funds it in the same answer (`fund.mjs`: a row in
+the month's cycle file `Roadmap/bets/wave-YYYY-MM.md` recording what it displaced, `underwritten_by:`, and a
+build position), in the same commit as the scaffold, while **Park it** leaves it `ready` and scaffolds nothing
+(the gates' words: groom `references/gates.md`); **nothing scaffolded is unfunded** — `build-order.mjs` fails a
+live bet with no `underwritten_by:`;
 and **uphill work stays on the strongest model**. An L bet is re-bet at each wave boundary with one line
 when its builder stops there ("fund the next wave of `<slug>`? what does it displace?"; yes runs `fund.mjs`
 again, position kept). Fixed scope (appetite S) and reactive/ops work go through the same gate, straight to

package/package.json

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