gcf-aif-ext 0.2.7 → 0.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 The Game Context Framework as an [AI Factory](https://github.com/lee-to/ai-factory) extension: a documentary layer for building games with an AI agent, where the documents hold **state instead of history**.
 
-One overwritable document per subsystem. Feature cards that collapse into those documents on a human playtest verdict and then cease to exist. A graveyard that keeps the reasons things were killed. Read rules that keep the token cost of a task flat as the project ages.
+A Design Model: the design lives in `gcf/design/<system>.md` as units with typed slots — what the GDD says, quoted and anchored, and `TBD` for everything it does not. A soft unit taken into work becomes a feature card with the same body; the card collapses into its subsystem's document on a human playtest verdict and then ceases to exist. A hard unit leaves through its tests. A graveyard keeps the reasons things were killed. Read rules keep the token cost of a task flat as the project ages.
 
 Runtime-agnostic — everything here works on any AI Factory runtime. The Claude-Code-specific orchestration lives in [`gcf-harness-aif-ext`](../gcf-harness-aif-ext), which is optional.
 
@@ -58,11 +58,13 @@ Removal leaves `gcf/` and `cnlp.config.json` in place. It also leaves the pre-co
 
 **Skills** — `gcf-init`, `gcf-adopt`, `gcf-card`, `gcf-verdict`, `gcf-audit`, `gcf-vision`, `gcf-debate`, `gcf-ingest`.
 
-**A deterministic core** behind `ai-factory gcf …` — `init`, `index`, `context`, `audit`, `playtest`, `verdict`, `anchor`, `section`, `quotes`, `lint`, `hooks-install`. These are plain Node scripts with no LLM in the loop: the same functions the skills call, the pre-commit gate runs, and the harness gates against.
+**A deterministic core** behind `ai-factory gcf …` — `init`, `index`, `context`, `audit`, `playtest`, `verdict`, `anchor`, `section`, `quotes`, `lint`, `design check`, `where`, `take`, `done`, `drop`, `hooks-install`. These are plain Node scripts with no LLM in the loop: the same functions the skills call, the pre-commit gate runs, and the harness gates against.
 
-**A pre-commit gate** that breaks the commit on a terminal status stored in a card file, a malformed `[until:]` annotation, a card built on an unplayed dependency, a dependency that names no known card, or a П2 linter finding in a subsystem document. It regenerates `gcf/INDEX.md` and stages it for you.
+**A pre-commit gate** that breaks the commit on a terminal status stored in a card file, a malformed `[until:]` annotation, a card built on an unplayed dependency, a dependency that names no known id, a П2 linter finding in a subsystem document, or a blocking design-check finding: a malformed unit or card, a digit in prose, a forbidden synonym, a quote that is not verbatim in its GDD section, an id living in two places, a backlog out of step with `gcf/design/`. An unfinished unit (`TBD`) never breaks a commit. The gate regenerates `gcf/INDEX.md` and stages it for you.
 
-**CNLP profiles and a card schema** for the documents the agent reads, plus injections into `aif-plan`, `aif-review` and `aif-commit`.
+**CNLP profiles and a card schema** for the documents the agent reads — one profile per unit type, shared by a unit and its card — plus injections into `aif-plan`, `aif-review` and `aif-commit`.
+
+**Upgrading from 0.2.x:** a card is schema 2 now — `cards/<id>.md` with a slug id, `type`, `pillars`, no `slug` and no `route`; the gate names the steps for a schema 1 card. Backlog candidate lines (`cand-NNN | …`) become units in `gcf/design/` with `ai-factory gcf design migrate` (deterministic, no commit): it keeps the backlog order, writes the quote as provenance and every slot the line did not carry as `TBD`, rewrites `cand-NNN` references in `open-questions.md` and `graveyard.md`, and copies the keeps and dones of old commit messages into `gcf/history.md` once — the ledger reads that file, not the log. Then run `ai-factory gcf design check`, fix what it reports — typically a digit in a description — and commit.
 
 ## Docs
 

package/commands/gcf.js

@@ -1,6 +1,6 @@
 // CLI wrapper over the deterministic core (GCF-PRD §10.1): harness and human call
 // the same functions. Registered by AIF via extension.json `commands`.
-import { mkdir, copyFile, readFile } from 'node:fs/promises';
+import { mkdir, copyFile, readFile, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
@@ -70,8 +70,24 @@ function aif(args) {
 
 const today = () => new Date().toISOString().slice(0, 10);
 
+const UNION = ['gcf/history.md merge=union', 'gcf/graveyard.md merge=union'];
+
+/**
+ * Two branches that end different lives may add their lines at the same spot of history.md or
+ * graveyard.md: a union merge keeps both instead of a conflict whose "ours" loses one. Adds the
+ * missing rules to `<dir>/.gitattributes`; a project that ran an older init gets them on re-run.
+ */
+export async function unionAttributes(dir) {
+  const file = path.join(dir, '.gitattributes');
+  const text = existsSync(file) ? await readFile(file, 'utf8') : '';
+  const missing = UNION.filter((rule) => !text.split(/\r?\n/).includes(rule));
+  if (!missing.length) return;
+  const sep = text && !text.endsWith('\n') ? '\n' : '';
+  await writeFile(file, `${text}${sep}${missing.join('\n')}\n`, 'utf8');
+}
+
 async function seedSkeleton(root) {
-  for (const dir of ['cards', 'systems', 'source', '.metrics']) {
+  for (const dir of ['design', 'cards', 'systems', 'source', '.metrics']) {
     await mkdir(path.join(root, dir), { recursive: true });
   }
 
@@ -86,8 +102,14 @@ async function seedSkeleton(root) {
     if (!existsSync(target)) await copyFile(path.join(EXT_ROOT, 'templates', tpl), target);
   }
 
+  const { HISTORY_HEAD } = await lib('verdict-fs');
   for (const [name, header] of [
-    ['graveyard.md', '# Graveyard — one line per killed idea, written by gcf verdict kill\n'],
+    ['history.md', HISTORY_HEAD],
+    [
+      'graveyard.md',
+      '# Graveyard — `- <id> | <reason> | tags: <tags>`, one line per idea killed by a verdict ' +
+        'or dropped before work\n',
+    ],
     [
       'open-questions.md',
       '# Open questions — records with id/lens/sections/sys/class/question/proposed, ' +
@@ -95,13 +117,13 @@ async function seedSkeleton(root) {
     ],
   ]) {
     const target = path.join(root, name);
-    if (!existsSync(target))
-      await (await import('node:fs/promises')).writeFile(target, header, 'utf8');
+    if (!existsSync(target)) await writeFile(target, header, 'utf8');
   }
 
   const cnlpCfg = path.join(process.cwd(), 'cnlp.config.json');
   if (!existsSync(cnlpCfg))
     await copyFile(path.join(EXT_ROOT, 'templates', 'cnlp.config.json'), cnlpCfg);
+  await unionAttributes(process.cwd());
 }
 
 async function offerHarness(program, opts) {
@@ -134,8 +156,8 @@ function registerInit(gcf, program) {
       const { writeIndex } = await lib('index-gen');
       await writeIndex(root);
       console.log(
-        'gcf/ ready. Write PILLARS.md through /gcf-init, then add candidates to backlog.md ' +
-          'or import a GDD with /gcf-ingest.',
+        'gcf/ ready. Write PILLARS.md through /gcf-init, then import a GDD with /gcf-ingest ' +
+          'or start the design with /gcf-vision.',
       );
       await offerHarness(program, opts);
     });
@@ -222,7 +244,7 @@ function registerPlaytest(gcf) {
       const list = await playtestList(gcfRoot());
       out(opts.json, list, (l) =>
         l.length
-          ? l.map((c) => `${c.id} ${c.slug} [${c.system.join(',')}]: ${c.question}`).join('\n')
+          ? l.map((c) => `${c.id} [${c.system.join(',')}]: ${c.question}`).join('\n')
           : 'nothing in built — nothing to playtest',
       );
     });
@@ -267,19 +289,23 @@ function registerAnchor(gcf) {
     )
     .option('--json', 'machine output')
     .action(async (file, opts) => {
-      const { splitSections, importSource, loadAnchorMap, classifyDelta } = await lib('anchors');
+      const anchors = await lib('anchors');
+      const { splitSections, importSource, loadAnchorMap, classifyDelta } = anchors;
       const base = path.basename(file);
       const oldMap = await loadAnchorMap(process.cwd(), base);
       const { readFile } = await import('node:fs/promises');
       const sections = splitSections(await readFile(file, 'utf8'));
       const delta = oldMap?.anchors ? classifyDelta(oldMap.anchors, sections) : null;
       await importSource(process.cwd(), file);
+      // A renamed heading moves its anchor: provenance and source: follow it.
+      const rewritten = delta ? await anchors.rewriteAnchors(process.cwd(), delta.renamed) : [];
       const rebaselined = Boolean(oldMap?.rebaselined);
       const result = {
         file: `gcf/source/${base}`,
         sections: sections.map((s) => ({ anchor: s.anchor, heading: s.heading, lines: s.lines })),
         delta,
         rebaselined,
+        rewritten,
       };
       out(opts.json, result, (r) =>
         [
@@ -287,6 +313,7 @@ function registerAnchor(gcf) {
             (s) => `${s.anchor}  L${s.lines[0]}-${s.lines[1]}  ${s.heading ?? '(preamble)'}`,
           ),
           anchorDeltaLine(r),
+          ...r.rewritten.map((f) => `renamed anchors rewritten in gcf/${f}`),
         ].join('\n'),
       );
     });
@@ -308,18 +335,165 @@ function registerSection(gcf) {
 function registerQuotes(gcf) {
   gcf
     .command('quotes')
-    .description('Verify each backlog q: quote is verbatim in its src: section (GCF-PRD §11.2)')
+    .description('Provenance only: every quote verbatim in its src: section (design check M9)')
     .option('--json', 'machine output')
     .action(async (opts) => {
-      const { checkQuotes } = await lib('anchors');
-      const problems = await checkQuotes(process.cwd());
+      const { designCheck } = await lib('design-check');
+      const problems = (await designCheck(process.cwd())).issues.filter((i) => i.check === 'M9');
       out(opts.json, problems, (l) =>
-        l.length ? l.map((p) => `${p.id} ${p.anchor}: ${p.problem}`).join('\n') : 'clean',
+        l.length ? l.map((p) => `${p.file}:${p.line} ${p.id}: ${p.message}`).join('\n') : 'clean',
       );
       if (problems.length) process.exitCode = 1;
     });
 }
 
+const issueLine = (i) => `${i.severity} ${i.check} ${i.file}:${i.line} ${i.id ?? ''} ${i.message}`;
+
+function designSummary(r) {
+  const rows = Object.entries(r.systems).map(
+    ([s, t]) => `${s}: ${t.units} units, ${t.ready} ready, ${t.tbd}/${t.values} TBD`,
+  );
+  const blocking = r.issues.filter((i) => i.severity === 'block');
+  const notes = r.issues.filter((i) => i.severity === 'report');
+
+  return [
+    ...blocking.map(issueLine),
+    ...notes.map(issueLine),
+    ...rows,
+    blocking.length ? `${blocking.length} blocking finding(s)` : 'no blocking findings',
+  ].join('\n');
+}
+
+function registerDesign(gcf) {
+  const design = gcf.command('design').description('Design Model: units in gcf/design/');
+  design
+    .command('check')
+    .description('Mechanical checks over gcf/design/ and the cards; exit 1 on a blocking finding')
+    .option('--json', 'machine output')
+    .action(async (opts) => {
+      const { designCheck } = await lib('design-check');
+      const report = await designCheck(process.cwd());
+      out(opts.json, report, designSummary);
+      if (report.blocking) process.exitCode = 1;
+    });
+  design
+    .command('export')
+    .description('Glue game.md, glossary.md and the units into one bundle a designer edits')
+    .option('--system <name>', 'only this subsystem')
+    .option('--milestone <name>', 'only the units of this milestone')
+    .option('--out <file>', 'write the bundle here instead of stdout')
+    .action(async (opts) => {
+      const { exportBundle } = await lib('bundle');
+      const text = await exportBundle(process.cwd(), opts);
+      if (!opts.out) return void process.stdout.write(text);
+      const { writeFile } = await import('node:fs/promises');
+      await writeFile(opts.out, text, 'utf8');
+      console.log(`bundle written → ${opts.out}`);
+    });
+  design
+    .command('import <bundle>')
+    .description('Bring an edited bundle back: 3-way by base hash, conflicts reported, no commit')
+    .option('--json', 'machine output')
+    .action(async (bundle, opts) => {
+      const { importBundle } = await lib('bundle');
+      const r = await importBundle(process.cwd(), await readFile(bundle, 'utf8'));
+      out(opts.json, r, (x) =>
+        [
+          ...x.applied.map((a) => `applied ${a}`),
+          ...x.report.map((p) => `${p.outcome} ${p.part}: ${p.note}`),
+          x.applied.length || x.report.length ? '' : 'nothing changed',
+        ]
+          .filter(Boolean)
+          .join('\n'),
+      );
+      if (r.report.some((p) => p.outcome !== 'deleted')) process.exitCode = 1;
+    });
+  registerMigrate(design);
+}
+
+function registerMigrate(design) {
+  design
+    .command('migrate')
+    .description('One-shot: backlog cand-NNN lines become units in gcf/design/ (no commit)')
+    .option(
+      '--skip <ids>',
+      'converted by hand, comma-separated: cand-NNN, cand-NNN=<id> or cand-NNN=<id>+<id>',
+    )
+    .action(async (opts) => {
+      const { migrateBacklog } = await lib('migrate');
+      const skip = opts.skip ? opts.skip.split(',').map((s) => s.trim()) : [];
+      const r = await migrateBacklog(process.cwd(), { skip });
+      for (const l of r.lost_depends) console.log(`lost depends: ${l} (map it: --skip cand=id)`);
+      for (const l of r.maybe_duplicates) console.log(`maybe a duplicate: ${l}`);
+      for (const l of r.unmoved_gaps) console.log(`check its unit holds these gaps: ${l}`);
+      console.log(
+        `${r.units} units written, ${r.skipped} skipped, ${r.history} history lines from git; ` +
+          'run ai-factory gcf design check',
+      );
+    });
+}
+
+const placeLines = (x) => [...x.live.map((p) => `${p.state} gcf/${p.file}`), ...x.terminal];
+
+function registerWhere(gcf) {
+  gcf
+    .command('where [id]')
+    .description('Where an id lives: a design section, a card, a terminal event; no id lists all')
+    .option('--json', 'machine output')
+    .action(async (id, opts) => {
+      const { buildLedger } = await lib('ledger');
+      const ledger = await buildLedger(process.cwd());
+      // Without an id: every id the project has used, so an import never mints a taken one.
+      if (!id) {
+        const all = ledger.ids().map((i) => ledger.where(i));
+        out(opts.json, all, (l) => l.map((x) => `${x.id}: ${placeLines(x).join(', ')}`).join('\n'));
+
+        return;
+      }
+
+      out(opts.json, ledger.where(id), (x) => placeLines(x).join('\n') || `${id} is unknown`);
+    });
+}
+
+function registerMoves(gcf) {
+  const ops = () => lib('unit-ops');
+  gcf
+    .command('take <id>')
+    .description('Move a ready soft unit from gcf/design/ into cards/<id>.md (no commit)')
+    .action(async (id) => console.log((await (await ops()).takeUnit(process.cwd(), id)).card));
+  gcf
+    .command('done <id>')
+    .description('A hard unit is built and tested: it leaves gcf/design/ (commit gcf(done))')
+    .option(
+      '--constraint <line>',
+      'a line every reader of the subsystem must remember',
+      (v, p) => [...p, v],
+      [],
+    )
+    .option('--no-commit', 'skip the commit (tests only)')
+    .action(async (id, o) => {
+      const r = await (
+        await ops()
+      ).doneUnit(process.cwd(), id, { constraints: o.constraint, commit: o.commit });
+      console.log(`done ${r.id}${r.hash ? ` (${r.hash.slice(0, 7)})` : ''}`);
+    });
+  gcf
+    .command('drop <id>')
+    .description(
+      'Drop a unit before any work: a graveyard line keeps the reason (commit gcf(drop))',
+    )
+    .requiredOption('--reason <text>', 'why the idea dies')
+    .option('--tags <list>', 'graveyard tags, comma-separated (default: its systems)')
+    .option('--no-commit', 'skip the commit (tests only)')
+    .action(async (id, o) => {
+      const tags = o.tags ? o.tags.split(',').map((t) => t.trim()) : [];
+      const r = await (
+        await ops()
+      ).dropUnit(process.cwd(), id, { reason: o.reason, tags, commit: o.commit });
+      console.log(`dropped ${r.id}${r.hash ? ` (${r.hash.slice(0, 7)})` : ''}`);
+    });
+}
+
 function registerHooksInstall(gcf) {
   gcf
     .command('hooks-install')
@@ -378,6 +552,9 @@ export function register(program) {
   registerAnchor(gcf);
   registerSection(gcf);
   registerQuotes(gcf);
+  registerDesign(gcf);
+  registerWhere(gcf);
+  registerMoves(gcf);
   registerHooksInstall(gcf);
   registerLint(gcf);
 }

package/extension.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/lee-to/ai-factory/2.x/schemas/extension.schema.json",
   "name": "gcf-aif-ext",
-  "version": "0.2.7",
+  "version": "0.3.0",
   "description": "Game Context Framework for AI Factory",
   "skills": [
     "skills/gcf-init",

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');
@@ -33,8 +34,8 @@ function git(args) {
 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) {
@@ -45,52 +46,55 @@ if (staged !== null) {
   }
 }
 
-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}`);
 
-function checkDep(c, dep) {
-  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)`);
+// 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 ?? []) {
+    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 cards) {
-  for (const dep of c.data.depends ?? []) checkDep(c, dep);
+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}`);

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/lib/anchors.js

@@ -155,27 +155,10 @@ export async function readSection(projectDir, baseName, anchor) {
   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) {
+export async function sourceBodies(sourceDir) {
   /** @type {Map<string, string[]>} */
   const bodies = new Map();
   if (!existsSync(sourceDir)) return bodies;
@@ -188,20 +171,39 @@ async function sourceBodies(sourceDir) {
   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 };
+/** 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;
 }