bmad-plus 0.22.0 → 0.23.0

package/tools/cli/commands/intake.js

@@ -0,0 +1,124 @@
+/** Validate, plan, record and render a pack intake; the host asks, the user answers. */
+'use strict';
+
+const path = require('node:path');
+const intake = require('../lib/intake');
+
+const collect = (value, list) => [...list, value];
+
+function describePlan(result) {
+  const lines = [
+    `${result.intake} (${result.pack}): ${result.ready ? 'ready' : 'not ready'} — ` +
+      `${result.counts.answered} answered, ${result.counts.defaulted} defaulted, ` +
+      `${result.counts.unknown} unknown, ${result.counts.pending} not asked yet.`,
+  ];
+  if (result.missing.length) lines.push(`Must-haves still open: ${result.missing.join(', ')}`);
+  if (result.next.length) {
+    lines.push(`Ask next (at most ${result.maxPerMessage} per message):`);
+    for (const question of result.next) {
+      const hints = [];
+      if (question.mustHave) hints.push('must-have');
+      if (question.choices) hints.push(`choices: ${question.choices.join(', ')}`);
+      if (question.default !== undefined)
+        hints.push(`default: ${JSON.stringify(question.default)}`);
+      lines.push(
+        `  - ${question.id} [${question.kind}] ${question.ask}${hints.length ? ` (${hints.join('; ')})` : ''}`
+      );
+    }
+  }
+  for (const unknown of result.unknowns) {
+    lines.push(`Unknown: ${unknown.id}${unknown.risk ? ` — risk: ${unknown.risk}` : ''}`);
+  }
+  return lines;
+}
+
+module.exports = {
+  command: 'intake <action> [file]',
+  description:
+    'Pack intake: check a file, plan the next questions, record answers, render the brief',
+  options: [
+    ['-d, --directory <path>', 'Project directory (default: current directory)'],
+    ['--intake <file>', 'Intake file, relative to the project'],
+    ['--answers <file>', 'Answers file, relative to the project (created by record)'],
+    [
+      '--set <id=VALUE>',
+      'Record an answer, or id=UNKNOWN to mark it unknown (repeatable)',
+      collect,
+      [],
+    ],
+    ['--default <id>', 'Record the proposed default of a question (repeatable)', collect, []],
+    ['--reset', 'Start the answers file again, empty, for this intake (record)'],
+    ['--out <file>', 'Brief to write (render)'],
+    ['--json', 'Machine-readable output'],
+  ],
+  action: (action, file, options = {}) => {
+    const projectDir = path.resolve(options.directory || process.cwd());
+    const needs = (name) => {
+      if (!options[name]) throw new Error(`--${name} is required for intake ${action}`);
+      return options[name];
+    };
+    try {
+      let result;
+      let lines;
+      if (action === 'check') {
+        if (!file) throw new Error('Use intake check FILE.');
+        result = intake.check({ projectDir, file });
+        process.exitCode = result.ok ? 0 : 1;
+        lines = result.ok
+          ? [
+              `${result.file}: valid intake ${result.id} (${result.pack}), ${result.questions} questions, ${result.mustHave} must-have.`,
+            ]
+          : [
+              `${result.file}: not a valid intake`,
+              ...result.problems.map((problem) => `  - ${problem}`),
+            ];
+        result = { status: result.ok ? 'valid' : 'invalid', ...result };
+      } else if (action === 'plan') {
+        result = intake.plan({
+          projectDir,
+          intakeFile: needs('intake'),
+          answersFile: needs('answers'),
+        });
+        process.exitCode = result.ready ? 0 : 2;
+        lines = describePlan(result);
+        result = { status: result.ready ? 'ready' : 'needs-answers', ...result };
+      } else if (action === 'record') {
+        result = intake.record({
+          projectDir,
+          intakeFile: needs('intake'),
+          answersFile: needs('answers'),
+          sets: options.set,
+          defaults: options.default,
+          reset: options.reset === true,
+        });
+        process.exitCode = 0;
+        lines = [
+          result.reset
+            ? `Reset ${result.answersFile}${result.recorded.length ? `, recorded ${result.recorded.join(', ')}` : ''}.`
+            : `Recorded ${result.recorded.join(', ')} in ${result.answersFile}.`,
+          ...describePlan(result),
+        ];
+        result = { status: 'recorded', ...result };
+      } else if (action === 'render') {
+        result = intake.render({
+          projectDir,
+          intakeFile: needs('intake'),
+          answersFile: needs('answers'),
+          out: needs('out'),
+        });
+        process.exitCode = 0;
+        lines = [
+          `Brief written to ${result.out} (${result.bytes} bytes); ${result.ready ? 'the intake is ready' : 'a must-have is still open'}.`,
+        ];
+        result = { status: 'rendered', ...result };
+      } else throw new Error('Use intake check FILE, plan, record or render.');
+      if (options.json) console.log(JSON.stringify({ schemaVersion: 1, ...result }, null, 2));
+      else for (const line of lines) console.log(line);
+    } catch (error) {
+      process.exitCode = 1;
+      if (options.json)
+        console.log(JSON.stringify({ schemaVersion: 1, status: 'error', error: error.message }));
+      else console.error('Intake: ' + error.message);
+    }
+  },
+};

