gcf-aif-ext 0.2.7 → 0.4.0

package/lib/audit-core.js

@@ -2,91 +2,127 @@ import { readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { listCards, listSystems, readConfig, tokensEst } from './gcf-paths.js';
+import { listItems, listSystems, readConfig, tokensEst, legacyCards } from './gcf-paths.js';
 import { lint } from './linter.js';
 import { drifted } from './index-gen.js';
+import { designCheck, recordsIn } from './design-check.js';
+import { buildLedger } from './ledger.js';
+import { STORED } from './transitions.js';
+import { openDepends } from './work-ops.js';
 
 function git(args, cwd) {
-  const res = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  // A blame of a long file overflows the 1 MiB default, and an overflow reads as a git failure.
+  const res = spawnSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
 
   return res.status === 0 ? res.stdout.trim() : null;
 }
 
-const UNTIL_RE = /\[until:\s*(verdict\(card-\d{3}\)|retune\([a-z0-9-]+\)|manual\([^)]*\))\]/g;
-const LEGAL_STATUS = ['proposed', 'built', 'tuning'];
+const UNTIL_RE = /\[until:\s*(verdict\([a-z0-9-]+\)|retune\([a-z0-9-]+\)|manual\([^)]*\))\]/g;
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 
 /**
  * @typedef {object} AuditReport
  * @property {string} first_line
- * @property {Array<{id: string, commits: number | null, limit: number}>} stale_built
+ * @property {Array<{id: string, status: string, commits: number | null, limit: number}>}
+ *   stale_waiting
  * @property {Array<{id: string, tune_count: number, limit: number}>} tune_limit
  * @property {Array<{id: string, depends: string[]}>} open_depends
  * @property {{count: number, limit: number, over: boolean}} wip
- * @property {{tokens: number, budget: number, over: boolean} | null} pillars
+ * @property {{count: number, warn_after: number, over: boolean}} unplayed
+ * @property {string[]} legacy_cards
+ * @property {{tokens: number, budget: number, over: boolean, count: number, too_many: boolean}
+ *   | null} pillars
  * @property {Array<{file: string, trigger: string, status: string}>} until
  * @property {Record<string, object[]>} linter
  * @property {object[]} pragmas
  * @property {boolean} index_drift
  * @property {Array<{id: string, status: string}>} illegal_status
+ * @property {Array<{id: string, commits: number | null, limit: number}>} stale_questions
  * @property {number} [schema]
- * @property {Array<{id: string, status: string, system: string[], depends: string[]}>} [cards]
+ * @property {Array<{id: string, type: string, gate: string, status: string, system: string[],
+ *   depends: string[], parent: string | null, tune_count: number}>} [items]
+ * @property {{blocking: number, units: number, ready: number}} [design]
  */
 
 /**
- * Deterministic audit core (GCF-PRD §10.1): until triggers, built staleness, tune
- * limits, WIP, PILLARS budget, П2 linter, INDEX drift. No LLM anywhere; the
+ * Deterministic audit core (GCF-PRD §10.1): until triggers, waiting staleness, tune limits,
+ * WIP, unplayed count, PILLARS budget, П2 linter, INDEX drift. No LLM anywhere; the
  * contradiction hunt is a separate optional skill pass.
  */
 export async function audit(projectDir) {
   const root = path.join(path.resolve(projectDir), 'gcf');
   const config = await readConfig(root);
-  const cards = await listCards(root);
+  const items = await listItems(root);
   const systems = await listSystems(root);
+  const ledger = await buildLedger(projectDir);
+  const unplayed = items.filter((c) => c.data.status === 'unplayed').length;
   /** @type {AuditReport} */
   const report = {
     first_line: '',
-    stale_built: [],
+    stale_waiting: [],
     tune_limit: [],
     open_depends: [],
-    wip: wipOf(cards, config),
+    wip: wipOf(items, config),
+    unplayed: {
+      count: unplayed,
+      warn_after: config.unplayed_warn_after,
+      over: unplayed > config.unplayed_warn_after,
+    },
+    legacy_cards: legacyCards(root),
     pillars: await pillarsOf(root, config),
-    until: untilRecords(cards, systems, projectDir),
+    until: untilRecords(items, systems, projectDir, ledger),
     linter: {},
     pragmas: [],
     index_drift: await drifted(root),
     illegal_status: [],
+    stale_questions: staleQuestions(projectDir, root, config),
   };
   // The harness gate reads everything from this one report — it never parses gcf/ itself.
   report.schema = config.schema;
-  report.cards = cards.map((c) => ({
+  report.items = items.map((c) => ({
     id: c.data.id,
+    type: c.data.type,
+    gate: c.data.gate,
     status: c.data.status,
     system: c.data.system ?? [],
     depends: c.data.depends ?? [],
+    parent: c.data.parent ?? null,
+    tune_count: c.data.tune_count ?? 0,
+    parallel: c.data.parallel ?? 'serial',
   }));
-  checkCards(report, cards, config, projectDir);
+  const design = await designCheck(projectDir);
+  checkItems(report, items, config, { projectDir, ledger });
+  report.design = {
+    blocking: design.blocking,
+    units: design.units.length,
+    ready: design.units.filter((u) => u.ready).length,
+  };
   lintSystems(report, systems);
   report.first_line = firstLine(report);
 
   return report;
 }
 
-/** Per-card checks: illegal status, built staleness, tune limit, open depends. */
-function checkCards(report, cards, config, projectDir) {
-  const liveIds = new Set(cards.map((c) => c.data.id));
+/**
+ * Per-item checks: illegal status, waiting staleness, tune limit, open depends — a dependency
+ * still in design/ or in work, not unplayed or parked, is what nobody has played yet.
+ */
+function checkItems(report, items, config, { projectDir, ledger }) {
   // Staleness is measured in commits, so outside a repository there is no answer to give.
-  // Without this probe every built card would read as stale and stop the harness.
+  // Without this probe every waiting item would read as stale and stop the harness.
   const inRepo = git(['rev-parse', '--git-dir'], projectDir) !== null;
 
-  for (const c of cards) {
-    if (!LEGAL_STATUS.includes(c.data.status)) {
+  for (const c of items) {
+    if (!STORED.includes(c.data.status)) {
       report.illegal_status.push({ id: c.data.id, status: c.data.status });
     }
 
     const stale = inRepo ? staleEntry(c, config, projectDir) : null;
-    if (stale) report.stale_built.push(stale);
+    if (stale) report.stale_waiting.push(stale);
 
-    if ((c.data.tune_count ?? 0) >= config.tune_limit) {
+    // At the limit, only the next verdict matters: a ready item still gets its last build.
+    const verdictDue = ['awaiting-verdict', 'unplayed'].includes(c.data.status);
+    if (verdictDue && (c.data.tune_count ?? 0) >= config.tune_limit) {
       report.tune_limit.push({
         id: c.data.id,
         tune_count: c.data.tune_count,
@@ -94,23 +130,26 @@ function checkCards(report, cards, config, projectDir) {
       });
     }
 
-    // A depends id that still has a card file is unplayed (GCF-PRD §7.2). Data for the
-    // harness gate, not an alert: a proposed card waiting on its dependency is normal.
-    const open = (c.data.depends ?? []).filter((d) => liveIds.has(d));
+    // Data for the harness gate, not an alert: a ready item waiting on its dependency is normal.
+    // A run may start on a dependency awaiting its verdict (Methodology §3.2); close and keep
+    // check the stricter rule themselves.
+    const open = openDepends(ledger, c.data.depends ?? [], { waiting: true });
     if (open.length) report.open_depends.push({ id: c.data.id, depends: open });
   }
 }
 
-/** A stale_built entry for a built card past the commit limit, else null. */
+/** A stale_waiting entry for an item waiting on the operator past the commit limit, else null. */
 function staleEntry(c, config, projectDir) {
-  if (c.data.status !== 'built' || !c.data.built_at) return null;
+  const waits = ['awaiting-verdict', 'awaiting-decision', 'blocked'].includes(c.data.status);
+  if (!waits || !c.data.since) return null;
   // git() is null when the ref no longer resolves (rebase, squash, amend, shallow clone).
   // Number(null) is 0, which reads as "fresh" — the one answer that must never be guessed.
-  const raw = git(['rev-list', '--count', `${c.data.built_at}..HEAD`], projectDir);
+  const raw = git(['rev-list', '--count', `${c.data.since}..HEAD`], projectDir);
   const n = raw === null ? NaN : Number(raw);
   if (!Number.isFinite(n) || n > config.built_stale_after_commits) {
     return {
       id: c.data.id,
+      status: c.data.status,
       commits: Number.isFinite(n) ? n : null,
       limit: config.built_stale_after_commits,
     };
@@ -119,29 +158,90 @@ function staleEntry(c, config, projectDir) {
   return null;
 }
 
-function wipOf(cards, config) {
-  const count = cards.filter((c) => c.data.status === 'built').length;
+/** WIP counts what waits for the playtest; unplayed items have their own warning (§4). */
+function wipOf(items, config) {
+  const count = items.filter((c) => c.data.status === 'awaiting-verdict').length;
 
   return { count, limit: config.wip_built_limit, over: count > config.wip_built_limit };
 }
 
+// GCF-PRD §5.3: no more than 7 pillars.
+const PILLARS_MAX = 7;
+
 async function pillarsOf(root, config) {
   const pillarsFile = path.join(root, 'PILLARS.md');
   if (!existsSync(pillarsFile)) return null;
-  const tokens = tokensEst(await readFile(pillarsFile, 'utf8'));
+  const text = await readFile(pillarsFile, 'utf8');
+  const tokens = tokensEst(text);
+  const count = recordsIn(text, 'pillars').length;
 
-  return { tokens, budget: config.pillars_budget, over: tokens > config.pillars_budget };
+  return {
+    tokens,
+    budget: config.pillars_budget,
+    over: tokens > config.pillars_budget,
+    count,
+    too_many: count > PILLARS_MAX,
+  };
 }
 
-/** Verdict history from commit messages of the fixed format (GCF-PRD §8). */
-function verdictMatchers(projectDir) {
+/**
+ * Open questions older than the limit, aged by the last commit that changed their `- id:` line
+ * beyond whitespace (GCF-PRD §7.4): a pile of unanswered ones means the human has dropped out
+ * of the loop.
+ */
+function staleQuestions(projectDir, root, config) {
+  if (!existsSync(path.join(root, 'open-questions.md'))) return [];
+  // null for an untracked file or outside a repository: no commit to age from. -w: a respaced
+  // or re-ended (CRLF/LF) line keeps the commit that wrote it.
+  const blame = git(['blame', '-w', '--porcelain', '--', 'gcf/open-questions.md'], projectDir);
+  if (blame === null) return [];
+  const added = [];
+  let hash = '';
+  for (const line of blame.split('\n')) {
+    const head = line.match(/^([0-9a-f]{40,64}) \d+ \d+/);
+    if (head) hash = head[1];
+    const id = line.match(/^\t\uFEFF?- id:\s*(\S+)/)?.[1];
+    // An uncommitted line blames to the all-zero hash: it is new, not old.
+    if (id && !/^0+$/.test(hash)) added.push({ id, hash });
+  }
+
+  const ages = new Map();
+  const ageOf = (h) => {
+    if (!ages.has(h)) {
+      const raw = git(['rev-list', '--count', `${h}..HEAD`], projectDir);
+      // Number(null) is 0, "fresh" — the one answer that must never be guessed (see staleEntry).
+      ages.set(h, raw === null ? null : Number(raw));
+    }
+
+    return ages.get(h);
+  };
+
+  const limit = config.question_stale_after_commits;
+
+  return added
+    .map(({ id, hash: h }) => ({ id, commits: ageOf(h), limit }))
+    .filter((q) => q.commits === null || q.commits > limit);
+}
+
+/**
+ * Whether a verdict fired. `verdict(id)` reads the files, as the ledger does (GCF-PRD §5.8): a
+ * keep or kill left a history or graveyard line, a tune left the item's tune_count — so a
+ * squash or a shallow clone does not hide it, and a revert takes it back.
+ */
+function verdictMatchers(projectDir, ledger, items) {
+  const tuned = items.filter((c) => (c.data.tune_count ?? 0) > 0);
   const verdictLog = git(['log', '--grep', '^gcf(verdict):', '--format=%s'], projectDir) ?? '';
 
   return {
-    verdict: (cardId) => new RegExp(`^gcf\\(verdict\\): \\w+ ${cardId}\\b`, 'm').test(verdictLog),
-    // ponytail: retune(sys) fires on any tune verdict naming the system; the PRD's
-    // feel-section-diff refinement can replace this when it proves too coarse.
-    retune: (system) => new RegExp(`^gcf\\(verdict\\): tune .*→ .*${system}`, 'm').test(verdictLog),
+    verdict: (id) =>
+      ledger.where(id).terminal.some((t) => t !== 'done') || tuned.some((c) => c.data.id === id),
+    // shortcut: a kept item's tunes leave no file behind, so retune(sys) also greps the verdict
+    // subjects; upgrade when tunes get their own history line.
+    retune: (system) =>
+      tuned.some((c) => (c.data.system ?? []).includes(system)) ||
+      new RegExp(`^gcf\\(verdict\\): tune .*→ (?:.*,)?${escapeRe(system)}(?:,|$)`, 'm').test(
+        verdictLog,
+      ),
   };
 }
 
@@ -157,11 +257,11 @@ function untilStatus(trigger, fired) {
   return 'manual';
 }
 
-/** Until annotations across cards and systems docs. */
-function untilRecords(cards, systems, projectDir) {
-  const fired = verdictMatchers(projectDir);
+/** Until annotations across work items and systems docs. */
+function untilRecords(items, systems, projectDir, ledger) {
+  const fired = verdictMatchers(projectDir, ledger, items);
   const docs = [
-    ...cards.map((c) => ({ rel: `cards/${c.name}`, body: c.body })),
+    ...items.map((c) => ({ rel: `work/${c.name}`, body: c.body })),
     ...systems.map((s) => ({ rel: `systems/${s.name}`, body: s.body })),
   ];
   const until = [];
@@ -183,20 +283,37 @@ function lintSystems(report, systems) {
   }
 }
 
+/** Alerts about items in flight, which lead the line. @param {AuditReport} report */
+const itemAlerts = (report) => [
+  report.legacy_cards.length &&
+    `${report.legacy_cards.length} schema 2 card(s) in gcf/cards/ — back to gcf/design/, then take`,
+  report.illegal_status.length && `${report.illegal_status.length} item(s) in illegal status`,
+  report.stale_waiting.length &&
+    `${report.stale_waiting.length} item(s) waiting on you too long — playtest or answer first`,
+  report.tune_limit.length &&
+    `${report.tune_limit.length} item(s) at tune limit — kill or redesign`,
+  report.wip.over && `WIP over limit (${report.wip.count}/${report.wip.limit})`,
+  report.unplayed.over &&
+    `${report.unplayed.count} unplayed item(s) (warn after ` +
+      `${report.unplayed.warn_after}) — play them`,
+];
+
+/** Alerts about the documents. @param {AuditReport} report */
+const docAlerts = (report) => [
+  report.until.filter((u) => u.status === 'stale').length && 'stale until-records present',
+  report.pillars?.over && 'PILLARS over token budget',
+  report.pillars?.too_many && `PILLARS has ${report.pillars.count} pillars (max ${PILLARS_MAX})`,
+  report.stale_questions.length &&
+    `${report.stale_questions.length} open question(s) unanswered for over ` +
+      `${report.stale_questions[0].limit} commits`,
+  Object.keys(report.linter).length && 'П2 linter findings in systems docs',
+  report.index_drift && 'INDEX drift (regenerate)',
+  report.design?.blocking && `${report.design.blocking} blocking design finding(s)`,
+];
+
 /** @param {AuditReport} report */
 function firstLine(report) {
-  const alerts = [
-    report.illegal_status.length && `${report.illegal_status.length} card(s) in illegal status`,
-    report.stale_built.length &&
-      `${report.stale_built.length} built card(s) stale — playtest first`,
-    report.tune_limit.length &&
-      `${report.tune_limit.length} card(s) at tune limit — kill or redesign`,
-    report.wip.over && `WIP over limit (${report.wip.count}/${report.wip.limit})`,
-    report.until.filter((u) => u.status === 'stale').length && 'stale until-records present',
-    report.pillars?.over && 'PILLARS over token budget',
-    Object.keys(report.linter).length && 'П2 linter findings in systems docs',
-    report.index_drift && 'INDEX drift (regenerate)',
-  ].filter(Boolean);
+  const alerts = [...itemAlerts(report), ...docAlerts(report)].filter(Boolean);
 
   return alerts.length ? alerts.join('; ') : 'clean';
 }

package/lib/bundle.js

@@ -0,0 +1,278 @@
+// The structured entry (GCF-PRD §11.10): `design export` glues game.md, glossary.md and the
+// units into one bundle a designer edits; `design import` brings it back without a model.
+// Each part carries the hash it was exported with, so an import tells a designer's edit from
+// an edit made in gcf/ after the export — and never overwrites the second one silently.
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { readDesign, SLUG_RE } from './design.js';
+import { buildLedger } from './ledger.js';
+import { designCheck } from './design-check.js';
+import { atomicWrite, withFileRollback, resolveInside } from './safe-path.js';
+import { writeIndex } from './index-gen.js';
+
+const DOCS = ['game', 'glossary'];
+// A part opens with a marker comment, not with a heading: a `# notes` line inside game.md or a
+// purpose is content, and a heading boundary would cut the document there.
+const PART_RE =
+  /^<!-- gcf:part (doc|system|unit) (\S+)(?: system=(\S+))?(?: base=([0-9a-f]{8}))? -->$/;
+const HELP =
+  '<!-- gcf:help edit inside a part; a new unit is a line ' +
+  '"gcf:part unit <id> system=<system>" in a comment like this one, ' +
+  'then "## <id>" and its text -->';
+export const hashOf = (text) =>
+  createHash('sha1').update(String(text).replace(/\r\n/g, '\n').trim()).digest('hex').slice(0, 8);
+
+/** The text of one unit as it stands in its design file: header and body, no heading. */
+function unitText(u) {
+  const header = Object.entries(u.header).map(([k, v]) => `${k}: ${v}`);
+
+  return `${header.join('\n')}\n\n${u.body.trim()}`.trim();
+}
+
+const purposeOf = (preamble) =>
+  preamble
+    .trimStart()
+    .replace(/^# .*\n?/, '')
+    .trim();
+
+/** Glue the design into one bundle; `system` or `milestone` narrows which units go in. */
+export async function exportBundle(projectDir, { system = null, milestone = null } = {}) {
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const design = (await readDesign(root)).filter((d) => !system || d.system === system);
+  const inScope = (u) => !milestone || u.header.milestone === milestone;
+  const ids = design.flatMap((d) => d.units.filter(inScope).map((u) => u.id));
+  const out = [`<!-- gcf:bundle ids=${ids.join(',')} -->`, HELP];
+  const part = (head, title, text) =>
+    out.push('', `<!-- gcf:part ${head} base=${hashOf(text)} -->`, ...title, text);
+  // A doc goes as it stands, its own heading included: a title added over it would be a second
+  // `# game` a designer deletes, and the import could not tell which one was the file's.
+  for (const name of DOCS) {
+    const file = path.join(root, `${name}.md`);
+    if (existsSync(file)) part(`doc ${name}`, [], (await readFile(file, 'utf8')).trim());
+  }
+
+  for (const d of design) {
+    part(`system ${d.system}`, [`# design: ${d.system}`, ''], purposeOf(d.preamble));
+    for (const u of d.units.filter(inScope)) {
+      part(`unit ${u.id} system=${d.system}`, [`## ${u.id}`, ''], unitText(u));
+    }
+  }
+
+  return `${out.join('\n')}\n`;
+}
+
+/** @typedef {{kind: string, name: string, system: ?string, base: ?string, lines: string[]}} Part */
+
+/** The heading export writes under a marker, for a reader; import drops it when it is there. */
+const titleOf = (p) =>
+  p.kind === 'doc' ? null : p.kind === 'system' ? `# design: ${p.name}` : `## ${p.name}`;
+
+/**
+ * A marker line read into an empty part, or null; `system` is the system part above it.
+ * @returns {Part | null}
+ */
+function partOf(line, system) {
+  const m = line.trimEnd().match(PART_RE);
+  if (!m) return null;
+  const owner = m[1] === 'unit' ? (m[3] ?? system) : m[1] === 'system' ? m[2] : null;
+
+  return { kind: m[1], name: m[2], system: owner, base: m[4] ?? null, lines: [] };
+}
+
+// Text no part owns — above the first marker, or a marker the editor mangled — would vanish
+// without a word: it is reported instead.
+const strayLine = (l, i, inPart) =>
+  /^<!-- gcf:part\b/.test(l) ||
+  (!inPart && i > 0 && l.trim() !== '' && !l.startsWith('<!-- gcf:help'));
+
+/** A bundle read back: the exported ids, the docs, and per system its purpose and units. */
+export function parseBundle(text) {
+  const lines = String(text).replace(/\r\n/g, '\n').split('\n');
+  const ids = (lines[0].match(/^<!-- gcf:bundle ids=(.*) -->$/)?.[1] ?? '')
+    .split(',')
+    .filter(Boolean);
+  /** @type {Part[]} */
+  const parts = [];
+  const stray = [];
+  /** @type {?string} */
+  let system = null;
+  for (const [i, l] of lines.entries()) {
+    const p = partOf(l, system);
+    if (p) {
+      if (p.kind === 'system') system = p.name;
+      parts.push(p);
+    } else if (strayLine(l, i, parts.length > 0)) stray.push(i + 1);
+    else parts.at(-1)?.lines.push(l);
+  }
+
+  return {
+    ids,
+    stray,
+    parts: parts.map((p) => {
+      const body = p.lines.join('\n').trim().split('\n');
+      if (body[0]?.trim() === titleOf(p)) body.shift();
+
+      return { ...p, text: body.join('\n').trim() };
+    }),
+  };
+}
+
+/** Three-way: what the bundle changed, against what gcf/ changed since the export. */
+function verdict(part, current) {
+  const mine = hashOf(part.text);
+  if (part.base === null) return current === null ? 'new' : 'taken';
+  if (mine === part.base) return 'same';
+  if (current === null) return 'gone';
+
+  return hashOf(current) === part.base ? 'apply' : 'conflict';
+}
+
+/** Current text of every importable part: docs, system purposes, units in design/. */
+async function currentParts(root) {
+  const cur = new Map();
+  for (const name of DOCS) {
+    const file = path.join(root, `${name}.md`);
+    if (existsSync(file)) cur.set(`doc:${name}`, (await readFile(file, 'utf8')).trim());
+  }
+
+  for (const d of await readDesign(root)) {
+    cur.set(`system:${d.system}`, purposeOf(d.preamble));
+    for (const u of d.units) cur.set(`unit:${u.id}`, unitText(u));
+  }
+
+  return cur;
+}
+
+/** A design file with the `## <id>` section replaced by `text`, or appended when absent. */
+function putUnit(fileText, id, text) {
+  // A file kept with CRLF stays CRLF: work in LF, write back in the file's own line ending.
+  const eol = fileText.match(/\r?\n/)?.[0] ?? '\n';
+  const lf = fileText.replace(/\r\n/g, '\n');
+  const lines = lf.split('\n');
+  const at = lines.findIndex((l) => l.trimEnd() === `## ${id}`);
+  const section = [`## ${id}`, '', ...text.replace(/\r\n/g, '\n').split('\n'), ''];
+  if (at < 0) return `${lf.trimEnd()}\n\n${section.join('\n')}`.replace(/\n/g, eol);
+  let end = lines.findIndex((l, i) => i > at && /^## \S/.test(l));
+  if (end < 0) end = lines.length;
+
+  return [...lines.slice(0, at), ...section, ...lines.slice(end)].join('\n').replace(/\n/g, eol);
+}
+
+/** A design file with its preamble purpose replaced; a title of the file's own stays. */
+function putPurpose(fileText, system, purpose) {
+  const at = fileText.search(/^## \S/m);
+  const rest = at < 0 ? '' : fileText.slice(at);
+  const title = fileText.trimStart().match(/^# .*/)?.[0] ?? `# ${system}`;
+
+  return `${title}\n\n${purpose}\n${rest ? `\n${rest}` : ''}`;
+}
+
+/** A part's names become file names: a doc is one of DOCS, a system and a unit are slugs. */
+const validName = (p) =>
+  p.kind === 'doc'
+    ? DOCS.includes(p.name)
+    : SLUG_RE.test(p.name) && SLUG_RE.test(String(p.system ?? ''));
+
+/** Plan every part: which write it gets, or which report line. */
+function plan(bundle, cur, ledger) {
+  const writes = [];
+  const note = `lines outside any part: ${bundle.stray.join(', ')} (a lost gcf:part marker?)`;
+  const report = bundle.stray.length ? [{ part: 'bundle', outcome: 'invalid', note }] : [];
+  for (const p of bundle.parts) {
+    const key = `${p.kind}:${p.name}`;
+    if (!validName(p)) {
+      report.push({ part: key, outcome: 'invalid', note: 'not a gcf doc, system or unit name' });
+      continue;
+    }
+
+    const v = verdict(p, cur.get(key) ?? null);
+    if (p.kind === 'unit' && v === 'new' && ledger.known(p.name)) {
+      report.push({ part: key, outcome: 'taken', note: 'the id is used: pick another slug' });
+    } else if (['apply', 'new'].includes(v)) writes.push({ ...p, outcome: v });
+    else if (v !== 'same') report.push({ part: key, outcome: v, note: NOTES[v] });
+  }
+
+  const kept = new Set(bundle.parts.filter((p) => p.kind === 'unit').map((p) => p.name));
+  for (const id of bundle.ids.filter((i) => !kept.has(i))) {
+    report.push({
+      part: `unit:${id}`,
+      outcome: 'deleted',
+      note: `confirm with gcf drop ${id} --reason "…"`,
+    });
+  }
+
+  return { writes, report };
+}
+
+const NOTES = {
+  conflict: 'changed in the bundle and in gcf/ since the export: a D1 for the human',
+  gone: 'no longer in design/ (taken, done or dropped): an edit to it is a D1',
+  taken: 'a part without a base hash that already exists: export again and edit that',
+};
+
+/** The file each write touches. */
+function fileOf(root, w) {
+  // validName already holds a doc to DOCS; resolveInside is the second lock on the path.
+  if (w.kind === 'doc') return resolveInside(root, `${w.name}.md`);
+
+  return resolveInside(path.join(root, 'design'), `${w.kind === 'system' ? w.name : w.system}.md`);
+}
+
+async function applyWrite(root, w) {
+  const file = fileOf(root, w);
+  const text = existsSync(file)
+    ? await readFile(file, 'utf8')
+    : `# ${w.system ?? w.name}\n\npurpose: TBD\n`;
+  if (w.kind === 'doc') return atomicWrite(file, `${w.text}\n`);
+  if (w.kind === 'system') return atomicWrite(file, putPurpose(text, w.name, w.text));
+  await atomicWrite(file, putUnit(text, w.name, w.text));
+  if (w.outcome !== 'new') return;
+  const backlog = path.join(root, 'backlog.md');
+  const order = existsSync(backlog) ? (await readFile(backlog, 'utf8')).trimEnd() : '';
+  await atomicWrite(backlog, `${order}\n- ${w.name}\n`.replace(/^\n/, ''));
+}
+
+/**
+ * Bring a bundle back into gcf/. A part the bundle changed and gcf/ did not is written; a part
+ * both changed is reported, never merged. Writes land only if the design check after them has
+ * no blocking finding — otherwise every file goes back and the findings are the error.
+ */
+export async function importBundle(projectDir, bundleText) {
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const bundle = parseBundle(bundleText);
+  const ledger = await buildLedger(projectDir);
+  const { writes, report } = plan(bundle, await currentParts(root), ledger);
+  const applied = writes.map((w) => `${w.kind}:${w.name} (${w.outcome})`);
+  if (!writes.length) return { applied, report };
+  // Only the findings the bundle brings refuse it: a project with open findings can still take
+  // a clean edit. A finding is keyed without its line, which an edit above it shifts, and
+  // counted, so a second finding with the same message in the same unit is still a new one.
+  const keyOf = (i) => `${i.check}|${i.file}|${i.id}|${i.message}`;
+  const blocking = async () =>
+    (await designCheck(projectDir)).issues.filter((i) => i.severity === 'block');
+  const before = new Map();
+  for (const i of await blocking()) before.set(keyOf(i), (before.get(keyOf(i)) ?? 0) + 1);
+  const files = [...new Set(writes.map((w) => fileOf(root, w)))];
+  await withFileRollback(
+    [...files, path.join(root, 'backlog.md'), path.join(root, 'INDEX.md')],
+    async () => {
+      for (const w of writes) await applyWrite(root, w);
+      const seen = new Map();
+      const fresh = (await blocking()).filter((i) => {
+        seen.set(keyOf(i), (seen.get(keyOf(i)) ?? 0) + 1);
+
+        return seen.get(keyOf(i)) > (before.get(keyOf(i)) ?? 0);
+      });
+      if (fresh.length) {
+        const first = fresh.slice(0, 3).map((i) => `${i.file}:${i.line} ${i.check} ${i.message}`);
+        throw new Error(`the bundle would break the design check:\n${first.join('\n')}`);
+      }
+
+      await writeIndex(root);
+    },
+  );
+
+  return { applied, report };
+}