gcf-aif-ext 0.2.1 → 0.2.5

package/README.md

@@ -31,6 +31,8 @@ ai-factory gcf hooks-install   # arms the pre-commit gate
 
 `gcf init` is idempotent: it creates what is missing and overwrites nothing.
 
+It then offers the optional [harness](../gcf-harness-aif-ext) — orchestration and a readset guard for **Claude Code only** — and on yes runs `ai-factory extension add gcf-harness-aif-ext` and `ai-factory gcf-harness init`. It asks only in a terminal and only when `.ai-factory.json` lists the Claude Code agent; an agent or CI run is never asked and installs nothing. `--harness` installs it without asking, `--no-harness` skips the question.
+
 `hooks-install` is a separate step because an AI Factory manifest can declare skills, commands and injections but cannot install a git hook — and because arming a gate that can break your commits is your call, not the extension's. It needs a git repository, and it will not overwrite a `pre-commit` it did not write: if husky or lefthook already owns the hook, it prints the one line to chain from it instead. Without the hook GCF still works; nothing enforces it at commit time.
 
 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.

package/commands/gcf.js

@@ -15,12 +15,53 @@ const MARKER = 'gcf-aif-ext pre-commit gate';
 
 const out = (json, value, human) => console.log(json ? JSON.stringify(value, null, 2) : human(value));
 
+const HARNESS = 'gcf-harness-aif-ext';
+
+/**
+ * `--harness` / `--no-harness` decide. Without either, ask only when someone can answer
+ * and the answer matters: an agent, CI or MinTTY run has no terminal, and a project
+ * without the Claude Code agent has no use for a Claude-Code-only extension.
+ */
+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'));
+    return agents.some((a) => a?.id === 'claude');
+  } catch {
+    return true; // unknown config shape: let the human decide
+  }
+}
+
+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] `);
+    return /^y(es)?$/i.test(answer.trim());
+  } finally {
+    rl.close();
+  }
+}
+
+// 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`);
+}
+
 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 () => {
+    .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 });
@@ -44,6 +85,16 @@ export function register(program) {
       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']);
     });
 
   gcf.command('index')
@@ -141,7 +192,7 @@ export function register(program) {
   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');
+      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' });
@@ -156,8 +207,9 @@ export function register(program) {
           + `node "${hookScript.replaceAll('\\', '/')}" || exit 1`);
       }
       await mkdir(path.dirname(target), { recursive: true });
-      await writeFile(target, shim, 'utf8');
-      await chmod(target, 0o755).catch(() => {});
+      // 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}`);
     });
 

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.1",
+  "version": "0.2.5",
   "description": "Game Context Framework for AI Factory",
   "skills": [
     "skills/gcf-init",

package/hooks/pre-commit.js

@@ -87,5 +87,7 @@ for (const s of systemDocs) {
 
 // 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' });
+// An unstaged INDEX (gitignored, locked index) would leave the commit without the row it validated.
+const added = spawnSync('git', ['add', '--', path.join(root, 'INDEX.md')], { cwd: projectDir, stdio: 'ignore' });
+if (added.status !== 0) fail('could not stage gcf/INDEX.md — is it gitignored?');
 process.exit(0);

package/lib/audit-core.js

@@ -22,7 +22,8 @@ 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: [] };
+  const report = { first_line: '', stale_built: [], tune_limit: [], open_depends: [], wip: null, pillars: null, until: [], linter: {}, pragmas: [], index_drift: false, illegal_status: [] };
+  const liveIds = new Set(cards.map((c) => c.data.id));
 
   // 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.
@@ -51,6 +52,10 @@ export async function audit(projectDir) {
     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 });
     }
+    // A depends id that still has a card file is unplayed (GCF-PRD §7.2). Data for the
+    // harness gate, not an alert: a proposed card waiting on its dependency is normal.
+    const open = (c.data.depends ?? []).filter((d) => liveIds.has(d));
+    if (open.length) report.open_depends.push({ id: c.data.id, depends: open });
   }
 
   const wipCount = cards.filter((c) => c.data.status === 'built').length;