package/tools/cli/commands/swarm.js

@@ -0,0 +1,119 @@
+/** Run a swarm of sub-agents under a budget: deal, brief, check, file, tally; the host launches. */
+'use strict';
+
+const path = require('node:path');
+const swarm = require('../lib/swarm');
+
+const USAGE =
+  'Use swarm init --definition FILE [--profile FILE | --units FILE] [--context NAME=FILE] [--n N] [--seed N] [--approved], ' +
+  'briefs RUN [--wave N], check RUN, save RUN UNIT --input FILE, tally RUN [--out FILE], inspect RUN, or plan RUN [--out FILE].';
+
+function lines(action, result) {
+  if (result.status === 'needs-approval') return [`${result.run}: needs approval. ${result.next}`];
+  switch (action) {
+    case 'init':
+      return [
+        `${result.run}: ${result.kind} of ${result.n} units, budget ${result.budget}, approval ${result.approval}.`,
+        result.seed === null
+          ? 'Units listed, no seed.'
+          : `Seed ${result.seed} (same seed, same cards).`,
+        `Next: ${result.next}`,
+      ];
+    case 'briefs':
+      return [
+        `${result.run}: ${result.pending} of ${result.units} units need a sub-agent, in waves of ${result.wave}.`,
+        ...result.waves.flatMap((wave) => [
+          `Wave ${wave.index}:`,
+          ...wave.units.map((unit) => `  ${unit.id}  ${unit.brief}`),
+        ]),
+        `Each sub-agent: ${result.instruction}`,
+        `Disclosure: ${result.disclosure}`,
+      ];
+    case 'check':
+      return [
+        `${result.run}: ${result.valid} of ${result.units} valid answers.`,
+        ...result.pending.map(
+          (unit) => `  ${unit.id}  ${unit.state}${unit.reason ? `: ${unit.reason}` : ''}`
+        ),
+      ];
+    case 'save':
+      return [`${result.run}: answer of ${result.unit} filed at ${result.answer}`];
+    case 'tally': {
+      const { valid, total, skipped } = result.tally.units;
+      return [
+        result.files.markdown,
+        `${valid} of ${total} units counted; ${skipped.length} skipped.`,
+        `Disclosure: ${result.tally.disclosure}`,
+      ];
+    }
+    case 'inspect': {
+      const { counts } = result;
+      return [
+        `${result.run.id}: ${result.status} (${result.run.kind}, ${result.budget.decision})`,
+        `units ${counts.units}, briefed ${counts.briefed}, valid ${counts.valid}, invalid ${counts.invalid}, missing ${counts.missing}`,
+        `Disclosure: ${result.disclosure}`,
+      ];
+    }
+    case 'plan':
+      return [
+        `${result.plan}: ${result.tasks} tasks, ${result.maxParallel} in parallel.`,
+        `Next: ${result.next}`,
+      ];
+    default:
+      return [JSON.stringify(result)];
+  }
+}
+
+module.exports = {
+  command: 'swarm <action> [run] [unit]',
+  description:
+    'Deal, brief, check, file and tally a swarm of sub-agents within the configured budget',
+  options: [
+    ['-d, --directory <path>', 'Project directory'],
+    ['--definition <file>', 'Swarm definition (project-relative JSON) for init'],
+    ['--profile <file>', 'Panel profile (project-relative JSON) for init'],
+    ['--units <file>', 'Fanout units (project-relative JSON) for init'],
+    [
+      '--context <name=file>',
+      'Context file included verbatim in the briefs (repeatable)',
+      (value, all) => [...all, value],
+      [],
+    ],
+    ['--n <count>', 'Units to deal for a panel'],
+    ['--seed <number>', 'Dealing seed; drawn once and recorded when absent'],
+    ['--approved', 'Record that the user agreed to exceed the budget'],
+    ['--wave <count>', 'Sub-agents launched together (default: the configured wave)'],
+    ['--input <file>', 'Printed reply to file with save (project-relative)'],
+    ['--out <file>', 'Output file for tally or plan, under .bmad-plus/swarm/'],
+    ['--json', 'Machine-readable output'],
+  ],
+  action: (action, runId, unitId, options = {}) => {
+    const directory = path.resolve(options.directory || process.cwd());
+    try {
+      let result;
+      if (action === 'init' && !runId) result = swarm.init(directory, options);
+      else if (action === 'briefs' && runId && !unitId)
+        result = swarm.briefs(directory, runId, options);
+      else if (action === 'check' && runId && !unitId) result = swarm.check(directory, runId);
+      else if (action === 'save' && runId && unitId)
+        result = swarm.save(directory, runId, unitId, options);
+      else if (action === 'tally' && runId && !unitId)
+        result = swarm.tally(directory, runId, options);
+      else if (action === 'inspect' && runId && !unitId) result = swarm.inspect(directory, runId);
+      else if (action === 'plan' && runId && !unitId)
+        result = swarm.plan(directory, runId, options);
+      else throw new Error(USAGE);
+      process.exitCode =
+        result.status === 'needs-approval' ? 2 : result.status === 'incomplete' ? 1 : 0;
+      if (options.json) console.log(JSON.stringify(result, null, 2));
+      else for (const line of lines(action, result)) console.log(line);
+    } catch (error) {
+      process.exitCode = 1;
+      if (options.json)
+        console.log(
+          JSON.stringify({ schemaVersion: 1, status: 'error', error: error.message }, null, 2)
+        );
+      else console.error('Swarm: ' + error.message.replace(/^Swarm: /, ''));
+    }
+  },
+};

