gcf-aif-ext 0.2.4 → 0.2.7

package/lib/id.js

@@ -11,6 +11,7 @@ export function slugify(name) {
     .replace(/[^a-z0-9]+/g, '-')
     .replace(/^-+|-+$/g, '');
   if (!slug) throw new Error(`Cannot derive a slug from: ${JSON.stringify(name)}`);
+
   return slug;
 }
 
@@ -22,6 +23,7 @@ export function isValidId(id) {
 export function candToCard(candId) {
   const m = String(candId).match(/^cand-(\d{3})$/);
   if (!m) throw new Error(`Not a candidate id: ${candId}`);
+
   return `card-${m[1]}`;
 }
 

package/lib/index-gen.js

@@ -10,36 +10,53 @@ import { atomicWrite } from './safe-path.js';
  */
 export async function generate(root) {
   const lines = ['# INDEX — generated, do not edit', ''];
-  const row = (type, file, status, system, descr) =>
+  const row = ([type, file, status, system, descr]) =>
     lines.push(`${type} | gcf/${file} | ${status} | ${system} | ${descr}`);
 
-  if (existsSync(path.join(root, 'PILLARS.md'))) row('pillars', 'PILLARS.md', '-', '-', 'pillars and negative invariants');
-  if (existsSync(path.join(root, 'backlog.md'))) {
-    const count = ((await readFile(path.join(root, 'backlog.md'), 'utf8')).match(/^- cand-/gm) ?? []).length;
-    row('backlog', 'backlog.md', '-', '-', `${count} candidates`);
+  if (existsSync(path.join(root, 'PILLARS.md')))
+    row(['pillars', 'PILLARS.md', '-', '-', 'pillars and negative invariants']);
+  const backlog = await readIfExists(root, 'backlog.md');
+  if (backlog !== null) {
+    row(['backlog', 'backlog.md', '-', '-', `${count(backlog, /^- cand-/gm)} candidates`]);
   }
+
   for (const s of await listSystems(root)) {
-    row('system', `systems/${s.name}`, '-', s.data.system ?? '-', firstBullet(s.body, 'purpose'));
+    const purpose = firstBullet(s.body, 'purpose');
+    row(['system', `systems/${s.name}`, '-', s.data.system ?? '-', purpose]);
   }
+
   for (const c of await listCards(root)) {
-    row('card', `cards/${c.name}`, c.data.status ?? '?', (c.data.system ?? []).join(','), firstBullet(c.body, 'behavior'));
+    const system = (c.data.system ?? []).join(',');
+    row(['card', `cards/${c.name}`, c.data.status ?? '?', system, firstBullet(c.body, 'behavior')]);
   }
-  if (existsSync(path.join(root, 'graveyard.md'))) {
-    const count = ((await readFile(path.join(root, 'graveyard.md'), 'utf8')).match(/^- card-/gm) ?? []).length;
-    row('graveyard', 'graveyard.md', '-', '-', `${count} killed ideas`);
+
+  const graveyard = await readIfExists(root, 'graveyard.md');
+  if (graveyard !== null) {
+    row(['graveyard', 'graveyard.md', '-', '-', `${count(graveyard, /^- card-/gm)} killed ideas`]);
   }
-  if (existsSync(path.join(root, 'open-questions.md'))) {
-    const txt = await readFile(path.join(root, 'open-questions.md'), 'utf8');
-    const d1 = (txt.match(/^\s*class:\s*D1/gm) ?? []).length;
-    const d2 = (txt.match(/^\s*class:\s*D2/gm) ?? []).length;
-    row('questions', 'open-questions.md', '-', '-', `${d1} D1, ${d2} D2`);
+
+  const txt = await readIfExists(root, 'open-questions.md');
+  if (txt !== null) {
+    const d1 = count(txt, /^\s*class:\s*D1/gm);
+    const d2 = count(txt, /^\s*class:\s*D2/gm);
+    row(['questions', 'open-questions.md', '-', '-', `${d1} D1, ${d2} D2`]);
   }
+
   return `${lines.join('\n')}\n`;
 }
 
+async function readIfExists(root, rel) {
+  const file = path.join(root, rel);
+
+  return existsSync(file) ? readFile(file, 'utf8') : null;
+}
+
+const count = (text, re) => (text.match(re) ?? []).length;
+
 export async function writeIndex(root) {
   const content = await generate(root);
   await atomicWrite(path.join(root, 'INDEX.md'), content);
+
   return content;
 }
 
@@ -47,5 +64,6 @@ export async function writeIndex(root) {
 export async function drifted(root) {
   const file = path.join(root, 'INDEX.md');
   if (!existsSync(file)) return true;
+
   return (await readFile(file, 'utf8')) !== (await generate(root));
 }

package/lib/linter.js

@@ -5,6 +5,15 @@
 const UNIT_NUM = /\d+(?:[.,]\d+)?\s?(?:ms|мс|s|с|dmg|hp|px|сек)\b/;
 const SIGNATURE = /\w+\s*\([^)]*\b(?:int|float|bool|string|void|var|ref|out)\b[^)]*\)/;
 const CAMEL = /\b[A-Z][a-z0-9]+(?:[A-Z][a-z0-9]+)+\b/;
+const ENVELOPE_FIELD = /^\s*(?:- )?(?:question|assumed|proposed):/;
+
+/**
+ * @typedef {object} LintState
+ * @property {string[]} lines
+ * @property {Array<{line: number, rule: string, text: string}>} issues
+ * @property {Array<{line: number, reason: string | null}>} pragmas
+ * @property {number} fenceStart line index of the open fence, -1 when outside one
+ */
 
 /** Which `key:` block a line sits in (flat CNL-P body). */
 function blockOf(lines, i) {
@@ -12,50 +21,79 @@ function blockOf(lines, i) {
     const m = lines[j].match(/^([a-z_]+):\s*$/) ?? lines[j].match(/^([a-z_]+):\s+\S/);
     if (m) return m[1];
   }
+
   return null;
 }
 
 export function lint(content) {
-  const lines = String(content).split('\n');
-  const issues = [];
-  const pragmas = [];
-  let fenceStart = -1;
-
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    const prev = lines[i - 1] ?? '';
-
-    const pragma = prev.match(/<!--\s*gcf:allow\s*(.*?)\s*-->/);
-    if (pragma && !pragma[1]) issues.push({ line: i, rule: 'pragma-without-reason', text: prev.trim() });
-    const allowed = Boolean(pragma && pragma[1]);
-    if (pragma) pragmas.push({ line: i, reason: pragma[1] || null });
-
-    if (line.startsWith('```')) {
-      if (fenceStart < 0) fenceStart = i;
-      else {
-        if (i - fenceStart - 1 > 3) issues.push({ line: fenceStart + 1, rule: 'fenced-code-over-3-lines', text: `${i - fenceStart - 1} lines` });
-        fenceStart = -1;
-      }
-      continue;
-    }
-    if (fenceStart >= 0 || allowed) continue;
-
-    const block = blockOf(lines, i);
-    if (block !== 'feel' && UNIT_NUM.test(line)) {
-      issues.push({ line: i + 1, rule: 'number-with-unit-outside-feel', text: line.trim() });
-    }
-    if (SIGNATURE.test(line)) {
-      issues.push({ line: i + 1, rule: 'signature', text: line.trim() });
-    }
-    // Three or more consecutive bullets each naming CamelCase identifiers = a member list.
-    if (/^- /.test(line) && CAMEL.test(line)
-      && /^- /.test(prev) && CAMEL.test(prev)
-      && /^- /.test(lines[i - 2] ?? '') && CAMEL.test(lines[i - 2] ?? '')) {
-      issues.push({ line: i + 1, rule: 'camelcase-member-list', text: line.trim() });
-    }
+  /** @type {LintState} */
+  const st = { lines: String(content).split('\n'), issues: [], pragmas: [], fenceStart: -1 };
+
+  for (let i = 0; i < st.lines.length; i++) {
+    const allowed = readPragma(st, i);
+    if (st.lines[i].startsWith('```')) toggleFence(st, i);
+    else if (st.fenceStart < 0 && !allowed) checkLine(st, i);
+  }
+
+  // An unclosed fence leaves fenceStart set, so the loop above skipped every remaining
+  // line: one stray fence would otherwise disable П2 for the rest of the file.
+  if (st.fenceStart >= 0)
+    st.issues.push({
+      line: st.fenceStart + 1,
+      rule: 'unterminated-fence',
+      text: 'code fence never closed',
+    });
+
+  return { issues: st.issues, pragmas: st.pragmas };
+}
+
+/** Records a pragma on the previous line; true when it carries a reason and so allows line i. */
+function readPragma(st, i) {
+  const prev = st.lines[i - 1] ?? '';
+  const pragma = prev.match(/<!--\s*gcf:allow\s*(.*?)\s*-->/);
+  if (!pragma) return false;
+  if (!pragma[1]) st.issues.push({ line: i, rule: 'pragma-without-reason', text: prev.trim() });
+  st.pragmas.push({ line: i, reason: pragma[1] || null });
+
+  return Boolean(pragma[1]);
+}
+
+/** Opens a fence, or closes it and flags a body over 3 lines. */
+function toggleFence(st, i) {
+  if (st.fenceStart < 0) {
+    st.fenceStart = i;
+
+    return;
+  }
+
+  const size = i - st.fenceStart - 1;
+  if (size > 3)
+    st.issues.push({
+      line: st.fenceStart + 1,
+      rule: 'fenced-code-over-3-lines',
+      text: `${size} lines`,
+    });
+  st.fenceStart = -1;
+}
+
+const memberBullet = (line) => /^- /.test(line) && CAMEL.test(line);
+
+/** Pattern rules for one prose line (outside fences, not pragma-allowed). */
+function checkLine(st, i) {
+  const line = st.lines[i];
+  const flag = (rule) => st.issues.push({ line: i + 1, rule, text: line.trim() });
+
+  // Envelopes are legal where the spec puts them: the feel block, and the question/assumed/
+  // proposed fields of an open-questions record, where import parks D2 envelopes for the human.
+  if (blockOf(st.lines, i) !== 'feel' && !ENVELOPE_FIELD.test(line) && UNIT_NUM.test(line)) {
+    flag('number-with-unit-outside-feel');
+  }
+
+  if (SIGNATURE.test(line)) flag('signature');
+
+  // Three or more consecutive bullets each naming CamelCase identifiers = a member list.
+  const prev = st.lines[i - 1] ?? '';
+  if (memberBullet(line) && memberBullet(prev) && memberBullet(st.lines[i - 2] ?? '')) {
+    flag('camelcase-member-list');
   }
-  // An unclosed fence leaves fenceStart set, so the loop above `continue`d past every
-  // remaining line: one stray fence would otherwise disable П2 for the rest of the file.
-  if (fenceStart >= 0) issues.push({ line: fenceStart + 1, rule: 'unterminated-fence', text: 'code fence never closed' });
-  return { issues, pragmas };
 }

package/lib/safe-path.js

@@ -21,6 +21,7 @@ export function resolveInside(projectDir, target) {
         '  next:     pass a path within the project root',
     );
   }
+
   return resolved;
 }
 
@@ -39,9 +40,21 @@ export async function atomicWrite(file, data) {
   }
 }
 
