@golden-frijoles/kit 0.10.0 → 0.12.0

package/dist/intent-match.mjs

@@ -121,6 +121,18 @@ export const INTENT_QUESTIONS = Object.freeze({
       'Yes: it names the action, where to do it and the exact result to observe, so two testers would agree.',
     ],
   },
+  agreement: {
+    // Asked by intent-reader.mjs at the architecture lock (D16), once per epic, only when `intent.reader` is on.
+    // Not measured: there is no labelled set of reader replies yet. Its answer is one signal among five, advisory.
+    type: 'noul',
+    instructions:
+      '`plan` is the architecture lock a builder wrote for this work. `reading` is what a second reader, given only the pitch, says they would build, would not build, and would ask first. Would the two of them build the same thing?',
+    criteria: {
+      true: 'Yes: the reading describes the same product and the same scope as the plan; the differences are wording, order, or detail the plan already settles.',
+      false:
+        'No: the reading would build something the plan does not, leave out something the plan builds, or its first question exposes a decision the plan has not made.',
+    },
+  },
   route: {
     type: 'choice',
     instructions:
@@ -150,6 +162,13 @@ export const INTENT_QUESTIONS = Object.freeze({
 
 const FRONTMATTER_RE = /^---\n[\s\S]*?\n---\n?/;
 
+/**
+ * A fence line, by CommonMark's rule: at most THREE spaces of indent. A line indented four or more is code, never a
+ * fence — and the reader writes its reply indented, so a `\s*` here let an odd fence line in a reply flip the scanner
+ * and make the next write delete every section after `## Intent match` (fresh review round 2, #197).
+ */
+export const FENCE_RE = /^ {0,3}(```|~~~)/;
+
 /** Flat frontmatter → { key: value } (comment-stripped, quotes stripped). The same rule epic-dod uses. */
 export function frontmatterOf(text) {
   const m = /^---\n([\s\S]*?)\n---/.exec(String(text));
@@ -167,7 +186,7 @@ export function sections(body) {
   const out = [{ heading: null, lines: [] }];
   let fence = false;
   for (const line of String(body).split('\n')) {
-    if (/^\s*(```|~~~)/.test(line)) fence = !fence;
+    if (FENCE_RE.test(line)) fence = !fence;
     if (!fence && /^## /.test(line)) out.push({ heading: line.slice(3).trim(), lines: [] });
     else out.at(-1).lines.push(line);
   }
@@ -184,7 +203,7 @@ export function listItems(lines, { numbered = false } = {}) {
   const top = numbered ? /^(\d+)[.)]\s+(.*)$/ : /^(?:[-*+]|\d+[.)])\s+(.*)$/;
   let fence = false;
   for (const raw of lines) {
-    if (/^\s*(```|~~~)/.test(raw)) {
+    if (FENCE_RE.test(raw)) {
       fence = !fence;
       continue;
     }
@@ -450,6 +469,24 @@ export function componentsOf(result) {
   return Object.fromEntries(Object.entries(result.signals).map(([k, v]) => [k, round(v)]));
 }
 
+/**
+ * The components a `--write` stored in a seed's `<!-- intent-match: {…} -->` comment, or null. Pure. Only unit
+ * numbers survive, so a hand-edited comment can never smuggle a non-number into a total.
+ */
+export function componentsFrom(text) {
+  const m = /<!-- intent-match: (\{[^\n]*?\}) -->/.exec(String(text ?? ''));
+  if (!m) return null;
+  let raw;
+  try {
+    raw = JSON.parse(m[1]);
+  } catch {
+    return null;
+  }
+  const out = {};
+  for (const k of Object.keys(SIGNAL_NAMES)) if (isUnit(raw?.[k])) out[k] = raw[k];
+  return Object.keys(out).length ? out : null;
+}
+
 /** The `## Intent match` section `--write` puts in the seed. Pure. */
 export function intentSection(result, opts = {}) {
   return [
@@ -466,34 +503,29 @@ export function intentSection(result, opts = {}) {
   ].join('\n');
 }
 
-/**
- * Put the score into the seed text. Pure. `intent_match:` goes into the frontmatter (replaced, or added before the
- * closing fence), `intent_ask: verbatim` is added when the seed has an ask and no `intent_ask:` yet, and
- * `## Intent match` replaces any earlier one or is appended.
- */
-export function writeIntoSeed(text, result, opts = {}) {
-  let src = String(text);
+/** Set `key: value` in a document's frontmatter — replaced, or added before the closing fence. Pure. */
+export function setFrontmatterKey(text, key, value, { onlyIfAbsent = false } = {}) {
+  const src = String(text);
   const fm = FRONTMATTER_RE.exec(src);
-  if (fm) {
-    let block = fm[0];
-    const set = (key, value, { onlyIfAbsent = false } = {}) => {
-      const re = new RegExp(`^${key}:.*$`, 'm');
-      if (re.test(block)) {
-        if (!onlyIfAbsent) block = block.replace(re, `${key}: ${value}`);
-      } else block = block.replace(/\n---\n?$/, `\n${key}: ${value}\n---\n`);
-    };
-    set('intent_match', result.total);
-    if (opts.hasAsk) set('intent_ask', 'verbatim', { onlyIfAbsent: true });
-    src = block + src.slice(fm[0].length);
-  }
-  const section = intentSection(result, opts);
+  if (!fm) return src;
+  let block = fm[0];
+  const re = new RegExp(`^${key}:.*$`, 'm');
+  if (re.test(block)) {
+    if (!onlyIfAbsent) block = block.replace(re, `${key}: ${value}`);
+  } else block = block.replace(/\n---\n?$/, `\n${key}: ${value}\n---\n`);
+  return block + src.slice(fm[0].length);
+}
+
+/** Replace the `## Intent match` section (up to the next `## `), or append it. Pure. */
+export function upsertIntentSection(text, section) {
+  const src = String(text);
   const lines = src.split('\n');
   // Fence-aware, like sections(): a `## Intent match` inside a code block is an example, and treating it as the
   // section deleted everything up to the next heading, closing fence included (fresh review of #196).
   const headingAt = [];
   let fence = false;
   lines.forEach((l, i) => {
-    if (/^\s*(```|~~~)/.test(l)) fence = !fence;
+    if (FENCE_RE.test(l)) fence = !fence;
     else if (!fence && /^## /.test(l)) headingAt.push(i);
   });
   const start = headingAt.find((i) => INTENT_HEADING.test(lines[i].slice(3).trim())) ?? -1;
@@ -504,6 +536,16 @@ export function writeIntoSeed(text, result, opts = {}) {
     .replace(/\n{3,}/g, '\n\n');
 }
 
+/**
+ * Put the score into the seed text. Pure. `intent_match:` goes into the frontmatter, `intent_ask: verbatim` is added
+ * when the seed has an ask and no `intent_ask:` yet, and `## Intent match` replaces any earlier one or is appended.
+ */
+export function writeIntoSeed(text, result, opts = {}) {
+  let src = setFrontmatterKey(text, 'intent_match', result.total);
+  if (opts.hasAsk) src = setFrontmatterKey(src, 'intent_ask', 'verbatim', { onlyIfAbsent: true });
+  return upsertIntentSection(src, intentSection(result, opts));
+}
+
 // ── The run, every side effect injected ───────────────────────────────────────────────────────────────────────
 
 const couldNotLook = (why) => ({ state: 'could-not-look', why });

package/dist/intent-outcomes.mjs

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+// intent-outcomes.mjs — does the intent score predict anything? One row per scored epic, across repos (intent-match
+// S3.2, D18).
+//
+//   node scripts/intent-outcomes.mjs                                  this repo
+//   node scripts/intent-outcomes.mjs --repo . --repo ../other-project  every repo on the same Roadmap layout
+//   node scripts/intent-outcomes.mjs --json                           the rows as JSON
+//
+// Each row joins three things, all read from files:
+//   the SCORE      the epic README's `intent_match:`, else its seed's, else the repo's backfill record
+//                  (`Roadmap/00-ideas/intent-backfill.json`, D19) — and whether the ask was verbatim or a proxy
+//   the ANSWER     the retrospective's `_Intent: yes | mostly | no_` — the product owner's word, the label
+//   CORRECTIONS    DERIVED, never self-reported: stories added after the scaffold (the README's `stories_total`
+//                  now vs. in the commit that added it), dated amendments (`Amended YYYY-MM-DD`), disproved scope
+//                  (`disprov…`). A plan that needed correcting is evidence the score can be checked against.
+//
+// The footer says how close the data is to the twenty answered epics the calibration waits for ("n of 20"). This
+// reports; it fits nothing (the intent-match no-go) and it gates nothing.
+//
+// git is only used to read the README as first committed. Its environment is SEALED (GIT_* stripped): run from a
+// hook in a linked worktree, an inherited GIT_DIR would point every `git -C <other repo>` at THIS repository.
+// Zero deps — Node 18+.
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { basename, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const CALIBRATION_N = 20;
+export const BACKFILL_PATH = join('Roadmap', '00-ideas', 'intent-backfill.json');
+
+/** Flat frontmatter, comment- and quote-stripped (the epic-dod rule). Pure. */
+export function frontmatter(text) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(String(text ?? ''));
+  const out = {};
+  if (!m) return out;
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = /^([A-Za-z_][\w-]*):\s*(.*?)\s*(?:#.*)?$/.exec(line);
+    if (kv) out[kv[1]] = kv[2].replace(/^["']|["']$/g, '');
+  }
+  return out;
+}
+
+const score = (v) => (/^\d{1,3}$/.test(String(v ?? '')) && Number(v) <= 100 ? Number(v) : null);
+
+/**
+ * The answer — the SAME rule as `epic-dod.mjs`'s `intentAnswer` (a spec pins the two together): comments stripped, a
+ * line that is exactly `_Intent: yes_` · `_mostly_` · `_no_`. Pure.
+ */
+export function intentAnswer(retro) {
+  const text = String(retro ?? '').replace(/<!--[\s\S]*?-->/g, '');
+  const m = /^_Intent:\s*(yes|mostly|no)\s*_\s*$/im.exec(text);
+  return m ? m[1].toLowerCase() : null;
+}
+
+/** Corrections derivable from the README alone. Pure. `firstReadme` is the README as first committed, or null. */
+export function corrections(readme, firstReadme) {
+  const now = Number(frontmatter(readme).stories_total);
+  const then = firstReadme == null ? NaN : Number(frontmatter(firstReadme).stories_total);
+  return {
+    storiesAdded: Number.isFinite(now) && Number.isFinite(then) ? Math.max(0, now - then) : null,
+    amendments: (String(readme).match(/\bAmended \d{4}-\d{2}-\d{2}\b/gi) ?? []).length,
+    disproved: (String(readme).match(/\bdisprov\w*/gi) ?? []).length,
+  };
+}
+
+/** The backfill record, or [] when there is none. A MALFORMED record throws: evidence tooling fails closed. */
+export function parseBackfill(text, where = BACKFILL_PATH) {
+  if (text == null) return [];
+  let json;
+  try {
+    json = JSON.parse(text);
+  } catch (e) {
+    throw new Error(`${where}: not JSON (${e.message})`);
+  }
+  if (!Array.isArray(json?.epics)) throw new Error(`${where}: needs an "epics" array`);
+  return json.epics.map((e, i) => {
+    if (typeof e?.slug !== 'string' || score(e.score) == null)
+      throw new Error(`${where}: epics[${i}] needs a slug and a whole-number score 0–100`);
+    return { slug: e.slug, score: Number(e.score), ask: e.ask === 'verbatim' ? 'verbatim' : 'proxy' };
+  });
+}
+
+/**
+ * One repo's rows. Pure over its inputs: epics = [{ slug, macro, readme, firstReadme, seed, retro }], backfill =
+ * parseBackfill(). Only SCORED epics get a row (D18).
+ */
+export function rowsFor(repo, epics, backfill = []) {
+  const back = new Map(backfill.map((b) => [b.slug, b]));
+  // A backfill slug with no epic folder (a typo, a renamed epic) would silently shrink the table: fail closed.
+  const known = new Set(epics.map((e) => e.slug));
+  const orphans = backfill.filter((b) => !known.has(b.slug)).map((b) => b.slug);
+  if (orphans.length)
+    throw new Error(
+      `${repo}: intent-backfill.json names epics with no Roadmap folder: ${orphans.join(', ')}`
+    );
+  const rows = [];
+  for (const e of epics) {
+    const rfm = frontmatter(e.readme);
+    const sfm = frontmatter(e.seed ?? '');
+    const b = back.get(e.slug);
+    const from =
+      score(rfm.intent_match) != null
+        ? 'readme'
+        : score(sfm.intent_match) != null
+          ? 'seed'
+          : b
+            ? 'backfill'
+            : null;
+    if (!from) continue;
+    const value =
+      from === 'readme' ? score(rfm.intent_match) : from === 'seed' ? score(sfm.intent_match) : b.score;
+    const ask =
+      from === 'backfill'
+        ? b.ask
+        : sfm.intent_ask === 'verbatim'
+          ? 'verbatim'
+          : sfm.intent_ask === 'proxy'
+            ? 'proxy'
+            : 'unknown';
+    const c = corrections(e.readme, e.firstReadme);
+    rows.push({
+      repo,
+      epic: e.slug,
+      macro: e.macro,
+      status: rfm.status ?? null,
+      score: value,
+      source: from,
+      ask,
+      answer: intentAnswer(e.retro),
+      ...c,
+      corrected: (c.storiesAdded ?? 0) + c.amendments + c.disproved > 0,
+    });
+  }
+  return rows;
+}
+
+/** The footer: how many rows are labelled, of the twenty the calibration waits for. Pure. */
+export function summary(rows, repoCount) {
+  const answered = rows.filter((r) => r.answer);
+  const proxy = answered.filter((r) => r.ask === 'proxy').length;
+  const waiting = rows.filter((r) => !r.answer && r.status === 'shipped').length;
+  return {
+    scored: rows.length,
+    answered: answered.length,
+    proxy,
+    waiting,
+    line:
+      `${answered.length} of ${CALIBRATION_N}: ${answered.length} scored epic(s) answered (${proxy} with a proxy ask), ` +
+      `${rows.length} scored across ${repoCount} repo(s); ${waiting} shipped but unanswered. ` +
+      (answered.length >= CALIBRATION_N
+        ? 'Enough to fit the thresholds.'
+        : `Thresholds are fitted at ${CALIBRATION_N}.`),
+  };
+}
+
+export function formatTable(rows) {
+  const head = ['repo', 'epic', 'score', 'ask', 'answer', '+stories', 'amended', 'disproved'];
+  const body = rows.map((r) => [
+    r.repo,
+    r.epic,
+    String(r.score),
+    r.ask === 'proxy' ? 'proxy ⚑' : r.ask,
+    r.answer ?? '—',
+    r.storiesAdded == null ? '?' : String(r.storiesAdded),
+    String(r.amendments),
+    String(r.disproved),
+  ]);
+  const w = head.map((h, i) => Math.max(h.length, ...body.map((b) => b[i].length)));
+  const line = (cells) =>
+    cells
+      .map((c, i) => c.padEnd(w[i]))
+      .join('  ')
+      .trimEnd();
+  return [line(head), ...body.map(line)].join('\n');
+}
+
+// ── I/O ───────────────────────────────────────────────────────────────────────────────────────────────────────
+
+/** process.env without GIT_DIR and friends — see the header. */
+export function sealedEnv(env = process.env) {
+  const out = { ...env };
+  for (const k of Object.keys(out)) if (/^GIT_/.test(k)) delete out[k];
+  return out;
+}
+
+/** The README exactly as the commit that ADDED it wrote it, or null (no git, never committed, unreadable). */
+export function firstCommitted(repoDir, relPath, exec = spawnSync) {
+  const git = (args) => exec('git', ['-C', repoDir, ...args], { encoding: 'utf8', env: sealedEnv() });
+  const log = git(['log', '--diff-filter=A', '--format=%H', '--', relPath]);
+  if (log.status !== 0) return null;
+  const sha = String(log.stdout).trim().split('\n').filter(Boolean).pop();
+  if (!sha) return null;
+  const show = git(['show', `${sha}:${relPath}`]);
+  return show.status === 0 ? String(show.stdout) : null;
+}
+
+/** Every epic under <repo>/Roadmap/<macro>/<slug>/README.md, with its seed and retro. */
+export function readRepo(repoDir, { exec = spawnSync } = {}) {
+  const roadmap = join(repoDir, 'Roadmap');
+  if (!existsSync(roadmap)) throw new Error(`${repoDir}: no Roadmap/ — not a repo on this layout`);
+  const read = (p) => (existsSync(p) ? readFileSync(p, 'utf8') : null);
+  const epics = [];
+  for (const macro of readdirSync(roadmap, { withFileTypes: true })) {
+    if (!macro.isDirectory() || macro.name === '00-ideas') continue;
+    for (const ep of readdirSync(join(roadmap, macro.name), { withFileTypes: true })) {
+      if (!ep.isDirectory()) continue;
+      const readmePath = join(roadmap, macro.name, ep.name, 'README.md');
+      const readme = read(readmePath);
+      if (readme == null) continue;
+      epics.push({
+        slug: ep.name,
+        macro: macro.name,
+        readme,
+        seed: read(join(roadmap, '00-ideas', 'seeds', `${ep.name}.md`)),
+        retro: read(join(roadmap, macro.name, ep.name, 'RETROSPECTIVE.md')),
+        readmePath: relative(repoDir, readmePath),
+      });
+    }
+  }
+  const backfill = parseBackfill(
+    read(join(repoDir, BACKFILL_PATH)),
+    join(basename(resolve(repoDir)), BACKFILL_PATH)
+  );
+  // Only a scored epic's first commit is worth a git call.
+  const scoredSlugs = new Set(rowsFor('', epics, backfill).map((r) => r.epic));
+  for (const e of epics)
+    e.firstReadme = scoredSlugs.has(e.slug) ? firstCommitted(repoDir, e.readmePath, exec) : null;
+  return { epics, backfill };
+}
+
+export function parseArgs(argv) {
+  const repos = [];
+  let json = false;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--repo') repos.push(argv[++i]);
+    else if (argv[i] === '--json') json = true;
+    else return { error: `unknown argument ${argv[i]}` };
+  }
+  if (repos.some((r) => !r)) return { error: '--repo needs a path' };
+  return { repos: repos.length ? repos : ['.'], json };
+}
+
+export function run(argv, io = {}) {
+  const { out = (t) => process.stdout.write(t), err = (t) => process.stderr.write(t), read = readRepo } = io;
+  const args = parseArgs(argv);
+  if (args.error) {
+    err(
+      `intent-outcomes: ${args.error}\nusage: node scripts/intent-outcomes.mjs [--repo <path>]... [--json]\n`
+    );
+    return 1;
+  }
+  const rows = [];
+  for (const r of args.repos) {
+    let data;
+    try {
+      data = read(r);
+    } catch (e) {
+      // One unreadable repo is "could not look" for the whole report: a table that silently drops a repo would
+      // report a smaller n as if it were the whole of it.
+      err(`intent-outcomes: could not look — ${e.message}\n`);
+      return 2;
+    }
+    rows.push(...rowsFor(basename(resolve(r)), data.epics, data.backfill));
+  }
+  const s = summary(rows, args.repos.length);
+  if (args.json) out(`${JSON.stringify({ rows, ...s }, null, 2)}\n`);
+  else
+    out(
+      `${rows.length ? formatTable(rows) : '(no scored epics yet)'}\n\n${s.line}\n⚑ = the ask is a proxy (D8): weigh or drop it when fitting.\n`
+    );
+  return 0;
+}
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) process.exitCode = run(process.argv.slice(2));

package/dist/intent-reader.mjs

@@ -0,0 +1,330 @@
+#!/usr/bin/env node
+// intent-reader.mjs — an OPTIONAL second-family read of a pitch at the architecture lock (intent-match D4, D16).
+//
+//   node scripts/intent-reader.mjs --epic <slug> [--timeout <seconds>]
+//
+// The epic kickoff's lock step names this command on every run. With `intent.reader` off — the default — it prints
+// one line and exits before touching any CLI, so it costs nothing. Turned on (`gf-kit config set intent.reader on`),
+// it hands the epic's seed (the pitch file, nothing else) to the first of codex, agy and vibe that is installed,
+// once, with a hard timeout, and asks Jev one Noul: would that reader build the same thing as the lock's plan? The
+// answer is the fifth signal, "agreement", and it is written into the epic README's `## Intent match` section.
+//
+// ── IT NEVER GETS IN THE WAY ─────────────────────────────────────────────────────────────────────────────────
+// Any failure — no reader CLI, a capped or logged-out CLI, a timeout, an empty or unstructured reply, Jev unable to
+// look — prints exactly ONE line, `reader skipped: <why>`, and exits 0. There is no retry and no second family after
+// one has been asked: free-tier CLIs can be finicky, and three reads of every pitch cost more time than they return
+// (the product owner's call at grooming). Exit 1 is kept for a usage error only.
+//
+// ── NEVER CLAUDE ─────────────────────────────────────────────────────────────────────────────────────────────
+// Planning and building run on Claude; a Claude reader adds no independent read. `FAMILIES` holds no Claude entry
+// and a spec pins that.
+//
+// Every CLI is spawned directly with `timeout`, from the argv builders `lib/cross-agent-cli.mjs` exports — never
+// through `runCodex`/`runAntigravity`/`runVibe`, which have no deadline, retry agy on a second model and print their
+// own warning line (C4). Zero deps — Node 18+.
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  AGY_ARG_LIMIT,
+  agyArgs,
+  codexExecArgs,
+  hasCmd,
+  VIBE_ARG_LIMIT,
+  vibeArgs,
+} from './lib/cross-agent-cli.mjs';
+import { getKey } from './lib/config.mjs';
+import { collectSecretValues, findSecretLeaks } from './lib/secret-guard.mjs';
+import { askJev, loadJevConfig, readApiKey, repoRoot, stateSize, STATE_CHAR_BUDGET } from './lib/jev.mjs';
+import {
+  componentsFrom,
+  INTENT_QUESTIONS,
+  INTENT_TIMEOUT_MS,
+  SIGNAL_NAMES,
+  setFrontmatterKey,
+  totalOf,
+  upsertIntentSection,
+} from './intent-match.mjs';
+
+export const DEFAULT_TIMEOUT_S = 120;
+
+/** The reader families, in preference order (review-route's order). NEVER Claude (D4). */
+export const FAMILIES = Object.freeze([
+  {
+    id: 'codex',
+    bin: 'codex',
+    argv: (prompt) => ({ args: codexExecArgs(prompt.head), input: prompt.body, limit: null }),
+  },
+  {
+    id: 'agy',
+    bin: 'agy',
+    argv: (prompt) => ({ args: agyArgs(prompt.full), input: '', limit: AGY_ARG_LIMIT }),
+  },
+  {
+    id: 'vibe',
+    bin: 'vibe',
+    argv: (prompt) => ({ args: vibeArgs(prompt.full), input: '', limit: VIBE_ARG_LIMIT }),
+  },
+]);
+
+/** The fixed prompt (D16): the reader gets the pitch file and these three headings, nothing else. */
+export const READER_PROMPT = `You are reading a product pitch you did not write, before anyone builds it. Do not open, run or change any file: the pitch is given to you below. Answer in exactly three sections, with exactly these headings:
+
+## Will build
+- each thing you would build from this pitch, one bullet each
+
+## Won't build
+- each thing this pitch leaves out on purpose, or that you would not build from it
+
+## First question
+- the one question you would ask the person who wrote it before you started
+
+Keep it short. No preamble, no other sections.`;
+
+const HEADINGS = [
+  /^#+\s*will build\b/im,
+  /^#+\s*won['’]?t build\b|^#+\s*will not build\b/im,
+  /^#+\s*first question\b/im,
+];
+
+/** Does a reply carry the three headings the prompt asked for? Pure. */
+export const isStructured = (text) => HEADINGS.every((re) => re.test(String(text ?? '')));
+
+/** The one line every skip prints. Pure. */
+export const skipLine = (why) => `reader skipped: ${why}`;
+
+const lastLine = (t) =>
+  String(t ?? '')
+    .trim()
+    .split('\n')
+    .filter(Boolean)
+    .pop() ?? '';
+
+/**
+ * Ask ONE family, once. Returns { ok: true, text } or { ok: false, why }. Never throws. The spawn result is read the
+ * way spawnSync reports a deadline: `error.code === 'ETIMEDOUT'` (with `timeout` set, the child is killed).
+ */
+export function askReader(family, pitch, { spawn = spawnSync, timeoutMs }) {
+  const prompt = { head: READER_PROMPT, body: pitch, full: `${READER_PROMPT}\n\n---\n\n${pitch}\n` };
+  const { args, input, limit } = family.argv(prompt);
+  if (limit && Buffer.byteLength(prompt.full, 'utf8') > limit)
+    return { ok: false, why: `${family.id}: the pitch is over its ${limit / 1024} KB argument limit` };
+  let r;
+  try {
+    r = spawn(family.bin, args, {
+      input,
+      encoding: 'utf8',
+      timeout: timeoutMs,
+      killSignal: 'SIGKILL',
+      maxBuffer: 16 * 1024 * 1024,
+    });
+  } catch (e) {
+    return { ok: false, why: `${family.id}: could not start (${e?.message || e})` };
+  }
+  if (r?.error?.code === 'ETIMEDOUT')
+    return { ok: false, why: `${family.id}: timed out after ${timeoutMs / 1000}s` };
+  if (r?.error?.code === 'ENOBUFS') return { ok: false, why: `${family.id}: the reply was over 16 MB` };
+  if (r?.error) return { ok: false, why: `${family.id}: could not start (${r.error.message})` };
+  if (r?.status !== 0)
+    return {
+      ok: false,
+      why: `${family.id}: exited ${r?.status ?? r?.signal ?? '?'}${lastLine(r?.stderr) ? ` — ${lastLine(r.stderr).slice(0, 160)}` : ''}`,
+    };
+  const text = String(r.stdout ?? '').trim();
+  if (!text) return { ok: false, why: `${family.id}: empty reply` };
+  if (!isStructured(text))
+    return {
+      ok: false,
+      why: `${family.id}: unstructured reply (no Will build / Won't build / First question)`,
+    };
+  return { ok: true, text };
+}
+
+/** The first family whose binary is installed, or null. Missing is the ONLY reason to move to the next one. */
+export function pickFamily(has = hasCmd) {
+  return FAMILIES.find((f) => has(f.bin)) ?? null;
+}
+
+const f2 = (n) => n.toFixed(2);
+
+/** The README's `## Intent match` section, with agreement. Pure. */
+export function readerSection({ family, agreement, seedComponents, seedTotal, date, reply }) {
+  const withAgreement = totalOf({ ...(seedComponents ?? {}), agreement });
+  const seedLine = seedComponents
+    ? `- Seed score: **${seedTotal ?? '—'}** (${Object.entries(seedComponents)
+        .map(([k, v]) => `${SIGNAL_NAMES[k]} ${f2(v)}`)
+        .join(' · ')})`
+    : '- Seed score: none recorded (run `node scripts/intent-match.mjs <seed> --write` at groom Stage 3.5)';
+  const lines = [
+    '## Intent match',
+    '',
+    '_Advisory and uncalibrated (intent-match D1, D3). Agreement written by `intent-reader.mjs` at the architecture lock._',
+    '',
+    seedLine,
+    `- Agreement (reader: ${family}, ${date}): **${f2(agreement)}** — P(the reader, given only the pitch, would build what this plan builds)`,
+  ];
+  if (seedComponents) lines.push(`- Total with agreement: **${withAgreement.total} / 100** — uncalibrated`);
+  const clipped = reply.length > 4000 ? `${reply.slice(0, 4000)}\n…[truncated]` : reply;
+  // Indented, never fenced: a reply is model output, and a fence it carries (``` or ~~~) would close ours and leave its
+  // own `## ` headings outside the section, where the next run cannot find them (fresh review of #197).
+  lines.push(
+    '',
+    "<details><summary>The reader's reply</summary>",
+    '',
+    ...clipped.split('\n').map((l) => `    ${l}`),
+    '',
+    '</details>',
+    ''
+  );
+  lines.push(
+    `<!-- intent-match: ${JSON.stringify({ ...(seedComponents ?? {}), agreement: Math.round(agreement * 1000) / 1000, total: seedComponents ? withAgreement.total : null })} -->`,
+    ''
+  );
+  return { text: lines.join('\n'), total: seedComponents ? withAgreement.total : null };
+}
+
+/** Roadmap/<macro>/<slug>/README.md and the seed, or { error }. */
+export function locateEpic(
+  root,
+  slug,
+  { exists = existsSync, list = (d) => readdirSync(d, { withFileTypes: true }) } = {}
+) {
+  const roadmap = join(root, 'Roadmap');
+  if (!exists(roadmap)) return { error: `no Roadmap/ under ${root}` };
+  const hits = list(roadmap)
+    .filter((d) => d.isDirectory() && exists(join(roadmap, d.name, slug, 'README.md')))
+    .map((d) => join(roadmap, d.name, slug, 'README.md'));
+  if (hits.length !== 1)
+    return {
+      error: hits.length ? `"${slug}" is under more than one macro` : `no epic "${slug}" under Roadmap/*/`,
+    };
+  const seed = join(roadmap, '00-ideas', 'seeds', `${slug}.md`);
+  return { readme: hits[0], seed: exists(seed) ? seed : null };
+}
+
+export function parseArgs(argv) {
+  const out = { epic: null, timeout: DEFAULT_TIMEOUT_S, help: false, bad: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') out.help = true;
+    else if (a === '--epic') out.epic = argv[++i] ?? null;
+    else if (a === '--timeout') {
+      const n = Number(argv[++i]);
+      if (!Number.isFinite(n) || n <= 0) out.bad = '--timeout needs a positive number of seconds';
+      else out.timeout = n;
+    } else out.bad = `unknown argument ${a}`;
+  }
+  if (!out.help && !out.bad && !out.epic) out.bad = '--epic <slug> is required';
+  return out;
+}
+
+/**
+ * The run. Every side effect injected; returns the exit code (0, or 1 for usage). io = { root, setting, config, key,
+ * has, spawn, ask, read, write, out, today }.
+ */
+export async function run(argv, io) {
+  const args = parseArgs(argv);
+  if (args.help || args.bad) {
+    if (args.bad) io.out(`intent-reader: ${args.bad}`);
+    io.out('usage: node scripts/intent-reader.mjs --epic <slug> [--timeout <seconds>]');
+    return args.help ? 0 : 1;
+  }
+  // OFF first, before anything is read or spawned: the default costs nothing and waits for nothing (D4).
+  const setting = io.setting();
+  if (setting !== 'on') {
+    io.out(
+      `intent reader: off (intent.reader: ${JSON.stringify(setting)}) — no reader asked. Turn it on with \`gf-kit config set intent.reader on\`.`
+    );
+    return 0;
+  }
+  const skip = (why) => {
+    io.out(skipLine(why));
+    return 0;
+  };
+  const where = locateEpic(io.root, args.epic);
+  if (where.error) return skip(where.error);
+  if (!where.seed)
+    return skip(
+      `no seed at Roadmap/00-ideas/seeds/${args.epic}.md — the reader reads the pitch, and there is none`
+    );
+  // Agreement is a Jev answer. Check Jev can be asked BEFORE spending up to two minutes on a reader.
+  const config = io.config();
+  if (config.egress !== true)
+    return skip(`Jev cannot score agreement (jev.egress is ${JSON.stringify(config.egress)}, not true)`);
+  const key = io.key();
+  if (!key) return skip('Jev cannot score agreement (no TYPESAFE_API_KEY)');
+  const family = pickFamily(io.has);
+  if (!family) return skip('no reader CLI on PATH (codex, agy or vibe)');
+  const pitch = io.read(where.seed);
+  const plan = io.read(where.readme);
+  const reply = askReader(family, pitch, { spawn: io.spawn, timeoutMs: args.timeout * 1000 });
+  if (!reply.ok) return skip(reply.why);
+  // The reply is about to leave this process twice: to Jev, then into a README that may be public. A reader can READ
+  // host files (codex's sandbox allows reads; agy has no tool restriction), so a secret-shaped reply is skipped before
+  // either, as cross-review does (lib/secret-guard.mjs). Names only: a value is never printed.
+  const leaks = io.secrets(reply.text).leaks;
+  if (leaks.length)
+    return skip(
+      `${family.id}: the reply carried secret-shaped text (${leaks.map((l) => l.name).join(', ')}); nothing sent, nothing written`
+    );
+  const state = { plan, reading: reply.text };
+  if (stateSize(state) > STATE_CHAR_BUDGET)
+    return skip(`the plan and the reading are over Jev's state budget (${stateSize(state)} chars)`);
+  const res = await io.ask(
+    { state, questions: { agreement: INTENT_QUESTIONS.agreement } },
+    { key, model: config.model }
+  );
+  const a = res?.ok ? res.answers?.agreement : undefined;
+  if (a?.type !== 'noul' || typeof a.noul !== 'number' || !(a.noul >= 0 && a.noul <= 1))
+    return skip(
+      `Jev could not look (${res?.ok ? 'malformed agreement answer' : (res?.error ?? 'no answer')})`
+    );
+  const seedText = pitch;
+  const seedComponents = componentsFrom(seedText);
+  const seedTotal = seedComponents ? totalOf(seedComponents)?.total : null;
+  const section = readerSection({
+    family: family.id,
+    agreement: a.noul,
+    seedComponents,
+    seedTotal,
+    date: io.today,
+    reply: reply.text,
+  });
+  let next = upsertIntentSection(plan, section.text);
+  if (section.total != null) next = setFrontmatterKey(next, 'intent_match', section.total);
+  io.write(where.readme, next);
+  io.out(
+    `intent reader: ${family.id} read the pitch — agreement ${f2(a.noul)}${section.total != null ? `; total ${section.total} (seed ${seedTotal})` : ''}, written to ${relative(io.root, where.readme)}`
+  );
+  return 0;
+}
+
+async function main() {
+  const root = repoRoot();
+  const code = await run(process.argv.slice(2), {
+    root,
+    setting: () => getKey('intent.reader', { root }),
+    config: () => loadJevConfig({ root }),
+    key: () => readApiKey({ root }),
+    has: hasCmd,
+    secrets: (text) => findSecretLeaks(text, { values: collectSecretValues({ root }) }),
+    spawn: spawnSync,
+    ask: (req, { key, model }) => askJev(req, { key, model, timeoutMs: INTENT_TIMEOUT_MS }),
+    read: (p) => readFileSync(p, 'utf8'),
+    write: (p, t) => writeFileSync(p, t),
+    out: (l) => process.stdout.write(`${l}\n`),
+    today: new Date().toISOString().slice(0, 10),
+  });
+  process.exitCode = code;
+}
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain)
+  main().catch((e) => {
+    // Even an unexpected crash is one skip line and exit 0: the reader never stops a lock (D4). A malformed config
+    // is the one thing a person must see, and it is still only one line.
+    process.stdout.write(`${skipLine(`internal error (${e?.message || e})`)}\n`);
+    process.exitCode = 0;
+  });

package/dist/lib/config-registry.mjs

@@ -142,6 +142,16 @@ export const REGISTRY = Object.freeze([
     default: 'every-risk-high-story-names-its-flag',
     question: 'Should every risk:high story name its kill-switch flag?',
   },
+  {
+    // intent-match D4/D16: an optional second-family read of the pitch at the architecture lock. OFF unless a person
+    // turns it on — never asked (`never-yet`), because a reader that runs by default is the stall D4 rules out.
+    key: 'intent.reader',
+    module: 'Plan',
+    askWhen: 'never-yet',
+    default: 'off',
+    choices: ['off', 'on'],
+    question: 'At the architecture lock, ask one other model family (codex, agy or vibe) to read the pitch and score whether it would build the same thing? Off by default; any failure is skipped.',
+  },
   {
     key: 'spend.telemetry',
     module: 'Spend',

package/dist/lib/config.mjs

@@ -43,6 +43,7 @@ export const SECTIONS = Object.freeze([
   'ship',
   'spend',
   'routines',
+  'intent',
 ]);
 
 /**

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

@@ -875,11 +875,17 @@ export function runWithCodexFallback({ prompt, stdin, antigravityArgv, builder =
   }
 }
 
+// The argv for one agy print-mode call. Exported so a caller that needs its OWN spawn (a hard timeout, one model, no
+// fallback line — the intent reader, intent-match C4) builds the identical invocation instead of a second copy of it.
+export function agyArgs(fullArgv, model = AGY_MODEL) {
+  return ['-p', fullArgv, '--model', model];
+}
+
 // One `agy -p "<prompt>" --model "<MODEL>"` invocation. The prompt+framed context ride in `fullArgv` (stdin is
 // NOT the prompt and must be at EOF — input:'' gives an immediate EOF or print mode blocks forever). Returns
 // the raw spawn result; the caller classifies status/stdout.
 function execAgy(fullArgv, model, spawn) {
-  return spawn('agy', ['-p', fullArgv, '--model', model], {
+  return spawn('agy', agyArgs(fullArgv, model), {
     input: '',
     encoding: 'utf8',
     maxBuffer: 64 * 1024 * 1024,
@@ -1252,16 +1258,8 @@ export const CLAUDE_REVIEW_MODEL = process.env.CLAUDE_REVIEW_MODEL || 'sonnet';
 // Empty stdout is treated as a FAILURE, not as "no findings". Every CLI on this roster can exit 0 having
 // produced nothing when it is quota-capped or misconfigured, and a review that silently becomes empty is
 // worse than one that errors — it reads as a clean pass. `deps.spawn` is injectable for tests.
-export function runVibe(fullArgv, opts = {}, deps = {}) {
-  const { spawn = spawnSync } = deps;
-  if (Buffer.byteLength(fullArgv, 'utf8') > VIBE_ARG_LIMIT) {
-    return fail(
-      opts.soft,
-      `input too large for vibe (${Math.round(Buffer.byteLength(fullArgv) / 1024)} KB > ` +
-        `${VIBE_ARG_LIMIT / 1024} KB; vibe takes the prompt in argv, not stdin) — use --agent codex instead.`
-    );
-  }
-
+// The argv for one vibe call, read-only (every tool disabled). Exported for the same reason as agyArgs (C4).
+export function vibeArgs(fullArgv) {
   const args = [
     '--prompt',
     fullArgv,
@@ -1276,8 +1274,20 @@ export function runVibe(fullArgv, opts = {}, deps = {}) {
     '*',
   ];
   if (VIBE_MODEL) args.push('--model', VIBE_MODEL);
+  return args;
+}
+
+export function runVibe(fullArgv, opts = {}, deps = {}) {
+  const { spawn = spawnSync } = deps;
+  if (Buffer.byteLength(fullArgv, 'utf8') > VIBE_ARG_LIMIT) {
+    return fail(
+      opts.soft,
+      `input too large for vibe (${Math.round(Buffer.byteLength(fullArgv) / 1024)} KB > ` +
+        `${VIBE_ARG_LIMIT / 1024} KB; vibe takes the prompt in argv, not stdin) — use --agent codex instead.`
+    );
+  }
 
-  const r = spawn('vibe', args, { input: '', encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  const r = spawn('vibe', vibeArgs(fullArgv), { input: '', encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
   if (r.error)
     return fail(
       opts.soft,

package/package.json

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