package/tools/cli/commands/uninstall.js

@@ -11,6 +11,7 @@ const pc = require('picocolors');
 const { t } = require('../i18n');
 const { PACKS, DERIVED } = require('../lib/packs');
 const { readInstallManifest } = require('../lib/install-manifest');
+const { externalModuleRoot } = require('../lib/pack-copy');
 const { generateUserFiles, USER_CONFIG_MARKER } = require('../../build/generate-adapters');
 const { contentHash } = require('../lib/installed-adapters');
 
@@ -44,6 +45,16 @@ function safeStat(projectDir, target) {
   return stat;
 }
 
+// The skills copied from an npm package are matched against that package. When it is gone
+// or no longer the pinned version, nothing can be compared and they stay.
+function resolvedExternalModule(externalModule, packageRoot) {
+  try {
+    return externalModuleRoot({ externalModule, projectRoot: packageRoot });
+  } catch {
+    return null;
+  }
+}
+
 function removalPlan(projectDir, manifest, manifestPath) {
   const packageRoot = path.join(__dirname, '..', '..', '..');
   const sourceRoot = path.join(packageRoot, 'src', 'bmad-plus');
@@ -91,6 +102,12 @@ function removalPlan(projectDir, manifest, manifestPath) {
         path.join(packageRoot, pack.externalPackage, 'skills'),
         targetPath('.agents', 'skills')
       );
+    if (pack.externalModule) {
+      const moduleRoot = resolvedExternalModule(pack.externalModule, packageRoot);
+      if (moduleRoot)
+        for (const name of pack.externalModule.skills)
+          matchSource(path.join(moduleRoot, 'skills', name), targetPath('.agents', 'skills', name));
+    }
   }
   for (const name of ['module.yaml', 'module-help.csv'])
     matchSource(path.join(sourceRoot, name), targetPath('_bmad', name));

