@golden-frijoles/kit 0.30.0 → 0.32.0

package/dist/epic-actuals.mjs

@@ -52,7 +52,10 @@ 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 { parseDocFrontmatter } from './lib/roadmap-contract.mjs';
+import { stampFrontmatter } from './lib/frontmatter-stamp.mjs';
+
+export { stampFrontmatter };
 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';
@@ -728,25 +731,7 @@ export async function pushUsage({
 
 // ── 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');
-}
+// stampFrontmatter moved to lib/frontmatter-stamp.mjs (result-record D8); re-exported above for existing callers.
 
 /** The three actual_* fields for an epic's report. */
 export function actualFields(report, basisPrefix, date) {

package/dist/epic-read.mjs

@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+// epic-read.mjs — read an epic's result on its read date: draft the verdict with its evidence; write it on approval.
+//
+//   node scripts/epic-read.mjs --epic <slug>                               # when is the read, and what it needs
+//   node scripts/epic-read.mjs --epic <slug> --actual 72 --evidence north-star:invoices_paid_on_time@2026-11-04
+//   node scripts/epic-read.mjs --epic <slug> --evidence "traffic too low (n = 18)"          # no number: unclear
+//   node scripts/epic-read.mjs --epic <slug> --verdict proven --evidence https://…           # an owner verdict
+//   … --write                                                              # the approval: stamp verdict_* into the README
+//   options: --today YYYY-MM-DD (default: today, UTC) · --repo-root <dir> · --json
+//
+// ── The shape (result-record D8) ─────────────────────────────────────────────────────────────────────────────────
+// The agent does the legwork, the owner decides. Without `--write` this prints a draft and the exact command that
+// approves it, and writes nothing. Inputs are flags, never a prompt: an agent asks the owner in the conversation and
+// passes what they said.
+//   • Before the read date it says when the read is due and stops — the date is the README's `read_date`, or, when none
+//     was written, 30 days after shipping (lib/result-dates.mjs, the one place that rule lives).
+//   • The draft: from `target_from` toward `target_to`; reached or passed → proven, short of it → disproven; no number
+//     → unclear, with the reason in `--evidence`. `--verdict` is the owner's word over the draft, and is said as such.
+//   • Proven and disproven need evidence that points somewhere (the contract's grammar: an https:// link,
+//     `north-star:<input>@YYYY-MM-DD` or `ab:<experiment>`). `--write` runs the contract's own `validateResultFields` on
+//     the record it is about to write, so a verdict the contract refuses never lands.
+//   • More than 90 days after shipping, the read is still written, and said to be late (the extract marks it).
+//   • An epic shipped with no target can be read too — an owner verdict and its evidence, one epic per run.
+//
+// ── With an account, and without ─────────────────────────────────────────────────────────────────────────────────
+// No route reads a North Star reading or an A/B decision for a key yet (the lock checked: `gf north-star` only sets,
+// `GET /api/v1/north-star` lists metrics and inputs with no values), so the actual always comes from the owner. With the
+// project's key (the one `roadmap-push` uses) this asks that route whether `target_metric` is one of the project's
+// inputs — grounded or not. No key, or any failure, is "could not check", and the read carries on.
+//
+// Zero deps — Node 18+.
+import { existsSync, readFileSync, readdirSync, realpathSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { projectRoot } from './lib/project-root.mjs';
+import {
+  VERDICTS,
+  isEvidencePointer,
+  parseDocFrontmatter,
+  validateResultFields,
+} from './lib/roadmap-contract.mjs';
+import { READ_CAP_DAYS, isLate, readDateOf, todayUtc, isDay } from './lib/result-dates.mjs';
+import { stampFrontmatter } from './lib/frontmatter-stamp.mjs';
+import { buildRows } from './roadmap-extract.mjs';
+import { apiKeyFrom } from './roadmap-push.mjs';
+
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+/** `2026-11-04` → `4 Nov 2026`. */
+export const longDay = (d) =>
+  `${Number(d.slice(8, 10))} ${MONTHS[Number(d.slice(5, 7)) - 1]} ${d.slice(0, 4)}`;
+
+const fig = (n) => (Number.isInteger(n) ? String(n) : String(Math.round(n * 100) / 100));
+
+/**
+ * The draft verdict for a target and a number read. Pure.
+ * From → to says the direction: a target above its start is met at or above it, one below at or below it.
+ */
+export function draftVerdict({ from, to, actual }) {
+  if (actual === null || actual === undefined || !Number.isFinite(actual)) return 'unclear';
+  if (!Number.isFinite(from) || !Number.isFinite(to)) return 'unclear';
+  const up = to > from;
+  return (up ? actual >= to : actual <= to) ? 'proven' : 'disproven';
+}
+
+/**
+ * Everything the read decides, from the README's frontmatter, the extract's row and the flags. Pure — no I/O.
+ * Returns `{ state, … }`: not-shipped · already-read · not-due · needs-input · refused · ready.
+ */
+export function planRead({ fm, shippedAt, shipped, today, actual = null, evidence = null, verdict = null }) {
+  const target = {
+    hypothesis: fm.hypothesis ?? null,
+    metric: fm.target_metric ?? null,
+    from: typeof fm.target_from === 'number' ? fm.target_from : null,
+    to: typeof fm.target_to === 'number' ? fm.target_to : null,
+  };
+  if (fm.verdict)
+    return { state: 'already-read', target, verdict: fm.verdict, verdictAt: fm.verdict_at ?? null };
+  if (!shipped) return { state: 'not-shipped', target };
+  if (verdict !== null && !VERDICTS.includes(verdict))
+    return {
+      state: 'refused',
+      target,
+      reasons: [`--verdict must be one of ${VERDICTS.join(' | ')}, got "${verdict}"`],
+    };
+
+  const { readDate, derived } = readDateOf({
+    readDate: fm.read_date,
+    targetMetric: target.metric,
+    shippedAt,
+  });
+  if (target.metric && readDate && today < readDate) return { state: 'not-due', target, readDate, derived };
+
+  const owner = verdict !== null;
+  if (!target.metric && !owner)
+    return {
+      state: 'needs-input',
+      target,
+      need: 'This epic shipped with no target. An owner verdict is allowed, one epic at a time: --verdict <proven|disproven|unclear> --evidence <pointer, or for unclear the reason> (and --actual <n> for proven/disproven).',
+    };
+  const drafted = target.metric ? draftVerdict({ from: target.from, to: target.to, actual }) : null;
+  const chosen = owner ? verdict : drafted;
+  if (chosen === 'unclear' && !evidence)
+    return {
+      state: 'needs-input',
+      target,
+      drafted,
+      readDate,
+      derived,
+      need:
+        actual === null
+          ? `Ask the owner for the number read for ${target.metric ?? 'this epic'} (--actual <n>) and where it came from (--evidence <https://… | north-star:<input>@YYYY-MM-DD | ab:<experiment>>), or why it cannot be told yet (--evidence "<reason>").`
+          : 'Unclear needs the reason in --evidence (e.g. "traffic too low to tell (n = 18)").',
+    };
+  if ((chosen === 'proven' || chosen === 'disproven') && !evidence)
+    return {
+      state: 'needs-input',
+      target,
+      drafted,
+      readDate,
+      derived,
+      need: `${chosen} needs evidence that points somewhere: --evidence <https://… | north-star:<input>@YYYY-MM-DD | ab:<experiment>>.`,
+    };
+
+  const fields = {
+    verdict: chosen,
+    verdict_actual: actual === null || actual === undefined ? null : actual,
+    verdict_evidence: evidence,
+    verdict_at: today,
+  };
+  const offenses = validateResultFields({ ...fm, ...fields }).map((o) => o.detail);
+  const late = isLate({ verdictAt: today, shippedAt });
+  if (offenses.length) return { state: 'refused', target, drafted, fields, reasons: offenses, late };
+  return { state: 'ready', target, drafted, owner, fields, late, readDate, derived };
+}
+
+/** `metric` against the project's North Star inputs, through the existing read route. Never throws. */
+export async function groundedCheck({ metric, apiKey, baseUrl, fetchFn = fetch }) {
+  if (!metric) return { checked: false, why: 'no target metric' };
+  if (!apiKey)
+    return { checked: false, why: 'no project key (SELF_PROJECT_API_KEY / GROWTH_ENGINE_API_KEY)' };
+  try {
+    const res = await fetchFn(`${String(baseUrl).replace(/\/$/, '')}/api/v1/north-star`, {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) return { checked: false, why: `the engine answered ${res.status}` };
+    const body = await res.json();
+    const keys = (body?.metrics ?? []).flatMap((m) => (m?.inputs ?? []).map((i) => i?.key)).filter(Boolean);
+    return { checked: true, grounded: keys.includes(metric), keys };
+  } catch (err) {
+    return { checked: false, why: `could not reach ${baseUrl}: ${err?.message ?? err}` };
+  }
+}
+
+/** The text a person reads. Pure. */
+export function renderPlan(plan, { slug, grounded, write, written }) {
+  const out = [];
+  const t = plan.target;
+  const head = t.metric
+    ? `${slug}: ${t.metric}${t.from !== null && t.to !== null ? ` ${fig(t.from)} → ${fig(t.to)}` : ''}${t.hypothesis ? ` — "${t.hypothesis}"` : ''}`
+    : `${slug}: no target`;
+  out.push(head);
+  if (grounded) {
+    if (grounded.checked)
+      out.push(
+        grounded.grounded
+          ? `  grounded: ${t.metric} is one of the project's North Star inputs`
+          : `  not grounded: ${t.metric} is not one of the project's North Star inputs (${grounded.keys.join(', ') || 'none'})`
+      );
+    else if (t.metric) out.push(`  could not check the metric against the North Star (${grounded.why})`);
+  }
+  switch (plan.state) {
+    case 'already-read':
+      out.push(
+        `  already read: ${plan.verdict}${plan.verdictAt ? ` on ${longDay(plan.verdictAt)}` : ''}. Nothing to do.`
+      );
+      break;
+    case 'not-shipped':
+      out.push('  not shipped yet: there is nothing out there to read.');
+      break;
+    case 'not-due':
+      out.push(
+        `  read due ${longDay(plan.readDate)}${plan.derived ? ' (30 days after shipping — no read_date was written)' : ''}. Not yet: come back then.`
+      );
+      break;
+    case 'needs-input':
+      if (plan.drafted) out.push(`  draft so far: ${plan.drafted}`);
+      out.push(`  needs: ${plan.need}`);
+      break;
+    case 'refused':
+      out.push('  refused — nothing written:');
+      for (const r of plan.reasons) out.push(`    · ${r}`);
+      break;
+    case 'ready': {
+      const f = plan.fields;
+      const word =
+        plan.owner && plan.drafted && plan.drafted !== f.verdict
+          ? `${f.verdict} (owner's verdict; drafted ${plan.drafted})`
+          : plan.owner
+            ? `${f.verdict} (owner's verdict)`
+            : f.verdict;
+      out.push(`  verdict:  ${word}`);
+      if (f.verdict_actual !== null)
+        out.push(`  actual:   ${fig(f.verdict_actual)}${t.to !== null ? ` (target ${fig(t.to)})` : ''}`);
+      out.push(
+        `  evidence: ${f.verdict_evidence}${isEvidencePointer(f.verdict_evidence) ? '' : ' (a reason, not a pointer)'}`
+      );
+      out.push(`  read on:  ${longDay(f.verdict_at)}`);
+      if (plan.late)
+        out.push(
+          `  late: more than ${READ_CAP_DAYS} days after shipping — it is recorded, and it will not count for the North Star.`
+        );
+      if (written)
+        out.push(
+          `  written to ${written}. Commit it, then push the roadmap (node scripts/roadmap-push.mjs).`
+        );
+      else if (!write) out.push('  Not written. If the owner approves, run the same command with --write.');
+      break;
+    }
+  }
+  return out.join('\n');
+}
+
+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;
+}
+
+const arg = (argv, name) => {
+  const i = argv.indexOf(name);
+  return i === -1 ? null : (argv[i + 1] ?? null);
+};
+
+export async function main(argv, { fetchFn = fetch, env = process.env, stdout = process.stdout } = {}) {
+  const slug = arg(argv, '--epic');
+  if (!slug) {
+    process.stderr.write('epic-read: --epic <slug> is required\n');
+    return 2;
+  }
+  const root = resolve(arg(argv, '--repo-root') ?? projectRoot());
+  const today = arg(argv, '--today') ?? todayUtc();
+  if (!isDay(today)) {
+    process.stderr.write(`epic-read: --today must be a day written YYYY-MM-DD, got "${today}"\n`);
+    return 2;
+  }
+  const actualRaw = arg(argv, '--actual');
+  const actual = actualRaw === null ? null : Number(actualRaw);
+  if (actualRaw !== null && !Number.isFinite(actual)) {
+    process.stderr.write(`epic-read: --actual must be a number, got "${actualRaw}"\n`);
+    return 2;
+  }
+  const path = epicReadme(root, slug);
+  if (!path) {
+    process.stderr.write(`epic-read: no Roadmap/*/${slug}/README.md under ${root}\n`);
+    return 2;
+  }
+  const md = readFileSync(path, 'utf8');
+  const parsed = parseDocFrontmatter(md);
+  if (!parsed.hasFrontmatter || parsed.error) {
+    process.stderr.write(`epic-read: cannot read ${path}'s frontmatter: ${parsed.error ?? 'none'}\n`);
+    return 2;
+  }
+  const row = buildRows({ root, facts: { mode: 'docs', prs: [], branches: [] } }).find(
+    (r) => r.grain === 'Epic' && r.slug === slug
+  );
+  const plan = planRead({
+    fm: parsed.data,
+    shippedAt: row?.shipped_at ?? null,
+    shipped: row?.stage === 'Shipped',
+    today,
+    actual,
+    evidence: arg(argv, '--evidence'),
+    verdict: arg(argv, '--verdict'),
+  });
+  const grounded =
+    plan.state === 'already-read' || plan.state === 'not-shipped'
+      ? null
+      : await groundedCheck({
+          metric: plan.target.metric,
+          apiKey: apiKeyFrom(env),
+          baseUrl: env.GROWTH_ENGINE_URL || 'http://localhost:3000',
+          fetchFn,
+        });
+  const write = argv.includes('--write');
+  let written = null;
+  if (write && plan.state === 'ready') {
+    const next = stampFrontmatter(md, plan.fields);
+    // The stamped file must still satisfy the contract as a whole — a second check on what actually lands.
+    const after = parseDocFrontmatter(next);
+    const offenses = after.error ? [after.error] : validateResultFields(after.data).map((o) => o.detail);
+    if (offenses.length) {
+      const refused = { ...plan, state: 'refused', reasons: offenses };
+      stdout.write(
+        argv.includes('--json')
+          ? `${JSON.stringify({ slug, ...refused, grounded, written: null })}\n`
+          : `${renderPlan(refused, { slug, grounded, write })}\n`
+      );
+      return 1;
+    }
+    writeFileSync(path, next);
+    written = path.slice(root.length + 1);
+  }
+  if (argv.includes('--json')) stdout.write(`${JSON.stringify({ slug, ...plan, grounded, written })}\n`);
+  else stdout.write(`${renderPlan(plan, { slug, grounded, write, written })}\n`);
+  if (plan.state === 'refused') return 1;
+  if (write && plan.state !== 'ready') return 1; // asked to write, and there was nothing approvable to write
+  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 = await main(process.argv.slice(2));
+  } catch (err) {
+    process.stderr.write(`epic-read: ${err && err.message ? err.message : err}\n`);
+    process.exitCode = 2;
+  }
+}

package/dist/lib/frontmatter-stamp.mjs

@@ -0,0 +1,25 @@
+// frontmatter-stamp.mjs — set fields in a Roadmap doc's frontmatter, in place (zero deps beyond the contract).
+//
+// Written for `epic-actuals.mjs --write` (finops S1.4/S2.5) and moved here when `epic-read.mjs --write` needed the same
+// stamp (result-record D8): two writers of one README must not each keep their own line editor.
+import { formatScalar } from './roadmap-contract.mjs';
+
+/**
+ * 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');
+}

package/dist/lib/result-dates.mjs

@@ -0,0 +1,75 @@
+// result-dates.mjs — the result record's date arithmetic, written once (result-record D5). Pure: zero I/O, zero deps.
+//
+// An epic that carries a target (`target_metric`) is read on its `read_date`. When none was written, the read falls
+// 30 days after shipping; a verdict written more than 90 days after shipping is late (it is kept, and it does not count
+// for the North Star). Those two numbers are `Roadmap/00-strategy/north-star.md`'s rule. Extract, `epic-read` and
+// `session-resume` import them from here; `apps/web/lib/roadmap-result.ts` holds a copy a spec pins to this one.
+//
+// Every date is a calendar day, `YYYY-MM-DD`, read and written in UTC so a reader's timezone never moves a read. The
+// day check itself is the contract's (`isDay`), which stays dependency-free.
+
+export const READ_DEFAULT_DAYS = 30;
+export const READ_CAP_DAYS = 90;
+
+import { isDay } from './roadmap-contract.mjs';
+
+export { isDay };
+
+const MS_PER_DAY = 86_400_000;
+
+/** The calendar day part of a date or date-time string, or null. `2026-10-04T12:00:00Z` → `2026-10-04`. */
+export function dayOf(v) {
+  if (typeof v !== 'string') return null;
+  const day = v.slice(0, 10);
+  return isDay(day) ? day : null;
+}
+
+/** `day` + `n` days, as `YYYY-MM-DD`. Null when `day` is not a day. */
+export function addDays(day, n) {
+  const d = dayOf(day);
+  if (!d) return null;
+  return new Date(Date.parse(`${d}T00:00:00Z`) + n * MS_PER_DAY).toISOString().slice(0, 10);
+}
+
+/** Whole days from `a` to `b` (positive when `b` is later). Null when either is not a day. */
+export function daysBetween(a, b) {
+  const x = dayOf(a);
+  const y = dayOf(b);
+  if (!x || !y) return null;
+  return Math.round((Date.parse(`${y}T00:00:00Z`) - Date.parse(`${x}T00:00:00Z`)) / MS_PER_DAY);
+}
+
+/** Today in UTC, `YYYY-MM-DD`. */
+export function todayUtc(now = new Date()) {
+  return now.toISOString().slice(0, 10);
+}
+
+/**
+ * The read date an epic is held to: the one written (or ship day, if it passed before shipping), else — only for a SHIPPED epic that HAS a target — 30 days after
+ * shipping, marked derived. An epic with no target has no read date (it can still be read by hand), so the 54 epics
+ * shipped before the result record existed are never due (the no-backfill rule).
+ */
+export function readDateOf({ readDate, targetMetric, shippedAt }) {
+  // A day written at grooming that passes before the epic ships is read on ship day (codex review, #290): there was
+  // nothing out there to read before then, and "overdue since before release" would be a false alarm.
+  const shipped = dayOf(shippedAt);
+  if (isDay(readDate))
+    return { readDate: shipped && readDate < shipped ? shipped : readDate, derived: false };
+  if (!targetMetric || !dayOf(shippedAt)) return { readDate: null, derived: false };
+  return { readDate: addDays(shippedAt, READ_DEFAULT_DAYS), derived: true };
+}
+
+/** Whether a verdict written on `verdictAt` is late: more than 90 days after shipping. False when either is unknown. */
+export function isLate({ verdictAt, shippedAt }) {
+  const days = daysBetween(shippedAt, verdictAt);
+  return days !== null && days > READ_CAP_DAYS;
+}
+
+/**
+ * Whether a read is due today: a shipped epic with a target, no verdict yet, and a read date that has arrived. An epic
+ * not yet shipped is never due, even past a read date written at grooming: there is nothing out there to read.
+ */
+export function isReadDue({ targetMetric, verdict, readDate, shipped }, today = todayUtc()) {
+  if (!shipped || !targetMetric || verdict || !isDay(readDate)) return false;
+  return today >= readDate;
+}

package/dist/lib/roadmap-contract.mjs

@@ -55,6 +55,91 @@ export const FINOPS_FIELDS = [
   'actual_basis',
 ];
 
+// result-record D1/D2 — the result record: what an epic should move (written at grooming) and its verdict (written at
+// the read), declared ONCE here. All optional: no target is "no target", never an error. Dates are calendar days.
+export const VERDICTS = ['proven', 'disproven', 'unclear'];
+export const TARGET_FIELDS = ['hypothesis', 'target_metric', 'target_from', 'target_to', 'read_date'];
+export const VERDICT_FIELDS = ['verdict', 'verdict_actual', 'verdict_evidence', 'verdict_at'];
+export const RESULT_FIELDS = [...TARGET_FIELDS, ...VERDICT_FIELDS];
+export const RESULT_NUMERIC_FIELDS = ['target_from', 'target_to', 'verdict_actual'];
+export const RESULT_DAY_FIELDS = ['read_date', 'verdict_at'];
+export const RESULT_TEXT_FIELDS = ['hypothesis', 'target_metric', 'verdict_evidence'];
+
+// D2 — what proven or disproven must point at, checked offline as syntax only: a link, a North Star input's reading
+// on a day, or an experiment's A/B decision record. Keys are the platform's own shape (lowercase, digits, _ . -).
+// Case-SENSITIVE on purpose (codex review, #290): with `/i`, `HTTPS:///` matched here and then skipped the URL parse
+// below, which keys on the lowercase scheme. Keys take either case; the scheme and prefixes are lowercase.
+export const EVIDENCE_POINTER_RE =
+  /^(?:https:\/\/\S+|north-star:[A-Za-z0-9][A-Za-z0-9_.-]*@\d{4}-\d{2}-\d{2}|ab:[A-Za-z0-9][A-Za-z0-9_.-]*)$/;
+
+// Zero dependencies is load-bearing: projects and fixtures copy this file on its own. So the day check lives here and
+// `result-dates.mjs` imports it, not the other way round.
+/** Whether `v` is a real calendar day written `YYYY-MM-DD` (`2026-02-30` is not), read in UTC. */
+export function isDay(v) {
+  if (typeof v !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(v)) return false;
+  const d = new Date(`${v}T00:00:00Z`);
+  return !Number.isNaN(d.getTime()) && d.toISOString().slice(0, 10) === v;
+}
+
+/** Whether `v` is an evidence pointer (D2). A `north-star:` pointer's day must be a real calendar day. */
+export function isEvidencePointer(v) {
+  if (typeof v !== 'string' || !EVIDENCE_POINTER_RE.test(v.trim())) return false;
+  const t = v.trim();
+  // A link must PARSE (codex review, #290): the regex alone lets `https:///` through. The WHATWG parser refuses an
+  // https URL with no host, so a successful parse is the whole check — the scheme was already matched above.
+  if (t.startsWith('https://')) {
+    try {
+      new URL(t);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  const day = /@(\d{4}-\d{2}-\d{2})$/.exec(t)?.[1];
+  return !day || isDay(day);
+}
+
+/** The result-record fields of an epic's frontmatter data → offenses (`contract-result-invalid`). Absent is fine. */
+export function validateResultFields(fm) {
+  const offenses = [];
+  const bad = (detail) => offenses.push({ rule: 'contract-result-invalid', detail });
+  const has = (key) => fm[key] !== undefined && fm[key] !== null;
+  for (const key of RESULT_NUMERIC_FIELDS)
+    if (has(key) && (typeof fm[key] !== 'number' || !Number.isFinite(fm[key])))
+      bad(`${key}: "${fm[key]}" is not a number (or null)`);
+  for (const key of RESULT_DAY_FIELDS)
+    if (has(key) && !isDay(fm[key])) bad(`${key}: "${fm[key]}" is not a day written YYYY-MM-DD (or null)`);
+  for (const key of RESULT_TEXT_FIELDS)
+    if (has(key) && (typeof fm[key] !== 'string' || !fm[key].trim())) bad(`${key}: "${fm[key]}" is not text (or null)`);
+  // A target is the three together — which number, from what, to what (fresh review, #290): from/to or a read date
+  // with no metric would never come due (everything keys off target_metric), and a metric with no numbers has no
+  // direction to judge. A hypothesis on its own is allowed: a sentence is not a target.
+  const targetKeys = ['target_metric', 'target_from', 'target_to', 'read_date'];
+  if (targetKeys.some(has)) {
+    for (const key of ['target_metric', 'target_from', 'target_to'])
+      if (!has(key)) bad(`a target needs target_metric, target_from and target_to together — ${key} is missing`);
+  }
+  if (has('target_from') && has('target_to') && fm.target_from === fm.target_to)
+    bad(`target_from and target_to are both ${fm.target_from}: a target has to move the number`);
+  if (has('verdict') && !VERDICTS.includes(fm.verdict))
+    bad(`verdict: "${fm.verdict}" is not one of ${VERDICTS.join(' | ')}`);
+  if (!has('verdict')) {
+    for (const key of VERDICT_FIELDS.slice(1)) if (has(key)) bad(`${key} is set but there is no verdict`);
+  } else {
+    if (!has('verdict_at')) bad('a verdict needs verdict_at (the day it was read)');
+    if (!has('verdict_evidence')) bad('a verdict needs verdict_evidence (a pointer, or for unclear, the reason)');
+    if (fm.verdict === 'proven' || fm.verdict === 'disproven') {
+      if (!has('verdict_actual')) bad(`verdict: ${fm.verdict} needs verdict_actual (the number that was read)`);
+      if (has('verdict_evidence') && !isEvidencePointer(fm.verdict_evidence))
+        bad(
+          `verdict: ${fm.verdict} needs evidence that points somewhere: an https:// link, ` +
+            `north-star:<input>@YYYY-MM-DD or ab:<experiment>, not "${fm.verdict_evidence}"`
+        );
+    }
+  }
+  return offenses;
+}
+
 // live-build-view D10 — `locked_at:` is stamped by `scripts/epic-phase.mjs lock` when the architecture lock is written;
 // the build view reads its absence as "Locking architecture". Optional (no epic before it has one), an ISO date-time
 // string when present: the command writes `"2026-10-03T20:34:34Z"` (quoted, so the frontmatter parser keeps the colons).
@@ -269,6 +354,7 @@ export function validateEpicFrontmatter(parsed, ctx = {}) {
       offenses.push({ rule: 'contract-total-invalid', detail: `${key}: "${fm[key]}" is not a whole number` });
   }
   offenses.push(...validateFinopsFields(fm));
+  offenses.push(...validateResultFields(fm));
   offenses.push(...validateLockedAt(fm));
   if (isInt(fm.sprints_total) && isInt(ctx.sprintCount) && fm.sprints_total !== ctx.sprintCount)
     offenses.push({

package/dist/roadmap-extract.mjs

@@ -68,7 +68,15 @@ 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 {
+  FINOPS_FIELDS,
+  FINOPS_NUMERIC_FIELDS,
+  RESULT_DAY_FIELDS,
+  RESULT_FIELDS,
+  RESULT_NUMERIC_FIELDS,
+  VERDICTS,
+} from './lib/roadmap-contract.mjs';
+import { isDay, isLate, readDateOf } from './lib/result-dates.mjs';
 import { pushRoadmap, reportPush } from './roadmap-push.mjs';
 
 const REPO = projectRoot(); // D2 — the CLI's default root; buildRows takes its own
@@ -120,6 +128,39 @@ export function finopsFields(fm) {
   return out;
 }
 
+/**
+ * result-record D5 — an epic's target and verdict, off its README frontmatter, plus what is DERIVED from them: the
+ * default read date (30 days after shipping, only for a shipped epic that has a target) and whether a verdict came
+ * late (more than 90 days after shipping). Derived here and labelled, never written back into the README. A value
+ * that does not read as its type is null (doc-format names it); a number is never invented as 0.
+ */
+export function resultFields(fm, shippedAt) {
+  const out = {};
+  for (const key of RESULT_FIELDS) {
+    const raw = fm[key];
+    const blank = raw === null || raw === undefined || raw === '' || raw === 'null' || raw === '~';
+    if (RESULT_NUMERIC_FIELDS.includes(key)) {
+      // A numeral or a number, nothing else (codex review, #290): `Number(' ')` is 0 and `Number(true)` is 1.
+      const numeral = typeof raw === 'string' && /^-?\d+(?:\.\d+)?$/.test(raw.trim());
+      const n = typeof raw === 'number' ? raw : numeral ? Number(raw) : NaN;
+      out[key] = !blank && Number.isFinite(n) ? n : null;
+    } else if (RESULT_DAY_FIELDS.includes(key)) out[key] = isDay(raw) ? raw : null;
+    else if (key === 'verdict') out[key] = VERDICTS.includes(raw) ? raw : null;
+    else out[key] = !blank && typeof raw === 'string' ? raw : null;
+  }
+  // A target is the three together (D1): a metric with no numbers gets no derived read date (codex review, #290).
+  const complete = out.target_metric !== null && out.target_from !== null && out.target_to !== null;
+  const { readDate, derived } = readDateOf({
+    readDate: out.read_date,
+    targetMetric: complete ? out.target_metric : null,
+    shippedAt,
+  });
+  out.read_date = readDate;
+  out.read_date_derived = derived;
+  out.read_late = out.verdict ? isLate({ verdictAt: out.verdict_at, shippedAt }) : false;
+  return out;
+}
+
 function parseFrontmatter(md) {
   if (!md.startsWith('---')) return {};
   const end = md.indexOf('\n---', 3);
@@ -576,6 +617,7 @@ export function buildRows({
       kickoff,
       shipped_at: stage === 'Shipped' ? statusDay : null,
       ...finopsFields(epicFm),
+      ...resultFields(epicFm, stage === 'Shipped' ? statusDay : null),
     });
 
     // Sprint rows (one per sprint-N.md), related to the Epic by slug. boardSprints already carries

package/dist/session-resume.mjs

@@ -61,6 +61,8 @@ import {
   JOURNAL_PATH,
 } from './lib/session-journal.mjs';
 import { loadReportingConfig, ReportingConfigError } from './lib/reporting-config.mjs';
+import { isReadDue, todayUtc } from './lib/result-dates.mjs';
+import { buildRows } from './roadmap-extract.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const DEFAULT_ROOT = join(__dirname, '..');
@@ -495,7 +497,52 @@ export function readMemoryIndex(cwd = process.cwd(), deps = {}) {
   }
 }
 
-export function buildAnomalies({ repoStates, migrationResults, expandOrphans = false, memoryIndex }) {
+// result-record D9 — a read that is due is something to act on before anything else, so it rides the anomaly list:
+// one line per epic, from the docs alone (no network), gone as soon as its verdict is written into the README.
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+export function decideReadsDue(rows, today = todayUtc()) {
+  return (rows || [])
+    .filter(
+      (r) =>
+        r.grain === 'Epic' &&
+        // A target is metric + from + to together (D1); a partial one is never due.
+        r.target_from != null &&
+        r.target_to != null &&
+        isReadDue(
+          {
+            targetMetric: r.target_metric,
+            verdict: r.verdict,
+            readDate: r.read_date,
+            shipped: r.stage === 'Shipped',
+          },
+          today
+        )
+    )
+    .sort((a, b) => a.read_date.localeCompare(b.read_date) || a.slug.localeCompare(b.slug))
+    .map((r) => ({
+      type: 'read-due',
+      detail: `Read due: ${r.name} · since ${Number(r.read_date.slice(8, 10))} ${MONTHS[Number(r.read_date.slice(5, 7)) - 1]} · run node scripts/epic-read.mjs --epic ${r.slug}`,
+    }));
+}
+
+/** The roadmap rows the reads-due check reads, docs only. A failure is a gap, never a silent "nothing due". */
+export function gatherRoadmapRows({ root, buildRowsFn = buildRows, existsSyncFn = existsSync }) {
+  // A project with no Roadmap/ has nothing to read: no gap on every run (fresh review, #291).
+  if (!existsSyncFn(join(root, 'Roadmap'))) return { available: true, rows: [] };
+  try {
+    return { available: true, rows: buildRowsFn({ root, facts: { mode: 'docs', prs: [], branches: [] } }) };
+  } catch (e) {
+    return { available: false, rows: [], reason: e.message };
+  }
+}
+
+export function buildAnomalies({
+  repoStates,
+  migrationResults,
+  expandOrphans = false,
+  memoryIndex,
+  readsDue = [],
+}) {
   const anomalies = [];
   // First, because it is the one anomaly that changes what the rest of this report is
   // worth: if the index is truncating, the session is missing facts it does not know it
@@ -504,6 +551,8 @@ export function buildAnomalies({ repoStates, migrationResults, expandOrphans = f
     const mem = decideMemoryBudgetAnomaly(memoryIndex);
     if (mem) anomalies.push(mem);
   }
+  // result-record D9 — a due read leads the rest: it is the one line here that asks for a decision, not a cleanup.
+  anomalies.push(...readsDue);
   for (const rs of repoStates || []) {
     if (rs.git?.available) {
       const openPrs = rs.gh?.available ? rs.gh.open : undefined; // undefined → decideStrayBranch treats as "unknown"
@@ -531,8 +580,15 @@ export function buildAnomalies({ repoStates, migrationResults, expandOrphans = f
 // D4: names every degraded source instead of silently dropping it. A missing repo path, an
 // unauthenticated/unreachable gh, an unavailable migration check, and an empty/unfetchable journal all
 // land here — distinct from `buildAnomalies`, which only reports CONFIRMED surprising states.
-export function buildGaps({ repoStates, migrationResults, journalAvailable, journalReason }) {
+export function buildGaps({
+  repoStates,
+  migrationResults,
+  journalAvailable,
+  journalReason,
+  roadmapReason = null,
+}) {
   const gaps = [];
+  if (roadmapReason) gaps.push(`reads due unknown — the roadmap could not be read: ${roadmapReason}.`);
   for (const rs of repoStates || []) {
     if (!rs.git?.available)
       gaps.push(`${rs.repo}: git state unavailable — ${rs.git?.reason || 'unknown reason'}.`);
@@ -570,12 +626,14 @@ export function buildReport({
   journalLimit = JOURNAL_LIMIT_DEFAULT,
   expandOrphans = false,
   memoryIndex,
+  readsDue = [],
+  roadmapReason = null,
   generatedAt,
 }) {
   return {
     generatedAt: generatedAt || new Date().toISOString(),
-    anomalies: buildAnomalies({ repoStates, migrationResults, expandOrphans, memoryIndex }),
-    gaps: buildGaps({ repoStates, migrationResults, journalAvailable, journalReason }),
+    anomalies: buildAnomalies({ repoStates, migrationResults, expandOrphans, memoryIndex, readsDue }),
+    gaps: buildGaps({ repoStates, migrationResults, journalAvailable, journalReason, roadmapReason }),
     journal: {
       available: journalAvailable,
       reason: journalAvailable ? null : journalReason || null,
@@ -860,6 +918,7 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
     now,
     resolveReposFn = resolveRepos,
     gatherFactsFn = gatherFacts,
+    buildRowsFn = buildRows,
   } = deps;
 
   let args;
@@ -904,6 +963,7 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
       spawn,
     });
     const journal = gatherJournal({ root: args.root, readLogFromBranchFn });
+    const roadmap = gatherRoadmapRows({ root: args.root, buildRowsFn });
 
     const report = buildReport({
       repoStates,
@@ -914,6 +974,8 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
       journalLimit: args.journalLimit,
       expandOrphans: args.expandOrphans,
       memoryIndex: readMemoryIndex(args.root, { stat: statFn, home: homeDir }),
+      readsDue: decideReadsDue(roadmap.rows, todayUtc(now || new Date())),
+      roadmapReason: roadmap.available ? null : roadmap.reason,
       generatedAt: (now || new Date()).toISOString(),
     });
 

package/package.json

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