gcf-aif-ext 0.2.5 → 0.3.0

package/lib/linter.js

@@ -1,10 +1,24 @@
 // П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).
+import { UNITS, closingComparison } from './design-check.js';
 
-const UNIT_NUM = /\d+(?:[.,]\d+)?\s?(?:ms|мс|s|с|dmg|hp|px|сек)\b/;
+const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+// One unit list with the design check (M5), plus the units balance values come in. The end of
+// a unit is any non-letter in any script: `\w` is ASCII-only, and "5 слотов" is not "5 с".
+const UNIT_WORDS = [...UNITS, 'мс', 'с', 'сек', 'dmg', 'hp', 'px'].map(esc).join('|');
+const UNIT_NUM = new RegExp(`\\d+(?:[.,]\\d+)?\\s?(?:${UNIT_WORDS})(?![\\p{L}\\p{N}_-])`, 'u');
 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 +26,85 @@ 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() });
-    }
+  // CRLF from a Windows checkout: a trailing `\r` would defeat every end-anchored pattern.
+  const lines = String(content).replace(/\r\n/g, '\n').split('\n');
+  /** @type {LintState} */
+  const st = { lines, 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.
+  // An exact limit is legal as a closing comparison in any block (GCF-PRD §11.3), as in the
+  // card M5 accepted: a boundary collapses into `behavior:` and must not fail its own verdict.
+  const block = blockOf(st.lines, i);
+  const limit = closingComparison(line);
+  if (block !== 'feel' && !limit && !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/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/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/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/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. */