gcf-aif-ext 0.2.0

package/lib/context.js

@@ -0,0 +1,77 @@
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { listCards, listSystems, readConfig, tokensEst } from './gcf-paths.js';
+
+/**
+ * Readset assembly — the whole command is deterministic (GCF-PRD §9.1, §10.1):
+ * PILLARS + touched systems + the card + its depends + graveyard tag hits +
+ * D2 assumptions whose sys overlaps. Never over_budget-throws: the caller gates.
+ */
+export async function buildContext(projectDir, cardId) {
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const config = await readConfig(root);
+  const cards = await listCards(root);
+  const card = cards.find((c) => c.data.id === cardId);
+  if (!card) throw new Error(`Card not found: ${cardId}`);
+
+  const files = [];
+  const push = async (rel) => {
+    const abs = path.join(root, rel);
+    if (!existsSync(abs)) return null;
+    const text = await readFile(abs, 'utf8');
+    const entry = { path: `gcf/${rel.replaceAll('\\', '/')}`, tokens_est: tokensEst(text) };
+    files.push(entry);
+    return text;
+  };
+
+  await push('PILLARS.md');
+  const systems = card.data.system ?? [];
+  for (const s of (await listSystems(root)).filter((d) => systems.includes(d.data.system))) {
+    await push(`systems/${s.name}`);
+  }
+  await push(`cards/${card.name}`);
+  for (const depId of card.data.depends ?? []) {
+    const dep = cards.find((c) => c.data.id === depId);
+    if (dep) await push(`cards/${dep.name}`);
+  }
+
+  // Graveyard: headline tags only; a hit is a tag appearing in the card's own text.
+  const graveyard_hits = [];
+  const gyFile = path.join(root, 'graveyard.md');
+  if (existsSync(gyFile)) {
+    const cardText = `${card.data.slug} ${systems.join(' ')} ${card.body}`.toLowerCase();
+    for (const line of (await readFile(gyFile, 'utf8')).split('\n')) {
+      const m = line.match(/^- (card-\d{3}) \| .* \| tags: (.+)$/);
+      if (!m) continue;
+      const tags = m[2].split(',').map((t) => t.trim().toLowerCase()).filter(Boolean);
+      if (tags.some((t) => cardText.includes(t))) graveyard_hits.push(line.trim());
+    }
+  }
+
+  // D2 assumptions whose sys: overlaps the card's systems (GCF-PRD §9.1).
+  const d2 = [];
+  const oqFile = path.join(root, 'open-questions.md');
+  if (existsSync(oqFile)) {
+    const records = (await readFile(oqFile, 'utf8')).split(/\n(?=- id:)/);
+    for (const rec of records) {
+      if (!/^\s*-?\s*id:/m.test(rec) || !/class:\s*D2/.test(rec)) continue;
+      const sys = rec.match(/sys:\s*(.+)/)?.[1] ?? '';
+      if (systems.some((s) => sys.includes(s))) {
+        d2.push(rec.trim());
+      }
+    }
+  }
+
+  const extraTokens = tokensEst(graveyard_hits.join('\n')) + tokensEst(d2.join('\n'));
+  const total_tokens_est = files.reduce((sum, f) => sum + f.tokens_est, 0) + extraTokens;
+  return {
+    card: cardId,
+    files,
+    graveyard_hits,
+    d2,
+    total_tokens_est,
+    budget: config.context_budget,
+    over_budget: total_tokens_est > config.context_budget,
+  };
+}

package/lib/frontmatter.js

@@ -0,0 +1,26 @@
+import YAML from 'yaml';
+
+// Leading `---` YAML block, then the rest of the document (the body).
+const FM_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+
+/**
+ * Split a Markdown document into `{ data, body, hasFrontmatter }`.
+ * `body` is preserved byte-for-byte; only frontmatter is re-serialized on write.
+ * Throws on a frontmatter block whose YAML is malformed (fail-safe: never guess).
+ */
+export function parse(content) {
+  const m = content.match(FM_RE);
+  if (!m) return { data: {}, body: content, hasFrontmatter: false };
+  let data;
+  try {
+    data = YAML.parse(m[1]) ?? {};
+  } catch (err) {
+    throw new Error(`Frontmatter YAML could not be parsed: ${err.message}`);
+  }
+  return { data, body: m[2], hasFrontmatter: true };
+}
+
+/** Recompose a document from frontmatter `data` + untouched `body`. */
+export function serialize(data, body) {
+  return `---\n${YAML.stringify(data)}---\n${body}`;
+}

