gcf-aif-ext 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleg (VirtualMaestro)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,41 @@
+# gcf-aif-ext
+
+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.
+
+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.
+
+## Requirements
+
+- AI Factory 2.x
+- Node.js ≥ 22.14
+- git (the enforcement gate is a pre-commit hook)
+
+## Install
+
+```bash
+ai-factory extension add <path-to>/packages/gcf-aif-ext
+ai-factory gcf init          # seeds gcf/ and cnlp.config.json
+ai-factory gcf hooks-install # installs the pre-commit gate
+```
+
+Then `/gcf-vision` for a brand-new game, `/gcf-adopt` for a project that already has code, `/gcf-ingest <gdd.md>` for an existing design doc, or `/gcf-card` to start a feature by hand.
+
+## What it adds
+
+**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`, `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 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.
+
+**CNLP profiles and a card schema** for the documents the agent reads, plus injections into `aif-plan`, `aif-review` and `aif-commit`.
+
+## Docs
+
+Full documentation lives in the [repository](https://github.com/VirtualMaestro/GCF): the [Usage Guide](https://github.com/VirtualMaestro/GCF/blob/main/docs/Usage-Guide.md) (RU) for day-to-day work, and [GCF-PRD](https://github.com/VirtualMaestro/GCF/blob/main/docs/GCF-PRD.md) for the spec — principles, data model, lifecycle, enforcement.
+
+## License
+
+MIT

package/commands/gcf.js

@@ -0,0 +1,173 @@
+// 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 { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const EXT_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+const lib = (name) => import(new URL(`../lib/${name}.js`, import.meta.url));
+
+// Must stay byte-identical to the comment line inside the shim below: hooks-install
+// refuses to overwrite a pre-commit hook that does not carry it.
+const MARKER = 'gcf-aif-ext pre-commit gate';
+
+const out = (json, value, human) => console.log(json ? JSON.stringify(value, null, 2) : human(value));
+
+export function register(program) {
+  const gcf = program.command('gcf').description('Game Context Framework core');
+
+  gcf.command('init')
+    .description('Create the gcf/ skeleton from templates (idempotent, never overwrites)')
+    .action(async () => {
+      const root = path.join(process.cwd(), 'gcf');
+      for (const dir of ['cards', 'systems', 'source', '.metrics']) {
+        await mkdir(path.join(root, dir), { recursive: true });
+      }
+      const seed = [
+        ['PILLARS.md', 'PILLARS.md'], ['backlog.md', 'backlog.md'], ['config.yml', 'config.yml'],
+      ];
+      for (const [tpl, dst] of seed) {
+        const target = path.join(root, dst);
+        if (!existsSync(target)) await copyFile(path.join(EXT_ROOT, 'templates', tpl), target);
+      }
+      for (const [name, header] of [
+        ['graveyard.md', '# Graveyard — one line per killed idea, written by gcf verdict kill\n'],
+        ['open-questions.md', '# Open questions — records with id/lens/sections/sys/class/proposed; answers move out, records die\n'],
+      ]) {
+        const target = path.join(root, name);
+        if (!existsSync(target)) await (await import('node:fs/promises')).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);
+      const { writeIndex } = await lib('index-gen');
+      await writeIndex(root);
+      console.log('gcf/ ready. Edit PILLARS.md, then add candidates to backlog.md.');
+    });
+
+  gcf.command('index')
+    .description('Regenerate gcf/INDEX.md (deterministic)')
+    .action(async () => {
+      const { gcfRoot } = await lib('gcf-paths');
+      const { writeIndex } = await lib('index-gen');
+      await writeIndex(gcfRoot());
+      console.log('INDEX.md regenerated');
+    });
+
+  gcf.command('context <card-id>')
+    .description('Assemble the readset for a card (GCF-PRD §9.1)')
+    .option('--json', 'machine output')
+    .action(async (cardId, opts) => {
+      const { buildContext } = await lib('context');
+      const ctx = await buildContext(process.cwd(), cardId);
+      // Metric 1 (GCF-PRD §14): readset size over time, one csv line per call.
+      const { appendFile, mkdir } = await import('node:fs/promises');
+      const metricsDir = path.join(process.cwd(), 'gcf', '.metrics');
+      await mkdir(metricsDir, { recursive: true });
+      await appendFile(path.join(metricsDir, 'context-log.csv'),
+        `${new Date().toISOString().slice(0, 10)},${cardId},${ctx.files.length},${ctx.total_tokens_est}\n`, 'utf8');
+      out(opts.json, ctx, (c) =>
+        [
+          ...c.files.map((f) => `${f.path} (${f.tokens_est})`),
+          ...(c.graveyard_hits.length ? ['graveyard hits:', ...c.graveyard_hits] : []),
+          `total ~${c.total_tokens_est} / ${c.budget}${c.over_budget ? ' OVER BUDGET' : ''}`,
+        ].join('\n'));
+      if (ctx.over_budget) process.exitCode = 2;
+    });
+
+  gcf.command('audit')
+    .description('Deterministic consistency audit (GCF-PRD §10.1)')
+    .option('--json', 'machine output')
+    .action(async (opts) => {
+      const { audit } = await lib('audit-core');
+      const report = await audit(process.cwd());
+      // Metric 2 (GCF-PRD §14): findings per audit run.
+      const findings = report.stale_built.length + report.tune_limit.length
+        + report.until.filter((u) => u.status === 'stale').length + Object.keys(report.linter).length;
+      const { appendFile, mkdir } = await import('node:fs/promises');
+      const metricsDir = path.join(process.cwd(), 'gcf', '.metrics');
+      if (existsSync(path.join(process.cwd(), 'gcf'))) {
+        await mkdir(metricsDir, { recursive: true });
+        await appendFile(path.join(metricsDir, 'audit-log.csv'), `${new Date().toISOString().slice(0, 10)},${findings}\n`, 'utf8');
+      }
+      out(opts.json, report, (r) => r.first_line);
+      if (report.first_line !== 'clean') process.exitCode = 1;
+    });
+
+  gcf.command('playtest')
+    .description('List built cards with their miss-criterion questions')
+    .option('--json', 'machine output')
+    .action(async (opts) => {
+      const { gcfRoot } = await lib('gcf-paths');
+      const { playtestList } = await lib('playtest-list');
+      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')
+        : 'nothing in built — nothing to playtest'));
+    });
+
+  gcf.command('verdict <card-id> <verdict>')
+    .description('Apply a human verdict: keep | tune | kill (GCF-PRD §8)')
+    .option('--note <text>', 'tune remark or kill reason')
+    .option('--no-commit', 'skip the verdict commit (tests only)')
+    .action(async (cardId, verdict, opts) => {
+      const { applyVerdict } = await lib('verdict-fs');
+      const res = await applyVerdict(process.cwd(), cardId, verdict, { note: opts.note ?? '', commit: opts.commit });
+      console.log(`${res.verdict} ${res.card} → ${res.systems.join(',')}${res.hash ? ` (${res.hash.slice(0, 7)})` : ''}`);
+    });
+
+  gcf.command('anchor <file>')
+    .description('Import a GDD into gcf/source/ with stable section anchors; on re-import prints the delta')
+    .option('--json', 'machine output')
+    .action(async (file, opts) => {
+      const { splitSections, importSource, loadAnchorMap, classifyDelta } = await lib('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);
+      const rebaselined = Boolean(oldMap?.rebaselined);
+      const result = { file: `gcf/source/${base}`, sections: sections.map((s) => ({ anchor: s.anchor, heading: s.heading })), delta, rebaselined };
+      out(opts.json, result, (r) => [
+        ...r.sections.map((s) => `${s.anchor}  ${s.heading ?? '(preamble)'}`),
+        r.delta
+          ? `delta: +${r.delta.added.length} ~${r.delta.changed.length} -${r.delta.removed.length} renamed ${r.delta.renamed.length}`
+          : (r.rebaselined ? 're-baselined: the stored anchor map predates the current hashing, no delta computed' : 'first import'),
+      ].join('\n'));
+    });
+
+  gcf.command('hooks-install')
+    .description('Install the gcf pre-commit gate into the repository hooks dir (idempotent)')
+    .action(async () => {
+      const { writeFile, chmod } = await import('node:fs/promises');
+      // --git-path resolves the hooks dir for a plain repo, a worktree and a submodule alike,
+      // where a bare existsSync('.git') passes on a worktree and then fails with ENOTDIR.
+      const res = spawnSync('git', ['rev-parse', '--git-path', 'hooks'], { cwd: process.cwd(), encoding: 'utf8' });
+      if (res.status !== 0) throw new Error('not a git repository');
+      const hookScript = path.join(EXT_ROOT, 'hooks', 'pre-commit.js');
+      const shim = `#!/bin/sh\n# gcf-aif-ext pre-commit gate\nnode "${hookScript.replaceAll('\\', '/')}" || exit 1\n`;
+      const target = path.resolve(process.cwd(), res.stdout.trim(), 'pre-commit');
+      if (existsSync(target) && !(await readFile(target, 'utf8')).includes(MARKER)) {
+        // Brownfield repos usually arrive with husky or lefthook already owning pre-commit,
+        // so the refusal hands over the exact line to chain instead of just naming the file.
+        throw new Error(`${target} already exists and is not ours - back it up, or chain the gate from it with:\n`
+          + `node "${hookScript.replaceAll('\\', '/')}" || exit 1`);
+      }
+      await mkdir(path.dirname(target), { recursive: true });
+      await writeFile(target, shim, 'utf8');
+      await chmod(target, 0o755).catch(() => {});
+      console.log(`pre-commit hook installed → ${target}`);
+    });
+
+  gcf.command('lint <file>')
+    .description('П2 linter over one document (GCF-PRD §13.2)')
+    .action(async (file) => {
+      const { lint } = await lib('linter');
+      const { issues } = lint(await readFile(file, 'utf8'));
+      for (const i of issues) console.log(`${file}:${i.line}: ${i.rule}: ${i.text}`);
+      if (issues.length) process.exitCode = 1;
+      else console.log('clean');
+    });
+}

