@golden-frijoles/kit 0.32.0 → 0.34.0

package/dist/epic-read.mjs

@@ -1,12 +1,14 @@
 #!/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>                               # fetches the number through gf, drafts
+//   node scripts/epic-read.mjs --epic <slug> --experiment smart-defaults   # … and cites the A/B decision record
 //   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
+//   options: --project <slug> (gf's; default: the remembered one) · --today YYYY-MM-DD (default: today, UTC)
+//            · --repo-root <dir> · --json · GF_BIN=<path to gf> (default: gf on PATH)
 //
 // ── The shape (result-record D8) ─────────────────────────────────────────────────────────────────────────────────
 // The agent does the legwork, the owner decides. Without `--write` this prints a draft and the exact command that
@@ -22,15 +24,19 @@
 //   • 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.
-//
+// ── The agent fetches the number (result-record S3, D17) ─────────────────────────────────────────────────────────
+// With a target and no `--actual`, this runs `gf north-star readings <target_metric> --to <today> --json` and takes
+// `latest`: the actual is its value, the evidence `north-star:<input>@<its day>`. A reading dated before the epic shipped
+// is no evidence for it. `--experiment <key>` also runs `gf experiments decision <key> --json`; a recorded decision
+// becomes the evidence, `ab:<key>`. gf is spawned without a shell (`$GF_BIN`, else `gf` on PATH), so a shell alias of
+// the same name never applies. `--actual` / `--evidence` still win: they are the owner's word. No gf, not signed in, no
+// project chosen, or any failure is one "could not fetch (why)" line, and the read asks the owner as before — it never
+// fails because the platform is not linked. Grounded is now "the readings route knows this input".
+
 // Zero deps — Node 18+.
 import { existsSync, readFileSync, readdirSync, realpathSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { projectRoot } from './lib/project-root.mjs';
 import {
@@ -39,10 +45,9 @@ import {
   parseDocFrontmatter,
   validateResultFields,
 } from './lib/roadmap-contract.mjs';
-import { READ_CAP_DAYS, isLate, readDateOf, todayUtc, isDay } from './lib/result-dates.mjs';
+import { READ_CAP_DAYS, addDays, dayOf, 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`. */
@@ -133,41 +138,90 @@ export function planRead({ fm, shippedAt, shipped, today, actual = null, evidenc
   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)' };
+/** Run one `gf … --json` and read its single JSON document. Never throws; `why` says what went wrong in words. */
+export function runGf(args, { env = process.env, spawnFn = spawnSync } = {}) {
+  const bin = env.GF_BIN || 'gf';
+  const res = spawnFn(bin, [...args, '--json'], { encoding: 'utf8', timeout: 30_000, env, shell: false });
+  if (res.error)
+    return {
+      ok: false,
+      why:
+        res.error.code === 'ENOENT'
+          ? 'gf is not installed (npm i -g @golden-frijoles/cli, then gf login)'
+          : `gf did not run: ${res.error.message}`,
+    };
+  let body = null;
   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}` };
+    body = JSON.parse(res.stdout || 'null');
+  } catch {
+    body = null;
   }
+  if (body && body.ok === true) return { ok: true, body };
+  if (res.status === 2) return { ok: false, code: 'unauthorized', why: 'gf is not signed in (run gf login)' };
+  const code = body?.code ?? null;
+  return { ok: false, code, why: body?.error ?? `gf exited ${res.status}` };
+}
+
+/**
+ * The number and its evidence, fetched through gf (D17). Pure apart from the injected `run`.
+ * Returns `{ fetched, actual?, evidence?, reading?, decision?, grounded, why? }`.
+ */
+export function fetchEvidence({ metric, experiment = null, today, shippedAt, project = null, run }) {
+  const scope = project ? ['--project', project] : [];
+  const out = { fetched: false, grounded: null };
+  const readings = run(['north-star', 'readings', metric, '--to', today, ...scope]);
+  if (!readings.ok) {
+    // `not_found` is also what an unknown or foreign PROJECT answers; only the input's own sentence means "not grounded".
+    if (readings.code === 'not_found' && /No North Star input/.test(readings.why ?? '')) out.grounded = false;
+    out.why = readings.why;
+  } else {
+    out.grounded = true;
+    const latest = readings.body.latest;
+    const shipped = dayOf(shippedAt);
+    if (!latest) out.why = `no reading of ${metric} yet`;
+    else if (shipped && latest.date < shipped)
+      out.why = `no reading of ${metric} since it shipped (the latest is ${latest.date})`;
+    else {
+      out.fetched = true;
+      out.reading = latest;
+      out.actual = latest.value;
+      out.evidence = `north-star:${metric}@${latest.date}`;
+    }
+  }
+  if (experiment) {
+    const decision = run(['experiments', 'decision', experiment, ...scope]);
+    if (decision.ok && decision.body.decisions?.state === 'decided') {
+      out.decision = decision.body.decisions.current;
+      out.evidence = `ab:${experiment}`; // the decision record is the stronger pointer; the reading stays the actual
+    } else if (decision.ok) out.decisionWhy = `${experiment} has no decision recorded yet`;
+    else out.decisionWhy = decision.why;
+  }
+  return out;
 }
 
 /** The text a person reads. Pure. */