package/lib/gcf-paths.js

@@ -0,0 +1,60 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import YAML from 'yaml';
+import { parse } from './frontmatter.js';
+
+const DEFAULT_CONFIG = {
+  schema: 1,
+  built_stale_after_commits: 5,
+  tune_limit: 3,
+  question_stale_after_commits: 20,
+  wip_built_limit: 5,
+  context_budget: 30000,
+  pillars_budget: 1500,
+  envelope_default_spread: 0.3,
+};
+
+/** `gcf/` lives at the repository root (GCF-PRD §5.1). Throws when absent. */
+export function gcfRoot(projectDir = process.cwd()) {
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  if (!existsSync(root)) throw new Error(`No gcf/ directory in ${projectDir}. Run gcf init first.`);
+  return root;
+}
+
+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')) ?? {}) };
+}
+
+/** Token estimate: ceil(chars/4). Stability over accuracy (GCF-PRD §9.1). */
+export function tokensEst(text) {
+  return Math.ceil(String(text).length / 4);
+}
+
+async function listDocs(dir) {
+  if (!existsSync(dir)) return [];
+  const out = [];
+  for (const name of (await readdir(dir)).filter((n) => n.endsWith('.md')).sort()) {
+    const file = path.join(dir, name);
+    const { data, body } = parse(await readFile(file, 'utf8'));
+    out.push({ file, name, data, body });
+  }
+  return out;
+}
+
+export const listCards = (root) => listDocs(path.join(root, 'cards'));
+export const listSystems = (root) => listDocs(path.join(root, 'systems'));
+
+/** First bullet of a `key:` block in a CNL-P body, for one-line descriptions. */
+export function firstBullet(body, key) {
+  const m = String(body).match(new RegExp(`^${key}:\\s*\\n- (.+)$`, 'm'));
+  return m ? m[1].trim() : '';
+}
+
+/** Scalar value of a `key:` line. */
+export function scalarOf(body, key) {
+  const m = String(body).match(new RegExp(`^${key}:\\s*(.+)$`, 'm'));
+  return m ? m[1].trim() : '';
+}

package/lib/git.js

@@ -0,0 +1,19 @@
+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.
+ */
+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;
+  }
+  return staged;
+}

package/lib/id.js

@@ -0,0 +1,42 @@
+import path from 'node:path';
+
+// GCF-PRD §5.2/§5.5: candidates are `cand-NNN`, cards are `card-NNN`; a card keeps the
+// candidate's number on materialization. The slug lives next to the id, not inside it.
+const ID_RE = /^(card|cand)-\d{3}$/;
+
+/** Derive a stable slug from a free-text name. Created once; never re-derived. */
+export function slugify(name) {
+  const slug = String(name)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  if (!slug) throw new Error(`Cannot derive a slug from: ${JSON.stringify(name)}`);
+  return slug;
+}
+
+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})$/);
+  if (!m) throw new Error(`Not a candidate id: ${candId}`);
+  return `card-${m[1]}`;
+}
+
+/** Card filename invariant: `cards/<id>-<slug>.md`. */
+export function stemMatches(file, id, slug) {
+  return path.basename(file, '.md') === `${id}-${slug}`;
+}

package/lib/index-gen.js