package/extension.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://raw.githubusercontent.com/lee-to/ai-factory/2.x/schemas/extension.schema.json",
+  "name": "gcf-aif-ext",
+  "version": "0.2.0",
+  "description": "Game Context Framework for AI Factory",
+  "skills": [
+    "skills/gcf-init",
+    "skills/gcf-adopt",
+    "skills/gcf-card",
+    "skills/gcf-verdict",
+    "skills/gcf-audit",
+    "skills/gcf-vision",
+    "skills/gcf-debate",
+    "skills/gcf-ingest"
+  ],
+  "commands": [
+    { "name": "gcf", "description": "Game Context Framework core", "module": "commands/gcf.js" }
+  ],
+  "injections": [
+    { "target": "aif-plan", "position": "append", "file": "./injections/plan-context.md" },
+    { "target": "aif-review", "position": "append", "file": "./injections/review-pillars.md" },
+    { "target": "aif-commit", "position": "append", "file": "./injections/commit-status.md" }
+  ]
+}

package/hooks/pre-commit.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// GCF pre-commit gate (GCF-PRD §13.1), cheap checks first, one-line reason on failure.
+// Runs from the repository root (git invokes hooks there). Silent no-op without gcf/.
+// 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 { 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';
+
+const projectDir = process.cwd();
+const root = path.join(projectDir, 'gcf');
+if (!existsSync(root)) process.exit(0);
+
+const fail = (msg) => {
+  console.error(`gcf pre-commit: ${msg}`);
+  process.exit(1);
+};
+
+// null when git itself failed (unborn HEAD, no work tree) — then fall through to the gate
+// 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.
+  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)');
+  }
+}
+
+const cards = await listCards(root);
+const cardIds = new Set(cards.map((c) => c.data.id));
+const systemDocs = await listSystems(root);
+
+// 1-2: frontmatter validity, storable statuses, until grammar, filename invariant.
+for (const c of 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`]),
+  ];
+  if (errors.length) fail(`${c.name}: ${errors[0]}`);
+}
+for (const s of systemDocs) {
+  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);
+
+for (const c of cards) {
+  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)`);
+    }
+  }
+}
+
+// 5: П2 linter over systems docs.
+for (const s of systemDocs) {
+  const { issues } = lint(s.body);
+  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);
+spawnSync('git', ['add', '--', path.join(root, 'INDEX.md')], { cwd: projectDir, stdio: 'ignore' });
+process.exit(0);

