@golden-frijoles/kit 0.21.0 → 0.22.0

package/dist/build-state.mjs

@@ -165,9 +165,10 @@ const TYPES_KNOWN = ['feature', 'spike', 'bug', 'chore'];
 
 /**
  * What the branch names, longest reading first: an epic, else a seed (a seed that carries `epic:` is that
- * epic — once scaffolded the seed is funnel-only), else null.
+ * epic — once scaffolded the seed is funnel-only), else null. Exported for epic-actuals.mjs (finops D16): spend is
+ * attributed to an epic by exactly this reading of a branch, never a second one.
  */
-function resolveTarget(root, branch) {
+export function resolveTarget(root, branch) {
   for (const c of branchCandidates(branch)) {
     const epic = readEpic(root, c.slug);
     if (epic) return { kind: 'epic', epic, sprint: c.sprint, match: c.exact ? 'exact' : 'prefix' };
@@ -258,6 +259,57 @@ export function prFromFacts(facts, branch) {
 
 const notInFlight = (reason, extra = {}) => ({ in_flight: false, reason, ...extra });
 
+// ── Spend (finops S1.3, D5) ─────────────────────────────────────────────────────────────────────────────
+// The band only READS: `<main checkout>/.golden-frijoles/usage-summary.json`, written by epic-actuals.mjs (refreshed
+// by the mod off the hot path, and by any CLI run). Nothing here scans a transcript. No summary, or no row for this
+// epic, means no Spend line — never a zero.
+export const USAGE_SUMMARY = ['.golden-frijoles', 'usage-summary.json'];
+
+/** The main checkout of `root` (the parent of git's common dir) — where the usage summary lives (finops D19). */
+function mainCheckoutOf(git, root) {
+  const common = tryGit(git, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+  if (!common) return root;
+  return /[\\/]\.git$/.test(common) ? dirname(common) : root;
+}
+
+/** This epic's row of the usage summary, or null. Never throws. */
+export function spendFor(root, git, slug) {
+  try {
+    const path = join(mainCheckoutOf(git, root), ...USAGE_SUMMARY);
+    if (!existsSync(path)) return null;
+    const summary = JSON.parse(readFileSync(path, 'utf8'));
+    // A first scan that ran out of its time budget is not a total yet: no row until it completes, never a low number.
+    if (summary?.complete === false) return null;
+    const row = summary?.epics?.[slug];
+    if (!row || typeof row.usd !== 'number') return null;
+    return {
+      usd: row.usd,
+      usd_known: row.usd_known !== false,
+      mtok: typeof row.mtok === 'number' ? row.mtok : null,
+      sessions: Number.isInteger(row.sessions) ? row.sessions : null,
+      basis: typeof summary.basis === 'string' ? summary.basis : 'this machine',
+      generated_at: summary.generated_at ?? null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** `≈$38` (a lower bound reads `≥$38`: some turns could not be priced — finops D4). */
+export function dollars(usd, known = true) {
+  const sign = known ? '≈' : '≥';
+  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(' · ');
+}
+
 /** Does `text` name `slug` as a whole slug — `aws` in "aws S1.1", but not inside "aws-s3 S1.1"? */
 export function namesSlug(text, slug) {
   const esc = slug.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -596,6 +648,7 @@ function resolve_({ root, offline = false, git = makeGit(root), facts = null, gh
     kind: 'epic',
     branch,
     branch_match: target.match,
+    spend: spendFor(root, git, epic.slug),
     lifecycle: epic.lifecycle,
     epic: {
       slug: epic.slug,
@@ -744,6 +797,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)}`);
   lines.push(`${pad('Status')}${statusValue(state)}`);
   return [...lines, ...also, ...boardLines(state, pad)];
 }

package/dist/epic-actuals.mjs

@@ -0,0 +1,798 @@
+#!/usr/bin/env node
+// epic-actuals.mjs — what each epic consumed, measured from this machine's Claude Code transcripts (finops S1).
+//
+//   node scripts/epic-actuals.mjs --epic <slug> [--json]   # one epic: sessions, tokens by kind/model/skill, ≈ API $
+//   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)
+//   options: --repo-root <dir> (default: the project) · --projects-dir <dir> (default: ~/.claude/projects)
+//
+// ── Where the numbers come from (README § Architecture lock) ────────────────────────────────────────
+// Claude Code writes every turn to `~/.claude/projects/<dir>/<session>.jsonl`, subagents to
+// `<dir>/<session>/subagents/agent-*.jsonl` (D14). Each assistant entry carries `message.id`, `message.model`,
+// `message.usage`, `cwd`, `gitBranch`, `sessionId` and sometimes `attributionSkill`. So no hook, receiver or
+// credential is needed: the record already exists.
+//   • D15 — an entry is THIS repo's when its cwd is the repo, under it, or under one of its worktrees.
+//   • D13 — one message is written as several entries (one per content block; the last carries the final
+//     output_tokens), and a resumed session copies earlier entries into a new file re-stamped with the NEW
+//     branch. So: one record per message id; its counts are the entry with the most output tokens; its
+//     attribution is the FIRST occurrence indexed (files are first read oldest-born first).
+//   • D16 — branch → epic is build-state.mjs's own resolveTarget(). Anything it does not name — main, a fix
+//     branch with no epic — is `unattributed`, reported by branch (D11), never guessed.
+//   • C14 — `gitBranch` is the branch of the session's OWN checkout. A session sitting on epic A that builds epic B
+//     in another directory is counted as A. So build an epic from a session on its branch, or in a worktree on it.
+//   • D4 — unknown is not zero: an unpriceable turn keeps its tokens and makes the $ a lower bound (`usd_known:
+//     false`); an entry missing a field the count needs is skipped and counted in `skipped`.
+//   • D9 — metrics only. Nothing here reads, stores or prints message content; a spec pins every output key.
+//
+// The index (D19) lives in the MAIN checkout's `.golden-frijoles/` so every worktree reads one summary, and it is
+// incremental: per transcript file it remembers how far it read. Aggregates outlive the transcripts — Claude Code
+// deletes old ones, the index keeps what it already counted.
+//
+// Zero deps — Node 18+.
+
+import { execFileSync } from 'node:child_process';
+import {
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readSync,
+  readdirSync,
+  realpathSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+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 { PRICES_AS_OF, PRICES_SOURCE, TOKEN_KINDS, tokensOf, usdOf } from './lib/model-prices.mjs';
+
+export const INDEX_VERSION = 1;
+export const STATE_DIR = '.golden-frijoles';
+export const INDEX_FILE = 'usage-index.json';
+export const SUMMARY_FILE = 'usage-summary.json';
+export const MACHINE = 'this machine';
+/** D12 — the agents whose passes this does not see. Named, so a reader never takes "Claude Code" for "everything". */
+export const NOT_MEASURED = Object.freeze(['codex', 'agy', 'vibe', 'devin']);
+export const NO_SKILL = '(no skill)';
+/** How long `--refresh` reads before saving and stopping (the mod's timeout is 10 s — D24). */
+export const REFRESH_BUDGET_MS = 6_000;
+
+// The same rule build-state.mjs applies: a git run from a hook must describe --repo-root, never an inherited GIT_DIR.
+const GIT_ENV_TO_CLEAR = [
+  'GIT_DIR',
+  'GIT_INDEX_FILE',
+  'GIT_WORK_TREE',
+  'GIT_COMMON_DIR',
+  'GIT_OBJECT_DIRECTORY',
+];
+function git(root, args) {
+  const env = { ...process.env };
+  for (const k of GIT_ENV_TO_CLEAR) delete env[k];
+  try {
+    return execFileSync('git', args, {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      env,
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+const real = (p) => {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+};
+
+// ── Where things are ────────────────────────────────────────────────────────────────────────────────
+
+/** The transcripts folder: `$CLAUDE_CONFIG_DIR/projects`, else `~/.claude/projects`. */
+export function defaultProjectsDir(env = process.env) {
+  return join(env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude'), 'projects');
+}
+
+/** D19 — the MAIN checkout (the parent of git's common dir), so every worktree shares one index. */
+export function mainCheckout(root) {
+  const common = git(root, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+  if (!common) return root;
+  return basename(common) === '.git' ? dirname(common) : root;
+}
+
+/** D15 — the paths an entry's cwd must sit in: the repo, its main checkout and every listed worktree. */
+export function repoPaths(root) {
+  const out = new Set([real(root), real(mainCheckout(root))]);
+  const list = git(root, ['worktree', 'list', '--porcelain']) || '';
+  for (const line of list.split('\n')) if (line.startsWith('worktree ')) out.add(real(line.slice(9)));
+  return [...out];
+}
+
+/** Is `cwd` one of `paths`, or under one? A sibling that merely shares a prefix (`repo-old`) is not. */
+export function inRepo(cwd, paths) {
+  if (typeof cwd !== 'string' || !cwd) return false;
+  const c = real(cwd);
+  return paths.some((p) => c === p || c.startsWith(p.endsWith(sep) ? p : p + sep));
+}
+
+/**
+ * Claude Code's folder name for a session started in `path`: every character other than a letter, digit or `-`
+ * becomes `-` (`/Users/me/repo` → `-Users-me-repo`, `/r/.claude/worktrees/x` → `-r--claude-worktrees-x`).
+ */
+export function projectDirName(path) {
+  return String(path).replace(/[^A-Za-z0-9-]/g, '-');
+}
+
+/**
+ * D15 (amended, C15) — the folders Claude Code keeps for this repo and its worktrees. A transcript in one of them is
+ * this repo's whatever `cwd` it recorded: when a checkout MOVES, Claude Code moves its folder but the entries keep the
+ * old path (this repo: 24k entries under ~/dobby/golden-beans, recorded before the 2026-09-29 folder move).
+ */
+export function ownProjectDirs(paths) {
+  return new Set(paths.map(projectDirName));
+}
+
+/** The project folder a transcript file lives in (`<projects>/<dir>/…`). */
+export function projectDirOf(file, projectsDir) {
+  const rel = file.slice(projectsDir.length).replace(/^[\\/]+/, '');
+  return rel.split(/[\\/]/)[0];
+}
+
+/** D14 — every transcript file: `<dir>/*.jsonl` and `<dir>/<session>/subagents/*.jsonl`. */
+export function listTranscripts(projectsDir) {
+  const files = [];
+  let dirs = [];
+  try {
+    dirs = readdirSync(projectsDir, { withFileTypes: true }).filter((d) => d.isDirectory());
+  } catch {
+    return files;
+  }
+  for (const d of dirs) {
+    const dir = join(projectsDir, d.name);
+    let names = [];
+    try {
+      names = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const n of names) {
+      if (n.isFile() && n.name.endsWith('.jsonl')) files.push(join(dir, n.name));
+      else if (n.isDirectory()) {
+        const sub = join(dir, n.name, 'subagents');
+        let subs = [];
+        try {
+          subs = readdirSync(sub);
+        } catch {
+          continue;
+        }
+        for (const f of subs) if (f.endsWith('.jsonl')) files.push(join(sub, f));
+      }
+    }
+  }
+  return files;
+}
+
+// ── One transcript line ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * One transcript line → `{ record }`, `{ skip: reason }` or null (not an assistant turn — most lines). The record holds
+ * metrics and ids ONLY (D9): it is built field by field, never by copying the entry.
+ */
+export function readEntry(line) {
+  if (!line.includes('"assistant"')) return null;
+  let d;
+  try {
+    d = JSON.parse(line);
+  } catch {
+    return { skip: 'unparseable' };
+  }
+  if (!d || d.type !== 'assistant') return null;
+  const m = d.message && typeof d.message === 'object' ? d.message : null;
+  if (!m) return { skip: 'no_message' };
+  const id = (typeof m.id === 'string' && m.id) || (typeof d.requestId === 'string' && d.requestId) || null;
+  if (!id) return { skip: 'no_id' };
+  if (m.model === '<synthetic>') return { skip: 'synthetic', cwd: d.cwd };
+  if (!m.usage || typeof m.usage !== 'object') return { skip: 'no_usage', cwd: d.cwd };
+  if (typeof m.model !== 'string' || !m.model) return { skip: 'no_model', cwd: d.cwd };
+  if (typeof d.cwd !== 'string' || !d.cwd) return { skip: 'no_cwd' };
+  return {
+    record: {
+      id,
+      session: typeof d.sessionId === 'string' ? d.sessionId : null,
+      branch: typeof d.gitBranch === 'string' && d.gitBranch ? d.gitBranch : null,
+      cwd: d.cwd,
+      skill: typeof d.attributionSkill === 'string' && d.attributionSkill ? d.attributionSkill : null,
+      model: m.model,
+      at: typeof d.timestamp === 'string' ? d.timestamp : null,
+      speed: m.usage.speed === 'fast' ? 'fast' : 'standard',
+      geo: m.usage.inference_geo === 'us' ? 'us' : null,
+      tokens: tokensOf(m.usage),
+    },
+  };
+}
+
+// ── The index ───────────────────────────────────────────────────────────────────────────────────────
+// messages[id] = [session, branch, skill, model, at, speed, geo, input, output, cache_read, w5, w1]
+// (compact on purpose: ~20k records). The cwd is checked at read time and not stored — every stored record is
+// this repo's.
+
+const T0 = 7; // first token column
+export function emptyIndex() {
+  return { version: INDEX_VERSION, files: {}, messages: {}, skipped: {} };
+}
+
+function packRecord(r) {
+  const t = r.tokens;
+  return [
+    r.session,
+    r.branch,
+    r.skill,
+    r.model,
+    r.at,
+    r.speed,
+    r.geo,
+    t.input,
+    t.output,
+    t.cache_read,
+    t.cache_write_5m,
+    t.cache_write_1h,
+  ];
+}
+
+/** D13 — the first occurrence owns the attribution; a later one may only raise the counts (the final streamed write). */
+export function mergeRecord(index, r) {
+  const prev = index.messages[r.id];
+  if (!prev) {
+    index.messages[r.id] = packRecord(r);
+    return 'added';
+  }
+  if (r.tokens.output > prev[T0 + 1]) {
+    const t = r.tokens;
+    prev.splice(T0, 5, t.input, t.output, t.cache_read, t.cache_write_5m, t.cache_write_1h);
+    return 'raised';
+  }
+  return 'same';
+}
+
+/** The bytes of `path` from `offset` to its last complete line. */
+function readFrom(path, offset, size) {
+  const len = size - offset;
+  if (len <= 0) return { text: '', end: offset };
+  const fd = openSync(path, 'r');
+  try {
+    const buf = Buffer.alloc(len);
+    readSync(fd, buf, 0, len, offset);
+    const lastNl = buf.lastIndexOf(0x0a);
+    if (lastNl === -1) return { text: '', end: offset };
+    return { text: buf.subarray(0, lastNl + 1).toString('utf8'), end: offset + lastNl + 1 };
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * Bring the index up to date: read only the bytes each transcript gained since the last run. A file that SHRANK
+ * (rewritten) is read again from the start — harmless, records are keyed by message id. Files are taken oldest-born
+ * first so an original session is indexed before a resumed copy of it (D13). Returns what changed.
+ */
+export function updateIndex(
+  index,
+  { projectsDir, paths, stat = statSync, deadline = Infinity, now = Date.now }
+) {
+  const own = ownProjectDirs(paths);
+  const files = listTranscripts(projectsDir)
+    .map((path) => {
+      try {
+        const s = stat(path);
+        return { path, size: s.size, mtimeMs: s.mtimeMs, born: s.birthtimeMs || s.mtimeMs };
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean)
+    .sort((a, b) => a.born - b.born || (a.path < b.path ? -1 : 1));
+  const changes = { files_read: 0, added: 0, raised: 0, complete: true };
+  for (const f of files) {
+    // A time budget (the mod's run is timeout-bound): stop BETWEEN files, so every file recorded is fully read and the
+    // next run resumes where this one stopped. A first scan on a slow machine then completes over a few runs instead of
+    // starting from zero every time and never saving (fresh review, #230).
+    // At least ONE file per run, by construction: listing and stat-ing every transcript happens inside the budget, so
+    // checking before the first file could let a slow listing read nothing, forever (round-2 review, #230).
+    if (changes.files_read > 0 && now() > deadline) {
+      changes.complete = false;
+      break;
+    }
+    const known = index.files[f.path];
+    if (known && known.size === f.size && known.mtimeMs === f.mtimeMs) continue;
+    const from = known && f.size >= known.offset ? known.offset : 0;
+    const { text, end } = readFrom(f.path, from, f.size);
+    changes.files_read++;
+    const ownFolder = own.has(projectDirOf(f.path, projectsDir));
+    for (const line of text.split('\n')) {
+      if (!line) continue;
+      const e = readEntry(line);
+      if (!e) continue;
+      if (e.skip) {
+        // Counted only when it is THIS repo's (its folder, or its cwd when the entry still has one) — another
+        // project's skips are not this summary's business. A line too broken to say counts only in our own folder.
+        if (ownFolder || inRepo(e.cwd, paths)) index.skipped[e.skip] = (index.skipped[e.skip] || 0) + 1;
+        continue;
+      }
+      if (!ownFolder && !inRepo(e.record.cwd, paths)) continue;
+      const how = mergeRecord(index, e.record);
+      if (how !== 'same') changes[how]++;
+    }
+    index.files[f.path] = { size: f.size, mtimeMs: f.mtimeMs, offset: end };
+  }
+  return changes;
+}
+
+export function readJson(path, fallback) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+/** Atomic: a second session writing at the same instant leaves one whole file, never a torn one. */
+export function writeJson(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  const ignore = join(dirname(path), '.gitignore');
+  if (!existsSync(ignore)) writeFileSync(ignore, '*\n');
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(value)}\n`);
+  renameSync(tmp, path);
+}
+
+export function loadIndex(file) {
+  const idx = readJson(file, null);
+  return idx && idx.version === INDEX_VERSION && idx.messages && idx.files ? idx : emptyIndex();
+}
+
+// ── Totals ──────────────────────────────────────────────────────────────────────────────────────────
+
+const zeroTokens = () => Object.fromEntries(TOKEN_KINDS.map((k) => [k, 0]));
+const totalTokens = (t) => TOKEN_KINDS.reduce((a, k) => a + (t[k] || 0), 0);
+
+function newBucket() {
+  return {
+    usd: 0,
+    usd_known: true,
+    tokens: zeroTokens(),
+    sessions: new Set(),
+    first_at: null,
+    last_at: null,
+  };
+}
+
+function addTo(bucket, rec) {
+  const [session, , , , at] = rec;
+  const t = tokensFromRecord(rec);
+  for (const k of TOKEN_KINDS) bucket.tokens[k] += t[k];
+  const usd = usdOf(rec[3], t, { speed: rec[5], inferenceGeo: rec[6] });
+  if (usd === null) bucket.usd_known = false;
+  else bucket.usd += usd;
+  if (session) bucket.sessions.add(session);
+  if (at && (!bucket.first_at || at < bucket.first_at)) bucket.first_at = at;
+  if (at && (!bucket.last_at || at > bucket.last_at)) bucket.last_at = at;
+}
+
+function tokensFromRecord(rec) {
+  return {
+    input: rec[T0],
+    output: rec[T0 + 1],
+    cache_read: rec[T0 + 2],
+    cache_write_5m: rec[T0 + 3],
+    cache_write_1h: rec[T0 + 4],
+  };
+}
+
+const round2 = (n) => Math.round(n * 100) / 100;
+const mtok = (t) => Math.round(totalTokens(t) / 1e5) / 10;
+
+function finish(b) {
+  return {
+    usd: round2(b.usd),
+    usd_known: b.usd_known,
+    tokens: b.tokens,
+    mtok: mtok(b.tokens),
+    sessions: b.sessions.size,
+    first_at: b.first_at,
+    last_at: b.last_at,
+  };
+}
+
+/**
+ * The index → per-epic totals (and the unattributed rest, by branch). `epicOf(branch)` is the D16 resolution —
+ * injected so a spec can drive it without a Roadmap on disk.
+ */
+export function summarize(index, { epicOf, now = new Date() }) {
+  const epics = new Map();
+  const unattributed = new Map();
+  const cache = new Map();
+  const resolveBranch = (b) => {
+    if (!b) return null;
+    if (!cache.has(b)) cache.set(b, epicOf(b));
+    return cache.get(b);
+  };
+  for (const rec of Object.values(index.messages)) {
+    const epic = resolveBranch(rec[1]);
+    if (!epic) {
+      const key = rec[1] || '(no branch)';
+      if (!unattributed.has(key)) unattributed.set(key, newBucket());
+      addTo(unattributed.get(key), rec);
+      continue;
+    }
+    if (!epics.has(epic))
+      epics.set(epic, { all: newBucket(), models: new Map(), skills: new Map(), branches: new Set() });
+    const e = epics.get(epic);
+    addTo(e.all, rec);
+    e.branches.add(rec[1]);
+    const model = rec[3];
+    if (!e.models.has(model)) e.models.set(model, newBucket());
+    addTo(e.models.get(model), rec);
+    const skill = rec[2] || NO_SKILL;
+    if (!e.skills.has(skill)) e.skills.set(skill, newBucket());
+    addTo(e.skills.get(skill), rec);
+  }
+  const part = (b) => {
+    const f = finish(b);
+    return { usd: f.usd, usd_known: f.usd_known, mtok: f.mtok, tokens: f.tokens };
+  };
+  const out = {};
+  for (const [slug, e] of [...epics].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+    out[slug] = {
+      ...finish(e.all),
+      branches: [...e.branches].sort(),
+      by_model: Object.fromEntries([...e.models].map(([k, b]) => [k, part(b)])),
+      by_skill: Object.fromEntries([...e.skills].map(([k, b]) => [k, part(b)])),
+    };
+  }
+  let oldest = null;
+  for (const rec of Object.values(index.messages))
+    if (rec[4] && (!oldest || rec[4] < oldest)) oldest = rec[4];
+  return {
+    generated_at: now.toISOString(),
+    basis: MACHINE,
+    oldest_at: oldest,
+    prices_as_of: PRICES_AS_OF,
+    prices_source: PRICES_SOURCE,
+    not_measured: [...NOT_MEASURED],
+    epics: out,
+    unattributed: Object.fromEntries(
+      [...unattributed].sort((a, b) => (a[0] < b[0] ? -1 : 1)).map(([k, b]) => [k, finish(b)])
+    ),
+    skipped: { ...index.skipped },
+  };
+}
+
+/** D16 — the epic slug a branch names in `root`'s Roadmap, or null. */
+export function epicOfBranch(root) {
+  return (branch) => {
+    try {
+      const t = resolveTarget(root, branch);
+      return t && t.kind === 'epic' ? t.epic.slug : null;
+    } catch {
+      return null;
+    }
+  };
+}
+
+/** 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 }) {
+  const dir = join(mainCheckout(root), STATE_DIR);
+  const indexPath = join(dir, INDEX_FILE);
+  const index = loadIndex(indexPath);
+  const changes = updateIndex(index, {
+    projectsDir,
+    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);
+  writeJson(join(dir, SUMMARY_FILE), summary);
+  return { summary, changes, dir };
+}
+
+/** One epic's report — the `--epic <slug> --json` shape (a spec pins the key set, D9). */
+export function epicReport(summary, slug) {
+  const e = summary.epics[slug];
+  return {
+    epic: slug,
+    measured: !!e,
+    basis: summary.basis,
+    sessions: e ? e.sessions : 0,
+    tokens: e ? e.tokens : zeroTokens(),
+    mtok: e ? e.mtok : 0,
+    usd: e ? e.usd : null,
+    usd_known: e ? e.usd_known : true,
+    first_at: e ? e.first_at : null,
+    last_at: e ? e.last_at : null,
+    branches: e ? e.branches : [],
+    by_model: e ? e.by_model : {},
+    by_skill: e ? e.by_skill : {},
+    skipped: summary.skipped,
+    prices_as_of: summary.prices_as_of,
+    prices_source: summary.prices_source,
+    not_measured: summary.not_measured,
+  };
+}
+
+/** `≈$38.42` / `≥$38.42` (a lower bound: some turns could not be priced — D4). */
+export function usdText(usd, known) {
+  return `${known ? '≈' : '≥'}$${usd >= 100 ? Math.round(usd) : usd.toFixed(2)}`;
+}
+
+// ── Stamping actual_* (S1.4 backfill, S2.5 close) ───────────────────────────────────────────────────
+
+/**
+ * Set `fields` in a doc's frontmatter: an existing `key:` line is replaced in place, a missing one is inserted just
+ * before the closing fence. No other line is touched. Re-running with the same values is a no-op (idempotent).
+ */
+export function stampFrontmatter(md, fields) {
+  const lines = md.split('\n');
+  if (lines[0].trim() !== '---') throw new Error('no frontmatter');
+  const end = lines.findIndex((l, i) => i > 0 && l.trim() === '---');
+  if (end === -1) throw new Error('unterminated frontmatter');
+  const missing = [];
+  for (const [key, value] of Object.entries(fields)) {
+    const line = `${key}: ${formatScalar(value)}`;
+    const at = lines.findIndex((l, i) => i > 0 && i < end && new RegExp(`^${key}:(\\s|$)`).test(l));
+    if (at === -1) missing.push(line);
+    else lines[at] = line;
+  }
+  lines.splice(end, 0, ...missing);
+  return lines.join('\n');
+}
+
+/** The three actual_* fields for an epic's report. */
+export function actualFields(report, basisPrefix, date) {
+  return {
+    actual_usd: report.usd,
+    actual_mtok: report.mtok,
+    actual_basis: `${basisPrefix}${MACHINE} · ${date} · ${report.sessions} session${report.sessions === 1 ? '' : 's'}${
+      report.usd_known ? '' : ' · lower bound (unpriced model)'
+    } · prices ${PRICES_AS_OF}`,
+  };
+}
+
+function epicReadme(root, slug) {
+  const roadmap = join(root, 'Roadmap');
+  for (const macro of existsSync(roadmap) ? readdirSync(roadmap).sort() : []) {
+    if (!/^\d{2}-/.test(macro)) continue;
+    const p = join(roadmap, macro, slug, 'README.md');
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+/** Write an epic's actual into its README. Returns the README path, or null when nothing was measured. */
+export function stampEpic({ root, summary, slug, basisPrefix = '', date, keepStamped = false }) {
+  const report = epicReport(summary, slug);
+  if (!report.measured) return null;
+  const path = epicReadme(root, slug);
+  if (!path) throw new Error(`no Roadmap/*/${slug}/README.md`);
+  const md = readFileSync(path, 'utf8');
+  // A backfill never overwrites an actual already written — one stamped at close, or a deliberate hold such as
+  // `actual_usd: null` with its reason (README C14). `--epic <slug> --write` (the close) is the one that replaces.
+  if (keepStamped) {
+    // Read through the contract's own parser: an empty `actual_basis:` or `actual_basis: null` is NOT a written actual.
+    const fm = parseDocFrontmatter(md);
+    // Fail CLOSED: a frontmatter this parser cannot read (an out-of-subset line, CRLF) may still hold an actual.
+    if (fm.error) return null;
+    const basis = fm.data.actual_basis;
+    if (typeof basis === 'string' && basis.trim()) return null;
+  }
+  const next = stampFrontmatter(md, actualFields(report, basisPrefix, date));
+  if (next !== md) writeFileSync(path, next);
+  return path;
+}
+
+// ── Backfill (S1.4) ─────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Every shipped epic: measured from local transcripts, or the reason it could not be (findings recorded, not fixed).
+ * `shippedAt(slug)` is when its README last changed; `oldestTranscriptAt` bounds what this machine can still see.
+ */
+export function backfillReport({
+  summary,
+  shipped,
+  oldestTranscriptAt,
+  shippedAt = () => null,
+  scaffoldedAt = () => null,
+}) {
+  const resolved = [];
+  const partial = [];
+  const unresolved = [];
+  for (const slug of shipped) {
+    const e = summary.epics[slug];
+    if (e) {
+      // An epic scaffolded before the oldest transcript this machine still has was partly built in sessions that are
+      // gone: its total is an UNDERSTATEMENT, and stamping it would teach the first quotes a number too low (D4).
+      // And one measured only on `docs/` branches (a retro, a close-out) is not its build: the build ran elsewhere.
+      const born = scaffoldedAt(slug);
+      const onlyDocs = (e.branches || []).length > 0 && e.branches.every((b) => /^docs\//.test(b));
+      const reason =
+        born && oldestTranscriptAt && born < oldestTranscriptAt
+          ? `scaffolded ${born.slice(0, 10)}, before the oldest transcript on this machine (${oldestTranscriptAt.slice(0, 10)}) — a partial total, not stamped`
+          : onlyDocs
+            ? `only close-out sessions here (${e.branches.join(', ')}) — the build ran elsewhere; a partial total, not stamped`
+            : null;
+      if (reason) partial.push({ epic: slug, ...epicReport(summary, slug), reason });
+      else resolved.push({ epic: slug, ...epicReport(summary, slug) });
+      continue;
+    }
+    const at = shippedAt(slug);
+    const reason =
+      at && oldestTranscriptAt && at < oldestTranscriptAt
+        ? `shipped ${at.slice(0, 10)}, before the oldest transcript on this machine (${oldestTranscriptAt.slice(0, 10)}) — no transcripts left`
+        : at
+          ? `shipped ${at.slice(0, 10)}, but no session on this machine ran on a branch naming it — built in the cloud, on another machine, or from a session whose own checkout sat on another branch`
+          : 'no session on this machine ran on a branch naming it';
+    unresolved.push({ epic: slug, reason });
+  }
+  return { resolved, partial, unresolved };
+}
+
+// ── CLI ─────────────────────────────────────────────────────────────────────────────────────────────
+
+function arg(argv, name) {
+  const i = argv.indexOf(name);
+  if (i === -1) return null;
+  const v = argv[i + 1];
+  if (!v || v.startsWith('--')) throw new Error(`${name} needs a value`);
+  return v;
+}
+
+function printEpic(r) {
+  if (!r.measured) return `${r.epic}: no session on ${MACHINE} ran on a branch naming this epic`;
+  const t = r.tokens;
+  const m = (n) => `${Math.round(n / 1e5) / 10}M`;
+  const lines = [
+    `${r.epic}: ${usdText(r.usd, r.usd_known)} · ${r.mtok}M tok · ${r.sessions} session${r.sessions === 1 ? '' : 's'} · ${MACHINE}`,
+    `  tokens   in ${m(t.input)} · out ${m(t.output)} · cache-read ${m(t.cache_read)} · cache-write ${m(t.cache_write_5m + t.cache_write_1h)}`,
+    `  models   ${Object.entries(r.by_model)
+      .map(([k, v]) => `${k} ${usdText(v.usd, v.usd_known)}`)
+      .join(' · ')}`,
+    `  skills   ${Object.entries(r.by_skill)
+      .map(([k, v]) => `${k} ${usdText(v.usd, v.usd_known)}`)
+      .join(' · ')}`,
+    `  span     ${r.first_at ?? '?'} → ${r.last_at ?? '?'} · branches ${r.branches.join(', ')}`,
+    `  ≈ API $ = list-price equivalent (${r.prices_source}, ${r.prices_as_of}); not measured: ${r.not_measured.join(', ')}`,
+  ];
+  return lines.join('\n');
+}
+
+function main(argv) {
+  const rootArg = arg(argv, '--repo-root');
+  const root = resolve(rootArg ?? projectRoot());
+  const projectsDir = arg(argv, '--projects-dir') ?? defaultProjectsDir();
+  const json = argv.includes('--json');
+  const write = argv.includes('--write');
+  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 });
+
+  if (argv.includes('--refresh')) {
+    if (json)
+      process.stdout.write(`${JSON.stringify({ changes, epics: Object.keys(summary.epics).length })}\n`);
+    return 0;
+  }
+  const slug = arg(argv, '--epic');
+  if (slug) {
+    const report = epicReport(summary, slug);
+    if (write) {
+      const path = stampEpic({ root, summary, slug, date: today });
+      if (!path) {
+        process.stderr.write(`epic-actuals: nothing measured for ${slug} on ${MACHINE} — nothing written\n`);
+        return 1;
+      }
+      process.stderr.write(`epic-actuals: stamped actual_* in ${path.slice(root.length + 1)}\n`);
+    }
+    process.stdout.write(json ? `${JSON.stringify(report, null, 2)}\n` : `${printEpic(report)}\n`);
+    return 0;
+  }
+  if (argv.includes('--backfill')) {
+    const rows = buildRows({ root, dates: false });
+    const shipped = rows.filter((r) => r.grain === 'Epic' && r.status === 'Shipped').map((r) => r.slug);
+    const shippedAt = (s) => {
+      const p = epicReadme(root, s);
+      // The FIRST commit that wrote `status: shipped` — a later edit (a move, a close-out) would date it too late.
+      const dates = p ? git(root, ['log', '--format=%cI', '-G', '^status: shipped', '--', p]) : null;
+      return dates ? dates.split('\n').filter(Boolean).at(-1) || null : null;
+    };
+    const scaffoldedAt = (s) => {
+      const p = epicReadme(root, s);
+      const dates = p ? git(root, ['log', '--format=%cI', '--follow', '--diff-filter=A', '--', p]) : null;
+      return dates ? dates.split('\n').filter(Boolean).at(-1) || null : null;
+    };
+    const rep = backfillReport({
+      summary,
+      shipped,
+      oldestTranscriptAt: summary.oldest_at,
+      shippedAt,
+      scaffoldedAt,
+    });
+    if (write)
+      for (const r of rep.resolved)
+        if (
+          !stampEpic({
+            root,
+            summary,
+            slug: r.epic,
+            basisPrefix: 'backfill · ',
+            date: today,
+            keepStamped: true,
+          })
+        )
+          process.stderr.write(`epic-actuals: ${r.epic} already carries an actual — left as written\n`);
+    if (json) {
+      process.stdout.write(
+        `${JSON.stringify({ ...rep, unattributed: summary.unattributed, written: write }, null, 2)}\n`
+      );
+      return 0;
+    }
+    const out = [
+      `Measured on ${MACHINE} (${rep.resolved.length} shipped epic${rep.resolved.length === 1 ? '' : 's'}):`,
+    ];
+    for (const r of rep.resolved)
+      out.push(
+        `  ${r.epic.padEnd(36)} ${usdText(r.usd, r.usd_known).padStart(9)} · ${r.mtok}M tok · ${r.sessions} session${r.sessions === 1 ? '' : 's'}`
+      );
+    out.push(`Partly measured — not stamped (${rep.partial.length}):`);
+    for (const r of rep.partial)
+      out.push(`  ${r.epic.padEnd(36)} ${usdText(r.usd, r.usd_known).padStart(9)} · ${r.reason}`);
+    out.push(`Could not measure (${rep.unresolved.length}):`);
+    for (const u of rep.unresolved) out.push(`  ${u.epic.padEnd(36)} ${u.reason}`);
+    const un = Object.entries(summary.unattributed);
+    out.push(
+      `Unattributed (D11 — planning on main, fixes with no epic; ${un.length} branch${un.length === 1 ? '' : 'es'}):`
+    );
+    for (const [b, v] of un.slice(0, 12))
+      out.push(
+        `  ${b.padEnd(36)} ${usdText(v.usd, v.usd_known).padStart(9)} · ${v.sessions} session${v.sessions === 1 ? '' : 's'}`
+      );
+    if (un.length > 12) out.push(`  … ${un.length - 12} more — --json`);
+    out.push(
+      write
+        ? 'Stamped actual_* on every measured shipped epic.'
+        : 'Dry run — add --write to stamp actual_* on the measured ones.'
+    );
+    process.stdout.write(`${out.join('\n')}\n`);
+    return 0;
+  }
+  process.stderr.write(
+    'usage: epic-actuals.mjs --epic <slug> [--json] [--write] | --refresh | --backfill [--write]\n'
+  );
+  return 2;
+}
+
+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(`epic-actuals: ${err && err.message ? err.message : err}\n`);
+    process.exitCode = 2;
+  }
+}

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

@@ -53,10 +53,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-09-30 against 1.2.14.
+// agy-doctor: last verified 2026-10-02 against 1.2.15.
 //   ^ 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.2.14';
+export const AGY_PINNED = '1.2.15';
 
 // 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/model-prices.mjs

@@ -0,0 +1,103 @@
+// model-prices.mjs — ONE dated price table for the ≈ API $ an epic cost (finops D3, D18).
+//
+// "≈ API $" is a LIST-PRICE EQUIVALENT: what the same tokens would have cost on the Claude API at the prices below.
+// It is not what anyone was billed (a subscription is not billed per token), and it says so wherever it is shown.
+// A stamped actual keeps the $ it was stamped with; changing this table re-prices only what is measured after.
+//
+// Read from the official pricing page on PRICES_AS_OF. To update: re-read that page, change the rows and the date
+// in ONE commit, and say in the CHANGELOG which models moved.
+//
+// Zero deps, no imports.
+
+export const PRICES_AS_OF = '2026-10-02';
+export const PRICES_SOURCE = 'https://platform.claude.com/docs/en/about-claude/pricing';
+
+// USD per million tokens, per kind. `fast`: the page lists fast-mode pricing for this model, at 2× (Opus 5.5 $8/$40,
+// Opus 5 and Opus 4.8 $10/$50); the prompt-caching multipliers stack on top, so every kind doubles.
+const row = (input, cache_write_5m, cache_write_1h, cache_read, output, fast = false) =>
+  Object.freeze({ input, cache_write_5m, cache_write_1h, cache_read, output, fast });
+
+export const PRICES = Object.freeze({
+  'claude-fable-5-1': row(10, 12.5, 20, 0.25, 50),
+  'claude-mythos-5-1': row(10, 12.5, 20, 0.25, 50),
+  'claude-fable-5': row(10, 12.5, 20, 1, 50),
+  'claude-mythos-5': row(10, 12.5, 20, 1, 50),
+  'claude-opus-5-5': row(4, 5, 8, 0.2, 20, true),
+  'claude-opus-5': row(5, 6.25, 10, 0.5, 25, true),
+  'claude-opus-4-8': row(5, 6.25, 10, 0.5, 25, true),
+  'claude-opus-4-7': row(5, 6.25, 10, 0.5, 25),
+  'claude-opus-4-6': row(5, 6.25, 10, 0.5, 25),
+  'claude-opus-4-5': row(5, 6.25, 10, 0.5, 25),
+  'claude-opus-4-1': row(15, 18.75, 30, 1.5, 75),
+  'claude-opus-4': row(15, 18.75, 30, 1.5, 75),
+  'claude-sonnet-5-5': row(2, 2.5, 4, 0.2, 10),
+  'claude-sonnet-5': row(2, 2.5, 4, 0.2, 10),
+  'claude-sonnet-4-6': row(3, 3.75, 6, 0.3, 15),
+  'claude-sonnet-4-5': row(3, 3.75, 6, 0.3, 15),
+  'claude-sonnet-4': row(3, 3.75, 6, 0.3, 15),
+  'claude-haiku-4-5': row(1, 1.25, 2, 0.1, 5),
+  'claude-haiku-3-5': row(0.8, 1, 1.6, 0.08, 4),
+});
+
+/** The token kinds a usage record carries, in the order every report prints them. */
+export const TOKEN_KINDS = Object.freeze([
+  'input',
+  'output',
+  'cache_read',
+  'cache_write_5m',
+  'cache_write_1h',
+]);
+
+/** `claude-haiku-4-5-20251001` → `claude-haiku-4-5`: a dated snapshot is priced as its model. */
+export function normalizeModel(model) {
+  return String(model || '').replace(/-\d{8}$/, '');
+}
+
+/** The price row for a model id, or null when the table does not know it (→ `$ unknown`, never $0 — D4). */
+export function priceFor(model) {
+  return PRICES[normalizeModel(model)] ?? null;
+}
+
+/**
+ * The tokens of one transcript `message.usage`, split by kind. A cache write with no 5m/1h split is counted as 5m
+ * (the cheaper rate — so the $ is never overstated) and reported in `unsplit_cache_write`.
+ */
+export function tokensOf(usage) {
+  const u = usage || {};
+  const n = (v) => (Number.isFinite(v) && v > 0 ? v : 0);
+  const split = u.cache_creation && typeof u.cache_creation === 'object' ? u.cache_creation : null;
+  const total = n(u.cache_creation_input_tokens);
+  let w5 = split ? n(split.ephemeral_5m_input_tokens) : 0;
+  const w1 = split ? n(split.ephemeral_1h_input_tokens) : 0;
+  let unsplit = 0;
+  if (!split || w5 + w1 < total) {
+    unsplit = total - w5 - w1;
+    w5 += unsplit;
+  }
+  return {
+    input: n(u.input_tokens),
+    output: n(u.output_tokens),
+    cache_read: n(u.cache_read_input_tokens),
+    cache_write_5m: w5,
+    cache_write_1h: w1,
+    unsplit_cache_write: unsplit,
+  };
+}
+
+/**
+ * ≈ API $ for one turn: Σ tokens × price per kind, × 2 in fast mode, × 1.1 for US-only inference. null when it cannot
+ * be priced (an unknown model, or fast mode on a model the page lists no fast price for).
+ */
+export function usdOf(model, tokens, { speed = 'standard', inferenceGeo = null } = {}) {
+  const p = priceFor(model);
+  if (!p) return null;
+  let mult = 1;
+  if (speed === 'fast') {
+    if (!p.fast) return null;
+    mult *= 2;
+  }
+  if (inferenceGeo === 'us') mult *= 1.1;
+  let usd = 0;
+  for (const kind of TOKEN_KINDS) usd += ((tokens[kind] || 0) * p[kind]) / 1e6;
+  return usd * mult;
+}

package/dist/lib/roadmap-contract.mjs

@@ -27,9 +27,10 @@
 // Deliberately small, so a zero-dependency parser owns it completely: top-level `key: scalar` lines
 // (an unquoted value may carry a trailing ` # comment`), whole-line `#` comments at any indent, and a
 // top-level `key:` followed by a list of flat maps (`  - k: v` then `    k: v`). A scalar is `null`,
-// `~` or empty (→ null), `[]` (an empty list), an integer, a double-quoted JSON string, a single-quoted
-// YAML string, or a bare string; any of them may carry a trailing ` # comment`. Booleans and floats are
-// not in the subset (no contract field uses one). Anything else is a parse error, not guessed around.
+// `~` or empty (→ null), `[]` (an empty list), an integer, a decimal (`38.42`, finops D17 — the FinOps
+// fields carry dollars), a double-quoted JSON string, a single-quoted YAML string, or a bare string; any of
+// them may carry a trailing ` # comment`. Booleans are not in the subset (no contract field uses one), and
+// neither are exponents or a bare `.5`. Anything else is a parse error, not guessed around.
 
 export const PHASES = ['Shaping', 'Locking architecture', 'Building', 'Verifying', 'In review', 'Shipped'];
 export const STORY_STATUSES = ['planned', 'in-progress', 'done'];
@@ -40,6 +41,53 @@ export const EPIC_FIELDS = ['title', 'area', 'risk', 'type', 'phase', 'sprints_t
 export const SPRINT_FIELDS = ['epic', 'sprint', 'title', 'risk', 'phase', 'stories_total', 'stories'];
 export const STORY_FIELDS = ['id', 'title', 'as_a', 'i_want', 'so_that', 'risk', 'status'];
 
+// finops D6/D17 — an epic's quote (written at grooming) and its actual (stamped at close), declared ONCE here.
+// 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'];
+export const FINOPS_FIELDS = [
+  'quote_low_usd',
+  'quote_high_usd',
+  'quote_basis',
+  'actual_usd',
+  'actual_mtok',
+  'actual_basis',
+];
+
+/** The FinOps fields of an epic's frontmatter data → offenses (`contract-finops-invalid`). Absent/null is fine. */
+export function validateFinopsFields(fm) {
+  const offenses = [];
+  for (const key of FINOPS_NUMERIC_FIELDS) {
+    const v = fm[key];
+    if (v === undefined || v === null) continue;
+    if (typeof v !== 'number' || !Number.isFinite(v) || v < 0)
+      offenses.push({
+        rule: 'contract-finops-invalid',
+        detail: `${key}: "${v}" is not a number >= 0 (or null)`,
+      });
+  }
+  for (const key of FINOPS_BASIS_FIELDS) {
+    const v = fm[key];
+    if (v === undefined || v === null) continue;
+    if (typeof v !== 'string')
+      offenses.push({ rule: 'contract-finops-invalid', detail: `${key}: "${v}" is not a string (or null)` });
+  }
+  const lo = fm.quote_low_usd;
+  const hi = fm.quote_high_usd;
+  if (typeof lo === 'number' && typeof hi === 'number' && lo > hi)
+    offenses.push({
+      rule: 'contract-finops-invalid',
+      detail: `quote_low_usd ${lo} is above quote_high_usd ${hi}`,
+    });
+  if ((typeof lo === 'number') !== (typeof hi === 'number'))
+    offenses.push({
+      rule: 'contract-finops-invalid',
+      detail: 'a quote needs both quote_low_usd and quote_high_usd',
+    });
+  return offenses;
+}
+
 // A story id names its sprint: S<sprint>.<ordinal>. The commit convention D2 derives from uses it.
 export const STORY_ID_RE = /^S(\d+)\.(\d+)$/;
 
@@ -58,6 +106,9 @@ function parseScalar(raw, where) {
   if (v === '' || v === 'null' || v === '~') return null;
   if (v === '[]') return [];
   if (/^-?\d+$/.test(v)) return Number(v);
+  // finops D17 — decimals. The corpus held no bare decimal frontmatter value when this was added (2026-10-02),
+  // so no existing reading changed.
+  if (/^-?\d+\.\d+$/.test(v)) return Number(v);
   if (v.startsWith('"')) {
     try {
       return JSON.parse(v);
@@ -139,7 +190,8 @@ export function formatScalar(v) {
   if (v === null || v === undefined) return 'null';
   if (typeof v === 'number') return String(v);
   const s = String(v);
-  if (BARE_SAFE.test(s) && !/^-?\d+$/.test(s) && !RESERVED.has(s.toLowerCase()) && !s.endsWith(' ')) return s;
+  if (BARE_SAFE.test(s) && !/^-?\d+(\.\d+)?$/.test(s) && !RESERVED.has(s.toLowerCase()) && !s.endsWith(' '))
+    return s;
   return JSON.stringify(s);
 }
 
@@ -203,6 +255,7 @@ export function validateEpicFrontmatter(parsed, ctx = {}) {
     if (fm[key] != null && !isInt(fm[key]))
       offenses.push({ rule: 'contract-total-invalid', detail: `${key}: "${fm[key]}" is not a whole number` });
   }
+  offenses.push(...validateFinopsFields(fm));
   if (isInt(fm.sprints_total) && isInt(ctx.sprintCount) && fm.sprints_total !== ctx.sprintCount)
     offenses.push({
       rule: 'contract-total-mismatch',

package/package.json

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