@@ -0,0 +1,51 @@
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { listCards, listSystems, firstBullet } from './gcf-paths.js';
+import { atomicWrite } from './safe-path.js';
+
+/**
+ * INDEX.md is a deterministic function of gcf/ contents (GCF-PRD §5.1): generated,
+ * never hand-written. The pre-commit hook regenerates it and stages the result.
+ */
+export async function generate(root) {
+  const lines = ['# INDEX — generated, do not edit', ''];
+  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`);
+  }
+  for (const s of await listSystems(root)) {
+    row('system', `systems/${s.name}`, '-', s.data.system ?? '-', firstBullet(s.body, 'purpose'));
+  }
+  for (const c of await listCards(root)) {
+    row('card', `cards/${c.name}`, c.data.status ?? '?', (c.data.system ?? []).join(','), 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`);
+  }
+  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`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+export async function writeIndex(root) {
+  const content = await generate(root);
+  await atomicWrite(path.join(root, 'INDEX.md'), content);
+  return content;
+}
+
+/** True when INDEX.md on disk differs from the regenerated one (audit check). */
+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

@@ -0,0 +1,61 @@
+// П2 linter (GCF-PRD §13.2): explicit patterns over systems docs, no ML.
+// `<!-- gcf:allow <reason> -->` on the preceding line suppresses the next line's finding;
+// a pragma without a reason is itself a finding. cnlp check runs separately (form/lexicon).
+
+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/;
+
+/** Which `key:` block a line sits in (flat CNL-P body). */
+function blockOf(lines, i) {
+  for (let j = i; j >= 0; j--) {
+    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() });
+    }
+  }
+  // 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/playtest-list.js

@@ -0,0 +1,13 @@
+import { listCards, scalarOf } from './gcf-paths.js';
+
+/** Playtest list (GCF-PRD §10): every built card with its miss-criterion question. */
+export async function playtestList(root) {
+  return (await listCards(root))
+    .filter((c) => c.data.status === 'built')
+    .map((c) => ({
+      id: c.data.id,
+      slug: c.data.slug,
+      system: c.data.system ?? [],
+      question: scalarOf(c.body, 'miss_criterion') || '(miss_criterion is empty)',
+    }));
+}

package/lib/safe-path.js

@@ -0,0 +1,71 @@
+import { readFile, writeFile, rename, mkdir, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { stageMove } from './git.js';
+
+/**
+ * Resolve `target` and assert it stays inside `projectDir` (reject traversal / outside-project).
+ * Throws on escape; returns the absolute resolved path otherwise.
+ * Deliberately not wired into `gcf anchor`: a GDD legitimately lives outside the project
+ * and is copied INTO it. Use this for any path that must stay inside the tree.
+ */
+export function resolveInside(projectDir, target) {
+  const base = path.resolve(projectDir);
+  const resolved = path.resolve(base, target);
+  const rel = path.relative(base, resolved);
+  if (rel.startsWith('..') || path.isAbsolute(rel)) {
+    throw new Error(
+      'Path escapes the project.\n' +
+        `  expected: a path inside ${base}\n` +
+        `  detected: ${target} → ${resolved}\n` +
+        '  files:    nothing was changed\n' +
+        '  next:     pass a path within the project root',
+    );
+  }
+  return resolved;
+}
+
+/** Write atomically: tmp file in the same dir, then rename over the target. */
+export async function atomicWrite(file, data) {
+  // pid+random: writeIndex is reachable from both the pre-commit hook and applyVerdict,
+  // and a shared `${file}.tmp` lets one rename publish the other's half-written content.
+  const tmp = `${file}.${process.pid}-${Math.random().toString(36).slice(2, 8)}.tmp`;
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(tmp, data, 'utf8');
+  try {
+    await rename(tmp, file);
+  } catch (err) {
+    await unlink(tmp).catch(() => {});
+    throw err;
+  }
+}
+
+/** Restore every listed file to its original bytes when `action` fails. */
+export async function withFileRollback(files, action) {
+  const snapshots = [];
+  for (const file of new Set(files)) {
+    try {
+      snapshots.push([file, await readFile(file, 'utf8')]);
+    } catch (err) {
+      if (err.code !== 'ENOENT') throw err;
+      snapshots.push([file, null]);
+    }
+  }
+
+  try {
+    return await action();
+  } catch (err) {
+    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);
+      } catch (rollbackError) {
+        rollbackErrors.push(rollbackError);
+      }
+    }
+    // An inner step may already have staged its move; realign the index with the restored tree.
+    stageMove(...snapshots.map(([file]) => file));
+    if (rollbackErrors.length) throw new AggregateError([err, ...rollbackErrors], `Operation failed and rollback was incomplete: ${err.message}`);
+    throw err;
+  }
+}

package/lib/transitions.js

@@ -0,0 +1,30 @@
+// GCF-PRD §7.1. `none` = materialization (no card file yet).
+// `validated` and `killed` are terminal and NEVER stored: the verdict that produces them
+// also deletes the card file, so a card file carrying one is a П1 violation (pre-commit check).
+const STORED = new Set(['proposed', 'built', 'tuning']);
+export const TERMINAL = new Set(['validated', 'killed']);
+
+const LEGAL = new Set([
+  'none>proposed',
+  'proposed>built', // agent flips frontmatter itself on implementation commit (GCF-PRD §5.1)
+  'built>tuning', //   /gcf-verdict tune
+  'tuning>built', //   agent re-built after tuning
+  'built>validated', // /gcf-verdict keep — file is deleted in the same atomic commit
+  'built>killed', //   /gcf-verdict kill — file is deleted in the same atomic commit
+]);
+
+export function isLegal(from, to) {
+  return LEGAL.has(`${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]);
+}
+
+/** A status a card FILE may carry. Terminal statuses exist only in the transition itself. */
+export function isStorable(status) {
+  return STORED.has(status);
+}