-export function renderPlan(plan, { slug, grounded, write, written }) {
+export function renderPlan(plan, { slug, fetched, 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)
+  if (fetched) {
+    if (fetched.grounded === true)
+      out.push(`  grounded: ${t.metric} is one of the project's North Star inputs`);
+    if (fetched.grounded === false)
+      out.push(`  not grounded: ${t.metric} is not one of the project's North Star inputs`);
+    if (fetched.fetched)
+      out.push(
+        `  fetched:  ${fig(fetched.reading.value)} on ${longDay(fetched.reading.date)} (gf north-star readings)`
+      );
+    else if (fetched.why) out.push(`  could not fetch the number: ${fetched.why}`);
+    if (fetched.decision)
       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'})`
+        `  decision: ${fetched.decision.outcome ?? 'recorded'}${fetched.decision.chosenVariantKey ? ` (${fetched.decision.chosenVariantKey})` : ''} (gf experiments decision)`
       );
-    else if (t.metric) out.push(`  could not check the metric against the North Star (${grounded.why})`);
+    else if (fetched.decisionWhy) out.push(`  decision: ${fetched.decisionWhy}`);
   }
   switch (plan.state) {
     case 'already-read':
@@ -236,7 +290,7 @@ const arg = (argv, name) => {
   return i === -1 ? null : (argv[i + 1] ?? null);
 };
 
-export async function main(argv, { fetchFn = fetch, env = process.env, stdout = process.stdout } = {}) {
+export async function main(argv, { spawnFn = spawnSync, env = process.env, stdout = process.stdout } = {}) {
   const slug = arg(argv, '--epic');
   if (!slug) {
     process.stderr.write('epic-read: --epic <slug> is required\n');
@@ -268,24 +322,41 @@ export async function main(argv, { fetchFn = fetch, env = process.env, stdout =
   const row = buildRows({ root, facts: { mode: 'docs', prs: [], branches: [] } }).find(
     (r) => r.grain === 'Epic' && r.slug === slug
   );
-  const plan = planRead({
+  const shippedAt = row?.shipped_at ?? null;
+  const evidenceFlag = arg(argv, '--evidence');
+  const base = {
     fm: parsed.data,
-    shippedAt: row?.shipped_at ?? null,
+    shippedAt,
     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,
-        });
+  };
+  let plan = planRead({ ...base, actual, evidence: evidenceFlag });
+  // D17 — fetch only when there is a read to make and the owner has not given the number: never before the read date,
+  // never for an epic already read or not shipped, never over the owner's own --actual.
+  let fetched = null;
+  const readable = !['already-read', 'not-shipped', 'not-due'].includes(plan.state);
+  // The owner's word wins: a number (--actual), a reason or pointer (--evidence) or a verdict (--verdict) means the
+  // owner has answered, and a fetched number must not overrule them (fresh review, #293).
+  const ownerAnswered = actual !== null || evidenceFlag !== null || base.verdict !== null;
+  if (readable && plan.target.metric && !ownerAnswered) {
+    fetched = fetchEvidence({
+      metric: plan.target.metric,
+      experiment: arg(argv, '--experiment'),
+      // Complete days only: today's telemetry count is a partial day (fresh review, #293).
+      today: addDays(today, -1),
+      shippedAt,
+      project: arg(argv, '--project'),
+      run: (args) => runGf(args, { env, spawnFn }),
+    });
+    // Only a reading is a number to draft from; a decision on its own only names the pointer for the owner to confirm.
+    if (fetched.fetched)
+      plan = planRead({
+        ...base,
+        actual: fetched.actual ?? null,
+        evidence: evidenceFlag ?? fetched.evidence ?? null,
+      });
+  }
   const write = argv.includes('--write');
   let written = null;
   if (write && plan.state === 'ready') {
@@ -297,16 +368,16 @@ export async function main(argv, { fetchFn = fetch, env = process.env, stdout =
       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`
+          ? `${JSON.stringify({ slug, ...refused, fetched, written: null })}\n`
+          : `${renderPlan(refused, { slug, fetched, 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 (argv.includes('--json')) stdout.write(`${JSON.stringify({ slug, ...plan, fetched, written })}\n`);
+  else stdout.write(`${renderPlan(plan, { slug, fetched, 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;

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

@@ -54,10 +54,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-10-06 against 1.3.0.
+// agy-doctor: last verified 2026-10-07 against 1.3.1.
 //   ^ 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.3.0';
+export const AGY_PINNED = '1.3.1';
 
 // 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/roadmap-contract.mjs

@@ -140,6 +140,25 @@ export function validateResultFields(fm) {
   return offenses;
 }
 
+// one-epic-page D11 — the epic's flag, decided at groom Stage 6b and copied into the README by the scaffold. The SDK's
+// flag-key grammar (`FLAG_KEY` in apps/web/lib/flag-admin-operation.ts). Optional: `flag_key: null` (no flag) is the
+// default and never an error; a value that is not a key is named, never pushed (the extract sends null for it).
+export const FLAG_KEY_RE = /^[a-z][a-z0-9_.-]{0,127}$/;
+
+/** `flag_key:` → offenses (`contract-flag-key-invalid`). Absent or null is fine. */
+export function validateFlagKey(fm) {
+  const v = fm.flag_key;
+  if (v === undefined || v === null) return [];
+  // The string "null" fits the grammar but means "no flag": named here as the push schema refuses it (codex, #297).
+  if (typeof v === 'string' && v !== 'null' && FLAG_KEY_RE.test(v)) return [];
+  return [
+    {
+      rule: 'contract-flag-key-invalid',
+      detail: `flag_key: "${v}" is not a flag key (a lowercase letter, then a-z 0-9 _ . -; at most 128) — or null`,
+    },
+  ];
+}
+
 // 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).
@@ -355,6 +374,7 @@ export function validateEpicFrontmatter(parsed, ctx = {}) {
   }
   offenses.push(...validateFinopsFields(fm));
   offenses.push(...validateResultFields(fm));
+  offenses.push(...validateFlagKey(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

@@ -73,6 +73,7 @@ import {
   FINOPS_NUMERIC_FIELDS,
   RESULT_DAY_FIELDS,
   RESULT_FIELDS,
+  FLAG_KEY_RE,
   RESULT_NUMERIC_FIELDS,
   VERDICTS,
 } from './lib/roadmap-contract.mjs';
@@ -161,6 +162,21 @@ export function resultFields(fm, shippedAt) {
   return out;
 }
 
+/**
+ * one-epic-page D11 — an epic's flag: `flag_key` off its README frontmatter (the SDK's key grammar, else null — the
+ * contract names a bad one) and `flag_note`, the README's own `**Flag:** …` line, which is where an epic with no flag
+ * says why. Both null when absent; nothing is inferred from prose about a flag the frontmatter does not name.
+ */
+export function flagFields(fm, readme) {
+  const raw = typeof fm.flag_key === 'string' ? fm.flag_key.trim() : '';
+  // A QUOTED `flag_key: "null"` (or `~`) arrives as a string, and "null" fits the key grammar — so the blank
+  // spellings are refused before the pattern is asked. (Unquoted `null` is already null from this file's reader.)
+  const blank = raw === '' || raw === 'null' || raw === '~';
+  const line = /^\*\*Flag:\*\*[ \t]*(.+)$/m.exec(readme ?? '');
+  const note = line ? line[1].replace(/[*`]/g, '').trim().slice(0, 280) : '';
+  return { flag_key: !blank && FLAG_KEY_RE.test(raw) ? raw : null, flag_note: note || null };
+}
+
 function parseFrontmatter(md) {
   if (!md.startsWith('---')) return {};
   const end = md.indexOf('\n---', 3);
@@ -583,6 +599,7 @@ export function buildRows({
       }
     }
 
+    const readme = readFileSync(join(e.path, 'README.md'), 'utf8');
     // Epic row
     rows.push({
       name: epicTitle(e.path, e.slug),
@@ -605,7 +622,7 @@ export function buildRows({
       build_order_num: buildOrderNum(buildOrder),
       doc_link: readmePath,
       epic_slug: null,
-      goal: firstParagraph(readFileSync(join(e.path, 'README.md'), 'utf8'), ['Why', 'Goal', 'Problem']),
+      goal: firstParagraph(readme, ['Why', 'Goal', 'Problem']),
       sprints: boardSprints.map((sp) => ({ n: sp.n, title: sp.title, done: sp.done, total: sp.total })),
       links: {
         readme: readmePath,
@@ -618,6 +635,7 @@ export function buildRows({
       shipped_at: stage === 'Shipped' ? statusDay : null,
       ...finopsFields(epicFm),
       ...resultFields(epicFm, stage === 'Shipped' ? statusDay : null),
+      ...flagFields(epicFm, readme),
     });
 
     // 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.32.0",
+  "version": "0.34.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": {