@golden-frijoles/kit 0.22.0 → 0.24.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,
   };
@@ -289,6 +290,10 @@ export function spendFor(root, git, slug) {
       sessions: Number.isInteger(row.sessions) ? row.sessions : null,
       basis: typeof summary.basis === 'string' ? summary.basis : 'this machine',
       generated_at: summary.generated_at ?? null,
+      // finops S3 (round 3, #232): snapshots the engine refused as malformed, cumulative for this index. Shown on the
+      // Spend line so a refusal during the automatic refresh is never only a number in a file nobody opens.
+      push_rejected:
+        Number.isInteger(summary.push_rejected) && summary.push_rejected > 0 ? summary.push_rejected : 0,
     };
   } catch {
     return null;
@@ -301,13 +306,57 @@ 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 line = spendLine(spend, quote);
+  return spend.push_rejected
+    ? `${line} · ${spend.push_rejected} usage push${spend.push_rejected === 1 ? '' : 'es'} refused — epic-actuals --push --json`
+    : line;
+}
+
+function spendLine(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 +698,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 +847,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/epic-actuals.mjs

@@ -5,6 +5,7 @@
 //   node scripts/epic-actuals.mjs --refresh [--json]       # update the index + summary only (what the band's mod runs)
 //   node scripts/epic-actuals.mjs --backfill [--write]     # every shipped epic: measured, or why not; --write stamps
 //   node scripts/epic-actuals.mjs --epic <slug> --write    # stamp actual_* into that epic's README (at close)
+//   node scripts/epic-actuals.mjs --push                   # send changed sessions to the engine (opt-in: spend.telemetry)
 //   options: --repo-root <dir> (default: the project) · --projects-dir <dir> (default: ~/.claude/projects)
 //
 // ── Where the numbers come from (README § Architecture lock) ────────────────────────────────────────
@@ -52,6 +53,8 @@ import { resolveTarget } from './build-state.mjs';
 import { buildRows } from './roadmap-extract.mjs';
 import { projectRoot } from './lib/project-root.mjs';
 import { formatScalar, parseDocFrontmatter } from './lib/roadmap-contract.mjs';
+import { needSetting } from './lib/config.mjs';
+import { apiKeyFrom } from './roadmap-push.mjs';
 import { PRICES_AS_OF, PRICES_SOURCE, TOKEN_KINDS, tokensOf, usdOf } from './lib/model-prices.mjs';
 
 export const INDEX_VERSION = 1;
@@ -490,7 +493,16 @@ export function epicOfBranch(root) {
 }
 
 /** Refresh index + summary under the main checkout's `.golden-frijoles/`. Returns { summary, changes, dir }. */
-export function refresh({ root, projectsDir = defaultProjectsDir(), now = new Date(), budgetMs = Infinity }) {
+export async function refresh({
+  root,
+  projectsDir = defaultProjectsDir(),
+  now = new Date(),
+  budgetMs = Infinity,
+  push = false,
+  throttle = false,
+  env = process.env,
+  fetchImpl = globalThis.fetch,
+}) {
   const dir = join(mainCheckout(root), STATE_DIR);
   const indexPath = join(dir, INDEX_FILE);
   const index = loadIndex(indexPath);
@@ -499,10 +511,27 @@ export function refresh({ root, projectsDir = defaultProjectsDir(), now = new Da
     paths: repoPaths(root),
     deadline: Date.now() + budgetMs,
   });
-  const summary = { ...summarize(index, { epicOf: epicOfBranch(root), now }), complete: changes.complete };
-  if (changes.files_read || !existsSync(indexPath)) writeJson(indexPath, index);
+  // The push runs only on a COMPLETE scan: a partial index would send understated snapshots (finops D24).
+  const pushed =
+    push && changes.complete
+      ? await pushUsage({ root, index, epicOf: epicOfBranch(root), env, fetchImpl, throttle })
+      : null;
+  const summary = {
+    ...summarize(index, { epicOf: epicOfBranch(root), now }),
+    complete: changes.complete,
+    pushed_at: Number.isFinite(index.pushed_at) ? new Date(index.pushed_at).toISOString() : null,
+    // Refusals since the last clean push — 0 once a later push went through with none.
+    push_rejected:
+      Number.isFinite(index.push_rejected_at) && !(index.push_clean_at > index.push_rejected_at)
+        ? (index.push_rejected ?? 0)
+        : 0,
+  };
+  // A push that TRIED the network changed the index (attempt time, 409/400 marks) even when no transcript moved — an
+  // idle machine must persist its backoff, or it retries every minute and re-sends what was refused (round 2, #232).
+  const triedNetwork = pushed && !/^(off|throttled|no ingest key|config unreadable)/.test(pushed.reason);
+  if (changes.files_read || triedNetwork || !existsSync(indexPath)) writeJson(indexPath, index);
   writeJson(join(dir, SUMMARY_FILE), summary);
-  return { summary, changes, dir };
+  return { summary, changes, dir, pushed };
 }
 
 /** One epic's report — the `--epic <slug> --json` shape (a spec pins the key set, D9). */
@@ -526,6 +555,7 @@ export function epicReport(summary, slug) {
     prices_as_of: summary.prices_as_of,
     prices_source: summary.prices_source,
     not_measured: summary.not_measured,
+    pushed_at: summary.pushed_at ?? null,
   };
 }
 
@@ -534,6 +564,168 @@ export function usdText(usd, known) {
   return `${known ? '≈' : '≥'}$${usd >= 100 ? Math.round(usd) : usd.toFixed(2)}`;
 }
 
+// ── The engine push (finops S3.1, D21–D24) ────────────────────────────────────────────────────────────
+// OPT-IN: nothing leaves this machine unless `spend.telemetry` is `on` (golden-frijoles.config.json; unset = off).
+// One `$agent_usage` event per (session, epic) on the EXISTING `POST /api/v1/track`, with the project's ingest key —
+// the same one the roadmap push reads (`apiKeyFrom`), so the engine resolves the project from the key and nothing in
+// the body names one (D23). Each event is a cumulative snapshot; the engine keeps the latest per (session, epic)
+// (D22), and the idempotency key makes an unchanged re-push a no-op. Metrics only: the payload is built field by
+// field from the index, which never held content (D9).
+
+export const AGENT_USAGE_EVENT = '$agent_usage';
+export const PUSH_EVERY_MS = 10 * 60_000;
+export const PUSH_BUDGET_MS = 5_000;
+
+const part = () => ({ tokens: zeroTokens(), usd: 0 });
+function addPart(p, t, usd) {
+  for (const k of TOKEN_KINDS) p.tokens[k] += t[k];
+  if (usd === null || p.usd === null) p.usd = null;
+  else p.usd += usd;
+}
+
+/**
+ * The index → one snapshot per (session, epic): the exact `$agent_usage` payload (the engine's lib/agent-usage.ts
+ * AGENT_USAGE_KEYS). Unattributed turns are never pushed — there is no epic to put them on (D11).
+ */
+export function sessionSnapshots(index, { epicOf }) {
+  const out = new Map();
+  for (const rec of Object.values(index.messages)) {
+    const [session, branch, skill, model, at, speed, geo] = rec;
+    const epic = branch ? epicOf(branch) : null;
+    if (!epic || !session || !at) continue;
+    const key = `${session}|${epic}`;
+    if (!out.has(key))
+      out.set(key, {
+        session_id: session,
+        epic,
+        branch,
+        model_breakdown: {},
+        skill_breakdown: {},
+        tokens_by_kind: zeroTokens(),
+        usd_estimate: 0,
+        price_table_date: PRICES_AS_OF,
+        first_at: at,
+        last_at: at,
+      });
+    const s = out.get(key);
+    const t = tokensFromRecord(rec);
+    const usd = usdOf(model, t, { speed, inferenceGeo: geo });
+    for (const k of TOKEN_KINDS) s.tokens_by_kind[k] += t[k];
+    if (usd !== null) s.usd_estimate += usd;
+    s.model_breakdown[model] ??= part();
+    addPart(s.model_breakdown[model], t, usd);
+    const sk = skill || NO_SKILL;
+    s.skill_breakdown[sk] ??= part();
+    addPart(s.skill_breakdown[sk], t, usd);
+    if (at < s.first_at) s.first_at = at;
+    if (at > s.last_at) {
+      s.last_at = at;
+      s.branch = branch;
+    }
+  }
+  const r = (p) => ({ tokens: p.tokens, usd: p.usd === null ? null : round2(p.usd) });
+  return [...out.values()].map((s) => ({
+    ...s,
+    usd_estimate: round2(s.usd_estimate),
+    model_breakdown: Object.fromEntries(Object.entries(s.model_breakdown).map(([k, p]) => [k, r(p)])),
+    skill_breakdown: Object.fromEntries(Object.entries(s.skill_breakdown).map(([k, p]) => [k, r(p)])),
+    // The engine wants ISO-8601 UTC with exactly milliseconds and a `Z`; the transcript writes that shape, copied as is.
+    first_at: s.first_at,
+    last_at: s.last_at,
+  }));
+}
+
+/**
+ * Push every snapshot that changed since the last push. Returns { sent, rejected, reason }. Never throws: a failure is a
+ * reason, and the snapshots it did not send go next time. `index.pushed` remembers what each (session, epic) last sent.
+ */
+export async function pushUsage({
+  root,
+  index,
+  epicOf,
+  env = process.env,
+  fetchImpl = globalThis.fetch,
+  now = Date.now(),
+  throttle = false,
+}) {
+  // Never throws (fresh review, #232): a malformed golden-frijoles.config.json must not take the Spend row's refresh
+  // down with it — it is a reason, and the scan still saves.
+  let setting;
+  try {
+    setting = needSetting('spend.telemetry', { root });
+  } catch (err) {
+    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 (gf-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)
+    return { sent: 0, reason: 'throttled' };
+  const key = apiKeyFrom(env);
+  if (!key) return { sent: 0, reason: 'no ingest key — set SELF_PROJECT_API_KEY (or GROWTH_ENGINE_API_KEY)' };
+  const base = String(env.GROWTH_ENGINE_URL || 'http://localhost:3000').replace(/\/+$/, '');
+  index.pushed ??= {};
+  index.push_attempt_at = now;
+  const due = sessionSnapshots(index, { epicOf }).filter(
+    (s) => index.pushed[`${s.session_id}|${s.epic}`] !== s.last_at
+  );
+  const deadline = Date.now() + PUSH_BUDGET_MS;
+  let sent = 0;
+  let rejected = 0;
+  for (const s of due) {
+    const left = deadline - Date.now();
+    if (left <= 0) return { sent, rejected, reason: 'budget — the rest go next time' };
+    let res;
+    try {
+      res = await fetchImpl(`${base}/api/v1/track`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${key}` },
+        body: JSON.stringify({
+          userId: 'agent:claude-code',
+          event: AGENT_USAGE_EVENT,
+          metadata: s,
+          context: { version: 1, idempotencyKey: `agent_usage:${s.session_id}:${s.epic}:${s.last_at}` },
+        }),
+        // Clamped to what is left of the budget, so the run as a whole stays inside the hook's timeout.
+        signal: AbortSignal.timeout(Math.max(1, left)),
+      });
+    } catch (err) {
+      return { sent, rejected, reason: `network — ${err && err.message ? err.message : err}` };
+    }
+    // Per snapshot, never "one bad row stops everything forever" (fresh review, #232):
+    //   201 stored · 200 this exact snapshot was already there → done.
+    //   409 the engine already holds a snapshot at this (session, epic, last_at) with other numbers — a rebuilt index,
+    //       or a new price table re-pricing an old session. The engine's copy stands (append-only, latest-wins) → done.
+    //   400 this snapshot will never be accepted (say, a branch name over the limit) → recorded and counted (the CLI says so
+    //       and exits non-zero); not retried at this `last_at` — a grown session tries again.
+    //   anything else (401 wrong key, 429 quota, 5xx) → stop; it is about the run, not the row. Next try in 10 min.
+    if (res.status === 201 || res.status === 200 || res.status === 409) {
+      index.pushed[`${s.session_id}|${s.epic}`] = s.last_at;
+      if (res.status !== 409) sent++;
+      continue;
+    }
+    if (res.status === 400) {
+      index.pushed[`${s.session_id}|${s.epic}`] = s.last_at;
+      index.push_rejected = (index.push_rejected ?? 0) + 1;
+      index.push_rejected_at = now;
+      rejected++;
+      continue;
+    }
+    return { sent, rejected, reason: `engine answered ${res.status}` };
+  }
+  index.pushed_at = now;
+  // A run that finished with no refusal clears the alarm (round 4, #232): the band stops saying "refused" once a later
+  // push went through cleanly, so a signal that fired once does not become one people learn to ignore.
+  // CLEAN means something actually went through with no refusal — an idle run ("nothing changed") or one where every
+  // snapshot was a 409 proves nothing, and must not silence a refusal that is still current (round 5, #232).
+  if (sent > 0 && !rejected) {
+    index.push_clean_at = now;
+    index.push_rejected = 0;
+  }
+  return { sent, rejected, reason: due.length ? 'ok' : 'nothing changed' };
+}
+
 // ── Stamping actual_* (S1.4 backfill, S2.5 close) ───────────────────────────────────────────────────
 
 /**
@@ -674,7 +866,7 @@ function printEpic(r) {
   return lines.join('\n');
 }
 
-function main(argv) {
+async function main(argv) {
   const rootArg = arg(argv, '--repo-root');
   const root = resolve(rootArg ?? projectRoot());
   const projectsDir = arg(argv, '--projects-dir') ?? defaultProjectsDir();
@@ -683,11 +875,34 @@ function main(argv) {
   const today = new Date().toISOString().slice(0, 10);
   // --refresh is what the mod runs under a 10 s timeout (D24): it saves what it read within REFRESH_BUDGET_MS.
   const budgetMs = argv.includes('--refresh') ? REFRESH_BUDGET_MS : Infinity;
-  const { summary, changes } = refresh({ root, projectsDir, budgetMs });
+  // The push: `--push` asks for it now; `--refresh` (the mod) pushes too when `spend.telemetry` is on, at most every
+  // PUSH_EVERY_MS. With the setting off both are a no-op that says so (D21).
+  const wantsPush = argv.includes('--push') || argv.includes('--refresh');
+  const { summary, changes, pushed } = await refresh({
+    root,
+    projectsDir,
+    budgetMs,
+    push: wantsPush,
+    throttle: !argv.includes('--push'),
+  });
+  if (argv.includes('--push')) {
+    // This run's refusals, and every one before it (a refusal during the band's automatic refresh lands here too).
+    const total = summary.push_rejected ?? 0; // since the last clean push
+    const refused = total
+      ? ` · ${pushed?.rejected ?? 0} refused now, ${total} since the last clean push — the engine answered 400 (malformed); run --push --json and report it`
+      : '';
+    process.stdout.write(
+      `epic-actuals: pushed ${pushed?.sent ?? 0} session snapshot(s) — ${pushed?.reason ?? 'scan incomplete, nothing sent'}${refused}\n`
+    );
+    // The exit code is THIS run's: a refusal last week must not fail every --push after it.
+    return pushed && /^(ok|nothing changed)$/.test(pushed.reason) && !pushed.rejected ? 0 : 1;
+  }
 
   if (argv.includes('--refresh')) {
     if (json)
-      process.stdout.write(`${JSON.stringify({ changes, epics: Object.keys(summary.epics).length })}\n`);
+      process.stdout.write(
+        `${JSON.stringify({ changes, epics: Object.keys(summary.epics).length, pushed })}\n`
+      );
     return 0;
   }
   const slug = arg(argv, '--epic');
@@ -790,7 +1005,7 @@ const isMain = (() => {
 })();
 if (isMain) {
   try {
-    process.exitCode = main(process.argv.slice(2));
+    process.exitCode = await main(process.argv.slice(2));
   } catch (err) {
     process.stderr.write(`epic-actuals: ${err && err.message ? err.message : err}\n`);
     process.exitCode = 2;

package/dist/lib/config-registry.mjs

@@ -185,7 +185,9 @@ export const REGISTRY = Object.freeze([
     askWhen: 'never-yet',
     default: 'off',
     choices: ['off', 'on'],
-    question: 'Export cost telemetry?',
+    // finops D21 — the opt-in for `epic-actuals --push`: one `$agent_usage` event per (session, epic), metrics only.
+    question:
+      "Send this project's Claude Code usage to its Golden Frijoles project (token counts, models, skills and ≈ API $ per session and epic — never message content)?",
   },
 ]);
 

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