gcf-aif-ext 0.2.5 → 0.3.0

package/hooks/pre-commit.js

@@ -4,14 +4,15 @@
 // The gate reads the WORKING TREE, so it only runs when the commit touches gcf/ and
 // refuses to judge a gcf/ whose working tree and index disagree.
 import { existsSync } from 'node:fs';
-import { readFile } from 'node:fs/promises';
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
-import { listCards, listSystems } from '../lib/gcf-paths.js';
+import { listSystems } from '../lib/gcf-paths.js';
 import { validateCard, validateUntil } from '../lib/validate-card.js';
 import { stemMatches } from '../lib/id.js';
 import { writeIndex } from '../lib/index-gen.js';
 import { lint } from '../lib/linter.js';
+import { buildLedger } from '../lib/ledger.js';
+import { designCheck } from '../lib/design-check.js';
 
 const projectDir = process.cwd();
 const root = path.join(projectDir, 'gcf');
@@ -26,68 +27,85 @@ const fail = (msg) => {
 // rather than letting a broken probe wave a commit past every check.
 function git(args) {
   const res = spawnSync('git', args, { cwd: projectDir, encoding: 'utf8' });
+
   return res.status === 0 ? res.stdout.trim() : null;
 }
 
 const staged = git(['diff', '--cached', '--name-only', '--', root]);
 if (staged === '') process.exit(0); // this commit does not touch gcf/
 if (staged !== null) {
-  // Untracked counts: listCards reads the directory, so an uncommitted card file would be
-  // validated and written into the staged INDEX while not being in the repository at all.
+  // Untracked counts: cards and units are found by reading directories, so an uncommitted file
+  // would be validated and written into the staged INDEX while not being in the repository.
   const unstaged = git(['diff', '--name-only', '--', root]);
   const untracked = git(['ls-files', '--others', '--exclude-standard', '--', root]);
   if (unstaged || untracked) {
-    fail('gcf/ has changes outside the index — stage them, or commit gcf/ separately (the gate reads the working tree)');
+    fail(
+      'gcf/ has changes outside the index — stage them, or commit gcf/ separately ' +
+        '(the gate reads the working tree)',
+    );
   }
 }
 
-const cards = await listCards(root);
-const cardIds = new Set(cards.map((c) => c.data.id));
-const systemDocs = await listSystems(root);
+const ledger = await buildLedger(projectDir);
 
 // 1-2: frontmatter validity, storable statuses, until grammar, filename invariant.
-for (const c of cards) {
+for (const c of ledger.cards) {
   const errors = [
     ...validateCard(c.data),
     ...validateUntil(c.body),
-    ...(stemMatches(c.file, c.data.id, c.data.slug) ? [] : [`filename must be ${c.data.id}-${c.data.slug}.md`]),
+    ...(stemMatches(c.file, c.data.id) ? [] : [`filename must be ${c.data.id}.md`]),
   ];
   if (errors.length) fail(`${c.name}: ${errors[0]}`);
 }
-for (const s of systemDocs) {
+
+for (const s of await listSystems(root)) {
   const errors = validateUntil(s.body);
   if (errors.length) fail(`systems/${s.name}: ${errors[0]}`);
 }
 
-// 4: depends reference known cards; a built card must not sit on un-collapsed depends.
-// A collapsed card leaves no file, so its trace is the verdict commit or the graveyard line.
-const verdictLog = git(['log', '--grep', '^gcf(verdict):', '--format=%s']) ?? '';
-const gyFile = path.join(root, 'graveyard.md');
-const graveyard = existsSync(gyFile) ? await readFile(gyFile, 'utf8') : '';
-const collapsed = (id) => new RegExp(`^gcf\\(verdict\\): \\w+ ${id}\\b`, 'm').test(verdictLog)
-  || new RegExp(`^- ${id} \\|`, 'm').test(graveyard);
+// A unit or card leaving without its move (take, done, drop, a verdict) loses its reason, not
+// its integrity: a card or unit still citing it fails M2 below, in this commit. A warning, not a
+// refusal — a revert of the commit that added it removes an id legitimately.
+for (const id of ledger.vanished()) {
+  console.error(
+    `gcf pre-commit: warning: ${id} left design/ or cards/ without done, drop or a verdict — ` +
+      'no history or graveyard line keeps why',
+  );
+}
+
+// Design model and card bodies: every finding of severity `block` refuses the commit.
+const first = (await designCheck(projectDir)).issues.find((i) => i.severity === 'block');
+if (first) fail(`${first.file}:${first.line}: ${first.check}: ${first.message}`);
 
-for (const c of cards) {
+// 4: a built card must not sit on an unplayed dependency — a live card, or a unit still in
+// design/. A collapsed, done or killed id is played; an unknown one is a typo (design check).
+for (const c of ledger.cards.filter((x) => x.data.status === 'built')) {
   for (const dep of c.data.depends ?? []) {
-    if (cardIds.has(dep)) {
-      if (c.data.status === 'built') {
-        fail(`${c.data.id} is built on top of unplayed ${dep} (collapse it first — GCF-PRD §7.2)`);
-      }
-    } else if (!collapsed(dep)) {
-      fail(`${c.data.id} depends on unknown ${dep} (no card, no verdict, no graveyard line)`);
-    }
+    const live = ledger.where(dep).live[0];
+    if (live)
+      fail(`${c.data.id} is built on top of unplayed ${dep} (${live.state} — GCF-PRD §7.2)`);
   }
 }
 
+for (const c of ledger.cards) {
+  const unknown = (c.data.depends ?? []).find((d) => !ledger.known(d));
+  if (unknown)
+    fail(`${c.data.id} depends on unknown ${unknown} (no unit, card, history or graveyard line)`);
+}
+
 // 5: П2 linter over systems docs.
-for (const s of systemDocs) {
+for (const s of await listSystems(root)) {
   const { issues } = lint(s.body);
-  if (issues.length) fail(`systems/${s.name}:${issues[0].line}: ${issues[0].rule}: ${issues[0].text}`);
+  if (issues.length)
+    fail(`systems/${s.name}:${issues[0].line}: ${issues[0].rule}: ${issues[0].text}`);
 }
 
 // 3: regenerate INDEX and stage it (deterministic artifact, not a human error).
 await writeIndex(root);
 // An unstaged INDEX (gitignored, locked index) would leave the commit without the row it validated.
-const added = spawnSync('git', ['add', '--', path.join(root, 'INDEX.md')], { cwd: projectDir, stdio: 'ignore' });
+const added = spawnSync('git', ['add', '--', path.join(root, 'INDEX.md')], {
+  cwd: projectDir,
+  stdio: 'ignore',
+});
 if (added.status !== 0) fail('could not stage gcf/INDEX.md — is it gitignored?');
 process.exit(0);

package/injections/commit-status.md

@@ -4,3 +4,4 @@ gcf_commit:
 - when `gcf/` exists and the commit implements a card, verify the card frontmatter is current
 - an implementation commit that completes a build flips `status:` to `built` and records `built_at:` with the commit hash in the same commit
 - do not commit a card file whose `status:` is `validated` or `killed`: those are terminal and never stored
+- when the commit makes a hard unit's tests green, run `ai-factory gcf done <id>` after it: the unit leaves `gcf/design/` in its own fixed-format commit

package/injections/plan-context.md

@@ -4,5 +4,6 @@ gcf_gate:
 - when `gcf/` exists and the task names a card, run `ai-factory gcf context <card-id>` first
 - the returned file list is the readset: read those files and nothing else under `gcf/`
 - `over_budget: true` in the result: stop and record a D1 question instead of planning
-- a card in `depends:` that still exists as a file is unplayed: do not plan on top of it, stop
-- shape the plan by the card slots: behavior, contract, feel envelope, interactions, negative constraints, miss criterion
+- an id in `depends:` that still lives as a card or as a unit of `gcf/design/` is unplayed: do not plan on top of it, stop
+- shape the plan by the card slots: intent, behavior, refusal, boundaries, persistence, feel envelopes, contract, interactions, constraints, miss criterion
+- when the task names a hard unit (rule, constraint, entity), there is no card: read its section only, from the file `ai-factory gcf where <id>` names, and plan its tests from `statement`, `threshold` or `fields`

package/injections/review-pillars.md

@@ -1,7 +1,7 @@
 ## GCF: pillar and constraint review (from gcf-aif-ext)
 
 gcf_review:
-- when `gcf/` exists and the change implements a card, read `gcf/PILLARS.md` and the card
+- when `gcf/` exists and the change implements a card, read the card and `gcf/PILLARS.md` when it exists (it stays absent until the pillars interview)
 - check the diff against every negative constraint of the card: name each violation with file and line
 - check the diff against each pillar's review question: a contradiction is a finding, not a note
 - numeric feel values in code outside the card's envelope: report the value and the envelope bounds

package/lib/anchors.js

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { readFile, writeFile, mkdir, readdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 
@@ -7,45 +7,67 @@ import path from 'node:path';
 // stable under reorder, not under rename. Re-import matches orphaned anchors by body
 // hash and reports a rename instead of delete+add.
 
-const norm = (s) => String(s).toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').trim();
+const norm = (s) =>
+  String(s)
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, ' ')
+    .trim();
 const h8 = (s) => createHash('sha1').update(s, 'utf8').digest('hex').slice(0, 8);
 // A body keeps its punctuation and structure, unlike a heading: `norm` would hash
 // `- a` + `- b` the same as `a, b`, hiding a real edit from classifyDelta.
-const bodyNorm = (s) => String(s).replace(/\r\n/g, '\n').replace(/[ \t]+$/gm, '').trim();
+const bodyNorm = (s) =>
+  String(s)
+    .replace(/\r\n/g, '\n')
+    .replace(/[ \t]+$/gm, '')
+    .trim();
 const EMPTY_HASH = h8('');
 // Bumped whenever body hashing changes: a stored map from an older scheme cannot be
 // compared against fresh hashes, and reporting every section as changed would flood the
 // human with D1 questions about a GDD nobody edited.
 export const HASH_VERSION = 2;
 
-/** Split markdown into heading-addressed sections. Text before the first heading is `GDD#preamble`. */
+/**
+ * Split markdown into heading-addressed sections.
+ * Text before the first heading is `GDD#preamble`.
+ */
 export function splitSections(markdown) {
   const lines = String(markdown).split('\n');
+  /**
+   * @typedef {{ heading: string | null, level: number, start: number, lines: string[] }} RawSection
+   */
+  /** @type {RawSection[]} */
   const sections = [];
-  let current = { heading: null, level: 0, lines: [] };
+  /** @type {RawSection} */
+  let current = { heading: null, level: 0, start: 1, lines: [] };
   const flush = () => {
     if (current.heading === null && !current.lines.join('').trim()) return;
     sections.push(current);
   };
-  for (const line of lines) {
+
+  for (const [i, line] of lines.entries()) {
     const m = line.match(/^(#{1,6})\s+(.+?)\s*$/);
     if (m) {
       flush();
-      current = { heading: m[2], level: m[1].length, lines: [] };
+      current = { heading: m[2], level: m[1].length, start: i + 1, lines: [] };
     } else current.lines.push(line);
   }
+
   flush();
 
   const seen = new Map();
+
   return sections.map((s) => {
     const base = s.heading === null ? 'preamble' : h8(norm(s.heading));
     const n = seen.get(base) ?? 0;
     seen.set(base, n + 1);
     const body = s.lines.join('\n');
+
     return {
       anchor: `GDD#${n ? `${base}-${n}` : base}`,
       heading: s.heading,
       level: s.level,
+      // 1-based and inclusive, heading line first: a reader opens the section, not the file.
+      lines: [s.start, s.start + s.lines.length - (s.heading === null ? 1 : 0)],
       body,
       body_hash: h8(bodyNorm(body)),
     };
@@ -60,9 +82,16 @@ export async function importSource(projectDir, file) {
   const base = path.basename(file);
   await mkdir(path.join(root, 'source'), { recursive: true });
   await writeFile(path.join(root, 'source', base), content, 'utf8');
-  const anchors = Object.fromEntries(sections.map((s) => [s.anchor, { heading: s.heading, body_hash: s.body_hash }]));
+  const anchors = Object.fromEntries(
+    sections.map((s) => [s.anchor, { heading: s.heading, body_hash: s.body_hash }]),
+  );
   const map = { hash_version: HASH_VERSION, anchors };
-  await writeFile(path.join(root, 'source', `${base}.anchors.json`), JSON.stringify(map, null, 2), 'utf8');
+  await writeFile(
+    path.join(root, 'source', `${base}.anchors.json`),
+    JSON.stringify(map, null, 2),
+    'utf8',
+  );
+
   return { file: `gcf/source/${base}`, sections };
 }
 
@@ -71,6 +100,10 @@ export async function importSource(projectDir, file) {
  * A removed anchor whose body hash reappears under a new anchor is a rename.
  */
 export function classifyDelta(oldMap, sections) {
+  /**
+   * @type {{ added: string[], changed: string[], removed: string[],
+   *   renamed: { from: string, to: string }[] }}
+   */
   const delta = { added: [], changed: [], removed: [], renamed: [] };
   const newByAnchor = new Map(sections.map((s) => [s.anchor, s]));
 
@@ -79,6 +112,7 @@ export function classifyDelta(oldMap, sections) {
     if (!old) continue;
     if (old.body_hash !== s.body_hash) delta.changed.push(s.anchor);
   }
+
   const missing = Object.entries(oldMap).filter(([a]) => !newByAnchor.has(a));
   const fresh = sections.filter((s) => !(s.anchor in oldMap));
   // Each fresh section can be claimed once: without consuming the match, one section
@@ -86,12 +120,15 @@ export function classifyDelta(oldMap, sections) {
   const pool = [...fresh];
   for (const [anchor, old] of missing) {
     // An empty body hashes the same everywhere, so it is evidence of nothing.
-    const i = old.body_hash === EMPTY_HASH ? -1 : pool.findIndex((s) => s.body_hash === old.body_hash);
+    const i =
+      old.body_hash === EMPTY_HASH ? -1 : pool.findIndex((s) => s.body_hash === old.body_hash);
     if (i >= 0) delta.renamed.push({ from: anchor, to: pool.splice(i, 1)[0].anchor });
     else delta.removed.push(anchor);
   }
+
   const renamedTo = new Set(delta.renamed.map((r) => r.to));
   delta.added = fresh.map((s) => s.anchor).filter((a) => !renamedTo.has(a));
+
   return delta;
 }
 
@@ -105,5 +142,68 @@ export async function loadAnchorMap(projectDir, baseName) {
   if (!existsSync(file)) return null;
   const raw = JSON.parse(await readFile(file, 'utf8'));
   if (raw.hash_version !== HASH_VERSION) return { anchors: null, rebaselined: true };
+
   return { anchors: raw.anchors ?? {}, rebaselined: false };
 }
+
+/** The section an anchor names in one gcf/source/ file, or null. */
+export async function readSection(projectDir, baseName, anchor) {
+  const file = path.join(path.resolve(projectDir), 'gcf', 'source', path.basename(baseName));
+  if (!existsSync(file))
+    throw new Error(`no gcf/source/${path.basename(baseName)} - anchor it first`);
+
+  return splitSections(await readFile(file, 'utf8')).find((s) => s.anchor === anchor) ?? null;
+}
+
+const ws = (t) => String(t).replace(/\s+/g, ' ').trim();
+
+/** anchor -> whitespace-collapsed bodies across every gcf/source/ file */
+export async function sourceBodies(sourceDir) {
+  /** @type {Map<string, string[]>} */
+  const bodies = new Map();
+  if (!existsSync(sourceDir)) return bodies;
+  for (const name of (await readdir(sourceDir)).filter((n) => n.endsWith('.md'))) {
+    for (const s of splitSections(await readFile(path.join(sourceDir, name), 'utf8'))) {
+      bodies.set(s.anchor, [...(bodies.get(s.anchor) ?? []), ws(s.body)]);
+    }
+  }
+
+  return bodies;
+}
+
+/** gcf-relative files that cite anchors: units, cards, and the `sections:` of questions. */
+async function anchorCiters(root) {
+  const out = [];
+  for (const dir of ['design', 'cards']) {
+    if (!existsSync(path.join(root, dir))) continue;
+    const names = (await readdir(path.join(root, dir))).filter((n) => n.endsWith('.md'));
+    out.push(...names.map((n) => `${dir}/${n}`));
+  }
+
+  if (existsSync(path.join(root, 'open-questions.md'))) out.push('open-questions.md');
+
+  return out;
+}
+
+/**
+ * A renamed heading changes its anchor (GCF-PRD §11.6): rewrite `GDD#<from>` to `GDD#<to>` in
+ * design/, cards/ and open-questions.md, so provenance, `source:` and `sections:` follow the
+ * section instead of pointing at an anchor that no longer exists. Returns the files it changed.
+ */
+export async function rewriteAnchors(projectDir, renamed) {
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const changed = [];
+  for (const rel of renamed.length ? await anchorCiters(root) : []) {
+    const file = path.join(root, rel);
+    const text = await readFile(file, 'utf8');
+    const next = renamed.reduce(
+      (t, r) => t.replace(new RegExp(`${r.from}(?![\\w-])`, 'g'), () => r.to),
+      text,
+    );
+    if (next === text) continue;
+    await writeFile(file, next, 'utf8');
+    changed.push(rel);
+  }
+
+  return changed;
+}

package/lib/audit-core.js

@@ -5,13 +5,36 @@ import { spawnSync } from 'node:child_process';
 import { listCards, listSystems, readConfig, tokensEst } from './gcf-paths.js';
 import { lint } from './linter.js';
 import { drifted } from './index-gen.js';
+import { designCheck } from './design-check.js';
+import { buildLedger } from './ledger.js';
 
 function git(args, cwd) {
   const res = spawnSync('git', args, { cwd, encoding: 'utf8' });
+
   return res.status === 0 ? res.stdout.trim() : null;
 }
 
-const UNTIL_RE = /\[until:\s*(verdict\(card-\d{3}\)|retune\([a-z0-9-]+\)|manual\([^)]*\))\]/g;
+const UNTIL_RE = /\[until:\s*(verdict\([a-z0-9-]+\)|retune\([a-z0-9-]+\)|manual\([^)]*\))\]/g;
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const LEGAL_STATUS = ['proposed', 'built', 'tuning'];
+
+/**
+ * @typedef {object} AuditReport
+ * @property {string} first_line
+ * @property {Array<{id: string, commits: number | null, limit: number}>} stale_built
+ * @property {Array<{id: string, tune_count: number, limit: number}>} tune_limit
+ * @property {Array<{id: string, depends: string[]}>} open_depends
+ * @property {{count: number, limit: number, over: boolean}} wip
+ * @property {{tokens: number, budget: number, over: boolean} | null} pillars
+ * @property {Array<{file: string, trigger: string, status: string}>} until
+ * @property {Record<string, object[]>} linter
+ * @property {object[]} pragmas
+ * @property {boolean} index_drift
+ * @property {Array<{id: string, status: string}>} illegal_status
+ * @property {number} [schema]
+ * @property {Array<{id: string, status: string, system: string[], depends: string[]}>} [cards]
+ * @property {{blocking: number, units: number, ready: number}} [design]
+ */
 
 /**
  * Deterministic audit core (GCF-PRD §10.1): until triggers, built staleness, tune
@@ -22,86 +45,188 @@ export async function audit(projectDir) {
   const root = path.join(path.resolve(projectDir), 'gcf');
   const config = await readConfig(root);
   const cards = await listCards(root);
-  const report = { first_line: '', stale_built: [], tune_limit: [], open_depends: [], wip: null, pillars: null, until: [], linter: {}, pragmas: [], index_drift: false, illegal_status: [] };
-  const liveIds = new Set(cards.map((c) => c.data.id));
+  const systems = await listSystems(root);
+  /** @type {AuditReport} */
+  const report = {
+    first_line: '',
+    stale_built: [],
+    tune_limit: [],
+    open_depends: [],
+    wip: wipOf(cards, config),
+    pillars: await pillarsOf(root, config),
+    until: untilRecords(cards, systems, projectDir, await buildLedger(projectDir)),
+    linter: {},
+    pragmas: [],
+    index_drift: await drifted(root),
+    illegal_status: [],
+  };
+  // The harness gate reads everything from this one report — it never parses gcf/ itself.
+  report.schema = config.schema;
+  report.cards = cards.map((c) => ({
+    id: c.data.id,
+    status: c.data.status,
+    system: c.data.system ?? [],
+    depends: c.data.depends ?? [],
+  }));
+  const design = await designCheck(projectDir);
+  checkCards(report, cards, config, { projectDir, designIds: design.units.map((u) => u.id) });
+  report.design = {
+    blocking: design.blocking,
+    units: design.units.length,
+    ready: design.units.filter((u) => u.ready).length,
+  };
+  lintSystems(report, systems);
+  report.first_line = firstLine(report);
 
+  return report;
+}
+
+/**
+ * Per-card checks: illegal status, built staleness, tune limit, open depends. `designIds` are
+ * units still in gcf/design/: a card depending on one builds on what nobody has played yet.
+ */
+function checkCards(report, cards, config, { projectDir, designIds }) {
+  const liveIds = new Set([...cards.map((c) => c.data.id), ...designIds]);
   // Staleness is measured in commits, so outside a repository there is no answer to give.
   // Without this probe every built card would read as stale and stop the harness.
   const inRepo = git(['rev-parse', '--git-dir'], projectDir) !== null;
 
-  // Verdict history from commit messages of the fixed format (GCF-PRD §8).
-  const verdictLog = git(['log', '--grep', '^gcf(verdict):', '--format=%s'], projectDir) ?? '';
-  const verdictFired = (cardId) => new RegExp(`^gcf\\(verdict\\): \\w+ ${cardId}\\b`, 'm').test(verdictLog);
-  // ponytail: retune(sys) fires on any tune verdict naming the system; the PRD's
-  // feel-section-diff refinement can replace this when it proves too coarse.
-  const retuneFired = (system) => new RegExp(`^gcf\\(verdict\\): tune .*→ .*${system}`, 'm').test(verdictLog);
-
   for (const c of cards) {
-    if (!['proposed', 'built', 'tuning'].includes(c.data.status)) {
+    if (!LEGAL_STATUS.includes(c.data.status)) {
       report.illegal_status.push({ id: c.data.id, status: c.data.status });
     }
-    if (inRepo && c.data.status === 'built' && c.data.built_at) {
-      // git() is null when the ref no longer resolves (rebase, squash, amend, shallow clone).
-      // Number(null) is 0, which reads as "fresh" — the one answer that must never be guessed.
-      const raw = git(['rev-list', '--count', `${c.data.built_at}..HEAD`], projectDir);
-      const n = raw === null ? NaN : Number(raw);
-      if (!Number.isFinite(n) || n > config.built_stale_after_commits) {
-        report.stale_built.push({ id: c.data.id, commits: Number.isFinite(n) ? n : null, limit: config.built_stale_after_commits });
-      }
-    }
+
+    const stale = inRepo ? staleEntry(c, config, projectDir) : null;
+    if (stale) report.stale_built.push(stale);
+
     if ((c.data.tune_count ?? 0) >= config.tune_limit) {
-      report.tune_limit.push({ id: c.data.id, tune_count: c.data.tune_count, limit: config.tune_limit });
+      report.tune_limit.push({
+        id: c.data.id,
+        tune_count: c.data.tune_count,
+        limit: config.tune_limit,
+      });
     }
+
     // A depends id that still has a card file is unplayed (GCF-PRD §7.2). Data for the
     // harness gate, not an alert: a proposed card waiting on its dependency is normal.
     const open = (c.data.depends ?? []).filter((d) => liveIds.has(d));
     if (open.length) report.open_depends.push({ id: c.data.id, depends: open });
   }
+}
+
+/** A stale_built entry for a built card past the commit limit, else null. */
+function staleEntry(c, config, projectDir) {
+  if (c.data.status !== 'built' || !c.data.built_at) return null;
+  // git() is null when the ref no longer resolves (rebase, squash, amend, shallow clone).
+  // Number(null) is 0, which reads as "fresh" — the one answer that must never be guessed.
+  const raw = git(['rev-list', '--count', `${c.data.built_at}..HEAD`], projectDir);
+  const n = raw === null ? NaN : Number(raw);
+  if (!Number.isFinite(n) || n > config.built_stale_after_commits) {
+    return {
+      id: c.data.id,
+      commits: Number.isFinite(n) ? n : null,
+      limit: config.built_stale_after_commits,
+    };
+  }
+
+  return null;
+}
+
+function wipOf(cards, config) {
+  const count = cards.filter((c) => c.data.status === 'built').length;
 
-  const wipCount = cards.filter((c) => c.data.status === 'built').length;
-  report.wip = { count: wipCount, limit: config.wip_built_limit, over: wipCount > config.wip_built_limit };
+  return { count, limit: config.wip_built_limit, over: count > config.wip_built_limit };
+}
 
+async function pillarsOf(root, config) {
   const pillarsFile = path.join(root, 'PILLARS.md');
-  if (existsSync(pillarsFile)) {
-    const tokens = tokensEst(await readFile(pillarsFile, 'utf8'));
-    report.pillars = { tokens, budget: config.pillars_budget, over: tokens > config.pillars_budget };
+  if (!existsSync(pillarsFile)) return null;
+  const tokens = tokensEst(await readFile(pillarsFile, 'utf8'));
+
+  return { tokens, budget: config.pillars_budget, over: tokens > config.pillars_budget };
+}
+
+/**
+ * Whether a verdict fired. `verdict(id)` reads the files, as the ledger does (GCF-PRD §5.8): a
+ * keep or kill left a history or graveyard line, a tune left the card's tune_count — so a
+ * squash or a shallow clone does not hide it, and a revert takes it back.
+ */
+function verdictMatchers(projectDir, ledger, cards) {
+  const tuned = cards.filter((c) => (c.data.tune_count ?? 0) > 0);
+  const verdictLog = git(['log', '--grep', '^gcf(verdict):', '--format=%s'], projectDir) ?? '';
+
+  return {
+    verdict: (id) =>
+      ledger.where(id).terminal.some((t) => t !== 'done') || tuned.some((c) => c.data.id === id),
+    // shortcut: a kept card's tunes leave no file behind, so retune(sys) also greps the verdict
+    // subjects; upgrade when tunes get their own history line.
+    retune: (system) =>
+      tuned.some((c) => (c.data.system ?? []).includes(system)) ||
+      new RegExp(`^gcf\\(verdict\\): tune .*→ (?:.*,)?${escapeRe(system)}(?:,|$)`, 'm').test(
+        verdictLog,
+      ),
+  };
+}
+
+function untilStatus(trigger, fired) {
+  if (trigger.startsWith('verdict(')) {
+    return fired.verdict(trigger.slice(8, -1)) ? 'stale' : 'open';
   }
 
-  // Until annotations across cards and systems docs.
+  if (trigger.startsWith('retune(')) {
+    return fired.retune(trigger.slice(7, -1)) ? 'stale' : 'open';
+  }
+
+  return 'manual';
+}
+
+/** Until annotations across cards and systems docs. */
+function untilRecords(cards, systems, projectDir, ledger) {
+  const fired = verdictMatchers(projectDir, ledger, cards);
   const docs = [
     ...cards.map((c) => ({ rel: `cards/${c.name}`, body: c.body })),
-    ...(await listSystems(root)).map((s) => ({ rel: `systems/${s.name}`, body: s.body })),
+    ...systems.map((s) => ({ rel: `systems/${s.name}`, body: s.body })),
   ];
+  const until = [];
   for (const doc of docs) {
     for (const m of doc.body.matchAll(UNTIL_RE)) {
-      const trigger = m[1];
-      let status = 'open';
-      if (trigger.startsWith('verdict(')) status = verdictFired(trigger.slice(8, -1)) ? 'stale' : 'open';
-      else if (trigger.startsWith('retune(')) status = retuneFired(trigger.slice(7, -1)) ? 'stale' : 'open';
-      else status = 'manual';
-      report.until.push({ file: `gcf/${doc.rel}`, trigger, status });
+      until.push({ file: `gcf/${doc.rel}`, trigger: m[1], status: untilStatus(m[1], fired) });
     }
   }
 
-  // П2 linter over systems docs.
-  for (const s of await listSystems(root)) {
+  return until;
+}
+
+/** П2 linter over systems docs. */
+function lintSystems(report, systems) {
+  for (const s of systems) {
     const { issues, pragmas } = lint(s.body);
     if (issues.length) report.linter[`gcf/systems/${s.name}`] = issues;
     report.pragmas.push(...pragmas.map((p) => ({ file: `gcf/systems/${s.name}`, ...p })));
   }
+}
 
-  report.index_drift = await drifted(root);
-
-  const alerts = [
-    report.illegal_status.length && `${report.illegal_status.length} card(s) in illegal status`,
-    report.stale_built.length && `${report.stale_built.length} built card(s) stale — playtest first`,
-    report.tune_limit.length && `${report.tune_limit.length} card(s) at tune limit — kill or redesign`,
-    report.wip.over && `WIP over limit (${report.wip.count}/${report.wip.limit})`,
-    report.until.filter((u) => u.status === 'stale').length && 'stale until-records present',
-    report.pillars?.over && 'PILLARS over token budget',
-    Object.keys(report.linter).length && 'П2 linter findings in systems docs',
-    report.index_drift && 'INDEX drift (regenerate)',
-  ].filter(Boolean);
-  report.first_line = alerts.length ? alerts.join('; ') : 'clean';
-  return report;
+/** Alerts about cards in flight, which lead the line. @param {AuditReport} report */
+const cardAlerts = (report) => [
+  report.illegal_status.length && `${report.illegal_status.length} card(s) in illegal status`,
+  report.stale_built.length && `${report.stale_built.length} built card(s) stale — playtest first`,
+  report.tune_limit.length &&
+    `${report.tune_limit.length} card(s) at tune limit — kill or redesign`,
+  report.wip.over && `WIP over limit (${report.wip.count}/${report.wip.limit})`,
+];
+
+/** Alerts about the documents. @param {AuditReport} report */
+const docAlerts = (report) => [
+  report.until.filter((u) => u.status === 'stale').length && 'stale until-records present',
+  report.pillars?.over && 'PILLARS over token budget',
+  Object.keys(report.linter).length && 'П2 linter findings in systems docs',
+  report.index_drift && 'INDEX drift (regenerate)',
+  report.design?.blocking && `${report.design.blocking} blocking design finding(s)`,
+];
+
+/** @param {AuditReport} report */
+function firstLine(report) {
+  const alerts = [...cardAlerts(report), ...docAlerts(report)].filter(Boolean);
+
+  return alerts.length ? alerts.join('; ') : 'clean';
 }