@golden-frijoles/kit 0.22.0 → 0.23.0

package/dist/build-state.mjs

@@ -137,6 +137,7 @@ function readEpic(root, slug) {
     risk: readme.data.risk ?? null,
     phase: readme.data.phase ?? null,
     lifecycle: readme.data.status ?? null,
+    quote: quoteOf(readme.data),
     contract: readme.hasFrontmatter && !readme.error && 'phase' in readme.data,
     sprints,
   };
@@ -301,13 +302,50 @@ export function dollars(usd, known = true) {
   return usd > 0 && usd < 1 ? `${sign}$${usd.toFixed(2)}` : `${sign}$${Math.round(usd)}`;
 }
 
-/** The Spend line's value (finops S1.3): `≈$38 · 1.9M tok · 4 sessions · this machine`. */
-export function spendValue(spend) {
-  const parts = [dollars(spend.usd, spend.usd_known)];
-  if (spend.mtok !== null) parts.push(`${spend.mtok}M tok`);
-  if (spend.sessions !== null) parts.push(`${spend.sessions} session${spend.sessions === 1 ? '' : 's'}`);
-  parts.push(spend.basis);
-  return parts.join(' · ');
+/**
+ * The quote's label (finops S2.4): `(M)` for a calibrated quote, `(M · 2 past epics, wide)` while history is thin. Read
+ * from the `quote_basis` quote.mjs writes (`M, n=2, wide` / `M, n=5, p25–p75`); an unreadable basis shows as written.
+ */
+export function quoteLabel(basis, appetite = null) {
+  const m = /^\s*([SML])\s*,\s*n=(\d+)\s*,\s*(wide|p25–p75)\s*$/.exec(String(basis ?? ''));
+  if (m)
+    return m[3] === 'wide' ? `(${m[1]} · ${m[2]} past epic${m[2] === '1' ? '' : 's'}, wide)` : `(${m[1]})`;
+  if (basis) return `(${basis})`;
+  return appetite ? `(${appetite})` : '';
+}
+
+/**
+ * The Spend line's value — the four states of the approved mockup (finops S2.4; the resolver owns the words, D3):
+ *   inside    ≈$38 of quote $30–55 (M) · 1.9M tok · 4 sessions
+ *   over      ≈$71 · 29% over quote $30–55 (M) · 3.4M tok              (D8: alert-only)
+ *   no quote  ≈$22 · no quote · 1.1M tok · 2 sessions                   (never an invented quote)
+ *   thin      ≈$9 of quote $25–90 (M · 2 past epics, wide) · …
+ * With no quote object at all (a seed, an old caller) it is Sprint 1's line, which names where it was measured.
+ */
+export function spendValue(spend, quote) {
+  const tok = spend.mtok !== null ? `${spend.mtok}M tok` : null;
+  const sessions =
+    spend.sessions !== null ? `${spend.sessions} session${spend.sessions === 1 ? '' : 's'}` : null;
+  const usd = dollars(spend.usd, spend.usd_known);
+  if (quote === undefined) return [usd, tok, sessions, spend.basis].filter(Boolean).join(' · ');
+  if (!quote) return [usd, 'no quote', tok, sessions].filter(Boolean).join(' · ');
+  const label = quoteLabel(quote.basis, quote.appetite);
+  const range = `$${quote.low}–${quote.high}${label ? ` ${label}` : ''}`;
+  if (spend.usd > quote.high) {
+    const pct = quote.high > 0 ? Math.round(((spend.usd - quote.high) / quote.high) * 100) : null;
+    // `<1% over`, never `0% over`: the comparison is on the raw dollars, so a rounded 0 would read as "not over".
+    const over = pct === null ? 'over' : pct < 1 ? '<1% over' : `${pct}% over`;
+    return [usd, `${over} quote ${range}`, tok].filter(Boolean).join(' · ');
+  }
+  return [`${usd} of quote ${range}`, tok, sessions].filter(Boolean).join(' · ');
+}
+
+/** The epic's quote off its README frontmatter, or null (an unquoted epic — never a $0 quote, D4). */
+export function quoteOf(readme) {
+  const lo = readme.quote_low_usd;
+  const hi = readme.quote_high_usd;
+  if (typeof lo !== 'number' || typeof hi !== 'number' || lo > hi) return null;
+  return { low: lo, high: hi, basis: readme.quote_basis ?? null, appetite: readme.appetite ?? null };
 }
 
 /** Does `text` name `slug` as a whole slug — `aws` in "aws S1.1", but not inside "aws-s3 S1.1"? */
@@ -649,6 +687,7 @@ function resolve_({ root, offline = false, git = makeGit(root), facts = null, gh
     branch,
     branch_match: target.match,
     spend: spendFor(root, git, epic.slug),
+    quote: epic.quote,
     lifecycle: epic.lifecycle,
     epic: {
       slug: epic.slug,
@@ -797,7 +836,7 @@ export function renderLines(state) {
   const storyPart = `Story ${progress.story ?? '?'} of ${progress.stories}`;
   const sprintPart = `Sprint ${progress.sprint ?? '?'} of ${progress.sprints}`;
   lines.push(`${pad('Progress')}${storyPart} · ${sprintPart}`);
-  if (state.spend) lines.push(`${pad('Spend')}${spendValue(state.spend)}`);
+  if (state.spend) lines.push(`${pad('Spend')}${spendValue(state.spend, state.quote ?? null)}`);
   lines.push(`${pad('Status')}${statusValue(state)}`);
   return [...lines, ...also, ...boardLines(state, pad)];
 }

package/dist/quote.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+// quote.mjs — the quote for an appetite, calibrated from this project's own shipped epics (finops S2.2, D7).
+//
+//   node scripts/quote.mjs --appetite M          # one line: $30–55 (M, n=6, p25–p75)
+//   node scripts/quote.mjs --appetite M --json   # for the scaffolder and the band
+//   node scripts/quote.mjs --report              # per appetite: how many actuals landed inside their quote
+//
+// The quote is the p25–p75 of `actual_usd` over SHIPPED epics at the same appetite — the middle half of what epics
+// that size actually cost here. Until there are MIN_HISTORY of them it is WIDE_DEFAULT, labelled `wide` with its n,
+// never a guess dressed as a calibration (D4). It is recomputed at every groom, so it moves as history accumulates.
+// Epics are read through the extractor (`buildRows`), so appetite follows the board's own rule (README, else seed —
+// D20) and no second frontmatter reader exists.
+//
+// The unit is ≈ API $ (list-price equivalent, D3) — see lib/model-prices.mjs.
+//
+// Zero deps — Node 18+.
+
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildRows } from './roadmap-extract.mjs';
+import { projectRoot } from './lib/project-root.mjs';
+
+export const APPETITES = Object.freeze(['S', 'M', 'L']);
+export const MIN_HISTORY = 3;
+/** The band before there is history (≈ API $). Deliberately wide: it says "we don't know yet", in dollars. */
+export const WIDE_DEFAULT = Object.freeze({ S: [5, 40], M: [20, 120], L: [50, 300] });
+
+/** Linear-interpolated percentile (p in 0..1) of a sorted list. */
+export function percentile(sorted, p) {
+  if (!sorted.length) return null;
+  const i = (sorted.length - 1) * p;
+  const lo = Math.floor(i);
+  const hi = Math.ceil(i);
+  return sorted[lo] + (sorted[hi] - sorted[lo]) * (i - lo);
+}
+
+/** The shipped actuals at an appetite, ascending. An epic with a quote but no actual is ignored. */
+export function actualsAt(rows, appetite) {
+  return rows
+    .filter((r) => r.grain === 'Epic' && r.status === 'Shipped' && r.appetite === appetite)
+    .map((r) => r.actual_usd)
+    .filter((v) => typeof v === 'number' && Number.isFinite(v))
+    .sort((a, b) => a - b);
+}
+
+/** `M, n=5, p25–p75` / `M, n=2, wide` — the basis string the scaffolder writes and the band reads. */
+export function basisOf(q) {
+  return `${q.appetite}, n=${q.n}, ${q.kind}`;
+}
+
+/** The quote for an appetite: { appetite, low, high, n, kind: 'p25–p75' | 'wide', basis, line }. */
+export function quoteFor(rows, appetite) {
+  if (!APPETITES.includes(appetite))
+    throw new Error(`appetite must be one of ${APPETITES.join(', ')} (got ${appetite})`);
+  const xs = actualsAt(rows, appetite);
+  const calibrated = xs.length >= MIN_HISTORY;
+  const [low, high] = calibrated
+    ? [Math.floor(percentile(xs, 0.25)), Math.ceil(percentile(xs, 0.75))]
+    : WIDE_DEFAULT[appetite];
+  const q = { appetite, low, high, n: xs.length, kind: calibrated ? 'p25–p75' : 'wide' };
+  return { ...q, basis: basisOf(q), line: `$${low}–${high} (${basisOf(q)})` };
+}
+
+/**
+ * The calibration signal: per appetite, of the shipped epics that carry BOTH a quote and an actual, how many landed
+ * inside it, and the n behind today's quote.
+ */
+export function calibrationReport(rows) {
+  return APPETITES.map((appetite) => {
+    const judged = rows.filter(
+      (r) =>
+        r.grain === 'Epic' &&
+        r.status === 'Shipped' &&
+        r.appetite === appetite &&
+        typeof r.actual_usd === 'number' &&
+        typeof r.quote_low_usd === 'number' &&
+        typeof r.quote_high_usd === 'number'
+    );
+    const inside = judged.filter(
+      (r) => r.actual_usd >= r.quote_low_usd && r.actual_usd <= r.quote_high_usd
+    ).length;
+    const over = judged.filter((r) => r.actual_usd > r.quote_high_usd).length;
+    return {
+      appetite,
+      quote: quoteFor(rows, appetite),
+      judged: judged.length,
+      inside,
+      over,
+      under: judged.length - inside - over,
+    };
+  });
+}
+
+function main(argv) {
+  const i = argv.indexOf('--repo-root');
+  const root = resolve(i !== -1 && argv[i + 1] ? argv[i + 1] : projectRoot());
+  const rows = buildRows({ root, dates: false });
+  if (argv.includes('--report')) {
+    const rep = calibrationReport(rows);
+    if (argv.includes('--json')) process.stdout.write(`${JSON.stringify(rep, null, 2)}\n`);
+    else
+      for (const r of rep)
+        process.stdout.write(
+          `${r.appetite}  quote ${r.quote.line} · ${r.judged ? `${r.inside} of ${r.judged} landed inside (${r.over} over, ${r.under} under)` : 'no quoted epic has shipped yet'}\n`
+        );
+    return 0;
+  }
+  const a = argv.indexOf('--appetite');
+  const appetite = a !== -1 ? String(argv[a + 1] || '').toUpperCase() : null;
+  if (!appetite) {
+    process.stderr.write('usage: quote.mjs --appetite S|M|L [--json] | --report [--json]\n');
+    return 2;
+  }
+  const q = quoteFor(rows, appetite);
+  process.stdout.write(argv.includes('--json') ? `${JSON.stringify(q)}\n` : `${q.line}\n`);
+  return 0;
+}
+
+const isMain = (() => {
+  try {
+    return (
+      !!process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))
+    );
+  } catch {
+    return false;
+  }
+})();
+if (isMain) {
+  try {
+    process.exitCode = main(process.argv.slice(2));
+  } catch (err) {
+    process.stderr.write(`quote: ${err && err.message ? err.message : err}\n`);
+    process.exitCode = 2;
+  }
+}

package/dist/roadmap-extract.mjs

@@ -68,6 +68,7 @@ import { attributeFacts, resolveStage } from './lib/stage.mjs';
 import { gatherFacts } from './lib/stage-facts.mjs';
 import { epicKickoffFromDir, sprintBranch } from './lib/epic-kickoff.mjs';
 import { renderBoardText } from './lib/board-text.mjs';
+import { FINOPS_FIELDS, FINOPS_NUMERIC_FIELDS } from './lib/roadmap-contract.mjs';
 import { pushRoadmap, reportPush } from './roadmap-push.mjs';
 
 const REPO = projectRoot(); // D2 — the CLI's default root; buildRows takes its own
@@ -109,6 +110,23 @@ const PRIORITY_LABEL = {
 };
 const TYPE_LABEL = { feature: 'Feature', spike: 'Spike', chore: 'Chore', bug: 'Bug', epic: 'Epic' };
 
+/**
+ * finops D6 — an epic's quote and actual, off its README frontmatter (this file's own line reader yields strings).
+ * A number field that does not read as a finite number >= 0 is null, never 0: doc-format reports the bad value, and
+ * the board must not show a quote nobody wrote. The field list is the contract's, not a second copy.
+ */
+export function finopsFields(fm) {
+  const out = {};
+  for (const key of FINOPS_FIELDS) {
+    const raw = fm[key];
+    if (FINOPS_NUMERIC_FIELDS.includes(key)) {
+      const n = raw === null || raw === undefined || raw === '' ? NaN : Number(raw);
+      out[key] = Number.isFinite(n) && n >= 0 ? n : null;
+    } else out[key] = typeof raw === 'string' && raw ? raw : null;
+  }
+  return out;
+}
+
 function parseFrontmatter(md) {
   if (!md.startsWith('---')) return {};
   const end = md.indexOf('\n---', 3);
@@ -546,7 +564,8 @@ export function buildRows({
       priority,
       type: TYPE_LABEL[epicFm.type || seed.type] || 'Epic',
       risk,
-      appetite: seed.appetite || null,
+      // finops D20 — the README's own appetite first (an epic groomed after FinOps carries it), else the seed's.
+      appetite: epicFm.appetite || seed.appetite || null,
       underwritten_by: seed.underwritten_by || null,
       sprint_progress: totStories ? `${doneStories}/${totStories} stories` : `${sprints.length} sprints`,
       build_order: buildOrder,
@@ -564,6 +583,7 @@ export function buildRows({
       pr: prOf(pr),
       kickoff,
       shipped_at: stage === 'Shipped' ? statusDay : null,
+      ...finopsFields(epicFm),
     });
 
     // Sprint rows (one per sprint-N.md), related to the Epic by slug. boardSprints already carries
@@ -707,7 +727,7 @@ if (isMain) {
     ].find((p) => existsSync(p));
     if (!notion) {
       process.stderr.write(
-        'roadmap-extract: no roadmap-to-notion.mjs beside this script or in the project\'s scripts/ — the Notion sink is opt-in: copy ' +
+        "roadmap-extract: no roadmap-to-notion.mjs beside this script or in the project's scripts/ — the Notion sink is opt-in: copy " +
           'template/optional/notion/roadmap-to-notion.mjs into scripts/ and set NOTION_TOKEN + NOTION_DB_ID.\n'
       );
       process.exit(2);

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

@@ -186,6 +186,8 @@ mechanical half (sprints merged, README `status: shipped`, sprint statuses ticke
 retrospective, no leftover branch) — **and** the judgment items below are true:
 
 - [ ] The **product poster** reflects what is now live (✅ = enforced in code).
+- [ ] **The actual is stamped** — `node scripts/epic-actuals.mjs --epic <slug> --write` writes `actual_*` into the
+      epic README (`epic-dod` warns when it is missing), and the retro's `Quote vs actual:` line carries it.
 - [ ] **`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

package/package.json

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