+/** Put one snapshotted file back: `null` content means it did not exist before. */
+async function restoreSnapshot(file, content) {
+  if (content === null)
+    await unlink(file).catch((e) => {
+      if (e.code !== 'ENOENT') throw e;
+    });
+  else await atomicWrite(file, content);
+}
+
 /**
  * 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.
+ * @param {string[]} files
+ * @param {() => Promise<any>} action
+ * @param {{ gitCwd?: string | null }} [options]
  */
 export async function withFileRollback(files, action, { gitCwd = null } = {}) {
   const unique = [...new Set(files)];
@@ -62,16 +75,22 @@ export async function withFileRollback(files, action, { gitCwd = null } = {}) {
     const rollbackErrors = [];
     for (const [file, content] of snapshots) {
       try {
-        if (content === null) await unlink(file).catch((e) => { if (e.code !== 'ENOENT') throw e; });
-        else await atomicWrite(file, content);
+        await restoreSnapshot(file, content);
       } catch (rollbackError) {
         rollbackErrors.push(rollbackError);
       }
     }
+
     // 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.
+    // 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}`);
+    if (rollbackErrors.length)
+      throw new AggregateError(
+        [err, ...rollbackErrors],
+        `Operation failed and rollback was incomplete: ${err.message}`,
+        { cause: err },
+      );
     throw err;
   }
 }

