gcf-aif-ext 0.2.7 → 0.4.0

package/lib/live.js

@@ -0,0 +1,179 @@
+// LIVE.md (Methodology §8): what the game is now, one short record per capability and per known
+// issue, no history. Capabilities change only through the live: delta of an item, applied in the
+// commit of the move that ends it; known issues are the parked bugs, written by `decide known`
+// and taken out by any end of that bug.
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { atomicWrite } from './safe-path.js';
+import { listItems } from './gcf-paths.js';
+import { summaryProblem } from './validate-item.js';
+
+const SECTIONS = { capabilities: 'capabilities', 'known-issues': 'knownIssues' };
+const NONE = {
+  capabilities: '- none: no capability recorded yet',
+  'known-issues': '- none: no known issue',
+};
+
+/** @typedef {{id: string, summary: string, refs?: string}} LiveRecord */
+
+/** Parse LIVE.md text: `{capabilities, knownIssues, problems}`. */
+export function parseLive(text) {
+  /** @type {{capabilities: LiveRecord[], knownIssues: LiveRecord[], problems: string[]}} */
+  const out = { capabilities: [], knownIssues: [], problems: [] };
+  const body = String(text)
+    .replace(/\r\n/g, '\n')
+    .replace(/^---\n[\s\S]*?\n---\n?/, '');
+  /** @type {'capabilities' | 'knownIssues' | null} */
+  let section = null;
+  /** @type {LiveRecord | null} */
+  let rec = null;
+  body.split('\n').forEach((line, i) => {
+    const head = line.match(/^([a-z-]+):\s*$/);
+    if (head) {
+      section = SECTIONS[head[1]] ?? null;
+      if (!section) out.problems.push(`line ${i + 1}: unknown section ${head[1]}:`);
+      rec = null;
+
+      return;
+    }
+
+    const start = line.match(/^- id:\s*(\S+)\s*$/);
+    if (start && section) {
+      rec = { id: start[1], summary: '' };
+      out[section].push(rec);
+
+      return;
+    }
+
+    const field = line.match(/^ {2}(summary|refs):\s*(.+?)\s*$/);
+    if (field && rec) {
+      rec[field[1]] = field[2];
+
+      return;
+    }
+
+    if (line.trim() && !/^- none\b/.test(line) && !line.startsWith('#'))
+      out.problems.push(`line ${i + 1}: not a record line: ${line.trim()}`);
+  });
+
+  return out;
+}
+
+const recordText = (r) =>
+  [`- id: ${r.id}`, `  summary: ${r.summary}`, ...(r.refs ? [`  refs: ${r.refs}`] : [])].join('\n');
+
+const byId = (a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+
+/** LIVE.md text: records sorted by id, so two branches touching different ids merge cleanly. */
+export function serializeLive({ capabilities, knownIssues }) {
+  const block = (key, list) =>
+    `${key}:\n${list.length ? [...list].sort(byId).map(recordText).join('\n') : NONE[key]}\n`;
+
+  return [
+    '---\ntype: live\n---\n',
+    block('capabilities', capabilities),
+    block('known-issues', knownIssues),
+  ].join('\n');
+}
+
+export const liveFile = (root) => path.join(root, 'LIVE.md');
+
+export async function readLive(root) {
+  const file = liveFile(root);
+
+  return parseLive(existsSync(file) ? await readFile(file, 'utf8') : '');
+}
+
+export async function writeLive(root, live) {
+  await atomicWrite(liveFile(root), serializeLive(live));
+}
+
+/**
+ * The capabilities after `delta` (an item's `live:`), or a thrown reason. `none` changes nothing;
+ * `added` needs a new id, `modified` and `removed` an existing one.
+ */
+export function applyDelta(capabilities, delta, itemId) {
+  if (!delta) throw new Error(`${itemId} has no live: delta — say what it changes, or none: <why>`);
+  if ('none' in delta) return capabilities;
+  let next = [...capabilities];
+  for (const c of delta.changes) {
+    const at = next.findIndex((r) => r.id === c.id);
+    if (c.change === 'added' && at >= 0)
+      throw new Error(`${itemId}: capability ${c.id} already exists — use change: modified`);
+    if (c.change !== 'added' && at < 0)
+      throw new Error(`${itemId}: capability ${c.id} is not in LIVE.md — nothing to ${c.change}`);
+    if (c.change === 'removed') next = next.filter((r) => r.id !== c.id);
+    else {
+      const rec = { id: c.id, summary: c.summary, ...(c.refs ? { refs: c.refs } : {}) };
+      if (at >= 0) next[at] = { ...next[at], ...rec };
+      else next.push(rec);
+    }
+  }
+
+  return next;
+}
+
+/**
+ * The capabilities without what `delta` added: an unplayed mechanic killed, dropped or sent back
+ * to tuning leaves the game, so its record leaves LIVE.md with it. `modified` and `removed`
+ * cannot be undone from the delta alone and stay as they are.
+ */
+export function revertDelta(capabilities, delta) {
+  if (!delta || 'none' in delta) return capabilities;
+  const added = delta.changes.filter((c) => c.change === 'added').map((c) => c.id);
+
+  return capabilities.filter((r) => !added.includes(r.id));
+}
+
+/** The known-issue record of a parked bug: its title or first intent bullet, and its file. */
+export function knownIssueOf(item) {
+  const intent = String(item.body ?? '').match(/^intent:\s*\n- (.+)$/m)?.[1];
+  const summary = String(item.data.title ?? intent ?? item.data.id).trim();
+
+  return { id: String(item.data.id), summary, refs: `gcf/work/${item.data.id}.md` };
+}
+
+/** The refs of a record that name no file of the project. */
+const brokenRefs = (projectDir, r) =>
+  String(r.refs ?? '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter((ref) => ref && !existsSync(path.join(projectDir, ref.split('#')[0])));
+
+/**
+ * `live check`: record form, duplicate ids, refs that name no file, a known issue without its
+ * parked bug and a parked bug without its known issue.
+ */
+export async function checkLive(projectDir) {
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const live = await readLive(root);
+  const issues = [...live.problems];
+  /** @type {Array<[string, LiveRecord[]]>} */
+  const kinds = [
+    ['capability', live.capabilities],
+    ['known issue', live.knownIssues],
+  ];
+  for (const [name, list] of kinds) {
+    const seen = new Set();
+    for (const r of list) {
+      if (seen.has(r.id)) issues.push(`${name} ${r.id} is listed twice`);
+      seen.add(r.id);
+      const bad = summaryProblem(r.summary);
+      if (bad) issues.push(`${name} ${r.id}: ${bad}`);
+      issues.push(
+        ...brokenRefs(projectDir, r).map((ref) => `${name} ${r.id}: refs ${ref} names no file`),
+      );
+    }
+  }
+
+  const parked = (await listItems(root)).filter((i) => i.data.status === 'parked');
+  const known = new Set(live.knownIssues.map((r) => r.id));
+  for (const p of parked)
+    if (!known.has(p.data.id)) issues.push(`parked bug ${p.data.id} has no known-issue record`);
+  for (const id of known)
+    if (!parked.some((p) => p.data.id === id))
+      issues.push(`known issue ${id} has no parked bug in gcf/work/`);
+
+  return { ...live, issues };
+}

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/plan-check.js

@@ -0,0 +1,31 @@
+// `gcf plan check <id>` (Methodology §5.2.1): the deterministic check after each improve pass —
+// the plan exists, it holds task checkboxes, and the item's readset fits the context budget.
+// Whether the plan is any good is the improve passes' job; this only says it is usable.
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { buildLedger } from './ledger.js';
+import { buildContext } from './context.js';
+
+export async function planCheck(projectDir, id) {
+  const item = (await buildLedger(projectDir)).item(id);
+  if (!item) throw new Error(`${id} is not a work item of gcf/work/`);
+  const plan = item.data.plan ?? `.ai-factory/plans/${id}.md`;
+  const file = path.resolve(projectDir, plan);
+  const problems = [];
+  let tasks = 0;
+  let done = 0;
+  if (!existsSync(file)) problems.push(`no plan at ${plan}`);
+  else {
+    const text = await readFile(file, 'utf8');
+    tasks = (text.match(/^\s*- \[[ xX]\] /gm) ?? []).length;
+    done = (text.match(/^\s*- \[[xX]\] /gm) ?? []).length;
+    if (!tasks) problems.push(`${plan} has no task checkboxes (- [ ] …)`);
+  }
+
+  const ctx = await buildContext(projectDir, id);
+  if (ctx.over_budget)
+    problems.push(`readset ~${ctx.total_tokens_est} tokens is over the budget ${ctx.budget}`);
+
+  return { id, plan, tasks, done, problems, ok: problems.length === 0 };
+}

package/lib/playtest-list.js

@@ -1,12 +1,16 @@
-import { listCards, scalarOf } from './gcf-paths.js';
+import { listItems, scalarOf } from './gcf-paths.js';
 
-/** Playtest list (GCF-PRD §10): every built card with its miss-criterion question. */
+/**
+ * Playtest list (Methodology §5.3): every item waiting for its verdict, and every unplayed one,
+ * with the question the play must answer.
+ */
 export async function playtestList(root) {
-  return (await listCards(root))
-    .filter((c) => c.data.status === 'built')
+  return (await listItems(root))
+    .filter((c) => ['awaiting-verdict', 'unplayed'].includes(c.data.status))
     .map((c) => ({
       id: c.data.id,
-      slug: c.data.slug,
+      title: c.data.title ?? null,
+      status: c.data.status,
       system: c.data.system ?? [],
       question: scalarOf(c.body, 'miss_criterion') || '(miss_criterion is empty)',
     }));

package/lib/systems-doc.js

@@ -0,0 +1,85 @@
+// 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 item 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}`;
+}
+
+/**
+ * The `key:` bullet block without `dropLines` — the inverse of upsertBlock. A block left empty
+ * gets the `- none:` placeholder back, as a new systems doc starts.
+ */
+export function removeLines(rawBody, key, dropLines) {
+  const body = lf(rawBody);
+  const existing = blockLines(body, key);
+  const kept = existing.filter((l) => !dropLines.includes(l));
+  if (kept.length === existing.length) return body;
+  const block = `${key}:\n${(kept.length ? kept : [NONE_LINE]).join('\n')}\n`;
+  const re = new RegExp(`^${key}:[^\\n]*\\n(?:(?!\\S+:).*\\n?)*`, 'm');
+
+  return body.replace(re, () => `${block}\n`).replace(/\n{3,}/g, '\n\n');
+}
+
+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` };
+}