package/lib/gcf-paths.js

@@ -25,7 +25,18 @@ export function gcfRoot(projectDir = process.cwd()) {
 export async function readConfig(root) {
   const file = path.join(root, 'config.yml');
   if (!existsSync(file)) return { ...DEFAULT_CONFIG };
-  return { ...DEFAULT_CONFIG, ...(YAML.parse(await readFile(file, 'utf8')) ?? {}) };
+  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');
+  // 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)) };
+  // 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])}`);
+    }
+  }
+  return config;
 }
 
 /** Token estimate: ceil(chars/4). Stability over accuracy (GCF-PRD §9.1). */

package/lib/git.js

@@ -2,18 +2,41 @@ import { spawnSync } from 'node:child_process';
 import path from 'node:path';
 
 /**
- * Stage a lifecycle relocation so git reports it as a rename rather than a delete plus an
- * untracked file: git derives the rename from content once both sides sit in the index.
- * Silent no-op outside a work tree or when git is missing — the file operation has
- * already succeeded and must not be undone by a staging failure.
+ * 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
+ * tree), so a missing parent directory of a file never misreads as "untracked". A
+ * conflicted path is left out: writing a single entry back would mark it resolved.
+ * Returns null outside a work tree — there is no index to put back.
  */
-export function stageMove(...files) {
-  const paths = files.filter(Boolean);
-  let staged = false;
-  // One `git add` per path: a single unmatched pathspec aborts the whole batch otherwise.
-  for (const file of paths) {
-    const res = spawnSync('git', ['add', '--', file], { cwd: path.dirname(file), stdio: 'ignore' });
-    if (res.status === 0) staged = true;
+export function snapshotIndex(cwd, files) {
+  const rels = files.map((f) => path.relative(cwd, f).replaceAll('\\', '/'));
+  // -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 entries = new Map();
+  const conflicted = new Set();
+  for (const rec of res.stdout.split('\0').filter(Boolean)) {
+    const m = rec.match(/^(\d+) ([0-9a-f]+) (\d)\t(.+)$/s);
+    if (!m) continue;
+    if (m[3] === '0') entries.set(m[4], { mode: m[1], blob: m[2] });
+    else conflicted.add(m[4]);
   }
-  return staged;
+  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. */
+export function restoreIndex(snapshot) {
+  if (!snapshot) return [];
+  const errors = [];
+  for (const { rel, entry } of snapshot.files) {
+    // --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', '--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}`));
+  }
+  return errors;
 }

package/lib/id.js

@@ -18,17 +18,6 @@ export function isValidId(id) {
   return ID_RE.test(String(id ?? ''));
 }
 
-/** Next free number across BOTH kinds: a card and a candidate never share a number. */
-export function nextId(kind, existingIds) {
-  if (kind !== 'card' && kind !== 'cand') throw new Error(`Unknown id kind: ${kind}`);
-  let max = 0;
-  for (const id of existingIds) {
-    const m = String(id).match(/^(?:card|cand)-(\d{3})$/);
-    if (m) max = Math.max(max, Number(m[1]));
-  }
-  return `${kind}-${String(max + 1).padStart(3, '0')}`;
-}
-
 /** `cand-012` → `card-012`: materialization keeps the number (GCF-PRD §5.2). */
 export function candToCard(candId) {
   const m = String(candId).match(/^cand-(\d{3})$/);

package/lib/safe-path.js

@@ -1,6 +1,6 @@
 import { readFile, writeFile, rename, mkdir, unlink } from 'node:fs/promises';
 import path from 'node:path';
-import { stageMove } from './git.js';
+import { snapshotIndex, restoreIndex } from './git.js';
 
 /**
  * Resolve `target` and assert it stays inside `projectDir` (reject traversal / outside-project).
@@ -39,10 +39,15 @@ export async function atomicWrite(file, data) {
   }
 }
 
-/** Restore every listed file to its original bytes when `action` fails. */
-export async function withFileRollback(files, action) {
+/**
+ * Restore every listed file to its original bytes when `action` fails. With `gitCwd` (an
+ * existing directory in the work tree) the files' git index entries are restored as well.
+ */
+export async function withFileRollback(files, action, { gitCwd = null } = {}) {
+  const unique = [...new Set(files)];
   const snapshots = [];
-  for (const file of new Set(files)) {
+  const index = gitCwd ? snapshotIndex(gitCwd, unique) : null;
+  for (const file of unique) {
     try {
       snapshots.push([file, await readFile(file, 'utf8')]);
     } catch (err) {
@@ -63,8 +68,9 @@ export async function withFileRollback(files, action) {
         rollbackErrors.push(rollbackError);
       }
     }
-    // An inner step may already have staged its move; realign the index with the restored tree.
-    stageMove(...snapshots.map(([file]) => file));
+    // An inner step may already have staged its writes. Re-adding the restored files would
+    // fold the user's unstaged edits into the index; putting back the old entries keeps them apart.
+    rollbackErrors.push(...restoreIndex(index));
     if (rollbackErrors.length) throw new AggregateError([err, ...rollbackErrors], `Operation failed and rollback was incomplete: ${err.message}`);
     throw err;
   }

package/lib/verdict-fs.js

@@ -4,7 +4,7 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { parse, serialize } from './frontmatter.js';
 import { listCards } from './gcf-paths.js';
-import { atomicWrite, withFileRollback } from './safe-path.js';
+import { atomicWrite, resolveInside, withFileRollback } from './safe-path.js';
 import { writeIndex } from './index-gen.js';
 import { isLegal } from './transitions.js';
 
@@ -44,8 +44,6 @@ function operationInProgress(projectDir) {
 }
 
 function gitCommit(projectDir, message, addPaths) {
-  const busy = operationInProgress(projectDir);
-  if (busy) throw new Error(`cannot record a verdict while ${busy} is in progress — finish or abort it first`);
   // Stage and commit exactly the files this verdict touched: `git add -- gcf/` would stage a
   // user's unrelated edits under gcf/, and rollback only restores what it snapshotted.
   for (const p of addPaths) spawnSync('git', ['add', '--', p], { cwd: projectDir, stdio: 'ignore' });
@@ -72,6 +70,10 @@ export async function applyVerdict(projectDir, cardId, verdict, { note = '', tag
   if (!isLegal(card.data.status, target)) {
     throw new Error(`Illegal transition ${card.data.status} -> ${target} for ${cardId} (verdict needs status=built)`);
   }
+  // Before any write: refusing after the files changed would send a failed commit through the
+  // rollback, and restoring a conflicted index entry marks the conflict resolved.
+  const busy = commit ? operationInProgress(projectDir) : null;
+  if (busy) throw new Error(`cannot record a verdict while ${busy} is in progress — finish or abort it first`);
 
   const touched = [card.file, path.join(root, 'INDEX.md')];
   const systems = card.data.system ?? [];
@@ -95,7 +97,9 @@ export async function applyVerdict(projectDir, cardId, verdict, { note = '', tag
       await unlink(card.file);
     };
   } else {
-    const sysFiles = systems.map((s) => path.join(root, 'systems', `${s}.md`));
+    // `system:` names files, and the pre-commit gate validates it only after they are written:
+    // `../../x` would already have overwritten a file outside gcf/.
+    const sysFiles = systems.map((s) => resolveInside(path.join(root, 'systems'), `${s}.md`));
     touched.push(...sysFiles);
     mutate = async () => {
       for (const [i, sysFile] of sysFiles.entries()) {
@@ -121,6 +125,6 @@ export async function applyVerdict(projectDir, cardId, verdict, { note = '', tag
     await mutate();
     await writeIndex(root);
     if (commit) hash = gitCommit(projectDir, message, touched);
-  });
+  }, { gitCwd: commit ? path.resolve(projectDir) : null });
   return { verdict, card: cardId, systems, hash };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gcf-aif-ext",
-  "version": "0.2.1",
+  "version": "0.2.5",
   "description": "Game Context Framework for AI Factory",
   "type": "module",
   "license": "MIT",