gcf-aif-ext 0.2.5 → 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.
 
@@ -25,7 +25,7 @@ ai-factory extension add gcf-aif-ext                        # npm
 This installs the 8 skills into each configured runtime, registers the `gcf` command and appends the injections to `aif-plan`, `aif-review` and `aif-commit`. Then set up the project — two steps, run once:
 
 ```bash
-ai-factory gcf init            # seeds gcf/ and cnlp.config.json
+ai-factory gcf init            # seeds gcf/ and cnlp.config.json (PILLARS.md is written by /gcf-init)
 ai-factory gcf hooks-install   # arms the pre-commit gate
 ```
 
@@ -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`, `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,19 +1,20 @@
 // 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';
 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));
+const lib = (name) => import(new URL(`../lib/${name}.js`, import.meta.url).href);
 
 // 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));
+const out = (json, value, human) =>
+  console.log(json ? JSON.stringify(value, null, 2) : human(value));
 
 const HARNESS = 'gcf-harness-aif-ext';
 
@@ -24,12 +25,16 @@ const HARNESS = 'gcf-harness-aif-ext';
  */
 export async function harnessWanted(flag, ask, canAsk) {
   if (flag !== undefined) return flag;
+
   return canAsk ? ask() : false;
 }
 
 async function claudeConfigured() {
   try {
-    const { agents } = JSON.parse(await readFile(path.join(process.cwd(), '.ai-factory.json'), 'utf8'));
+    const { agents } = JSON.parse(
+      await readFile(path.join(process.cwd(), '.ai-factory.json'), 'utf8'),
+    );
+
     return agents.some((a) => a?.id === 'claude');
   } catch {
     return true; // unknown config shape: let the human decide
@@ -40,7 +45,10 @@ async function askHarness() {
   const { createInterface } = await import('node:readline/promises');
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   try {
-    const answer = await rl.question(`Also install ${HARNESS} (orchestration + readset guard, Claude Code only)? [y/N] `);
+    const answer = await rl.question(
+      `Also install ${HARNESS} (orchestration + readset guard, Claude Code only)? [y/N] `,
+    );
+
     return /^y(es)?$/i.test(answer.trim());
   } finally {
     rl.close();
@@ -50,54 +58,114 @@ async function askHarness() {
 // Re-enter the AIF CLI that is running this command, not whatever `ai-factory` PATH holds
 // (an npx run has none on PATH).
 function aif(args) {
-  const res = spawnSync(process.execPath, [process.argv[1], ...args], { cwd: process.cwd(), stdio: 'inherit' });
-  if (res.status !== 0) throw new Error(`ai-factory ${args.join(' ')} failed — gcf/ is ready; retry that command by hand`);
+  const res = spawnSync(process.execPath, [process.argv[1], ...args], {
+    cwd: process.cwd(),
+    stdio: 'inherit',
+  });
+  if (res.status !== 0)
+    throw new Error(
+      `ai-factory ${args.join(' ')} failed — gcf/ is ready; retry that command by hand`,
+    );
 }
 
-export function register(program) {
-  const gcf = program.command('gcf').description('Game Context Framework core');
+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 ['design', 'cards', 'systems', 'source', '.metrics']) {
+    await mkdir(path.join(root, dir), { recursive: true });
+  }
+
+  // No PILLARS.md: a seeded example would be read as the game's truth in every readset
+  // until someone replaced it. The pillars interview writes the file; until then it is absent.
+  const seed = [
+    ['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);
+  }
+
+  const { HISTORY_HEAD } = await lib('verdict-fs');
+  for (const [name, header] of [
+    ['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, ' +
+        'a D2 also assumed/until; answers move out, records die\n',
+    ],
+  ]) {
+    const target = path.join(root, name);
+    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) {
+  const installed = program.commands?.some(
+    (c) => (typeof c?.name === 'function' ? c.name() : c?.name) === 'gcf-harness',
+  );
+  if (installed) {
+    if (opts.harness) aif(['gcf-harness', 'init']);
+
+    return;
+  }
+
+  const canAsk = Boolean(process.stdin.isTTY && process.stdout.isTTY) && (await claudeConfigured());
+  if (!(await harnessWanted(opts.harness, askHarness, canAsk))) return;
+  aif(['extension', 'add', HARNESS]);
+  aif(['gcf-harness', 'init']);
+}
 
-  gcf.command('init')
-    .description('Create the gcf/ skeleton from templates (idempotent, never overwrites); offers the harness')
+function registerInit(gcf, program) {
+  gcf
+    .command('init')
+    .description(
+      'Create the gcf/ skeleton from templates (idempotent, never overwrites); offers the harness',
+    )
     .option('--harness', `also install ${HARNESS} and run gcf-harness init (Claude Code only)`)
     .option('--no-harness', 'do not offer the harness')
     .action(async (opts) => {
       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);
+      await seedSkeleton(root);
       const { writeIndex } = await lib('index-gen');
       await writeIndex(root);
-      console.log('gcf/ ready. Edit PILLARS.md, then add candidates to backlog.md.');
-
-      const installed = program.commands?.some((c) => (typeof c?.name === 'function' ? c.name() : c?.name) === 'gcf-harness');
-      if (installed) {
-        if (opts.harness) aif(['gcf-harness', 'init']);
-        return;
-      }
-      const canAsk = Boolean(process.stdin.isTTY && process.stdout.isTTY) && (await claudeConfigured());
-      if (!(await harnessWanted(opts.harness, askHarness, canAsk))) return;
-      aif(['extension', 'add', HARNESS]);
-      aif(['gcf-harness', 'init']);
+      console.log(
+        '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);
     });
+}
 
-  gcf.command('index')
+function registerIndex(gcf) {
+  gcf
+    .command('index')
     .description('Regenerate gcf/INDEX.md (deterministic)')
     .action(async () => {
       const { gcfRoot } = await lib('gcf-paths');
@@ -105,8 +173,11 @@ export function register(program) {
       await writeIndex(gcfRoot());
       console.log('INDEX.md regenerated');
     });
+}
 
-  gcf.command('context <card-id>')
+function registerContext(gcf) {
+  gcf
+    .command('context <card-id>')
     .description('Assemble the readset for a card (GCF-PRD §9.1)')
     .option('--json', 'machine output')
     .action(async (cardId, opts) => {
@@ -116,104 +187,350 @@ export function register(program) {
       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');
+      await appendFile(
+        path.join(metricsDir, 'context-log.csv'),
+        `${today()},${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'));
+        ].join('\n'),
+      );
       if (ctx.over_budget) process.exitCode = 2;
     });
+}
 
-  gcf.command('audit')
+function registerAudit(gcf) {
+  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 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');
+        await appendFile(
+          path.join(metricsDir, 'audit-log.csv'),
+          `${today()},${findings}\n`,
+          'utf8',
+        );
       }
+
       out(opts.json, report, (r) => r.first_line);
       if (report.first_line !== 'clean') process.exitCode = 1;
     });
+}
 
-  gcf.command('playtest')
+function registerPlaytest(gcf) {
+  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'));
+      out(opts.json, list, (l) =>
+        l.length
+          ? l.map((c) => `${c.id} [${c.system.join(',')}]: ${c.question}`).join('\n')
+          : 'nothing in built — nothing to playtest',
+      );
     });
+}
 
-  gcf.command('verdict <card-id> <verdict>')
+function registerVerdict(gcf) {
+  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)})` : ''}`);
+      const res = await applyVerdict(process.cwd(), cardId, verdict, {
+        note: opts.note ?? '',
+        commit: opts.commit,
+      });
+      const hash = res.hash ? ` (${res.hash.slice(0, 7)})` : '';
+      console.log(`${res.verdict} ${res.card} → ${res.systems.join(',')}${hash}`);
     });
+}
+
+function anchorDeltaLine(r) {
+  if (r.delta) {
+    const { added, changed, removed, renamed } = r.delta;
 
-  gcf.command('anchor <file>')
-    .description('Import a GDD into gcf/source/ with stable section anchors; on re-import prints the delta')
+    return (
+      `delta: +${added.length} ~${changed.length} -${removed.length} ` + `renamed ${renamed.length}`
+    );
+  }
+
+  return r.rebaselined
+    ? 're-baselined: the stored anchor map predates the current hashing, no delta computed'
+    : 'first import';
+}
+
+function registerAnchor(gcf) {
+  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 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 })), 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'));
+      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) =>
+        [
+          ...r.sections.map(
+            (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'),
+      );
     });
+}
 
-  gcf.command('hooks-install')
+function registerSection(gcf) {
+  gcf
+    .command('section <source> <anchor>')
+    .description('Print one anchored section of a gcf/source/ file (read by anchor, not whole)')
+    .action(async (source, anchor) => {
+      const { readSection } = await lib('anchors');
+      const s = await readSection(process.cwd(), source, anchor);
+      if (!s) throw new Error(`${anchor} is not a section of gcf/source/${path.basename(source)}`);
+      console.log(`${s.anchor}  L${s.lines[0]}-${s.lines[1]}  ${s.heading ?? '(preamble)'}`);
+      console.log(s.body);
+    });
+}
+
+function registerQuotes(gcf) {
+  gcf
+    .command('quotes')
+    .description('Provenance only: every quote verbatim in its src: section (design check M9)')
+    .option('--json', 'machine output')
+    .action(async (opts) => {
+      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.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')
     .description('Install the gcf pre-commit gate into the repository hooks dir (idempotent)')
     .action(async () => {
       const { writeFile } = 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' });
+      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 gateLine = `node "${hookScript.replaceAll('\\', '/')}" || exit 1`;
+      const shim = `#!/bin/sh\n# ${MARKER}\n${gateLine}\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`);
+        throw new Error(
+          `${target} already exists and is not ours - back it up, ` +
+            `or chain the gate from it with:\n${gateLine}`,
+        );
       }
+
       await mkdir(path.dirname(target), { recursive: true });
       // Mode on creation, not a chmod afterwards that can fail with the hook already in place.
       // A file being replaced is our own earlier shim, already executable.
       await writeFile(target, shim, { encoding: 'utf8', mode: 0o755 });
       console.log(`pre-commit hook installed → ${target}`);
     });
+}
 
-  gcf.command('lint <file>')
+function registerLint(gcf) {
+  gcf
+    .command('lint <file>')
     .description('П2 linter over one document (GCF-PRD §13.2)')
     .action(async (file) => {
       const { lint } = await lib('linter');
@@ -223,3 +540,21 @@ export function register(program) {
       else console.log('clean');
     });
 }
+
+export function register(program) {
+  const gcf = program.command('gcf').description('Game Context Framework core');
+  registerInit(gcf, program);
+  registerIndex(gcf);
+  registerContext(gcf);
+  registerAudit(gcf);
+  registerPlaytest(gcf);
+  registerVerdict(gcf);
+  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.5",
+  "version": "0.3.0",
   "description": "Game Context Framework for AI Factory",
   "skills": [
     "skills/gcf-init",