package/lib/validate-card.js

@@ -0,0 +1,48 @@
+// 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 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)`,
+  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',
+  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',
+  created: (v) => /^\d{4}-\d{2}-\d{2}$/.test(dateStr(v)) || 'created must be YYYY-MM-DD',
+};
+
+const dateStr = (v) => (v instanceof Date ? v.toISOString().slice(0, 10) : String(v));
+
+const UNTIL_OK = /^\[until:\s*(verdict\(card-\d{3}\)|retune\([a-z0-9-]+\)|manual\([^)]*\))\]$/;
+
+/** Validate card frontmatter. Returns a list of one-line errors (empty = valid). */
+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)' : ''}`);
+    else if (key in RULES) {
+      const res = RULES[key](data[key]);
+      if (res !== true) errors.push(res);
+    }
+  }
+  return errors;
+}
+
+/** Validate every `[until: ...]` annotation in a body against the trigger grammar (§7.3). */
+export function validateUntil(body) {
+  const errors = [];
+  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))`);
+    }
+  });
+  return errors;
+}

package/lib/verdict-fs.js

@@ -0,0 +1,126 @@
+import { readFile, unlink } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+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 { writeIndex } from './index-gen.js';
+import { isLegal } from './transitions.js';
+
+// Slot → systems-doc section map (GCF-PRD §8.2). Deterministic merge: lines are
+// carried verbatim and deduplicated; the LLM compression of `behavior` happens in the
+// card BEFORE the verdict (the skill edits the card), not here.
+const MERGE_MAP = [
+  ['behavior', 'behavior'],
+  ['contract', 'code'],
+  ['feel', 'feel'],
+  ['constraints', 'constraints'],
+];
+
+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('- ')) : [];
+}
+
+function upsertBlock(body, key, addLines) {
+  if (!addLines.length) return body;
+  const existing = new Set(blockLines(body, key));
+  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`);
+  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'];
+function operationInProgress(projectDir) {
+  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) {
+  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' });
+  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();
+}
+
+/**
+ * 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
+ * touched systems doc; `kill` writes the graveyard line; `tune` bumps the counter and
+ * appends the human note to the feel slot.
+ *
+ * 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 } = {}) {
+  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 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 {
+    const sysFiles = systems.map((s) => 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 message = `gcf(verdict): ${verdict} ${cardId} ${card.data.slug} → ${systems.join(',')}`;
+  let hash = null;
+  await withFileRollback(touched, async () => {
+    await mutate();
+    await writeIndex(root);
+    if (commit) hash = gitCommit(projectDir, message, touched);
+  });
+  return { verdict, card: cardId, systems, hash };
+}