@golden-frijoles/kit 1.4.0 → 1.6.0

package/dist/build-state.mjs

@@ -56,7 +56,7 @@ function repoEnv() {
 import { readFileSync, readdirSync, existsSync, statSync, realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join, resolve } from 'node:path';
-import { PHASES, isDay, parseDocFrontmatter } from './lib/roadmap-contract.mjs';
+import { PHASES, isDay, parseDocFrontmatter, wrapWords, WHY_LINES_MAX } from './lib/roadmap-contract.mjs';
 import { parseJournal, JOURNAL_BRANCH, JOURNAL_PATH } from './lib/session-journal.mjs';
 import { branchCandidates, parseBranch } from './lib/work-branch.mjs';
 import { buildRows } from './roadmap-extract.mjs';
@@ -120,7 +120,8 @@ export function storyCheck({ root, branch, subject, env = {} }) {
   if (EXEMPT_SUBJECT_RE.test(s)) return { ok: true, why: 'merge, revert or fixup' };
   const type = CONVENTIONAL_RE.exec(s)?.[1]?.toLowerCase() ?? null;
   // An untyped subject is gated: an untyped commit must not be a silent way around the check (D8).
-  if (type !== null && !STORY_GATED_TYPES.includes(type)) return { ok: true, why: `type ${type} is not gated` };
+  if (type !== null && !STORY_GATED_TYPES.includes(type))
+    return { ok: true, why: `type ${type} is not gated` };
   if (!branch) return { ok: true, why: 'detached HEAD' };
   let target;
   try {
@@ -134,16 +135,28 @@ export function storyCheck({ root, branch, subject, env = {} }) {
   const stories = epic.sprints.flatMap((sp) => sp.stories.map((st) => ({ ...st, sprint: sp.n })));
   const valid = stories.filter((st) => sprint === null || st.sprint === sprint);
   const scope = sprint === null ? `epic ${epic.slug}` : `epic ${epic.slug}, sprint ${sprint}`;
-  const refuse = (why) => ({ ok: false, why, valid: valid.map((st) => ({ id: st.id, title: st.title ?? '' })), scope, epic: epic.slug });
+  const refuse = (why) => ({
+    ok: false,
+    why,
+    valid: valid.map((st) => ({ id: st.id, title: st.title ?? '' })),
+    scope,
+    epic: epic.slug,
+  });
   if (!valid.length) return { ok: true, why: `${scope} lists no stories` };
   // A bare continuation (`1.2` after `S1.1/`) counts only when this epic lists it: `S2.1, 3.4 GB` is one story. An id
   // spelled with its own `S` always counts, listed or not — naming a stranger is the mistake this check exists for.
   const listed = new Set(stories.map((st) => st.id));
-  const ids = [...new Set(storyIdsWithKind(s).filter((x) => !x.bare || listed.has(x.id)).map((x) => x.id))];
+  const ids = [
+    ...new Set(
+      storyIdsWithKind(s)
+        .filter((x) => !x.bare || listed.has(x.id))
+        .map((x) => x.id)
+    ),
+  ];
   if (ids.length === 0) return refuse('it names no story');
-  if (ids.length > 1) return refuse(`it names ${ids.length} stories (${ids.join(', ')}) — one commit, one story`);
-  if (!valid.some((st) => st.id === ids[0]))
-    return refuse(`${ids[0]} is not a story of ${scope}`);
+  if (ids.length > 1)
+    return refuse(`it names ${ids.length} stories (${ids.join(', ')}) — one commit, one story`);
+  if (!valid.some((st) => st.id === ids[0])) return refuse(`${ids[0]} is not a story of ${scope}`);
   return { ok: true, why: `names ${ids[0]}` };
 }
 
@@ -921,8 +934,7 @@ function stageParts(state) {
       : state.facts_mode === 'snapshot'
         ? `snapshot, ${state.stage_age ?? 'age unknown'}`
         : 'docs only, no snapshot yet';
-  const phase =
-    state.phase_written && state.phase_written !== stage ? ` · phase ${state.phase_written}` : '';
+  const phase = state.phase_written && state.phase_written !== stage ? ` · phase ${state.phase_written}` : '';
   return { stage, locking, source, age, phase };
 }
 
@@ -960,20 +972,24 @@ export function shortDay(day, now = new Date()) {
 // Four significant digits, so a small target (0.004 → 0.006) never rounds to 0 (#312 review).
 const fmtNum = (n) => (Number.isInteger(n) ? String(n) : String(Number(n.toPrecision(4))));
 
-/** The Why line and, with a target, its continuation — each clipped to fit 80 columns. */
+// why-as-a-story D4 — the Why is read in full: it wraps (lib/roadmap-contract's wrapWords, the guard's own wrap).
+export { wrapWords, WHY_LINES_MAX };
+
+/** The Why, wrapped over as many lines as it needs (D4), then the target. Every line fits 80 columns. */
 export function whyLines(target, pad, cont, now = new Date()) {
   const room = WIDTH - cont.length;
   const t = target || {};
+  const story = t.hypothesis
+    ? wrapWords(t.hypothesis, room).map((l, i) => (i === 0 ? `${pad('Why')}${l}` : `${cont}${l}`))
+    : [];
   if (!t.metric) {
     if (!t.hypothesis) return [`${pad('Why')}no target set`];
-    return [`${pad('Why')}${clip(t.hypothesis, room)}`, `${cont}no target set`];
+    return [...story, `${cont}no target set`];
   }
   const read = t.read_date ? `read ${shortDay(t.read_date, now)}` : 'read 30 days after shipping';
   const numbers = ` ${fmtNum(t.from)} ━━▸ ${fmtNum(t.to)} · ${read}`;
   const metric = `${clip(t.metric, Math.max(8, room - numbers.length))}${numbers}`;
-  return t.hypothesis
-    ? [`${pad('Why')}${clip(t.hypothesis, room)}`, `${cont}${clip(metric, room)}`]
-    : [`${pad('Why')}${clip(metric, room)}`];
+  return t.hypothesis ? [...story, `${cont}${clip(metric, room)}`] : [`${pad('Why')}${clip(metric, room)}`];
 }
 
 // build-view-upgrade D2 — one cell per story, sprint by sprint: ▰ has a commit, ▱ not yet, │ between sprints.
@@ -986,7 +1002,10 @@ export function sprintBars(bySprint) {
     .map((sp) => {
       const width = Math.min(sp.total, SPRINT_CELLS_MAX);
       // Rounded down, so a scaled sprint is never drawn full before every story has a commit (#312 review).
-      const filled = sp.done >= sp.total ? width : Math.max(0, Math.min(width - 1, Math.floor((sp.done / sp.total) * width)));
+      const filled =
+        sp.done >= sp.total
+          ? width
+          : Math.max(0, Math.min(width - 1, Math.floor((sp.done / sp.total) * width)));
       return '▰'.repeat(filled) + '▱'.repeat(width - filled);
     })
     .join('│');

package/dist/epic-actuals.mjs

@@ -660,7 +660,10 @@ export async function pushUsage({
     return { sent: 0, reason: `config unreadable — ${err && err.message ? err.message : err}` };
   }
   if (setting !== 'on')
-    return { sent: 0, reason: 'off — spend.telemetry is not on (frijoles-kit config set spend.telemetry on)' };
+    return {
+      sent: 0,
+      reason: 'off — spend.telemetry is not on (frijoles-kit config set spend.telemetry on)',
+    };
   // The throttle counts ATTEMPTS, not successes: a persistent 401 or 429 retries every 10 minutes, not every minute.
   const last = Math.max(index.pushed_at ?? -Infinity, index.push_attempt_at ?? -Infinity);
   if (throttle && Number.isFinite(last) && now - last < PUSH_EVERY_MS)
@@ -733,11 +736,26 @@ export async function pushUsage({
 
 // stampFrontmatter moved to lib/frontmatter-stamp.mjs (result-record D8); re-exported above for existing callers.
 
-/** The three actual_* fields for an epic's report. */
+/**
+ * why-as-a-story D6 — the crew that actually worked, by model: `claude-opus-5-5 ≈$40.12 · claude-sonnet-5-5 ≈$3.10`,
+ * most spent first. Subagents are in the transcripts, so a delegated builder shows here; outside tools (Codex, agy,
+ * Devin) are not, and the retrospective names them from the PR's review records. Null when nothing was measured.
+ */
+export function modelsText(byModel) {
+  const rows = Object.entries(byModel ?? {}).filter(([, p]) => p && typeof p.usd === 'number');
+  if (!rows.length) return null;
+  return rows
+    .sort((a, b) => b[1].usd - a[1].usd || (a[0] < b[0] ? -1 : 1))
+    .map(([model, p]) => `${model} ${usdText(p.usd, p.usd_known)}`)
+    .join(' · ');
+}
+
+/** The actual_* fields for an epic's report: the spend, its tokens, where it came from, and by which models. */
 export function actualFields(report, basisPrefix, date) {
   return {
     actual_usd: report.usd,
     actual_mtok: report.mtok,
+    actual_models: modelsText(report.by_model),
     actual_basis: `${basisPrefix}${MACHINE} · ${date} · ${report.sessions} session${report.sessions === 1 ? '' : 's'}${
       report.usd_known ? '' : ' · lower bound (unpriced model)'
     } · prices ${PRICES_AS_OF}`,

package/dist/intent-match.mjs

@@ -226,9 +226,20 @@ export function stateOf(parsed) {
     pitch: parsed.pitch,
     claims: Object.fromEntries(parsed.claims.map((c, i) => [claimKey(i), c])),
     criteria: Object.fromEntries(parsed.criteria.map((a, j) => [criterionKey(j), a])),
+    // why-as-a-story D3: the Why, asked about on its own (advisory, outside the total). Only when the seed has one.
+    ...(whyOf(parsed) ? { why: whyOf(parsed) } : {}),
   };
 }
 
+/** The seed's Why (`hypothesis`), or null when it has none. Pure. */
+export function whyOf(parsed) {
+  const v = parsed.frontmatter?.hypothesis;
+  // A folded YAML block (`>-`, `|`) is not a Why the flat reader can see: never send its indicator to Jev as one.
+  return typeof v === 'string' && v.trim() && v.trim() !== 'null' && !/^[>|][1-9]?[+-]?[1-9]?$/.test(v.trim())
+    ? v.trim()
+    : null;
+}
+
 /**
  * The scoring request. Pure. Claims are required — without the ask there is nothing to match against, so the
  * caller reports "could not look" rather than a clarity-only number wearing the name "intent match".
@@ -242,6 +253,7 @@ export function buildRequest(parsed) {
     questions[`out_${criterionKey(j)}`] = itemQuestion('coverage_out', `criteria.${criterionKey(j)}`);
     questions[`clar_${criterionKey(j)}`] = itemQuestion('clarity', `criteria.${criterionKey(j)}`);
   });
+  if (whyOf(parsed)) questions.why_story = itemQuestion('why_story', 'why');
   return { state: stateOf(parsed), questions };
 }
 
@@ -316,7 +328,12 @@ export function scoreAnswers(parsed, answers) {
   const untraced = criteria
     .filter((a) => a.traced < 0.5)
     .map((a) => ({ id: a.id, value: a.traced, text: a.text }));
-  return { ok: true, signals, total, present, band: band(total), claims, criteria, gaps, untraced };
+  // why-as-a-story D3: advisory and outside the total. A missing or malformed answer is "could not look", never a
+  // failure of the whole score: the total's calibration must not move because this question exists.
+  const w = answers?.why_story;
+  // Not asked (no Why in the seed) is undefined, so the report leaves the line out (verifier #343).
+  const whyStory = !whyOf(parsed) ? undefined : w?.type === 'noul' && isUnit(w.noul) ? w.noul : null;
+  return { ok: true, signals, total, present, band: band(total), claims, criteria, gaps, untraced, whyStory };
 }
 
 const GAP_WORDS = {
@@ -377,6 +394,17 @@ export function formatReport(result, { source = 'the seed', agreement, reader }
     agreement == null
       ? '  agreement     pending  (the optional reader at the architecture lock)'
       : row('agreement', agreement, reader ? `(reader: ${reader})` : ''),
+    ...(result.whyStory === undefined
+      ? []
+      : [
+          result.whyStory === null
+            ? '  why story     —     (could not look; advisory, not in the total)'
+            : row(
+                'why story',
+                result.whyStory,
+                `(advisory, not in the total${result.whyStory < 0.5 ? ': rewrite the Why as a story' : ''})`
+              ),
+        ]),
     `Total ${result.total} / 100 — uncalibrated · signals: ${result.present.map((k) => SIGNAL_NAMES[k]).join(', ')}`,
     `Band: ${result.band} (placeholder bands: 80 build · 60 resolve follow-ups · below 60 sketch or spike)`,
   ];

package/dist/lib/config-registry.mjs

@@ -44,6 +44,19 @@ export const REGISTRY = Object.freeze([
     question:
       'An account adds flags you can roll out and turn off, each bet measured on its read date, every product in one place and an outcome report you can send. Sign in now (recommended: frijoles login, then frijoles init), or later?',
   },
+  {
+    // one-bet-wired D6 — the one place an account is suggested outside setup: refine's Measure question, when the
+    // founder wants to know if a feature worked and is not signed in. Asked once per project; the answer is kept here.
+    key: 'measure.signIn',
+    module: 'Measure',
+    // Asked by refine's Measure step, never by setup, and only when the founder is signed out: `never-yet` keeps
+    // `frijoles doctor` from reporting Measure as unconfigured for everyone (verifier, #341).
+    askWhen: 'never-yet',
+    default: null,
+    choices: ['later', 'now'],
+    question:
+      'Measuring needs a Golden Frijoles account: it serves the flag and counts who used it. Sign in now (opens your browser once), or later (the bet is saved here either way)?',
+  },
   {
     key: 'board.sink',
     module: 'Plan',

package/dist/lib/config.mjs

@@ -45,6 +45,7 @@ export const SECTIONS = Object.freeze([
   'routines',
   'intent',
   'lint',
+  'measure', // one-bet-wired D6: refine's Measure step (measure.signIn)
 ]);
 
 /**

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-09 against 1.3.2.
+// agy-doctor: last verified 2026-10-10 against 1.3.3.
 //   ^ 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.2';
+export const AGY_PINNED = '1.3.3';
 
 // 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/jev-questions/intent.json

@@ -82,6 +82,17 @@
       },
       "measured": null,
       "unmeasured": "A route is a suggestion for the next artifact and never part of the score, so it has no labels (intent-match D15)."
+    },
+    {
+      "id": "why_story",
+      "type": "noul",
+      "instructions": "{item} is the Why of a planned change, written for a founder to approve. Would a stranger with no technical background follow it as a short story: who has a problem today, what changes for them, and why that matters?",
+      "criteria": {
+        "true": "Yes: it tells who has the problem, what changes for them and why it matters, in plain words a stranger could follow.",
+        "false": "No: it lists parts, components or mechanics, leans on internal or technical terms, or leaves out who it is for or why it matters."
+      },
+      "measured": null,
+      "unmeasured": "why-as-a-story D3, 2026-10-10: no labelled Whys yet; advisory, reported outside the total."
     }
   ]
 }

package/dist/lib/roadmap-contract.mjs

@@ -45,7 +45,9 @@ export const STORY_FIELDS = ['id', 'title', 'as_a', 'i_want', 'so_that', 'risk',
 // All optional: an epic scaffolded before FinOps has none, and an absent field is never a zero (D4). The numeric
 // ones are numbers >= 0 or null; a `*_basis` says where the number came from, in words.
 export const FINOPS_NUMERIC_FIELDS = ['quote_low_usd', 'quote_high_usd', 'actual_usd', 'actual_mtok'];
-export const FINOPS_BASIS_FIELDS = ['quote_basis', 'actual_basis'];
+// `actual_models` (why-as-a-story D6) is text too, validated here but NOT in FINOPS_FIELDS: it stays in the README for the
+// retrospective's Crew line and is never pushed, so the hosted push schema does not change.
+export const FINOPS_BASIS_FIELDS = ['quote_basis', 'actual_basis', 'actual_models'];
 export const FINOPS_FIELDS = [
   'quote_low_usd',
   'quote_high_usd',
@@ -110,14 +112,16 @@ export function validateResultFields(fm) {
   for (const key of RESULT_DAY_FIELDS)
     if (has(key) && !isDay(fm[key])) bad(`${key}: "${fm[key]}" is not a day written YYYY-MM-DD (or null)`);
   for (const key of RESULT_TEXT_FIELDS)
-    if (has(key) && (typeof fm[key] !== 'string' || !fm[key].trim())) bad(`${key}: "${fm[key]}" is not text (or null)`);
+    if (has(key) && (typeof fm[key] !== 'string' || !fm[key].trim()))
+      bad(`${key}: "${fm[key]}" is not text (or null)`);
   // A target is the three together — which number, from what, to what (fresh review, #290): from/to or a read date
   // with no metric would never come due (everything keys off target_metric), and a metric with no numbers has no
   // direction to judge. A hypothesis on its own is allowed: a sentence is not a target.
   const targetKeys = ['target_metric', 'target_from', 'target_to', 'read_date'];
   if (targetKeys.some(has)) {
     for (const key of ['target_metric', 'target_from', 'target_to'])
-      if (!has(key)) bad(`a target needs target_metric, target_from and target_to together — ${key} is missing`);
+      if (!has(key))
+        bad(`a target needs target_metric, target_from and target_to together — ${key} is missing`);
   }
   if (has('target_from') && has('target_to') && fm.target_from === fm.target_to)
     bad(`target_from and target_to are both ${fm.target_from}: a target has to move the number`);
@@ -127,9 +131,11 @@ export function validateResultFields(fm) {
     for (const key of VERDICT_FIELDS.slice(1)) if (has(key)) bad(`${key} is set but there is no verdict`);
   } else {
     if (!has('verdict_at')) bad('a verdict needs verdict_at (the day it was read)');
-    if (!has('verdict_evidence')) bad('a verdict needs verdict_evidence (a pointer, or for unclear, the reason)');
+    if (!has('verdict_evidence'))
+      bad('a verdict needs verdict_evidence (a pointer, or for unclear, the reason)');
     if (fm.verdict === 'proven' || fm.verdict === 'disproven') {
-      if (!has('verdict_actual')) bad(`verdict: ${fm.verdict} needs verdict_actual (the number that was read)`);
+      if (!has('verdict_actual'))
+        bad(`verdict: ${fm.verdict} needs verdict_actual (the number that was read)`);
       if (has('verdict_evidence') && !isEvidencePointer(fm.verdict_evidence))
         bad(
           `verdict: ${fm.verdict} needs evidence that points somewhere: an https:// link, ` +
@@ -162,6 +168,120 @@ export function validateFlagKey(fm) {
 // grounded-bets D1 — `grounded:` is the founder's word at Stage 1.5: true (traced to a North Star input), false (funded
 // anyway, and `grounded_reason` says why), or absent/null (a Bug, a Chore, or an epic refined before it existed).
 // Whether a bet COUNTS as grounded is derived from its target (bets-grounded.mjs, D2), never from this field alone.
+// one-bet-wired D1 — a bet's measurement: what its flag funnel reads. Optional as a whole; once any field is set it
+// needs a flag and an adoption event, the only segment is `everyone` (named segments are tars-segments), and the window
+// is 1–90 whole days. Event names are tokens: what the SDK sends.
+export const BET_FIELDS = [
+  'target_segment',
+  'adopted_event',
+  'retained_event',
+  'retention_days',
+  'satisfied_event',
+];
+export const BET_SEGMENTS = ['everyone'];
+const EVENT_NAME = /^[A-Za-z0-9_.:$-]{1,200}$/;
+
+/** The bet's measurement fields → offenses (`contract-bet-invalid`). All absent is fine. */
+export function validateBet(fm) {
+  const offenses = [];
+  const bad = (detail) => offenses.push({ rule: 'contract-bet-invalid', detail });
+  const has = (key) => fm[key] !== undefined && fm[key] !== null;
+  if (!BET_FIELDS.some(has)) return offenses;
+  if (!has('flag_key')) bad('a bet with measurement needs a flag_key (the flag whose funnel it reads)');
+  if (!has('adopted_event')) bad('a bet with measurement needs an adopted_event (what counts as adopting)');
+  if (has('target_segment') && !BET_SEGMENTS.includes(fm.target_segment))
+    bad(
+      `target_segment: "${fm.target_segment}" is not one of ${BET_SEGMENTS.join(' | ')} (named segments come with tars-segments)`
+    );
+  for (const key of ['adopted_event', 'retained_event', 'satisfied_event'])
+    if (has(key) && !(typeof fm[key] === 'string' && EVENT_NAME.test(fm[key])))
+      bad(`${key}: "${fm[key]}" is not an event name (letters, digits, _ . : $ -)`);
+  if (
+    has('retention_days') &&
+    !(Number.isInteger(fm.retention_days) && fm.retention_days >= 1 && fm.retention_days <= 90)
+  )
+    bad(`retention_days: "${fm.retention_days}" is not a whole number of days from 1 to 90`);
+  return offenses;
+}
+
+// why-as-a-story D2/D4 — the Why is read in full, so it must fit what shows it. The build view gives the Why WHY_ROOM
+// columns (80, less its 11-column label) and WHY_LINES_MAX lines; `wrapWords` is the ONE wrap both the view and the
+// guard use, so "passes the guard" and "shows in full" cannot drift apart. The rest of the guard keeps it plain words:
+// what a script can tell (a path, a backtick, a code name, a short list of internal words). Whether it reads as a story
+// is a judgment (intent-match's advisory question), never this.
+export const WHY_ROOM = 69;
+export const WHY_LINES_MAX = 5;
+export const WHY_INTERNAL_WORDS = Object.freeze([
+  'wiring',
+  'wired',
+  'seam',
+  'endpoint',
+  'frontmatter',
+  'schema',
+  'payload',
+  'middleware',
+  'refactor',
+]);
+
+/** Words into lines of at most `room` characters; past `max` lines, the last one ends in "…". Pure. */
+export function wrapWords(text, room = WHY_ROOM, max = WHY_LINES_MAX) {
+  const lines = [];
+  let line = '';
+  for (const word of String(text ?? '')
+    .split(/\s+/)
+    .filter(Boolean)) {
+    const next = line ? `${line} ${word}` : word;
+    if (next.length <= room) line = next;
+    else {
+      if (line) lines.push(line);
+      // One word wider than the room is the only thing ever cut mid-word.
+      line = word.length > room ? `${word.slice(0, room - 1)}…` : word;
+    }
+  }
+  if (line) lines.push(line);
+  if (lines.length <= max) return lines;
+  const kept = lines.slice(0, max);
+  const last = kept[max - 1];
+  kept[max - 1] = last.length < room ? `${last}…` : `${last.slice(0, room - 1)}…`;
+  return kept;
+}
+
+/** A Why (a Feature's `hypothesis`) → what keeps it from reading in full and in plain words. Empty = fine. Pure. */
+export function whyProblems(text) {
+  const why = String(text ?? '').trim();
+  if (!why) return ['the Why is empty'];
+  const problems = [];
+  if (/^[>|][1-9]?[+-]?[1-9]?$/.test(why))
+    return ['it is a folded YAML block the readers cannot see: write the Why on one line, in quotes'];
+  // A word wider than a line is cut mid-word in the view, so it fails here too (verifier #343).
+  const wide = why.split(/\s+/).find((w) => w.length > WHY_ROOM);
+  if (wide)
+    problems.push(`one word is wider than a line ("${wide.slice(0, 24)}…"): shorten it or leave it out`);
+  const lines = wrapWords(why, WHY_ROOM, Infinity).length;
+  if (lines > WHY_LINES_MAX)
+    problems.push(
+      `it takes ${lines} lines on screen; the build view shows ${WHY_LINES_MAX} (about 320 characters)`
+    );
+  if (why.includes('`')) problems.push('it has a backtick: write the words, not code');
+  const path = why.match(
+    // A file with a code extension (not `.js`: Next.js and Node.js are product names), or a path rooted at `/`, `./` or
+    // `../`. A bare `reader/writer/editor` or `and/or` is prose (verifier #343).
+    /\b[\w-]+\.(?:mjs|cjs|tsx?|md|json|sql|ya?ml)\b|(?:^|\s)\.{0,2}\/[\w.-]+(?:\/[\w.-]+)+/
+  );
+  if (path) problems.push(`it names a file or path ("${path[0].trim()}")`);
+  const ident = why.match(
+    // snake_case (and dotted keys holding one, `bets.flag_funnels_enabled`), or camelCase with a lowercase run of two or
+    // more before the hump and a lowercase after it, so iPhone, eBay, iOS and macOS stay prose (verifier #343).
+    /\b[a-z][a-z0-9]*(?:[._][a-z0-9]+)*_[a-z0-9]+\b|\b[a-z]{2,}[A-Z][a-z][A-Za-z0-9]*\b/
+  );
+  if (ident) problems.push(`it names a code identifier ("${ident[0]}")`);
+  const words = why.toLowerCase().match(/[a-z]+/g) ?? [];
+  const internal = WHY_INTERNAL_WORDS.filter((w) => words.includes(w));
+  if (internal.length)
+    problems.push(`it uses internal words (${internal.join(', ')}): say what changes for the person`);
+  return problems;
+}
+
 /** `grounded:` as a boolean: the frontmatter readers keep a bare `true` as the string "true". Null when absent or neither. */
 export function groundedValue(v) {
   if (v === true || v === 'true') return true;
@@ -178,8 +298,10 @@ export function validateGrounded(fm) {
   const reason = fm.grounded_reason;
   const hasReason = reason !== undefined && reason !== null;
   if (raw !== undefined && raw !== null && g === null) bad(`grounded: "${raw}" is not true, false or null`);
-  if (hasReason && (typeof reason !== 'string' || !reason.trim())) bad(`grounded_reason: "${reason}" is not text (or null)`);
-  if (g === false && !hasReason) bad('grounded: false needs grounded_reason (why it was funded anyway, one sentence)');
+  if (hasReason && (typeof reason !== 'string' || !reason.trim()))
+    bad(`grounded_reason: "${reason}" is not text (or null)`);
+  if (g === false && !hasReason)
+    bad('grounded: false needs grounded_reason (why it was funded anyway, one sentence)');
   if (g !== false && hasReason) bad('grounded_reason is set but grounded is not false');
   return offenses;
 }
@@ -194,7 +316,12 @@ export function validateLockedAt(fm) {
   const v = fm.locked_at;
   if (v === undefined || v === null) return [];
   if (typeof v === 'string' && LOCKED_AT_RE.test(v) && !Number.isNaN(Date.parse(v))) return [];
-  return [{ rule: 'contract-locked-at-invalid', detail: `locked_at: "${v}" is not an ISO date-time (e.g. "2026-10-03T20:34:34Z")` }];
+  return [
+    {
+      rule: 'contract-locked-at-invalid',
+      detail: `locked_at: "${v}" is not an ISO date-time (e.g. "2026-10-03T20:34:34Z")`,
+    },
+  ];
 }
 
 /** The FinOps fields of an epic's frontmatter data → offenses (`contract-finops-invalid`). Absent/null is fine. */
@@ -401,6 +528,7 @@ export function validateEpicFrontmatter(parsed, ctx = {}) {
   offenses.push(...validateResultFields(fm));
   offenses.push(...validateFlagKey(fm));
   offenses.push(...validateGrounded(fm));
+  offenses.push(...validateBet(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

@@ -178,6 +178,22 @@ export function flagFields(fm, readme) {
   return { flag_key: !blank && FLAG_KEY_RE.test(raw) ? raw : null, flag_note: note || null };
 }
 
+/**
+ * one-bet-wired D1 — the bet's measurement as pushed: each field as written when it is well-formed, else null (the
+ * contract names a bad one). Defaults are the reader's (an absent window is 7 days), never written here.
+ */
+export function betFields(fm) {
+  const token = (v) => (typeof v === 'string' && /^[A-Za-z0-9_.:$-]{1,200}$/.test(v.trim()) ? v.trim() : null);
+  const days = Number(fm.retention_days);
+  return {
+    target_segment: fm.target_segment === 'everyone' ? 'everyone' : null,
+    adopted_event: token(fm.adopted_event),
+    retained_event: token(fm.retained_event),
+    retention_days: Number.isInteger(days) && days >= 1 && days <= 90 ? days : null,
+    satisfied_event: token(fm.satisfied_event),
+  };
+}
+
 /**
  * grounded-bets D9 — the founder's grounding, as recorded at Stage 1.5: `grounded` true | false | null and, when false,
  * `grounded_reason`. Anything else is null (the contract names it); the reason travels only with false.
@@ -648,6 +664,7 @@ export function buildRows({
       ...resultFields(epicFm, stage === 'Shipped' ? statusDay : null),
       ...flagFields(epicFm, readme),
       ...groundedFields(epicFm),
+      ...betFields(epicFm),
     });
 
     // Sprint rows (one per sprint-N.md), related to the Epic by slug. boardSprints already carries

package/dist/templates/kickoff.md

@@ -22,5 +22,13 @@ the scope `scripts/review-config.json` sets. A family never reviews its own diff
 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.
 
+Dispatch (the strongest model, this session, is the orchestrator): keep the plan, the shared surface (CI,
+`package.json`, lint config, a lib module many stories import), money, auth, migrations, tenancy, concurrency, high-risk
+stories and every merge. A story with a clear acceptance check, no shared surface and risk low or medium goes to
+a Sonnet-class builder in its own worktree, with a brief naming the story, the files, the checks to run and
+"commit, do not push". Re-derive the result yourself (the diff, the tests); never trust the builder's final
+message. After one failed attempt, take the story back. The Plan gate's Crew block is the plan; the
+retrospective records what happened. Where things stand, at any time: `refine/references/checkpoint.md`.
+
 Sprint {{N}} of "{{EPIC_TITLE}}" — "{{SPRINT_TITLE}}" — stories:
 {{STORY_LIST}}

package/dist/why-check.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// why-check.mjs — does this Why read in full and in plain words? (why-as-a-story D2)
+//
+//   node scripts/why-check.mjs "<the Why>"         check a sentence
+//   node scripts/why-check.mjs --seed <seed.md>    check a seed's (or an epic README's) `hypothesis`
+//
+// Exit 0: it fits the build view and reads as plain words. Exit 1: the problems, one per line. Exit 2: usage.
+// Whether it reads as a STORY is a judgment, asked by intent-match (advisory); this checks only what a script can tell.
+
+import { readFileSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import {
+  parseDocFrontmatter,
+  whyProblems,
+  wrapWords,
+  WHY_LINES_MAX,
+  WHY_ROOM,
+} from './lib/roadmap-contract.mjs';
+
+const USAGE = 'usage: why-check "<the Why>" | why-check --seed <seed.md>';
+
+/** argv → { text } | { error }. Pure, except reading the seed file it names. */
+export function whyFromArgs(argv, read = (p) => readFileSync(p, 'utf8')) {
+  if (argv[0] === '--seed') {
+    if (!argv[1]) return { error: USAGE };
+    let md;
+    try {
+      md = read(argv[1]);
+    } catch (e) {
+      return { error: `why-check: cannot read ${argv[1]} (${e.code ?? e.message})` };
+    }
+    const { data } = parseDocFrontmatter(md);
+    const text = data?.hypothesis;
+    if (text === undefined || text === null || text === 'null')
+      return { error: `why-check: ${argv[1]} has no hypothesis` };
+    return { text: String(text) };
+  }
+  if (argv.length !== 1 || argv[0].startsWith('--')) return { error: USAGE };
+  return { text: argv[0] };
+}
+
+export function main(argv, out = process.stdout, err = process.stderr) {
+  const parsed = whyFromArgs(argv);
+  if (parsed.error) {
+    err.write(`${parsed.error}\n`);
+    return 2;
+  }
+  const problems = whyProblems(parsed.text);
+  if (problems.length) {
+    out.write(`The Why needs another pass:\n${problems.map((p) => `  - ${p}`).join('\n')}\n`);
+    return 1;
+  }
+  const lines = wrapWords(parsed.text, WHY_ROOM, Infinity).length;
+  out.write(`The Why reads in full (${lines} of ${WHY_LINES_MAX} lines) and in plain words.\n`);
+  return 0;
+}
+
+const isMain = (() => {
+  try {
+    return (
+      !!process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))
+    );
+  } catch {
+    return false;
+  }
+})();
+if (isMain) process.exit(main(process.argv.slice(2)));

package/package.json

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