package/injections/commit-status.md

@@ -0,0 +1,6 @@
+## GCF: card status before commit (from gcf-aif-ext)
+
+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

package/injections/plan-context.md

@@ -0,0 +1,8 @@
+## GCF: readset before planning (from gcf-aif-ext)
+
+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

package/injections/review-pillars.md

@@ -0,0 +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
+- 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

@@ -0,0 +1,109 @@
+import { createHash } from 'node:crypto';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+// GDD anchoring (GCF-PRD §11.2.1): a section id is the hash of its normalized heading —
+// 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 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 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`. */
+export function splitSections(markdown) {
+  const lines = String(markdown).split('\n');
+  const sections = [];
+  let current = { heading: null, level: 0, lines: [] };
+  const flush = () => {
+    if (current.heading === null && !current.lines.join('').trim()) return;
+    sections.push(current);
+  };
+  for (const line of lines) {
+    const m = line.match(/^(#{1,6})\s+(.+?)\s*$/);
+    if (m) {
+      flush();
+      current = { heading: m[2], level: m[1].length, 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,
+      body,
+      body_hash: h8(bodyNorm(body)),
+    };
+  });
+}
+
+/** Copy a GDD into gcf/source/ and write its anchor map next to it. */
+export async function importSource(projectDir, file) {
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const content = await readFile(file, 'utf8');
+  const sections = splitSections(content);
+  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 map = { hash_version: HASH_VERSION, anchors };
+  await writeFile(path.join(root, 'source', `${base}.anchors.json`), JSON.stringify(map, null, 2), 'utf8');
+  return { file: `gcf/source/${base}`, sections };
+}
+
+/**
+ * Delta classification for a re-import (GCF-PRD §11.6): added | changed | removed | renamed.
+ * A removed anchor whose body hash reappears under a new anchor is a rename.
+ */
+export function classifyDelta(oldMap, sections) {
+  const delta = { added: [], changed: [], removed: [], renamed: [] };
+  const newByAnchor = new Map(sections.map((s) => [s.anchor, s]));
+
+  for (const s of sections) {
+    const old = oldMap[s.anchor];
+    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
+  // becomes the rename target of every missing anchor that shares its hash.
+  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);
+    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;
+}
+
+/**
+ * Load a previously written anchor map: `{ anchors, rebaselined }`, or null on first import.
+ * `rebaselined` means the stored hashes came from an older scheme, so there is no delta to
+ * compute — the import re-baselines silently instead of calling every section changed.
+ */
+export async function loadAnchorMap(projectDir, baseName) {
+  const file = path.join(path.resolve(projectDir), 'gcf', 'source', `${baseName}.anchors.json`);
+  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 };
+}

package/lib/audit-core.js

@@ -0,0 +1,102 @@
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+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';
+
+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;
+
+/**
+ * Deterministic audit core (GCF-PRD §10.1): until triggers, built staleness, tune
+ * limits, WIP, PILLARS budget, П2 linter, INDEX drift. No LLM anywhere; the
+ * contradiction hunt is a separate optional skill pass.
+ */
+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: [], wip: null, pillars: null, until: [], linter: {}, pragmas: [], index_drift: false, illegal_status: [] };
+
+  // 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)) {
+      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 });
+      }
+    }
+    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 });
+    }
+  }
+
+  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 };
+
+  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 };
+  }
+
+  // Until annotations across cards and systems docs.
+  const docs = [
+    ...cards.map((c) => ({ rel: `cards/${c.name}`, body: c.body })),
+    ...(await listSystems(root)).map((s) => ({ rel: `systems/${s.name}`, body: s.body })),
+  ];
+  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 });
+    }
+  }
+
+  // П2 linter over systems docs.
+  for (const s of await listSystems(root)) {
+    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;
+}