gcf-aif-ext 0.2.5 → 0.2.7

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,66 @@ 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;
+}
+
+/**
+ * Provenance check over gcf/backlog.md (GCF-PRD §11.2.3): every line citing `src: GDD#…`
+ * must carry `q: "…"`, and the quote must be a verbatim substring of that section in some
+ * gcf/source/ file. Line wraps in the GDD are not edits, so runs of whitespace compare equal.
+ */
+export async function checkQuotes(projectDir) {
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const backlog = path.join(root, 'backlog.md');
+  if (!existsSync(backlog)) return [];
+  const bodies = await sourceBodies(path.join(root, 'source'));
+
+  return (await readFile(backlog, 'utf8'))
+    .split('\n')
+    .map((line) => quoteProblem(line, bodies))
+    .filter((p) => p !== null);
+}
+
+const ws = (t) => String(t).replace(/\s+/g, ' ').trim();
+
+/** anchor -> whitespace-collapsed bodies across every gcf/source/ file */
+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;
+}
+
+/** The provenance problem of one backlog line, or null when it has none or cites no GDD. */
+function quoteProblem(line, bodies) {
+  const id = line.match(/^- (cand-\d+)/)?.[1];
+  const anchor = line.match(/\|\s*src:\s*(GDD#[\w-]+)/)?.[1];
+  if (!id || !anchor) return null;
+  // The closing quote is the one before the next field, so a quote may itself hold `"`.
+  const quote = line.match(/\|\s*q:\s*"(.*?)"\s*(?:\||$)/)?.[1];
+  const found = bodies.get(anchor);
+  /** @type {string | null} */
+  let problem = null;
+  if (!found) problem = 'anchor not found in gcf/source/';
+  else if (!quote) problem = 'no q: "<verbatim quote>"';
+  else if (!found.some((b) => b.includes(ws(quote))))
+    problem = 'quote is not verbatim in the section';
+
+  return problem && { id, anchor, problem };
+}

package/lib/audit-core.js

@@ -8,10 +8,29 @@ import { drifted } from './index-gen.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 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]
+ */
 
 /**
  * Deterministic audit core (GCF-PRD §10.1): until triggers, built staleness, tune
@@ -22,86 +41,162 @@ 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),
+    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 ?? [],
+  }));
+  checkCards(report, cards, config, projectDir);
+  lintSystems(report, systems);
+  report.first_line = firstLine(report);
 
+  return report;
+}
+
+/** Per-card checks: illegal status, built staleness, tune limit, open depends. */
+function checkCards(report, cards, config, projectDir) {
+  const liveIds = new Set(cards.map((c) => c.data.id));
   // 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;
+}
 
-  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 };
+function wipOf(cards, config) {
+  const count = cards.filter((c) => c.data.status === 'built').length;
 
+  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 };
+}
+
+/** Verdict history from commit messages of the fixed format (GCF-PRD §8). */
+function verdictMatchers(projectDir) {
+  const verdictLog = git(['log', '--grep', '^gcf(verdict):', '--format=%s'], projectDir) ?? '';
+
+  return {
+    verdict: (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.
+    retune: (system) => new RegExp(`^gcf\\(verdict\\): tune .*→ .*${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) {
+  const fired = verdictMatchers(projectDir);
   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);
-
+/** @param {AuditReport} report */
+function firstLine(report) {
   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.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;
+
+  return alerts.length ? alerts.join('; ') : 'clean';
 }

package/lib/context.js

@@ -15,14 +15,34 @@ export async function buildContext(projectDir, cardId) {
   const card = cards.find((c) => c.data.id === cardId);
   if (!card) throw new Error(`Card not found: ${cardId}`);
 
+  const systems = card.data.system ?? [];
+  const files = await readsetFiles(root, card, cards);
+  const cardText = `${card.data.slug} ${systems.join(' ')} ${card.body}`.toLowerCase();
+  const graveyard_hits = await graveyardHits(root, cardText);
+  const d2 = await d2Assumptions(root, systems);
+
+  const extraTokens = tokensEst(graveyard_hits.join('\n')) + tokensEst(d2.join('\n'));
+  const total_tokens_est = files.reduce((sum, f) => sum + f.tokens_est, 0) + extraTokens;
+
+  return {
+    card: cardId,
+    files,
+    graveyard_hits,
+    d2,
+    total_tokens_est,
+    budget: config.context_budget,
+    over_budget: total_tokens_est > config.context_budget,
+  };
+}
+
+/** PILLARS, touched systems, the card, its depends — in that order, skipping absent files. */
+async function readsetFiles(root, card, cards) {
   const files = [];
   const push = async (rel) => {
     const abs = path.join(root, rel);
-    if (!existsSync(abs)) return null;
+    if (!existsSync(abs)) return;
     const text = await readFile(abs, 'utf8');
-    const entry = { path: `gcf/${rel.replaceAll('\\', '/')}`, tokens_est: tokensEst(text) };
-    files.push(entry);
-    return text;
+    files.push({ path: `gcf/${rel.replaceAll('\\', '/')}`, tokens_est: tokensEst(text) });
   };
 
   await push('PILLARS.md');
@@ -30,48 +50,46 @@ export async function buildContext(projectDir, cardId) {
   for (const s of (await listSystems(root)).filter((d) => systems.includes(d.data.system))) {
     await push(`systems/${s.name}`);
   }
+
   await push(`cards/${card.name}`);
   for (const depId of card.data.depends ?? []) {
     const dep = cards.find((c) => c.data.id === depId);
     if (dep) await push(`cards/${dep.name}`);
   }
 
-  // Graveyard: headline tags only; a hit is a tag appearing in the card's own text.
-  const graveyard_hits = [];
+  return files;
+}
+
+/** Graveyard: headline tags only; a hit is a tag appearing in the card's own text. */
+async function graveyardHits(root, cardText) {
   const gyFile = path.join(root, 'graveyard.md');
-  if (existsSync(gyFile)) {
-    const cardText = `${card.data.slug} ${systems.join(' ')} ${card.body}`.toLowerCase();
-    for (const line of (await readFile(gyFile, 'utf8')).split('\n')) {
-      const m = line.match(/^- (card-\d{3}) \| .* \| tags: (.+)$/);
-      if (!m) continue;
-      const tags = m[2].split(',').map((t) => t.trim().toLowerCase()).filter(Boolean);
-      if (tags.some((t) => cardText.includes(t))) graveyard_hits.push(line.trim());
-    }
+  if (!existsSync(gyFile)) return [];
+  const hits = [];
+  for (const line of (await readFile(gyFile, 'utf8')).split('\n')) {
+    const m = line.match(/^- (card-\d{3}) \| .* \| tags: (.+)$/);
+    if (!m) continue;
+    const tags = m[2]
+      .split(',')
+      .map((t) => t.trim().toLowerCase())
+      .filter(Boolean);
+    if (tags.some((t) => cardText.includes(t))) hits.push(line.trim());
   }
 
-  // D2 assumptions whose sys: overlaps the card's systems (GCF-PRD §9.1).
-  const d2 = [];
+  return hits;
+}
+
+/** D2 assumptions whose sys: overlaps the card's systems (GCF-PRD §9.1). */
+async function d2Assumptions(root, systems) {
   const oqFile = path.join(root, 'open-questions.md');
-  if (existsSync(oqFile)) {
-    const records = (await readFile(oqFile, 'utf8')).split(/\n(?=- id:)/);
-    for (const rec of records) {
-      if (!/^\s*-?\s*id:/m.test(rec) || !/class:\s*D2/.test(rec)) continue;
+  if (!existsSync(oqFile)) return [];
+  const records = (await readFile(oqFile, 'utf8')).split(/\n(?=- id:)/);
+
+  return records
+    .filter((rec) => /^\s*-?\s*id:/m.test(rec) && /class:\s*D2/.test(rec))
+    .filter((rec) => {
       const sys = rec.match(/sys:\s*(.+)/)?.[1] ?? '';
-      if (systems.some((s) => sys.includes(s))) {
-        d2.push(rec.trim());
-      }
-    }
-  }
 
-  const extraTokens = tokensEst(graveyard_hits.join('\n')) + tokensEst(d2.join('\n'));
-  const total_tokens_est = files.reduce((sum, f) => sum + f.tokens_est, 0) + extraTokens;
-  return {
-    card: cardId,
-    files,
-    graveyard_hits,
-    d2,
-    total_tokens_est,
-    budget: config.context_budget,
-    over_budget: total_tokens_est > config.context_budget,
-  };
+      return systems.some((s) => sys.includes(s));
+    })
+    .map((rec) => rec.trim());
 }

package/lib/frontmatter.js

@@ -15,8 +15,9 @@ export function parse(content) {
   try {
     data = YAML.parse(m[1]) ?? {};
   } catch (err) {
-    throw new Error(`Frontmatter YAML could not be parsed: ${err.message}`);
+    throw new Error(`Frontmatter YAML could not be parsed: ${err.message}`, { cause: err });
   }
+
   return { data, body: m[2], hasFrontmatter: true };
 }
 

package/lib/gcf-paths.js

@@ -19,6 +19,7 @@ const DEFAULT_CONFIG = {
 export function gcfRoot(projectDir = process.cwd()) {
   const root = path.join(path.resolve(projectDir), 'gcf');
   if (!existsSync(root)) throw new Error(`No gcf/ directory in ${projectDir}. Run gcf init first.`);
+
   return root;
 }
 
@@ -26,16 +27,23 @@ export async function readConfig(root) {
   const file = path.join(root, 'config.yml');
   if (!existsSync(file)) return { ...DEFAULT_CONFIG };
   const parsed = YAML.parse(await readFile(file, 'utf8')) ?? {};
-  if (typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('gcf/config.yml must be a key: value mapping');
+  if (typeof parsed !== 'object' || Array.isArray(parsed))
+    throw new Error('gcf/config.yml must be a key: value mapping');
   // A blank `key:` parses as null and means "not set", like an absent key.
-  const config = { ...DEFAULT_CONFIG, ...Object.fromEntries(Object.entries(parsed).filter(([, v]) => v !== null)) };
+  const config = {
+    ...DEFAULT_CONFIG,
+    ...Object.fromEntries(Object.entries(parsed).filter(([, v]) => v !== null)),
+  };
   // A limit that is not a number compares false against everything, which silently
   // switches its gate off — the one failure a gate must not have.
   for (const key of Object.keys(DEFAULT_CONFIG)) {
     if (!Number.isFinite(config[key]) || config[key] < 0) {
-      throw new Error(`gcf/config.yml: ${key} must be a non-negative number, got ${JSON.stringify(config[key])}`);
+      throw new Error(
+        `gcf/config.yml: ${key} must be a non-negative number, got ${JSON.stringify(config[key])}`,
+      );
     }
   }
+
   return config;
 }
 
@@ -52,6 +60,7 @@ async function listDocs(dir) {
     const { data, body } = parse(await readFile(file, 'utf8'));
     out.push({ file, name, data, body });
   }
+
   return out;
 }
 
@@ -61,11 +70,13 @@ export const listSystems = (root) => listDocs(path.join(root, 'systems'));
 /** First bullet of a `key:` block in a CNL-P body, for one-line descriptions. */
 export function firstBullet(body, key) {
   const m = String(body).match(new RegExp(`^${key}:\\s*\\n- (.+)$`, 'm'));
+
   return m ? m[1].trim() : '';
 }
 
 /** Scalar value of a `key:` line. */
 export function scalarOf(body, key) {
   const m = String(body).match(new RegExp(`^${key}:\\s*(.+)$`, 'm'));
+
   return m ? m[1].trim() : '';
 }

package/lib/git.js

@@ -13,7 +13,10 @@ export function snapshotIndex(cwd, files) {
   // -z: no C-quoting of non-ASCII paths, so the output is the path itself.
   const res = spawnSync('git', ['ls-files', '-s', '-z', '--', ...rels], { cwd, encoding: 'utf8' });
   if (res.status !== 0) return null;
-  const prefix = spawnSync('git', ['rev-parse', '--show-prefix'], { cwd, encoding: 'utf8' }).stdout.trim();
+  const prefix = spawnSync('git', ['rev-parse', '--show-prefix'], {
+    cwd,
+    encoding: 'utf8',
+  }).stdout.trim();
   const entries = new Map();
   const conflicted = new Set();
   for (const rec of res.stdout.split('\0').filter(Boolean)) {
@@ -22,7 +25,14 @@ export function snapshotIndex(cwd, files) {
     if (m[3] === '0') entries.set(m[4], { mode: m[1], blob: m[2] });
     else conflicted.add(m[4]);
   }
-  return { cwd, prefix, files: rels.filter((r) => !conflicted.has(r)).map((rel) => ({ rel, entry: entries.get(rel) ?? null })) };
+
+  return {
+    cwd,
+    prefix,
+    files: rels
+      .filter((r) => !conflicted.has(r))
+      .map((rel) => ({ rel, entry: entries.get(rel) ?? null })),
+  };
 }
 
 /** Put back the entries `snapshotIndex` took. Returns one Error per path it could not restore. */
@@ -33,10 +43,18 @@ export function restoreIndex(snapshot) {
     // --cacheinfo takes a path from the repository root and ignores the cwd; --force-remove
     // takes one relative to the cwd.
     const args = entry
-      ? ['update-index', '--add', '--cacheinfo', `${entry.mode},${entry.blob},${snapshot.prefix}${rel}`]
+      ? [
+          'update-index',
+          '--add',
+          '--cacheinfo',
+          `${entry.mode},${entry.blob},${snapshot.prefix}${rel}`,
+        ]
       : ['update-index', '--force-remove', '--', rel];
     const res = spawnSync('git', args, { cwd: snapshot.cwd, encoding: 'utf8' });
-    if (res.status !== 0) errors.push(new Error(`could not restore the index entry of ${rel}: ${(res.stderr || '').trim() || res.error?.message}`));
+    const reason = (res.stderr || '').trim() || res.error?.message;
+    if (res.status !== 0)
+      errors.push(new Error(`could not restore the index entry of ${rel}: ${reason}`));
   }
+
   return errors;
 }