package/lib/transitions.js

@@ -19,9 +19,7 @@ export function isLegal(from, to) {
 
 /** Statuses reachable from `from`, for error messages. */
 export function legalTargets(from) {
-  return [...LEGAL]
-    .filter((t) => t.startsWith(`${from}>`))
-    .map((t) => t.split('>')[1]);
+  return [...LEGAL].filter((t) => t.startsWith(`${from}>`)).map((t) => t.split('>')[1]);
 }
 
 /** A status a card FILE may carry. Terminal statuses exist only in the transition itself. */

package/lib/validate-card.js

@@ -1,19 +1,43 @@
 // Runtime mirror of schemas/card.schema.json for the pre-commit hook (no ajv in
 // production deps). The parity test keeps the two in agreement.
-const FIELDS = ['schema', 'id', 'slug', 'status', 'route', 'system', 'depends', 'source', 'tune_count', 'built_at', 'created'];
+const FIELDS = [
+  'schema',
+  'id',
+  'slug',
+  'status',
+  'route',
+  'system',
+  'depends',
+  'source',
+  'tune_count',
+  'built_at',
+  'created',
+];
 const REQUIRED = FIELDS.filter((f) => f !== 'built_at');
 
 const RULES = {
   schema: (v) => v === 1 || 'schema must be 1',
   id: (v) => /^card-\d{3}$/.test(v) || 'id must match card-NNN',
   slug: (v) => /^[a-z0-9]+(-[a-z0-9]+)*$/.test(v) || 'slug must be a lowercase hyphen slug',
-  status: (v) => ['proposed', 'built', 'tuning'].includes(v) || `status "${v}" is not storable (П1: terminal statuses never live in a file)`,
+  status: (v) =>
+    ['proposed', 'built', 'tuning'].includes(v) ||
+    `status "${v}" is not storable (П1: terminal statuses never live in a file)`,
   route: (v) => ['soft', 'hard'].includes(v) || 'route must be soft or hard',
-  system: (v) => (Array.isArray(v) && v.length >= 1 && v.every((s) => /^[a-z0-9]+(-[a-z0-9]+)*$/.test(s))) || 'system must list >=1 subsystem slugs',
-  depends: (v) => (Array.isArray(v) && v.every((d) => /^card-\d{3}$/.test(d))) || 'depends must list card-NNN ids',
-  source: (v) => /^(GDD#[A-Za-z0-9_-]+|manual|inferred)$/.test(v) || 'source must be GDD#<id>, manual or inferred',
+  system: (v) =>
+    (Array.isArray(v) && v.length >= 1 && v.every((s) => /^[a-z0-9]+(-[a-z0-9]+)*$/.test(s))) ||
+    'system must list >=1 subsystem slugs',
+  depends: (v) =>
+    (Array.isArray(v) && v.every((d) => /^card-\d{3}$/.test(d))) ||
+    'depends must list card-NNN ids',
+  source: (v) =>
+    /^(GDD#[A-Za-z0-9_-]+|manual|inferred)$/.test(v) ||
+    'source must be GDD#<id>, manual or inferred',
   tune_count: (v) => (Number.isInteger(v) && v >= 0) || 'tune_count must be an integer >= 0',
-  built_at: (v) => v === null || v === undefined || /^[0-9a-f]{7,40}$/.test(v) || 'built_at must be null or a commit hash',
+  built_at: (v) =>
+    v === null ||
+    v === undefined ||
+    /^[0-9a-f]{7,40}$/.test(v) ||
+    'built_at must be null or a commit hash',
   created: (v) => /^\d{4}-\d{2}-\d{2}$/.test(dateStr(v)) || 'created must be YYYY-MM-DD',
 };
 
@@ -26,12 +50,17 @@ export function validateCard(data) {
   const errors = [];
   for (const key of REQUIRED) if (!(key in data)) errors.push(`missing field: ${key}`);
   for (const key of Object.keys(data)) {
-    if (!FIELDS.includes(key)) errors.push(`unknown field: ${key}${key === 'until' ? ' (until: is a line annotation, not frontmatter)' : ''}`);
+    if (!FIELDS.includes(key))
+      errors.push(
+        `unknown field: ${key}` +
+          (key === 'until' ? ' (until: is a line annotation, not frontmatter)' : ''),
+      );
     else if (key in RULES) {
       const res = RULES[key](data[key]);
       if (res !== true) errors.push(res);
     }
   }
+
   return errors;
 }
 
@@ -41,8 +70,13 @@ export function validateUntil(body) {
   const lines = String(body).split('\n');
   lines.forEach((line, i) => {
     for (const m of line.matchAll(/\[until:[^\]]*\]/g)) {
-      if (!UNTIL_OK.test(m[0])) errors.push(`line ${i + 1}: bad until annotation ${m[0]} (use verdict(card-NNN), retune(system) or manual(text))`);
+      if (!UNTIL_OK.test(m[0]))
+        errors.push(
+          `line ${i + 1}: bad until annotation ${m[0]} ` +
+            '(use verdict(card-NNN), retune(system) or manual(text))',
+        );
     }
   });
+
   return errors;
 }

package/lib/verdict-fs.js

@@ -20,6 +20,7 @@ const MERGE_MAP = [
 
 function blockLines(body, key) {
   const m = String(body).match(new RegExp(`^${key}:\\s*\\n((?:- .*\\n?)*)`, 'm'));
+
   return m ? m[1].split('\n').filter((l) => l.startsWith('- ')) : [];
 }
 
@@ -29,29 +30,122 @@ function upsertBlock(body, key, addLines) {
   const fresh = addLines.filter((l) => !existing.has(l));
   if (!fresh.length) return body;
   const re = new RegExp(`(^${key}:\\s*\\n(?:- .*\\n?)*)`, 'm');
-  if (re.test(body)) return body.replace(re, (blk) => `${blk.endsWith('\n') ? blk : `${blk}\n`}${fresh.join('\n')}\n`);
+  if (re.test(body))
+    return body.replace(
+      re,
+      (blk) => `${blk.endsWith('\n') ? blk : `${blk}\n`}${fresh.join('\n')}\n`,
+    );
+
   return `${body.trimEnd()}\n\n${key}:\n${fresh.join('\n')}\n`;
 }
 
 // `git commit --only <paths>` is a partial commit, which git refuses outright while a merge
 // or a sequencer operation is in progress. Detect it up front so the failure has a reason.
-const IN_PROGRESS = ['MERGE_HEAD', 'CHERRY_PICK_HEAD', 'REVERT_HEAD', 'rebase-merge', 'rebase-apply'];
+const IN_PROGRESS = [
+  'MERGE_HEAD',
+  'CHERRY_PICK_HEAD',
+  'REVERT_HEAD',
+  'rebase-merge',
+  'rebase-apply',
+];
 function operationInProgress(projectDir) {
-  const gitDir = spawnSync('git', ['rev-parse', '--git-dir'], { cwd: projectDir, encoding: 'utf8' });
+  const gitDir = spawnSync('git', ['rev-parse', '--git-dir'], {
+    cwd: projectDir,
+    encoding: 'utf8',
+  });
   if (gitDir.status !== 0) return null;
   const dir = path.resolve(projectDir, gitDir.stdout.trim());
+
   return IN_PROGRESS.find((name) => existsSync(path.join(dir, name))) ?? null;
 }
 
 function gitCommit(projectDir, message, addPaths) {
   // 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' });
-  const res = spawnSync('git', ['commit', '-m', message, '--only', '--', ...addPaths], { cwd: projectDir, encoding: 'utf8' });
+  for (const p of addPaths)
+    spawnSync('git', ['add', '--', p], { cwd: projectDir, stdio: 'ignore' });
+  const res = spawnSync('git', ['commit', '-m', message, '--only', '--', ...addPaths], {
+    cwd: projectDir,
+    encoding: 'utf8',
+  });
   if (res.status !== 0) throw new Error(`verdict commit failed: ${res.stderr || res.stdout}`);
-  return spawnSync('git', ['rev-parse', 'HEAD'], { cwd: projectDir, encoding: 'utf8' }).stdout.trim();
+
+  return spawnSync('git', ['rev-parse', 'HEAD'], {
+    cwd: projectDir,
+    encoding: 'utf8',
+  }).stdout.trim();
+}
+
+/** Find the card and refuse an unknown verdict or a transition the lifecycle forbids. */
+async function findVerdictCard(root, cardId, verdict) {
+  const card = (await listCards(root)).find((c) => c.data.id === cardId);
+  if (!card) throw new Error(`Card not found: ${cardId}`);
+  const target = { keep: 'validated', tune: 'tuning', kill: 'killed' }[verdict];
+  if (!target) throw new Error(`Unknown verdict: ${verdict}`);
+  if (!isLegal(card.data.status, target)) {
+    throw new Error(
+      `Illegal transition ${card.data.status} -> ${target} for ${cardId} ` +
+        '(verdict needs status=built)',
+    );
+  }
+
+  return card;
+}
+
+function planTune({ card, note }) {
+  return async () => {
+    const data = { ...card.data, status: 'tuning', tune_count: (card.data.tune_count ?? 0) + 1 };
+    const body = note ? upsertBlock(card.body, 'feel', [`- retune: ${note}`]) : card.body;
+    await atomicWrite(card.file, serialize(data, body));
+  };
+}
+
+function planKill({ root, card, cardId, note, tags, systems, touched }) {
+  const gyFile = path.join(root, 'graveyard.md');
+  touched.push(gyFile);
+
+  return async () => {
+    const reason = note || 'no reason recorded';
+    const tagStr = (tags.length ? tags : systems).join(', ');
+    const line = `- ${cardId} | ${card.data.slug} | ${reason} | tags: ${tagStr}\n`;
+    const existing = existsSync(gyFile) ? await readFile(gyFile, 'utf8') : '';
+    await atomicWrite(gyFile, existing + line);
+    await unlink(card.file);
+  };
 }
 
+async function mergeIntoSystem(sysFile, system, card, cardId) {
+  let doc = existsSync(sysFile)
+    ? parse(await readFile(sysFile, 'utf8'))
+    : { data: { system }, body: 'purpose:\n- (fill in)\n' };
+  let body = doc.body;
+  for (const [slot, section] of MERGE_MAP) {
+    body = upsertBlock(body, section, blockLines(card.body, slot));
+  }
+
+  // Lines with a live until: move to `open` (GCF-PRD §8.2.5).
+  const openLines = blockLines(card.body, 'interactions').filter((l) => l.includes('[until:'));
+  body = upsertBlock(body, 'open', openLines);
+  await atomicWrite(sysFile, serialize({ ...doc.data, updated_by: cardId }, body));
+}
+
+function planKeep({ root, card, cardId, systems, touched }) {
+  // `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);
+
+  return async () => {
+    for (const [i, sysFile] of sysFiles.entries()) {
+      await mergeIntoSystem(sysFile, systems[i], card, cardId);
+    }
+
+    await unlink(card.file);
+  };
+}
+
+const PLANS = { tune: planTune, kill: planKill, keep: planKeep };
+
 /**
  * The one operation that collapses a card (GCF-PRD §8). Atomic: file changes roll back
  * on failure; the verdict commit has the fixed greppable format. `keep` merges into every
@@ -61,70 +155,39 @@ function gitCommit(projectDir, message, addPaths) {
  * The commit runs INSIDE the rollback: it fires the pre-commit gate, which can reject the
  * merged systems doc, and a card unlinked by a commit that never landed is a lost card.
  */
-export async function applyVerdict(projectDir, cardId, verdict, { note = '', tags = [], commit = true } = {}) {
+export async function applyVerdict(
+  projectDir,
+  cardId,
+  verdict,
+  { note = '', tags = [], commit = true } = {},
+) {
   const root = path.join(path.resolve(projectDir), 'gcf');
-  const card = (await listCards(root)).find((c) => c.data.id === cardId);
-  if (!card) throw new Error(`Card not found: ${cardId}`);
-  const target = { keep: 'validated', tune: 'tuning', kill: 'killed' }[verdict];
-  if (!target) throw new Error(`Unknown verdict: ${verdict}`);
-  if (!isLegal(card.data.status, target)) {
-    throw new Error(`Illegal transition ${card.data.status} -> ${target} for ${cardId} (verdict needs status=built)`);
-  }
+  const card = await findVerdictCard(root, cardId, verdict);
+
   // 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`);
+  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 ?? [];
-  let mutate;
-
-  if (verdict === 'tune') {
-    mutate = async () => {
-      const data = { ...card.data, status: 'tuning', tune_count: (card.data.tune_count ?? 0) + 1 };
-      const body = note ? upsertBlock(card.body, 'feel', [`- retune: ${note}`]) : card.body;
-      await atomicWrite(card.file, serialize(data, body));
-    };
-  } else if (verdict === 'kill') {
-    const gyFile = path.join(root, 'graveyard.md');
-    touched.push(gyFile);
-    mutate = async () => {
-      const reason = note || 'no reason recorded';
-      const tagStr = (tags.length ? tags : systems).join(', ');
-      const line = `- ${cardId} | ${card.data.slug} | ${reason} | tags: ${tagStr}\n`;
-      const existing = existsSync(gyFile) ? await readFile(gyFile, 'utf8') : '';
-      await atomicWrite(gyFile, existing + line);
-      await unlink(card.file);
-    };
-  } else {
-    // `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()) {
-        let doc = existsSync(sysFile)
-          ? parse(await readFile(sysFile, 'utf8'))
-          : { data: { system: systems[i] }, body: 'purpose:\n- (fill in)\n' };
-        let body = doc.body;
-        for (const [slot, section] of MERGE_MAP) {
-          body = upsertBlock(body, section, blockLines(card.body, slot));
-        }
-        // Lines with a live until: move to `open` (GCF-PRD §8.2.5).
-        const openLines = blockLines(card.body, 'interactions').filter((l) => l.includes('[until:'));
-        body = upsertBlock(body, 'open', openLines);
-        await atomicWrite(sysFile, serialize({ ...doc.data, updated_by: cardId }, body));
-      }
-      await unlink(card.file);
-    };
-  }
+  const mutate = PLANS[verdict]({ root, card, cardId, note, tags, systems, touched });
 
   const message = `gcf(verdict): ${verdict} ${cardId} ${card.data.slug} → ${systems.join(',')}`;
+  /** @type {string | null} */
   let hash = null;
-  await withFileRollback(touched, async () => {
-    await mutate();
-    await writeIndex(root);
-    if (commit) hash = gitCommit(projectDir, message, touched);
-  }, { gitCwd: commit ? path.resolve(projectDir) : null });
+  await withFileRollback(
+    touched,
+    async () => {
+      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.4",
+  "version": "0.2.7",
   "description": "Game Context Framework for AI Factory",
   "type": "module",
   "license": "MIT",

package/skills/gcf-adopt/SKILL.md

@@ -24,7 +24,7 @@ forbidden_behaviors:
 - do not read code files whole: names, paths and entry points are the whole input
 
 workflow:
-1. run `ai-factory gcf init` and report what it created; when `backlog.md` and `PILLARS.md` still hold the template examples, clear those example lines so INDEX does not count them
+1. run `ai-factory gcf init` and report what it created; when `.ai-factory/DESCRIPTION.md` is absent, tell the human to run `/aif` before the first `/gcf-card`
 2. scan the code tree by names only - directories, `*.asmdef`, feature classes, entry points - and propose a subsystem list with a path per entry
 3. ask the human to edit and confirm the names; a name they reject or doubt becomes a D1 record in `gcf/open-questions.md`, not a file
 4. write `gcf/systems/<name>.md` per confirmed subsystem from the package template, frontmatter `system: <name>` and `updated_by: adopt`
@@ -32,7 +32,7 @@ workflow:
 6. fill `purpose:` with one line of intent the human confirmed: the INDEX row of a subsystem is its first `purpose` bullet
 7. fill `behavior:` and `constraints:` with 1 placeholder each, annotated `[until: manual(first verdict touching <name>)]`: the profile requires both blocks, and a `manual(...)` trigger is not an audit finding
 8. write a constraint the human states out loud into `constraints:`, and do not interview subsystem by subsystem for more: unanswered questions on adoption day are the staleness this framework exists to remove
-9. draft `PILLARS.md` by the interview in the `gcf-init` skill, steps 3..5, and do not restate that interview here
+9. draft `PILLARS.md` by the interview in the `gcf-init` skill, steps 4..6, and do not restate that interview here
 10. run `npx cnlp check`, then `ai-factory gcf lint` over each new systems doc, then `ai-factory gcf index`
 11. ask the human to run `ai-factory gcf hooks-install`; when it refuses over a foreign pre-commit, hand them the chain line it prints
 12. state the next step: an old design document goes through `/gcf-ingest`, new work starts at `/gcf-card`