gcf-aif-ext 0.2.5 → 0.3.0

package/lib/design.js

@@ -0,0 +1,179 @@
+// Design Model (GCF-PRD §5.7): gcf/design/<system>.md holds design units, one `## <id>`
+// section each. A unit's body is the body its card carries once it is taken into work,
+// so one CNL-P profile per type serves both places.
+import { readFile, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseBlocks, itemsOf, readRecords, loadProfileAt } from 'cnlp-kit';
+
+export const SLUG_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+export const UNIT_TYPES = ['mechanic', 'resource', 'rule', 'constraint', 'entity'];
+// Only a soft unit becomes a card; a hard one leaves design/ through `gcf done`.
+export const CARD_TYPES = ['mechanic', 'resource'];
+export const HEADER_KEYS = [
+  'type',
+  'title',
+  'route',
+  'system',
+  'milestone',
+  'pillars',
+  'depends',
+  'source',
+  'flags',
+  'reopens',
+];
+// Engineering decisions of the agent, not words of the designer: no provenance needed.
+export const AGENT_SLOTS = ['check', 'measure', 'contract', 'interactions'];
+
+const PROFILES_DIR = fileURLToPath(new URL('../profiles/', import.meta.url));
+
+/** The CNL-P profile of a document kind shipped in profiles/ (`unit-mechanic`, `game`, …). */
+export const loadDocProfile = (name) => loadProfileAt(path.join(PROFILES_DIR, `${name}.md`));
+
+/** `[a, b]`, `a, b` → ['a', 'b']; `none` and `[]` → []; `TBD` stays the string 'TBD'. */
+export function listOf(value) {
+  const v = String(value ?? '').trim();
+  if (v === 'TBD') return 'TBD';
+  const inner = v.replace(/^\[|\]$/g, '').trim();
+  if (!inner || inner === 'none') return [];
+
+  return inner
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/**
+ * @typedef {object} Unit
+ * @property {string} id
+ * @property {string} file    gcf-relative path of the design file
+ * @property {string} system  the subsystem the file names
+ * @property {number} line    1-based line of the `## <id>` heading
+ * @property {Record<string, string>} header
+ * @property {Record<string, number>} headerLines
+ * @property {string} body    the blocks below the header
+ * @property {number} bodyLine 1-based file line the body starts at
+ */
+
+/** Header fields at the top of a unit: `key: value` lines until the first other key. */
+function splitHeader(lines, start) {
+  /** @type {Record<string, string>} */
+  const header = {};
+  /** @type {Record<string, number>} */
+  const headerLines = {};
+  let i = 0;
+  for (; i < lines.length; i++) {
+    if (!lines[i].trim()) continue;
+    const m = lines[i].match(/^([a-z_]+):\s*(.*)$/);
+    if (!m || !HEADER_KEYS.includes(m[1]) || m[1] in header) break;
+    header[m[1]] = m[2].trim();
+    headerLines[m[1]] = start + i;
+  }
+
+  return { header, headerLines, rest: i };
+}
+
+/**
+ * One design file → `{ system, file, preamble, units }`. The preamble is everything above the
+ * first `## <id>`: the `# <system>` title and the subsystem's `purpose:` block.
+ */
+export function parseDesign(text, system, file = `design/${system}.md`) {
+  const lines = String(text).split(/\r?\n/);
+  const starts = lines.flatMap((l, i) => (/^## \S/.test(l) ? [i] : []));
+  const preamble = lines.slice(0, starts[0] ?? lines.length).join('\n');
+  /** @type {Unit[]} */
+  const units = starts.map((at, n) => {
+    const chunk = lines.slice(at + 1, starts[n + 1] ?? lines.length);
+    const { header, headerLines, rest } = splitHeader(chunk, at + 2);
+
+    return {
+      id: lines[at].slice(3).trim(),
+      file,
+      system,
+      line: at + 1,
+      header,
+      headerLines,
+      body: chunk.slice(rest).join('\n'),
+      bodyLine: at + 2 + rest,
+    };
+  });
+
+  return { system, file, preamble, units };
+}
+
+/** Every design file of a project, parsed; [] when gcf/design/ does not exist. */
+export async function readDesign(root) {
+  const dir = path.join(root, 'design');
+  if (!existsSync(dir)) return [];
+  const names = (await readdir(dir)).filter((n) => n.endsWith('.md')).sort();
+
+  return Promise.all(
+    names.map(async (n) =>
+      parseDesign(await readFile(path.join(dir, n), 'utf8'), n.slice(0, -3), `design/${n}`),
+    ),
+  );
+}
+
+/** A scalar `key:` value from a preamble or a body. */
+export function scalarIn(text, key) {
+  return parseBlocks(text).sections.find((s) => s.key === key)?.value ?? '';
+}
+
+/**
+ * Every value a body's slots carry: a scalar, a bullet, or a record value other than `name`
+ * (a record's name addresses it, it states nothing). `provenance` is metadata, not a slot.
+ */
+export function slotValues(body, profile) {
+  const { lines, sections } = parseBlocks(body);
+  const forms = new Map(profile.sections.map((s) => [s.key, s.form]));
+  const out = [];
+  for (const s of sections.filter((x) => x.key !== 'provenance')) {
+    if (s.value) {
+      out.push({ block: s.key, value: s.value, line: s.line, name: null });
+      continue;
+    }
+
+    const items = itemsOf(lines, s.line);
+    if (forms.get(s.key) === 'record-list') out.push(...recordValues(s.key, items));
+    else
+      out.push(
+        ...items.map((i) => ({
+          block: s.key,
+          value: i.text.replace(/^- /, ''),
+          line: i.line,
+          name: null,
+        })),
+      );
+  }
+
+  return out;
+}
+
+function recordValues(block, items) {
+  const out = [];
+  for (const rec of readRecords(items).records) {
+    const name = rec.values.name ?? null;
+    for (const k of rec.keys.filter((x) => x !== 'name')) {
+      out.push({ block, value: rec.values[k], line: rec.line, name });
+    }
+  }
+
+  return out;
+}
+
+/** The provenance records of a body: `{ slot, src, quote, answer, assumed, line }`. */
+export function provenanceOf(body) {
+  const { lines, sections } = parseBlocks(body);
+  const at = sections.find((s) => s.key === 'provenance');
+  if (!at) return [];
+
+  return readRecords(itemsOf(lines, at.line)).records.map((r) => ({
+    ...r.values,
+    quote: r.values.quote?.replace(/^"/, '').replace(/"$/, ''),
+    line: r.line,
+  }));
+}
+
+/** A value that says "not known yet": the whole value, or the tail of `- <subject>: TBD`. */
+export const isTbd = (v) => v === 'TBD' || /: TBD$/.test(v);

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

@@ -1,6 +1,69 @@
 import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
 import path from 'node:path';
 
+// `git commit --only <paths>` is a partial commit, which git refuses outright while a merge
+// or a sequencer operation is in progress. Detect it up front so the failure has a reason.
+const IN_PROGRESS = [
+  'MERGE_HEAD',
+  'CHERRY_PICK_HEAD',
+  'REVERT_HEAD',
+  'rebase-merge',
+  'rebase-apply',
+];
+
+/** The name of the merge or sequencer operation in progress, or null. */
+export function operationInProgress(projectDir) {
+  const gitDir = spawnSync('git', ['rev-parse', '--git-dir'], {
+    cwd: projectDir,
+    encoding: 'utf8',
+  });
+  if (gitDir.status !== 0) return null;
+  const dir = path.resolve(projectDir, gitDir.stdout.trim());
+
+  return IN_PROGRESS.find((name) => existsSync(path.join(dir, name))) ?? null;
+}
+
+const tracked = (projectDir, p) =>
+  spawnSync('git', ['ls-files', '--error-unmatch', '--', p], { cwd: projectDir, stdio: 'ignore' })
+    .status === 0;
+
+/**
+ * Paths with uncommitted changes, staged or not. A move stages whole files, so a user's own
+ * edit in one of them would ride along in the move's commit unseen.
+ */
+export function dirtyPaths(projectDir, paths) {
+  // No existence filter: a staged deletion is neither on disk nor in the index, and a move
+  // writing that file anew would commit away every line the deleted file held.
+  if (!paths.length) return [];
+  const res = spawnSync('git', ['status', '--porcelain', '--', ...paths], {
+    cwd: projectDir,
+    encoding: 'utf8',
+  });
+
+  return res.status === 0 ? res.stdout.split('\n').filter(Boolean) : [];
+}
+
+/**
+ * Stage and commit exactly `paths`: `git add -- gcf/` would stage a user's unrelated edits
+ * under gcf/, and a rollback only restores what it snapshotted. A path that neither exists nor
+ * is tracked is left out — git refuses a pathspec that matches nothing. Returns the new HEAD.
+ */
+export function commitPaths(projectDir, message, paths) {
+  const real = paths.filter((p) => existsSync(p) || tracked(projectDir, p));
+  for (const p of real) spawnSync('git', ['add', '--', p], { cwd: projectDir, stdio: 'ignore' });
+  const res = spawnSync('git', ['commit', '-m', message, '--only', '--', ...real], {
+    cwd: projectDir,
+    encoding: 'utf8',
+  });
+  if (res.status !== 0) throw new Error(`commit failed: ${res.stderr || res.stdout}`);
+
+  return spawnSync('git', ['rev-parse', 'HEAD'], {
+    cwd: projectDir,
+    encoding: 'utf8',
+  }).stdout.trim();
+}
+
 /**
  * The stage-0 index entry (mode + blob) of each file, or `entry: null` when the index
  * holds none. Paths are taken relative to `cwd` (an existing directory inside the work
@@ -13,7 +76,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 +88,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 +106,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;
 }

package/lib/id.js

@@ -1,16 +1,17 @@
 import path from 'node:path';
 
-// GCF-PRD §5.2/§5.5: candidates are `cand-NNN`, cards are `card-NNN`; a card keeps the
-// candidate's number on materialization. The slug lives next to the id, not inside it.
-const ID_RE = /^(card|cand)-\d{3}$/;
+// GCF-PRD §5.8: a unit's id is a slug, one for every stage — the `## <id>` section in design/,
+// the card file cards/<id>.md, the graveyard line, the verdict commit. It is frozen once made.
+const ID_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 
-/** Derive a stable slug from a free-text name. Created once; never re-derived. */
+/** Derive a slug from a free-text name. Created once; never re-derived. */
 export function slugify(name) {
   const slug = String(name)
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, '-')
     .replace(/^-+|-+$/g, '');
   if (!slug) throw new Error(`Cannot derive a slug from: ${JSON.stringify(name)}`);
+
   return slug;
 }
 
@@ -18,14 +19,7 @@ export function isValidId(id) {
   return ID_RE.test(String(id ?? ''));
 }
 
-/** `cand-012` → `card-012`: materialization keeps the number (GCF-PRD §5.2). */
-export function candToCard(candId) {
-  const m = String(candId).match(/^cand-(\d{3})$/);
-  if (!m) throw new Error(`Not a candidate id: ${candId}`);
-  return `card-${m[1]}`;
-}
-
-/** Card filename invariant: `cards/<id>-<slug>.md`. */
-export function stemMatches(file, id, slug) {
-  return path.basename(file, '.md') === `${id}-${slug}`;
+/** Card filename invariant: `cards/<id>.md`. */
+export function stemMatches(file, id) {
+  return path.basename(file, '.md') === id;
 }

package/lib/index-gen.js

@@ -3,43 +3,94 @@ import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { listCards, listSystems, firstBullet } from './gcf-paths.js';
 import { atomicWrite } from './safe-path.js';
+import { readDesign, slotValues, loadDocProfile, isTbd, UNIT_TYPES } from './design.js';
 
 /**
  * INDEX.md is a deterministic function of gcf/ contents (GCF-PRD §5.1): generated,
  * never hand-written. The pre-commit hook regenerates it and stages the result.
  */
+const SINGLETONS = [
+  ['pillars', 'PILLARS.md', 'pillars and negative invariants'],
+  ['game', 'game.md', 'vision, scope and milestones'],
+  ['glossary', 'glossary.md', 'terms and forbidden synonyms'],
+];
+
 export async function generate(root) {
   const lines = ['# INDEX — generated, do not edit', ''];
-  const row = (type, file, status, system, descr) =>
+  const row = ([type, file, status, system, descr]) =>
     lines.push(`${type} | gcf/${file} | ${status} | ${system} | ${descr}`);
 
-  if (existsSync(path.join(root, 'PILLARS.md'))) row('pillars', 'PILLARS.md', '-', '-', 'pillars and negative invariants');
-  if (existsSync(path.join(root, 'backlog.md'))) {
-    const count = ((await readFile(path.join(root, 'backlog.md'), 'utf8')).match(/^- cand-/gm) ?? []).length;
-    row('backlog', 'backlog.md', '-', '-', `${count} candidates`);
+  for (const [type, file, descr] of SINGLETONS) {
+    if (existsSync(path.join(root, file))) row([type, file, '-', '-', descr]);
+  }
+
+  const backlog = await readIfExists(root, 'backlog.md');
+  if (backlog !== null) {
+    row(['backlog', 'backlog.md', '-', '-', `${count(backlog, /^- \S+/gm)} units in order`]);
   }
+
+  // One row per subsystem, not per unit: INDEX is the one file read whole.
+  for (const d of await readDesign(root)) {
+    const tbd = await tbdCount(d.units);
+    row(['design', d.file, '-', d.system, `${d.units.length} units, ${tbd} TBD`]);
+  }
+
   for (const s of await listSystems(root)) {
-    row('system', `systems/${s.name}`, '-', s.data.system ?? '-', firstBullet(s.body, 'purpose'));
+    const purpose = firstBullet(s.body, 'purpose');
+    row(['system', `systems/${s.name}`, '-', s.data.system ?? '-', purpose]);
   }
+
   for (const c of await listCards(root)) {
-    row('card', `cards/${c.name}`, c.data.status ?? '?', (c.data.system ?? []).join(','), firstBullet(c.body, 'behavior'));
-  }
-  if (existsSync(path.join(root, 'graveyard.md'))) {
-    const count = ((await readFile(path.join(root, 'graveyard.md'), 'utf8')).match(/^- card-/gm) ?? []).length;
-    row('graveyard', 'graveyard.md', '-', '-', `${count} killed ideas`);
+    const system = (c.data.system ?? []).join(',');
+    row(['card', `cards/${c.name}`, c.data.status ?? '?', system, firstBullet(c.body, 'intent')]);
   }
-  if (existsSync(path.join(root, 'open-questions.md'))) {
-    const txt = await readFile(path.join(root, 'open-questions.md'), 'utf8');
-    const d1 = (txt.match(/^\s*class:\s*D1/gm) ?? []).length;
-    const d2 = (txt.match(/^\s*class:\s*D2/gm) ?? []).length;
-    row('questions', 'open-questions.md', '-', '-', `${d1} D1, ${d2} D2`);
+
+  await endRows(root, row);
+
+  const txt = await readIfExists(root, 'open-questions.md');
+  if (txt !== null) {
+    const d1 = count(txt, /^\s*class:\s*D1/gm);
+    const d2 = count(txt, /^\s*class:\s*D2/gm);
+    row(['questions', 'open-questions.md', '-', '-', `${d1} D1, ${d2} D2`]);
   }
+
   return `${lines.join('\n')}\n`;
 }
 
+/** The rows of the files that record how lives ended: one count per file. */
+async function endRows(root, row) {
+  for (const [type, what] of [
+    ['history', 'built or kept'],
+    ['graveyard', 'killed ideas'],
+  ]) {
+    const text = await readIfExists(root, `${type}.md`);
+    if (text !== null) row([type, `${type}.md`, '-', '-', `${count(text, /^- \S+ \|/gm)} ${what}`]);
+  }
+}
+
+async function readIfExists(root, rel) {
+  const file = path.join(root, rel);
+
+  return existsSync(file) ? readFile(file, 'utf8') : null;
+}
+
+const count = (text, re) => (text.match(re) ?? []).length;
+
+/** TBD values across units, read with each unit's own profile; an unknown type counts none. */
+async function tbdCount(units) {
+  let n = 0;
+  for (const u of units.filter((x) => UNIT_TYPES.includes(x.header.type))) {
+    const values = slotValues(u.body, await loadDocProfile(`unit-${u.header.type}`));
+    n += values.filter((v) => isTbd(v.value)).length;
+  }
+
+  return n;
+}
+
 export async function writeIndex(root) {
   const content = await generate(root);
   await atomicWrite(path.join(root, 'INDEX.md'), content);
+
   return content;
 }
 
@@ -47,5 +98,6 @@ export async function writeIndex(root) {
 export async function drifted(root) {
   const file = path.join(root, 'INDEX.md');
   if (!existsSync(file)) return true;
+
   return (await readFile(file, 'utf8')) !== (await generate(root));
 }

package/lib/ledger.js

@@ -0,0 +1,92 @@
+// Where an id lives (GCF-PRD §5.8): a live place is a section of design/ or a file of cards/,
+// an end is the line the move wrote in the commit that ended the life — history.md for done and
+// keep, graveyard.md for drop and kill. Files, not commit messages: a squash, a shallow clone or
+// a rewritten history keeps them, and a revert of the move takes its line out with it.
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { readDesign } from './design.js';
+import { listCards } from './gcf-paths.js';
+
+const HISTORY_EVENTS = ['done', 'collapsed'];
+
+/** `[id, second field]` of each line `- <id> | <field> | …` of a gcf file. */
+async function recordLines(root, name) {
+  const file = path.join(root, name);
+  if (!existsSync(file)) return [];
+
+  return (await readFile(file, 'utf8')).split('\n').flatMap((l) => {
+    const m = l.match(/^- (\S+) \|\s*([^|]*?)\s*(?:\||$)/);
+
+    return m ? [[m[1], m[2]]] : [];
+  });
+}
+
+const gitOut = (args, cwd) => {
+  const res = spawnSync('git', args, { cwd, encoding: 'utf8' });
+
+  return res.status === 0 ? res.stdout : null;
+};
+
+/** Ids HEAD holds as a card file or a design section. */
+function headIds(projectDir) {
+  const files = gitOut(
+    ['ls-tree', '-r', '--name-only', 'HEAD', '--', 'gcf/cards', 'gcf/design'],
+    projectDir,
+  );
+  const ids = new Set();
+  // Top level only, as readDesign and listCards read: a nested archive file is not a unit.
+  for (const f of (files ?? '')
+    .split('\n')
+    .filter((x) => /^gcf\/(cards|design)\/[^/]+\.md$/.test(x))) {
+    if (f.startsWith('gcf/cards/')) ids.add(path.basename(f, '.md'));
+    // `./` makes the path relative to the cwd, as ls-tree printed it.
+    else
+      for (const m of (gitOut(['show', `HEAD:./${f}`], projectDir) ?? '').matchAll(/^## (\S+)/gm))
+        ids.add(m[1]);
+  }
+
+  return ids;
+}
+
+/**
+ * @typedef {object} Place
+ * @property {'design' | 'card'} state
+ * @property {string} file gcf-relative
+ */
+
+/**
+ * Build the ledger of a project: `where(id)` answers `{ live, terminal }` — the live places
+ * (a design section, a card file) and the terminal events (collapsed, killed, done).
+ */
+export async function buildLedger(projectDir) {
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const design = await readDesign(root);
+  const cards = await listCards(root);
+  /** @type {Map<string, Place[]>} */
+  const live = new Map();
+  const add = (id, place) => live.set(id, [...(live.get(id) ?? []), place]);
+  for (const d of design) for (const u of d.units) add(u.id, { state: 'design', file: d.file });
+  for (const c of cards) add(String(c.data.id), { state: 'card', file: `cards/${c.name}` });
+
+  /** @type {Map<string, Set<string>>} */
+  const terminal = new Map();
+  const mark = (id, event) => terminal.set(id, (terminal.get(id) ?? new Set()).add(event));
+  for (const [id, event] of await recordLines(root, 'history.md'))
+    if (HISTORY_EVENTS.includes(event)) mark(id, event);
+  for (const [id] of await recordLines(root, 'graveyard.md')) mark(id, 'killed');
+  // An id HEAD holds that has no live place and no terminal line is vanishing in this commit:
+  // it is not known, so a card or unit still citing it fails M2 in this very commit, and
+  // `vanished()` lets the gate warn that its reason was lost.
+  const vanished = [...headIds(projectDir)].filter((id) => !live.has(id) && !terminal.has(id));
+
+  return {
+    design,
+    cards,
+    where: (id) => ({ id, live: live.get(id) ?? [], terminal: [...(terminal.get(id) ?? [])] }),
+    known: (id) => live.has(id) || terminal.has(id),
+    ids: () => [...new Set([...live.keys(), ...terminal.keys()])].sort(),
+    vanished: () => vanished,
+  };
+}