@golden-frijoles/kit 1.5.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/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, ` +
@@ -165,7 +171,13 @@ export function validateFlagKey(fm) {
 // 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_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}$/;
 
@@ -178,15 +190,98 @@ export function validateBet(fm) {
   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)`);
+    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))
+  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;
@@ -203,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;
 }
@@ -219,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. */

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.5.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": {