@golden-frijoles/kit 0.30.0 → 0.31.0

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/package.json

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