gcf-aif-ext 0.2.7 → 0.3.0

package/lib/migrate.js

@@ -0,0 +1,345 @@
+// One-shot upgrade from the 0.2 backlog (GCF-PRD v5.8 §5.2) to the Design Model (v6.0): each
+// `- cand-NNN | …` line becomes a unit in gcf/design/<sys>.md, the backlog keeps only the order.
+// Deterministic: the line format was fixed, so nothing here needs a model. Only the quote is the
+// GDD's; every slot the line did not carry reads TBD, because the description was a paraphrase.
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { slugify } from './id.js';
+import { buildLedger } from './ledger.js';
+import { atomicWrite, withFileRollback, resolveInside } from './safe-path.js';
+import { writeIndex } from './index-gen.js';
+import { recordLine } from './verdict-fs.js';
+
+// The id stops before a quote: a revert subject closes the quoted original right after it.
+// A v5.8 verdict names the card file first (`keep card-012 tile-rotation → board`): the slug
+// after it is the id v6 uses.
+const MOVE_RE = /^gcf\((verdict|done)\): (?:(keep|kill|tune) )?(?:card-\d+ (?=[a-z0-9]))?([^\s"]+)/;
+
+/** `Revert "…"` undoes once, `Reapply "…"` (a revert of a revert) twice: parity decides. */
+function unwrap(subject) {
+  let s = subject;
+  let depth = 0;
+  for (;;) {
+    if (s.startsWith('Revert "')) [s, depth] = [s.slice(8), depth + 1];
+    else if (s.startsWith('Reapply "')) [s, depth] = [s.slice(9), depth + 2];
+    else return { s, undo: depth % 2 === 1 };
+  }
+}
+
+/**
+ * Keeps and dones still in force in commit subjects, newest first, as `[id, event, index]`: an
+ * undo cancels the next older event of its kind for that id.
+ * @param {string[]} subjects
+ * @returns {[string, string, number][]}
+ */
+export function lifeEvents(subjects) {
+  const cancels = new Map();
+  /** @type {[string, string, number][]} */
+  const out = [];
+  for (const [i, subject] of subjects.entries()) {
+    const { s, undo } = unwrap(subject);
+    const m = s.match(MOVE_RE);
+    const event = m && (m[1] === 'done' ? 'done' : m[2] === 'keep' ? 'collapsed' : null);
+    if (!m || !event) continue;
+    const key = `${event}:${m[3]}`;
+    if (undo) cancels.set(key, (cancels.get(key) ?? 0) + 1);
+    else if (cancels.get(key)) cancels.set(key, cancels.get(key) - 1);
+    else out.push([m[3], event, i]);
+  }
+
+  return out;
+}
+
+/**
+ * A project older than history.md keeps its keeps (v5.8 verdicts) and dones only in commit
+ * subjects: the `[id, event, date]` lines history.md lacks, to write once.
+ * @returns {Promise<[string, string, string][]>}
+ */
+async function historySeed(projectDir, root) {
+  const res = spawnSync(
+    'git',
+    ['log', '-E', '--grep', '^((Revert|Reapply) ")*gcf\\((verdict|done)\\):', '--format=%as %s'],
+    { cwd: projectDir, encoding: 'utf8' },
+  );
+  const log = res.status === 0 ? res.stdout.split('\n').filter(Boolean) : [];
+  const file = path.join(root, 'history.md');
+  const text = existsSync(file) ? await readFile(file, 'utf8') : '';
+  const have = new Set([...text.matchAll(/^- (\S+) \|/gm)].map((m) => m[1]));
+
+  return lifeEvents(log.map((l) => l.slice(11)))
+    .filter(([id]) => !have.has(id))
+    .map(([id, event, i]) => [id, event, log[i].slice(0, 10)]);
+}
+
+const SOFT = ['behavior', 'refusal', 'boundaries', 'persistence', 'feel_like', 'feel'];
+const LIST_LENSES = ['refusal', 'boundaries'];
+
+/** `soft (why)` → `{ hard, why }`; a missing route reads soft, the safe default. */
+function routeOf(value) {
+  const m = String(value ?? '').match(/^(soft|hard)\s*\((.*)\)$/);
+
+  return { hard: m?.[1] === 'hard', why: m?.[2] || 'acceptance is a playtest' };
+}
+
+/** `- cand-NNN | name | route: soft (why) | sys: s | deps: a, b | src: X | q: "…" | … | descr` */
+export function parseCandidate(line) {
+  const id = line.match(/^- (cand-\d+) \|/)?.[1];
+  if (!id) return null;
+  // The quote may hold `|`: cut it out before splitting the fields.
+  const quote = line.match(/\|\s*q:\s*"(.*?)"\s*(?=\||$)/)?.[1] ?? null;
+  const fields = line
+    .replace(/\|\s*q:\s*".*?"\s*(?=\||$)/, '')
+    .split(' | ')
+    .map((f) => f.trim());
+  const get = (key) =>
+    fields
+      .find((f) => f.startsWith(`${key}:`))
+      ?.slice(key.length + 1)
+      .trim();
+
+  return {
+    id,
+    name: fields[1],
+    ...routeOf(get('route')),
+    system: get('sys') || 'unassigned',
+    deps: (get('deps') ?? '-')
+      .split(',')
+      .map((d) => d.trim())
+      .filter((d) => d && d !== '-'),
+    source: get('src') || 'manual',
+    quote,
+    gaps: get('gaps') ?? '',
+    flags: ['impl?', 'src-changed', 'orphan'].filter((f) => fields.includes(f)),
+    description: fields[fields.length - 1],
+  };
+}
+
+/** `refusal (target overlaps a placed tile), state (…)` → { refusal: ['target overlaps…'] } */
+function gapDetails(gaps) {
+  /** @type {Record<string, string[]>} */
+  const out = {};
+  for (const m of gaps.matchAll(/([a-z]+)(?:\s*\(([^)]*)\))?/g)) {
+    out[m[1]] = [...(out[m[1]] ?? []), ...(m[2] ? [m[2]] : [])];
+  }
+
+  return out;
+}
+
+const BEHAVIOR_KEYS = ['input', 'state', 'feedback'];
+const KNOWN_LENSES = [...BEHAVIOR_KEYS, ...LIST_LENSES, 'persistence'];
+
+/**
+ * Every gap note the line carried survives as a `TBD` in its slot: `state (anchor convention)`
+ * becomes `state: anchor convention: TBD`. A lens the slots do not name goes to `boundaries`.
+ */
+function softBody(c) {
+  const d = gapDetails(c.gaps);
+  const note = (lens) => (d[lens]?.length ? `${d[lens].join('; ')}: TBD` : 'TBD');
+  const other = Object.keys(d).filter((k) => !KNOWN_LENSES.includes(k));
+  const items = (k) => [
+    ...(d[k] ?? []).map((x) => `- ${x}: TBD`),
+    ...(k === 'boundaries' ? other.map((o) => `- ${[o, ...(d[o] ?? [])].join(': ')}: TBD`) : []),
+  ];
+  const list = (k) => (items(k).length ? [`${k}:`, ...items(k), ''] : [`${k}: TBD`, '']);
+  const behavior = BEHAVIOR_KEYS.some((k) => d[k]?.length)
+    ? ['behavior:', ...BEHAVIOR_KEYS.map((k, i) => `${i ? '  ' : '- '}${k}: ${note(k)}`), '']
+    : ['behavior: TBD', ''];
+
+  return [
+    ...behavior,
+    ...list('refusal'),
+    ...list('boundaries'),
+    `persistence: ${note('persistence')}`,
+    '',
+    ...SOFT.filter((b) => b.startsWith('feel')).flatMap((b) => [`${b}: TBD`, '']),
+  ];
+}
+
+/** A hard unit keeps its gap notes as `TBD` statements beside the one it was cut from. */
+const hardGaps = (c) =>
+  Object.entries(gapDetails(c.gaps)).map(
+    ([lens, notes]) => `- ${[lens, ...notes].join(': ')}: TBD`,
+  );
+
+/** The `## <id>` section a candidate becomes. */
+export function unitText(c, id, depends) {
+  const slot = c.hard ? 'statement' : 'intent';
+  const body = c.hard
+    ? ['statement:', `- ${c.description}`, ...hardGaps(c), '', 'check: TBD', '']
+    : [
+        'intent:',
+        `- ${c.description}`,
+        '',
+        ...softBody(c),
+        'constraints: TBD',
+        '',
+        'miss_criterion: TBD',
+        '',
+      ];
+  const prov =
+    c.quote && c.source.startsWith('GDD#')
+      ? ['provenance:', `- slot: ${slot}`, `  src: ${c.source}`, `  quote: "${c.quote}"`, '']
+      : [];
+
+  return [
+    `## ${id}`,
+    '',
+    `type: ${c.hard ? 'rule' : 'mechanic'}`,
+    `title: ${c.name}`,
+    `route: ${c.hard ? 'hard' : 'soft'} (${c.why})`,
+    `system: [${c.system}]`,
+    'milestone: TBD',
+    'pillars: TBD',
+    `depends: ${depends.length ? `[${depends.join(', ')}]` : 'none'}`,
+    `source: ${c.source.startsWith('GDD#') ? c.source : 'manual'}`,
+    ...(c.flags.length ? [`flags: ${c.flags.join(', ')}`] : []),
+    '',
+    ...body,
+    ...prov,
+  ].join('\n');
+}
+
+/** The slug of a name, or null when the name has no latin letter or digit to slug. */
+function safeSlug(name) {
+  try {
+    return slugify(name);
+  } catch {
+    return null;
+  }
+}
+
+/** cand-NNN → a slug no unit has used: the name, suffixed -2, -3… on a collision. */
+function mintIds(cands, taken) {
+  const map = new Map();
+  for (const c of cands) {
+    const base = safeSlug(c.name) ?? c.id;
+    let id = base;
+    for (let n = 2; taken.has(id); n++) id = `${base}-${n}`;
+    taken.add(id);
+    map.set(c.id, id);
+  }
+
+  return map;
+}
+
+const rewriteIds = (text, map) => text.replace(/\bcand-\d+\b/g, (m) => map.get(m) ?? m);
+
+/**
+ * The backlog in its old order: a candidate line becomes its new id, a skipped one goes, an
+ * id line stays; units already in design/ that the order lacks go to the end for the human.
+ */
+async function newBacklog(lines, map, ledger) {
+  const order = [];
+  for (const l of lines) {
+    const id = l.match(/^- (\S+)/)?.[1];
+    if (!id) continue;
+    if (/^cand-\d+$/.test(id)) {
+      if (map.has(id)) order.push(map.get(id));
+    } else order.push(id);
+  }
+
+  for (const u of ledger.design.flatMap((d) => d.units)) order.push(u.id);
+  const header = await readFile(new URL('../templates/backlog.md', import.meta.url), 'utf8');
+
+  return `${header.trimEnd()}\n${[...new Set(order)].map((id) => `- ${id}`).join('\n')}\n`;
+}
+
+/**
+ * `cand-002`, `cand-002=board-grid` (converted by hand into that unit) or `cand-002=board+rules`
+ * (split by hand into several) → a map entry.
+ * @param {string} s
+ * @returns {[string, string[]]}
+ */
+const skipEntry = (s) => {
+  const [cand, ids = ''] = s.split('=').map((x) => x.trim());
+
+  return [cand, ids.split('+').filter(Boolean)];
+};
+
+/** A dependency is a candidate (mapped to its new ids) or an id the project already knows. */
+function depTarget(skipped, map, known) {
+  return (d) => {
+    if (skipped.get(d)?.length) return skipped.get(d);
+    if (map.has(d)) return [map.get(d)];
+
+    return known(d) ? [d] : [];
+  };
+}
+
+/**
+ * Move every candidate line of gcf/backlog.md into gcf/design/. `skip` names candidates a
+ * human already converted by hand: their lines go, no unit is written for them, and with
+ * `cand-NNN=<id>` (or `=<id>+<id>` for a split) the dependencies on them follow to those units.
+ * No commit — the human reads the report and `design check`, fixes what they show, and commits.
+ */
+export async function migrateBacklog(projectDir, { skip = [] } = {}) {
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const backlogFile = path.join(root, 'backlog.md');
+  const lines = (await readFile(backlogFile, 'utf8')).split('\n');
+  const skipped = new Map(skip.map(skipEntry));
+  const all = lines.flatMap((l) => parseCandidate(l) ?? []);
+  const cands = all.filter((c) => !skipped.has(c.id));
+  // An id a v5.8 verdict kept is known and is not minted again; its line lands with the rest.
+  const seed = await historySeed(projectDir, root);
+  const ledger = await buildLedger(projectDir);
+  const known = (d) => ledger.known(d) || seed.some(([id]) => id === d);
+  const handIds = new Set(ledger.design.flatMap((d) => d.units.map((u) => u.id)));
+  const map = mintIds(cands, new Set([...ledger.ids(), ...seed.map(([id]) => id)]));
+  // A reference to a split candidate names its first unit; a dependency on it, every unit.
+  for (const [cand, ids] of skipped) if (ids.length) map.set(cand, ids[0]);
+  const target = depTarget(skipped, map, known);
+  /** @type {{lost_depends: string[], maybe_duplicates: string[], unmoved_gaps: string[]}} */
+  const report = { lost_depends: [], maybe_duplicates: [], unmoved_gaps: [] };
+  // A hand-converted candidate's gap notes may not have made it into its unit: the human checks
+  // each one there.
+  for (const c of all.filter((x) => skipped.has(x.id) && hardGaps(x).length)) {
+    const notes = hardGaps(c).map((g) => g.slice(2));
+    report.unmoved_gaps.push(`${map.get(c.id) ?? c.id}: ${notes.join('; ')}`);
+  }
+
+  const bySystem = new Map();
+  for (const c of cands) {
+    const id = map.get(c.id);
+    const lost = c.deps.filter((d) => !target(d).length);
+    report.lost_depends.push(...lost.map((d) => `${id} depended on ${d}`));
+    const slug = safeSlug(c.name);
+    if (slug && handIds.has(slug)) report.maybe_duplicates.push(`${id} ≈ ${slug}`);
+    const text = unitText(c, id, [...new Set(c.deps.flatMap(target))]);
+    bySystem.set(c.system, [...(bySystem.get(c.system) ?? []), text]);
+  }
+
+  const designFiles = [...bySystem.keys()].map((s) =>
+    resolveInside(path.join(root, 'design'), `${s}.md`),
+  );
+  const extra = ['open-questions.md', 'graveyard.md']
+    .map((f) => path.join(root, f))
+    .filter(existsSync);
+  const history = path.join(root, 'history.md');
+  await withFileRollback(
+    [backlogFile, ...designFiles, ...extra, history, path.join(root, 'INDEX.md')],
+    async () => {
+      for (const [id, event, date] of seed) await recordLine(root, id, event, date);
+      for (const [system, texts] of bySystem) {
+        const file = resolveInside(path.join(root, 'design'), `${system}.md`);
+        const head = existsSync(file)
+          ? (await readFile(file, 'utf8')).trimEnd()
+          : `# ${system}\n\npurpose: TBD`;
+        await atomicWrite(file, `${head}\n\n${texts.join('\n')}`.trimEnd() + '\n');
+      }
+
+      await atomicWrite(backlogFile, await newBacklog(lines, map, ledger));
+      for (const f of extra) await atomicWrite(f, rewriteIds(await readFile(f, 'utf8'), map));
+      await writeIndex(root);
+    },
+  );
+
+  return {
+    units: cands.length,
+    skipped: skipped.size,
+    history: seed.length,
+    ids: Object.fromEntries(map),
+    ...report,
+  };
+}

package/lib/playtest-list.js

@@ -6,7 +6,7 @@ export async function playtestList(root) {
     .filter((c) => c.data.status === 'built')
     .map((c) => ({
       id: c.data.id,
-      slug: c.data.slug,
+      title: c.data.title ?? null,
       system: c.data.system ?? [],
       question: scalarOf(c.body, 'miss_criterion') || '(miss_criterion is empty)',
     }));

package/lib/systems-doc.js

@@ -0,0 +1,70 @@
+// Writing into systems/<name>.md (GCF-PRD §8): the keep merge and the hard `gcf done` line.
+// Lines are carried verbatim and deduplicated; compressing them is the skill's job, before.
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { parseBlocks, itemsOf } from 'cnlp-kit';
+import { parse } from './frontmatter.js';
+import { scalarIn } from './design.js';
+
+const NONE_LINE = '- none: no card of this subsystem has collapsed yet';
+
+export function blockLines(body, key) {
+  const { lines, sections } = parseBlocks(body);
+  const at = sections.find((s) => s.key === key);
+
+  return at ? itemsOf(lines, at.line).map((i) => i.text) : [];
+}
+
+/**
+ * Append `addLines` to the `key:` bullet block of a body, skipping lines already there. A
+ * `- none: …` placeholder gives way: CNL-P reads it as the whole content or not at all.
+ */
+export function upsertBlock(rawBody, key, addLines) {
+  // A CRLF checkout: `\r` before each `\n` would stop the block match at its first line and
+  // duplicate every line after it.
+  const body = lf(rawBody);
+  const existing = blockLines(body, key);
+  const fresh = addLines.filter((l) => !existing.includes(l));
+  if (!fresh.length) return body;
+  const kept = existing.filter((l) => !/^- none\b/.test(l));
+  const block = `${key}:\n${[...kept, ...fresh].join('\n')}\n`;
+  const re = new RegExp(`^${key}:[^\\n]*\\n(?:(?!\\S+:).*\\n?)*`, 'm');
+  // A replacer function: a string replacement would expand `$&` or `$'` inside a line.
+  if (re.test(body)) return body.replace(re, () => `${block}\n`).replace(/\n{3,}/g, '\n\n');
+
+  return `${body.trimEnd()}\n\n${block}`;
+}
+
+const lf = (text) => String(text).replace(/\r\n/g, '\n');
+
+/** Purpose lines a new systems doc starts with: design/<sys>.md's `purpose:`, or a marker. */
+async function purposeLines(root, system) {
+  const file = path.join(root, 'design', `${system}.md`);
+  const text = existsSync(file) ? lf(await readFile(file, 'utf8')) : '';
+  const pre = text.split(/^## /m)[0];
+  const bullets = blockLines(pre, 'purpose').filter((l) => !/^- (TBD|none\b)/.test(l));
+  if (bullets.length) return bullets;
+  const scalar = scalarIn(pre, 'purpose');
+  if (scalar && scalar !== 'TBD') return [`- ${scalar}`];
+
+  return [`- the purpose of ${system} is not written yet [until: manual(purpose of ${system})]`];
+}
+
+/**
+ * The systems doc of `system`, read, or started: purpose from design/, every other required
+ * block a `- none:` placeholder until a merge brings content.
+ */
+export async function openSystemDoc(root, system) {
+  const file = path.join(root, 'systems', `${system}.md`);
+  if (existsSync(file)) return { file, ...parse(lf(await readFile(file, 'utf8'))) };
+  const purpose = (await purposeLines(root, system)).join('\n');
+  const body = [
+    `purpose:\n${purpose}`,
+    `code:\n${NONE_LINE}`,
+    `behavior:\n${NONE_LINE}`,
+    `constraints:\n${NONE_LINE}`,
+  ].join('\n\n');
+
+  return { file, data: { system }, body: `\n${body}\n` };
+}

package/lib/unit-ops.js

@@ -0,0 +1,270 @@
+// The moves a design unit makes out of design/ (GCF-PRD §4): `take` into a card, `done` into
+// tests and code, `drop` into the graveyard. Each one removes the section and its backlog line
+// in the same step, so an id never lives in two places (M12).
+import { readFile, unlink } from 'node:fs/promises';
+import { existsSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { serialize } from './frontmatter.js';
+import { CARD_TYPES, listOf } from './design.js';
+import { buildLedger } from './ledger.js';
+import { designCheck } from './design-check.js';
+import { atomicWrite, withFileRollback } from './safe-path.js';
+import { writeIndex } from './index-gen.js';
+import { operationInProgress, commitPaths } from './git.js';
+import { upsertBlock, openSystemDoc } from './systems-doc.js';
+import { buryLine, recordLine } from './verdict-fs.js';
+
+/** A design file's text without the `## <id>` section. */
+export function removeUnit(text, id) {
+  const lines = String(text).split('\n');
+  const at = lines.findIndex((l) => l.trimEnd() === `## ${id}`);
+  if (at < 0) return text;
+  let end = lines.findIndex((l, i) => i > at && /^## \S/.test(l));
+  if (end < 0) end = lines.length;
+
+  return `${[...lines.slice(0, at), ...lines.slice(end)]
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trimEnd()}\n`;
+}
+
+/** backlog.md without the line of `id`. */
+export const backlogWithout = (text, id) =>
+  String(text)
+    .split('\n')
+    .filter((l) => l.match(/^- (\S+)/)?.[1] !== id)
+    .join('\n');
+
+/** The single design unit `id`, or an error naming where the id lives instead. */
+async function designUnit(projectDir, id) {
+  const ledger = await buildLedger(projectDir);
+  const { live, terminal } = ledger.where(id);
+  if (live.length !== 1 || live[0].state !== 'design') {
+    const at = live.map((p) => p.file).join(', ') || terminal.join(', ') || 'nowhere';
+    throw new Error(`${id} is not a single unit of gcf/design/ (it is: ${at})`);
+  }
+
+  const unit = ledger.design.flatMap((d) => d.units).find((u) => u.id === id);
+
+  return /** @type {import('./design.js').Unit} */ (unit);
+}
+
+/** Files a move rewrites: the design file, the backlog, then whatever the move adds. */
+function basePaths(root, unit) {
+  return { design: path.join(root, unit.file), backlog: path.join(root, 'backlog.md') };
+}
+
+async function cutUnit(paths, id) {
+  await atomicWrite(paths.design, removeUnit(await readFile(paths.design, 'utf8'), id));
+  if (existsSync(paths.backlog))
+    await atomicWrite(paths.backlog, backlogWithout(await readFile(paths.backlog, 'utf8'), id));
+}
+
+/** The frontmatter a card starts with: the unit's header plus the fields of the card stage. */
+function cardData(unit, today) {
+  const h = unit.header;
+  const pillars = listOf(h.pillars);
+
+  return {
+    schema: 2,
+    id: unit.id,
+    type: h.type,
+    ...(h.title ? { title: h.title } : {}),
+    status: 'proposed',
+    system: listOf(h.system),
+    depends: listOf(h.depends),
+    pillars: pillars === 'TBD' ? [] : pillars,
+    source: h.source,
+    ...(h.reopens ? { reopens: h.reopens } : {}),
+    tune_count: 0,
+    built_at: null,
+    created: today,
+  };
+}
+
+/**
+ * Take a ready soft unit into work: its section becomes cards/<id>.md with the same body.
+ * No commit — `/gcf-card` adds `contract` and `interactions`, and the pre-commit gate holds
+ * the card until it carries both.
+ */
+export async function takeUnit(
+  projectDir,
+  id,
+  { today = new Date().toISOString().slice(0, 10) } = {},
+) {
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const unit = await designUnit(projectDir, id);
+  if (!CARD_TYPES.includes(unit.header.type)) {
+    throw new Error(
+      `${id} is hard: close its TBD in place, run the AIF cycle, then gcf done ${id}`,
+    );
+  }
+
+  const summary = (await designCheck(projectDir)).units.find((u) => u.id === id);
+  if (!summary?.ready) {
+    const why = summary?.blocked_by.length
+      ? `blocked by ${summary.blocked_by.join(', ')}`
+      : `${summary?.tbd ?? '?'} TBD or a blocking design-check finding`;
+    throw new Error(`${id} is not ready (${why}): answer it in design/ first`);
+  }
+
+  const paths = { ...basePaths(root, unit), card: path.join(root, 'cards', `${id}.md`) };
+  if (existsSync(paths.card)) throw new Error(`gcf/cards/${id}.md already exists`);
+  await withFileRollback([...Object.values(paths), path.join(root, 'INDEX.md')], async () => {
+    await atomicWrite(paths.card, serialize(cardData(unit, today), `\n${unit.body.trim()}\n`));
+    await cutUnit(paths, id);
+    await writeIndex(root);
+  });
+
+  return { card: `gcf/cards/${id}.md` };
+}
+
+/** A file's text at a git revision spec (`HEAD:./x`, `:./x` for the index), '' when absent. */
+function gitText(projectDir, spec) {
+  const res = spawnSync('git', ['show', spec], { cwd: projectDir, encoding: 'utf8' });
+
+  return res.status === 0 ? res.stdout : '';
+}
+
+/**
+ * True when `file` differs from HEAD in the index or on disk. Line endings do not count: a file
+ * stored with CRLF and checked out with LF is not an edit.
+ */
+function uncommitted(projectDir, file) {
+  const rel = `./${path.relative(projectDir, file).replaceAll('\\', '/')}`;
+  const norm = (t) => String(t).replace(/\r\n/g, '\n').trimEnd();
+  const head = norm(gitText(projectDir, `HEAD:${rel}`));
+  const disk = norm(existsSync(file) ? readFileSync(file, 'utf8') : '');
+
+  return head !== norm(gitText(projectDir, `:${rel}`)) || head !== disk;
+}
+
+/**
+ * Run a move that ends with its fixed-format commit, all of it or none of it. The commit takes
+ * whole files and deletes the unit's section, so any uncommitted edit in them refuses the move
+ * up front — an answer in the unit itself included: it would leave in a commit that never held
+ * it, and no history would keep it.
+ */
+async function commitMove(projectDir, message, { files, mutate, commit }) {
+  const busy = commit ? operationInProgress(projectDir) : null;
+  if (busy) throw new Error(`cannot record ${message} while ${busy} is in progress`);
+  const dirty = commit ? files.filter((f) => uncommitted(projectDir, f)) : [];
+  if (dirty.length) {
+    const names = dirty.map((f) => path.relative(projectDir, f)).join(', ');
+    throw new Error(
+      `commit or stash these first (an answered unit is committed before its move), ` +
+        `${message} would carry them: ${names}`,
+    );
+  }
+
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const touched = [...files, path.join(root, 'INDEX.md')];
+  /** @type {string | null} */
+  let hash = null;
+  await withFileRollback(
+    touched,
+    async () => {
+      await mutate();
+      await writeIndex(root);
+      if (commit) hash = commitPaths(projectDir, message, touched);
+    },
+    { gitCwd: commit ? path.resolve(projectDir) : null },
+  );
+
+  return hash;
+}
+
+/**
+ * A hard unit is built and its tests are green: it leaves design/. A line every future reader
+ * of the subsystem must remember goes to the systems doc's `constraints:` (GCF-PRD §6.3).
+ */
+export async function doneUnit(projectDir, id, { constraints = [], commit = true } = {}) {
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const unit = await designUnit(projectDir, id);
+  if (CARD_TYPES.includes(unit.header.type))
+    throw new Error(`${id} is soft: it leaves design/ through a card and a verdict`);
+  const summary = (await designCheck(projectDir)).units.find((u) => u.id === id);
+  if (summary?.tbd)
+    throw new Error(`${id} still carries ${summary.tbd} TBD: it was built on a hole — answer it`);
+  const paths = basePaths(root, unit);
+  const doc = constraints.length ? await openSystemDoc(root, unit.system) : null;
+  const files = [paths.design, paths.backlog, path.join(root, 'history.md')];
+  if (doc) files.push(doc.file);
+  const mutate = async () => {
+    await cutUnit(paths, id);
+    await recordLine(root, id, 'done');
+    if (!doc) return;
+    const body = upsertBlock(
+      doc.body,
+      'constraints',
+      constraints.map((c) => `- ${c}`),
+    );
+    await atomicWrite(doc.file, serialize({ ...doc.data, updated_by: id }, body));
+  };
+
+  return {
+    id,
+    hash: await commitMove(projectDir, `gcf(done): ${id}`, { files, mutate, commit }),
+  };
+}
+
+/**
+ * A card taken into work but never built is given up: no playtest, so no verdict — a drop. Its
+ * file goes, the graveyard keeps the reason. A built card waits for its verdict instead.
+ */
+async function dropCard(projectDir, card, { reason, tags, commit }) {
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const id = String(card.data.id);
+  if (!['proposed', 'tuning'].includes(card.data.status))
+    throw new Error(`${id} is ${card.data.status}: play it and give the verdict, kill included`);
+  const rel = `./${path.relative(projectDir, card.file).replaceAll('\\', '/')}`;
+  if (commit && !gitText(projectDir, `HEAD:${rel}`)) {
+    throw new Error(
+      `${id} was taken but its card is not committed: commit it first, or undo the take ` +
+        `(delete the card, restore its section in gcf/design/ and its backlog line)`,
+    );
+  }
+
+  const files = [card.file, path.join(root, 'graveyard.md')];
+  const mutate = async () => {
+    await buryLine(root, id, reason, tags.length ? tags : (card.data.system ?? []));
+    await unlink(card.file);
+  };
+
+  return {
+    id,
+    hash: await commitMove(projectDir, `gcf(drop): ${id}`, { files, mutate, commit }),
+  };
+}
+
+/**
+ * A unit — or a card not yet built — is dropped before any playtest: a graveyard line keeps the
+ * reason (GCF-PRD §5.6).
+ */
+export async function dropUnit(projectDir, id, { reason, tags = [], commit = true }) {
+  if (!String(reason ?? '').trim())
+    throw new Error('a drop needs a reason: the graveyard keeps it');
+  const ledger = await buildLedger(projectDir);
+  const live = ledger.where(id).live;
+  if (live.length === 1 && live[0].state === 'card') {
+    const card = ledger.cards.find((c) => c.data.id === id);
+
+    return dropCard(projectDir, card, { reason, tags, commit });
+  }
+
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const unit = await designUnit(projectDir, id);
+  const paths = basePaths(root, unit);
+  const system = listOf(unit.header.system);
+  const files = [paths.design, paths.backlog, path.join(root, 'graveyard.md')];
+  const mutate = async () => {
+    await buryLine(root, id, reason, tags.length ? tags : system === 'TBD' ? [] : system);
+    await cutUnit(paths, id);
+  };
+
+  return {
+    id,
+    hash: await commitMove(projectDir, `gcf(drop): ${id}`, { files, mutate, commit }),
+  };
+}