package/tools/cli/i18n.js

@@ -48,6 +48,7 @@ const LANGUAGES = {
     guide_seo: 'SEO / GEO audit (360°)',
     guide_backup: 'Smart project backup',
     guide_animated: 'Animated luxury website',
+    guide_design: 'Design with Atelier',
     guide_shield: '\ud83d\udee1\ufe0f GRC Compliance',
     guide_example_shield_1: '\ud83d\udee1\ufe0f GRC: "Shield, audit my app for GDPR compliance"',
     guide_example_shield_2: '\ud83d\udee1\ufe0f GRC: "Shield, gap analysis ISO 27001 vs NIST CSF"',
@@ -88,6 +89,7 @@ const LANGUAGES = {
     guide_example_seo: '🔍 SEO: "/seo audit https://example.com"',
     guide_example_backup: '🗂️  Backup: "/backup create" → ZIP timestamped',
     guide_example_animated: '🎬 Animated: "/animated build hero.mp4"',
+    guide_example_design: '🎨 Design: "/design read" → Atelier interviews you, then builds',
     guide_example_osint: '🔍 OSINT: "Shadow, investigate John Doe"',
     guide_memory: '🧠 Persistent Brain',
     guide_dev_studio: '🏗️ Dev Studio',
@@ -141,6 +143,7 @@ const LANGUAGES = {
     guide_seo: 'Audit SEO / GEO (360°)',
     guide_backup: 'Sauvegarde intelligente',
     guide_animated: 'Site web animé de luxe',
+    guide_design: 'Design avec Atelier',
     guide_shield: '🛡️ Conformité GRC',
     guide_example_shield_1: '🛡️ GRC : "Shield, audite mon app pour la conformité RGPD"',
     guide_example_shield_2: '🛡️ GRC : "Shield, gap analysis ISO 27001 vs NIST CSF"',
@@ -180,6 +183,7 @@ const LANGUAGES = {
     guide_example_seo: '🔍 SEO : "/seo audit https://example.com"',
     guide_example_backup: '🗂️  Backup : "/backup create" → ZIP horodaté',
     guide_example_animated: '🎬 Animé : "/animated build hero.mp4"',
+    guide_example_design: '🎨 Design : "/design read" → Atelier vous interroge, puis construit',
     guide_example_osint: '🔍 OSINT : "Shadow, investigate John Doe"',
     guide_memory: '🧠 Cerveau persistant',
     guide_dev_studio: '🏗️ Dev Studio',
@@ -233,6 +237,7 @@ const LANGUAGES = {
     guide_seo: 'Auditoría SEO / GEO (360°)',
     guide_backup: 'Copia de seguridad inteligente',
     guide_animated: 'Sitio web animado de lujo',
+    guide_design: 'Diseño con Atelier',
     guide_shield: '\ud83d\udee1\ufe0f Cumplimiento GRC',
     guide_example_shield_1: '\ud83d\udee1\ufe0f GRC: "Shield, audita mi app para GDPR"',
     guide_example_shield_2:
@@ -274,6 +279,7 @@ const LANGUAGES = {
     guide_example_seo: '🔍 SEO: "/seo audit https://example.com"',
     guide_example_backup: '🗂️  Backup: "/backup create" → ZIP con marca de tiempo',
     guide_example_animated: '🎬 Animado: "/animated build hero.mp4"',
+    guide_example_design: '🎨 Diseño: "/design read" → Atelier te entrevista y luego construye',
     guide_example_osint: '🔍 OSINT: "Shadow, investigate John Doe"',
     guide_memory: '🧠 Cerebro persistente',
     guide_dev_studio: '🏗️ Dev Studio',
@@ -328,6 +334,7 @@ const LANGUAGES = {
     guide_seo: 'SEO / GEO Audit (360°)',
     guide_backup: 'Intelligente Projektsicherung',
     guide_animated: 'Animierte Luxus-Website',
+    guide_design: 'Design mit Atelier',
     guide_shield: '\ud83d\udee1\ufe0f GRC-Compliance',
     guide_example_shield_1:
       '\ud83d\udee1\ufe0f GRC: "Shield, pr\u00fcfe meine App auf DSGVO-Konformit\u00e4t"',
@@ -370,6 +377,7 @@ const LANGUAGES = {
     guide_example_seo: '🔍 SEO: "/seo audit https://example.com"',
     guide_example_backup: '🗂️  Backup: "/backup create" → ZIP mit Zeitstempel',
     guide_example_animated: '🎬 Animiert: "/animated build hero.mp4"',
+    guide_example_design: '🎨 Design: "/design read" → Atelier befragt dich, dann baut es',
     guide_example_osint: '🔍 OSINT: "Shadow, investigate John Doe"',
     guide_memory: '🧠 Beständiges Gehirn',
     guide_dev_studio: '🏗️ Dev Studio',
@@ -424,6 +432,7 @@ const LANGUAGES = {
     guide_seo: 'Auditoria SEO / GEO (360°)',
     guide_backup: 'Backup inteligente do projeto',
     guide_animated: 'Site animado de luxo',
+    guide_design: 'Design com Atelier',
     guide_shield: '\ud83d\udee1\ufe0f Conformidade GRC',
     guide_example_shield_1: '\ud83d\udee1\ufe0f GRC: "Shield, audite meu app para LGPD"',
     guide_example_shield_2:
@@ -465,6 +474,7 @@ const LANGUAGES = {
     guide_example_seo: '🔍 SEO: "/seo audit https://example.com"',
     guide_example_backup: '🗂️  Backup: "/backup create" → ZIP com timestamp',
     guide_example_animated: '🎬 Animado: "/animated build hero.mp4"',
+    guide_example_design: '🎨 Design: "/design read" → Atelier entrevista você, depois constrói',
     guide_example_osint: '🔍 OSINT: "Shadow, investigate John Doe"',
     guide_memory: '🧠 Cérebro persistente',
     guide_dev_studio: '🏗️ Dev Studio',
@@ -519,6 +529,7 @@ const LANGUAGES = {
     guide_seo: 'SEO / GEO аудит (360°)',
     guide_backup: 'Умное резервное копирование',
     guide_animated: 'Анимированный люксовый сайт',
+    guide_design: 'Дизайн с Atelier',
     guide_shield: '🛡️ Соответствие GRC',
     guide_example_shield_1: '🛡️ GRC: "Shield, проверь моё приложение на GDPR"',
     guide_example_shield_2: '🛡️ GRC: "Shield, gap-анализ ISO 27001 vs NIST CSF"',
@@ -557,6 +568,7 @@ const LANGUAGES = {
     guide_example_seo: '🔍 SEO: "/seo audit https://example.com"',
     guide_example_backup: '🗂️  Бэкап: "/backup create" → ZIP',
     guide_example_animated: '🎬 Анимация: "/animated build hero.mp4"',
+    guide_example_design: '🎨 Дизайн: "/design read" → Atelier опрашивает вас, затем строит',
     guide_example_osint: '🔍 OSINT: "Shadow, investigate John Doe"',
     guide_memory: '🧠 Постоянный мозг',
     guide_dev_studio: '🏗️ Dev Studio',
@@ -610,6 +622,7 @@ const LANGUAGES = {
     guide_seo: 'SEO / GEO 审计 (360°)',
     guide_backup: '智能项目备份',
     guide_animated: '动画奢华网站',
+    guide_design: '与 Atelier 一起设计',
     guide_shield: '🛡️ GRC 合规',
     guide_example_shield_1: '🛡️ GRC: "Shield, 审查我的应用 GDPR 合规性"',
     guide_example_shield_2: '🛡️ GRC: "Shield, ISO 27001 vs NIST CSF 差距分析"',
@@ -645,6 +658,7 @@ const LANGUAGES = {
     guide_example_seo: '🔍 SEO: "/seo audit https://example.com"',
     guide_example_backup: '🗂️  备份: "/backup create" → ZIP',
     guide_example_animated: '🎬 动画: "/animated build hero.mp4"',
+    guide_example_design: '🎨 设计: "/design read" → Atelier 先向你提问，再构建',
     guide_example_osint: '🔍 OSINT: "Shadow, investigate John Doe"',
     guide_memory: '🧠 持久记忆',
     guide_dev_studio: '🏗️ Dev Studio',
@@ -698,6 +712,7 @@ const LANGUAGES = {
     guide_seo: 'ביקורת SEO / GEO (360°)',
     guide_backup: 'גיבוי חכם של הפרויקט',
     guide_animated: 'אתר אנימציה יוקרתי',
+    guide_design: 'עיצוב עם Atelier',
     guide_shield: '🛡️ תאימות GRC',
     guide_example_shield_1: '🛡️ GRC: "Shield, בדוק את האפליקציה שלי ל-GDPR"',
     guide_example_shield_2: '🛡️ GRC: "Shield, ניתוח פערים ISO 27001 מול NIST CSF"',
@@ -733,6 +748,7 @@ const LANGUAGES = {
     guide_example_seo: '🔍 SEO: "/seo audit https://example.com"',
     guide_example_backup: '🗂️  גיבוי: "/backup create" → ZIP',
     guide_example_animated: '🎬 אנימציה: "/animated build hero.mp4"',
+    guide_example_design: '🎨 עיצוב: "/design read" → Atelier מראיין אותך ואז בונה',
     guide_example_osint: '🔍 OSINT: "Shadow, investigate John Doe"',
     guide_memory: '🧠 זיכרון מתמשך',
     guide_dev_studio: '🏗️ Dev Studio',
@@ -786,6 +802,7 @@ const LANGUAGES = {
     guide_seo: 'SEO / GEO 監査 (360°)',
     guide_backup: 'スマートプロジェクトバックアップ',
     guide_animated: 'アニメーション高級ウェブサイト',
+    guide_design: 'Atelier でデザイン',
     guide_shield: '🛡️ GRC コンプライアンス',
     guide_example_shield_1: '🛡️ GRC: "Shield, アプリのGDPR準拠を監査"',
     guide_example_shield_2: '🛡️ GRC: "Shield, ISO 27001 vs NIST CSF ギャップ分析"',
@@ -825,6 +842,7 @@ const LANGUAGES = {
     guide_example_seo: '🔍 SEO: "/seo audit https://example.com"',
     guide_example_backup: '🗂️  バックアップ: "/backup create" → ZIP',
     guide_example_animated: '🎬 アニメ: "/animated build hero.mp4"',
+    guide_example_design: '🎨 デザイン: "/design read" → Atelier がヒアリングしてから構築します',
     guide_example_osint: '🔍 OSINT: "Shadow, investigate John Doe"',
     guide_memory: '🧠 永続的な脳',
     guide_dev_studio: '🏗️ Dev Studio',
@@ -879,6 +897,7 @@ const LANGUAGES = {
     guide_seo: 'Audit SEO / GEO (360°)',
     guide_backup: 'Backup intelligente del progetto',
     guide_animated: 'Sito web animato di lusso',
+    guide_design: 'Design con Atelier',
     guide_shield: '\ud83d\udee1\ufe0f Conformit\u00e0 GRC',
     guide_example_shield_1: '\ud83d\udee1\ufe0f GRC: "Shield, verifica la mia app per il GDPR"',
     guide_example_shield_2: '\ud83d\udee1\ufe0f GRC: "Shield, gap analysis ISO 27001 vs NIST CSF"',
@@ -918,6 +937,7 @@ const LANGUAGES = {
     guide_example_seo: '🔍 SEO: "/seo audit https://example.com"',
     guide_example_backup: '🗂️  Backup: "/backup create" → ZIP con timestamp',
     guide_example_animated: '🎬 Animato: "/animated build hero.mp4"',
+    guide_example_design: '🎨 Design: "/design read" → Atelier ti intervista, poi costruisce',
     guide_example_osint: '🔍 OSINT: "Shadow, investigate John Doe"',
     guide_memory: '🧠 Memoria persistente',
     guide_dev_studio: '🏗️ Dev Studio',

package/tools/cli/lib/intake.js

@@ -0,0 +1,202 @@
+/** Read, plan, record and render a pack intake inside one project; the contract decides. */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const yaml = require('js-yaml');
+const { safeTarget } = require('../../build/generate-adapters');
+const contract = require('../../build/intake-contract');
+
+const MAX_FILE = 1024 * 1024;
+// Trees the intake never writes into, wherever they sit in the project.
+const RESERVED_DIRS = new Set(['.git', '_bmad', '.bmad-plus', 'node_modules']);
+
+/** A user-supplied path, kept inside the project and free of symlinks. */
+function projectFile(projectDir, file) {
+  if (typeof file !== 'string' || file.trim() === '') throw new Error('a file path is required');
+  const root = path.resolve(projectDir);
+  const relative = path.relative(root, path.resolve(root, file)).split(path.sep).join('/');
+  if (!relative || relative === '..' || relative.startsWith('../'))
+    throw new Error(`${file}: outside the project directory ${root}`);
+  return { relative, absolute: safeTarget(root, relative) };
+}
+
+/** A path the intake may write: outside the reserved trees, and never through a link. */
+function writableFile(projectDir, file) {
+  const target = projectFile(projectDir, file);
+  const reserved = target.relative.split('/').find((part) => RESERVED_DIRS.has(part));
+  if (reserved) throw new Error(`${target.relative}: the intake never writes under ${reserved}/`);
+  return target;
+}
+
+function readBounded(absolute, label) {
+  const stat = fs.lstatSync(absolute);
+  if (!stat.isFile()) throw new Error(`${label}: not a regular file`);
+  if (stat.size > MAX_FILE) throw new Error(`${label}: larger than ${MAX_FILE} bytes`);
+  return fs.readFileSync(absolute, 'utf8');
+}
+
+function describe(problems) {
+  return problems.map((problem) => `  - ${problem}`).join('\n');
+}
+
+/** Parse and validate an intake file; throws listing every problem. */
+function loadIntake(projectDir, file) {
+  const target = projectFile(projectDir, file);
+  let parsed;
+  try {
+    parsed = yaml.load(readBounded(target.absolute, target.relative), { schema: yaml.JSON_SCHEMA });
+  } catch (error) {
+    throw new Error(`${target.relative}: ${error.message}`, { cause: error });
+  }
+  const result = contract.validateIntake(parsed);
+  if (!result.ok)
+    throw new Error(`${target.relative} is not a valid intake:\n${describe(result.problems)}`);
+  return { file: target.relative, intake: parsed };
+}
+
+/** The parsed JSON of an existing answers file when it belongs to this intake; else throws. */
+function ownedAnswers(target, intake) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readBounded(target.absolute, target.relative));
+  } catch (error) {
+    throw new Error(
+      `${target.relative}: exists and is not an answers file of intake "${intake.id}" (${error.message}); move it away or pick another path`,
+      { cause: error }
+    );
+  }
+  if (!parsed || typeof parsed !== 'object' || parsed.intake !== intake.id) {
+    throw new Error(
+      `${target.relative}: exists and belongs to ${JSON.stringify(parsed && parsed.intake)}, not to intake "${intake.id}"; move it away or pick another path`
+    );
+  }
+  return parsed;
+}
+
+/** Parse and validate an answers file; an absent file means no answer yet. */
+function loadAnswers(projectDir, file, intake) {
+  const target = writableFile(projectDir, file);
+  if (!fs.existsSync(target.absolute)) {
+    return { file: target.relative, answers: contract.emptyAnswers(intake), exists: false };
+  }
+  const parsed = ownedAnswers(target, intake);
+  const result = contract.validateAnswers(parsed, intake);
+  if (!result.ok)
+    throw new Error(
+      `${target.relative} does not answer this intake:\n${describe(result.problems)}\nRecord again with --reset to start over.`
+    );
+  return { file: target.relative, answers: parsed, exists: true };
+}
+
+function atomicWrite(projectDir, relative, content) {
+  const target = safeTarget(projectDir, relative);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  const temporaryFile = `${relative}.${crypto.randomUUID()}.tmp`;
+  const temporary = safeTarget(projectDir, temporaryFile);
+  let fd;
+  try {
+    fd = fs.openSync(temporary, 'wx');
+    fs.writeFileSync(fd, content);
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = undefined;
+    safeTarget(projectDir, relative);
+    fs.renameSync(temporary, target);
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+    if (fs.existsSync(temporary)) fs.unlinkSync(temporary);
+  }
+}
+
+function check({ projectDir, file }) {
+  const target = projectFile(projectDir, file);
+  let parsed;
+  try {
+    parsed = yaml.load(readBounded(target.absolute, target.relative), { schema: yaml.JSON_SCHEMA });
+  } catch (error) {
+    return { file: target.relative, ok: false, problems: [error.message] };
+  }
+  const result = contract.validateIntake(parsed);
+  const summary = result.ok
+    ? {
+        id: parsed.id,
+        pack: parsed.pack,
+        questions: contract.listQuestions(parsed).length,
+        mustHave: contract.listQuestions(parsed).filter((q) => q.must_have === true).length,
+      }
+    : {};
+  return { file: target.relative, ...result, ...summary };
+}
+
+function plan({ projectDir, intakeFile, answersFile }) {
+  const { intake } = loadIntake(projectDir, intakeFile);
+  const { answers, file } = loadAnswers(projectDir, answersFile, intake);
+  return { answersFile: file, ...contract.planIntake(intake, answers) };
+}
+
+/**
+ * `sets` is a list of "id=VALUE" texts, `defaults` a list of question ids. With
+ * `reset`, the file starts again empty for this intake (an existing file must
+ * already belong to it), then takes the sets and defaults of the same call.
+ */
+function record({ projectDir, intakeFile, answersFile, sets = [], defaults = [], reset = false }) {
+  const { intake } = loadIntake(projectDir, intakeFile);
+  let loaded;
+  if (reset) {
+    const target = writableFile(projectDir, answersFile);
+    if (fs.existsSync(target.absolute)) ownedAnswers(target, intake);
+    loaded = { file: target.relative, answers: contract.emptyAnswers(intake) };
+  } else loaded = loadAnswers(projectDir, answersFile, intake);
+  const pairs = {};
+  for (const assignment of sets) {
+    const at = typeof assignment === 'string' ? assignment.indexOf('=') : -1;
+    if (at < 1) throw new Error(`--set expects id=VALUE, got "${assignment}"`);
+    const id = assignment.slice(0, at);
+    if (Object.hasOwn(pairs, id)) throw new Error(`question "${id}" is set twice in one call`);
+    pairs[id] = assignment.slice(at + 1);
+  }
+  if (!reset && Object.keys(pairs).length === 0 && defaults.length === 0)
+    throw new Error('nothing to record: pass --set id=VALUE, --default id or --reset');
+  const answers = contract.recordAnswers(intake, loaded.answers, { sets: pairs, defaults });
+  const result = contract.validateAnswers(answers, intake);
+  if (!result.ok) throw new Error(`recorded answers are invalid:\n${describe(result.problems)}`);
+  atomicWrite(projectDir, loaded.file, JSON.stringify(answers, null, 2) + '\n');
+  return {
+    answersFile: loaded.file,
+    reset,
+    recorded: [...Object.keys(pairs), ...defaults],
+    ...contract.planIntake(intake, answers),
+  };
+}
+
+/** The brief overwrites only a file it wrote before for the same intake. */
+function render({ projectDir, intakeFile, answersFile, out }) {
+  const { intake } = loadIntake(projectDir, intakeFile);
+  const { answers } = loadAnswers(projectDir, answersFile, intake);
+  const target = writableFile(projectDir, out);
+  if (fs.existsSync(target.absolute)) {
+    const marker = contract.briefMarker(intake);
+    const head = readBounded(target.absolute, target.relative).split(/\r?\n/, 2);
+    if (head[1] !== marker)
+      throw new Error(
+        `${target.relative}: exists and is not a brief of intake "${intake.id}" (its second line is not the ownership marker); move it away or pick another path`
+      );
+  }
+  const brief = contract.renderBrief(intake, answers);
+  atomicWrite(projectDir, target.relative, brief);
+  const planned = contract.planIntake(intake, answers);
+  return { out: target.relative, bytes: Buffer.byteLength(brief), ready: planned.ready };
+}
+
+module.exports = {
+  projectFile,
+  writableFile,
+  loadIntake,
+  loadAnswers,
+  check,
+  plan,
+  record,
+  render,
+};