engsys 1.0.0

package/lib/generate-team-avatars.mjs

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+/**
+ * Generate team-roster headshots for engsys agent personas.
+ *
+ * The image prompt is derived FROM the agent profile itself — the script reads
+ * the persona's name, role, and personality straight out of the .md and wraps it
+ * in a consistent "house style" art direction. Point it at any agent profile.
+ *
+ * Config (from .env at the repo root, or the environment):
+ *   OPENAI_API_KEY        required
+ *   OPENAI_IMAGE_MODEL    e.g. gpt-image-1 (default) or dall-e-3
+ *   OPENAI_IMAGE_QUALITY  optional override (gpt-image-1: low|medium|high|auto;
+ *                                            dall-e-3: standard|hd)
+ *
+ * Usage:
+ *   node lib/generate-team-avatars.mjs <agent.md> [<agent.md> ...] [options]
+ *
+ * Options:
+ *   --count=N     how many variations to generate per profile (1-5, default 1)
+ *   --out=DIR     output directory (default: tmp/ at the repo root)
+ *   --dry-run     print the constructed prompt(s) and exit — no API call, no cost
+ *
+ * Examples:
+ *   node lib/generate-team-avatars.mjs optional-agents/sandy.md --count=3
+ *   node lib/generate-team-avatars.mjs core/agents/*.md --count=2
+ *   node lib/generate-team-avatars.mjs optional-agents/gary.md --dry-run
+ *
+ * Output files are versioned (sandy-001.png, sandy-002.png, …) and never
+ * overwrite existing files. Pick the winner, then move it to team-images/<id>.png.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import process from 'node:process';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.join(__dirname, '..');
+
+// --- config / .env ---------------------------------------------------------
+const ENV_PATH = path.join(REPO_ROOT, '.env');
+if (fs.existsSync(ENV_PATH)) {
+  try {
+    process.loadEnvFile(ENV_PATH); // Node >= 20.12 / 22
+  } catch {
+    // minimal fallback parser (KEY=VALUE per line, ignores # comments)
+    for (const line of fs.readFileSync(ENV_PATH, 'utf8').split(/\r?\n/)) {
+      const m = line.match(/^\s*([\w.-]+)\s*=\s*(.*)\s*$/);
+      if (m && !line.trimStart().startsWith('#')) {
+        const val = m[2].replace(/^["']|["']$/g, '');
+        if (!(m[1] in process.env)) process.env[m[1]] = val;
+      }
+    }
+  }
+}
+
+const OPENAI_API_KEY = process.env.OPENAI_API_KEY;
+const MODEL = process.env.OPENAI_IMAGE_MODEL || 'gpt-image-1';
+const API_URL = 'https://api.openai.com/v1/images/generations';
+
+// --- prompt construction ---------------------------------------------------
+
+// Pull name / role / personality out of an agent profile .md.
+function extractPersona(md, fallbackId) {
+  let name = fallbackId;
+  let description = '';
+  let body = md;
+
+  if (md.startsWith('---')) {
+    const end = md.indexOf('\n---', 3);
+    if (end !== -1) {
+      const fm = md.slice(3, end);
+      const nm = fm.match(/^\s*name:\s*(.+)$/m);
+      if (nm) name = nm[1].trim().replace(/^["']|["']$/g, '');
+      const dm = fm.match(/^\s*description:\s*(.+)$/m);
+      if (dm) description = dm[1].trim().replace(/^["']|["']$/g, '');
+      body = md.slice(end + 4);
+    }
+  }
+
+  const titleMatch = body.match(/^#\s+(.+)$/m);
+  const title = titleMatch ? titleMatch[1].trim() : (name.charAt(0).toUpperCase() + name.slice(1));
+
+  // The Personality section is the richest source of look-and-vibe cues.
+  let personality = '';
+  const pm = body.match(/^#{2,3}\s*Personality[^\n]*\n([\s\S]*?)(?=\n#{2,3}\s|$)/im);
+  if (pm) personality = pm[1].trim();
+  if (!personality) {
+    // fall back to the opening prose of the profile
+    personality = body.replace(/^#.*$/m, '').trim().slice(0, 1200);
+  }
+
+  return { id: name, title, description, personality };
+}
+
+function clip(s, n) {
+  s = s.replace(/\s+/g, ' ').trim();
+  return s.length > n ? s.slice(0, n).replace(/\s+\S*$/, '') + '…' : s;
+}
+
+function buildPrompt({ title, description, personality }, appearance) {
+  const brief = [
+    description && `Role: ${clip(description, 400)}`,
+    personality && `Personality & vibe:\n${clip(personality, 1400)}`,
+  ].filter(Boolean).join('\n\n');
+
+  const likeness = appearance ? `\nPhysical likeness (use exactly, this overrides any inference): ${appearance}.\n` : '';
+
+  return `An illustrated character portrait for a software-engineering team roster — a single trading-card-style avatar.
+
+Subject: ${title}.
+${likeness}
+${brief}
+
+Art direction: a warm, characterful, stylized DIGITAL PORTRAIT ILLUSTRATION (clearly illustrated, NOT photorealistic) of one person who naturally embodies the personality above. Choose an age, build, clothing, expression, and one small thematic prop that fit the role and character. Head and upper chest only, face centered with generous padding on every side so it can be cropped to a circle without clipping. Tasteful thematic gradient background with subtle motifs related to the role. Friendly, professional, a touch playful. Consistent, clean illustrative style. Square 1024x1024.`;
+}
+
+// --- generation ------------------------------------------------------------
+
+function nextVersion(dir, id) {
+  if (!fs.existsSync(dir)) return 1;
+  const re = new RegExp(`^${id}-(\\d{3})\\.png$`);
+  let max = 0;
+  for (const f of fs.readdirSync(dir)) {
+    const m = f.match(re);
+    if (m) max = Math.max(max, parseInt(m[1], 10));
+  }
+  return max + 1;
+}
+
+function requestBody(prompt) {
+  const body = { model: MODEL, prompt, n: 1, size: '1024x1024' };
+  const q = process.env.OPENAI_IMAGE_QUALITY;
+  if (MODEL === 'dall-e-3') {
+    body.quality = q || 'standard';     // standard | hd
+    body.response_format = 'b64_json';
+  } else {
+    body.quality = q || 'high';         // gpt-image-1: low | medium | high | auto
+    // gpt-image-1 always returns b64_json; response_format is not accepted.
+  }
+  return body;
+}
+
+async function generate(persona, outDir, version) {
+  const v = String(version).padStart(3, '0');
+  console.log(`  generating ${persona.id} v${v} …`);
+  const res = await fetch(API_URL, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${OPENAI_API_KEY}` },
+    body: JSON.stringify(requestBody(persona.prompt)),
+  });
+  if (!res.ok) {
+    throw new Error(`OpenAI ${res.status}: ${(await res.text()).slice(0, 300)}`);
+  }
+  const data = await res.json();
+  const d = data.data[0];
+  let buf;
+  if (d.b64_json) buf = Buffer.from(d.b64_json, 'base64');
+  else if (d.url) buf = Buffer.from(await (await fetch(d.url)).arrayBuffer());
+  else throw new Error('unexpected response: no b64_json or url');
+
+  const file = path.join(outDir, `${persona.id}-${v}.png`);
+  fs.writeFileSync(file, buf);
+  console.log(`  ✓ ${path.relative(process.cwd(), file)}`);
+  if (d.revised_prompt) console.log(`    ↳ revised: ${clip(d.revised_prompt, 90)}`);
+  return file;
+}
+
+// --- main ------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const opts = { count: 1, out: null, dryRun: false, profiles: [] };
+  for (const a of argv) {
+    if (a === '--dry-run') opts.dryRun = true;
+    else if (a.startsWith('--count=')) opts.count = parseInt(a.split('=')[1], 10);
+    else if (a.startsWith('--out=')) opts.out = a.split('=')[1];
+    else if (a.startsWith('--appearance=')) opts.appearance = a.slice('--appearance='.length);
+    else if (a.startsWith('--prompt-file=')) opts.promptFile = a.slice('--prompt-file='.length);
+    else if (a.startsWith('--prompt=')) opts.prompt = a.slice('--prompt='.length);
+    else if (a.startsWith('--')) { console.error(`unknown option: ${a}`); process.exit(1); }
+    else opts.profiles.push(a);
+  }
+  return opts;
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+
+  if (!opts.profiles.length) {
+    console.error('usage: node lib/generate-team-avatars.mjs <agent.md> [...] [--count=N] [--out=DIR] [--dry-run]');
+    process.exit(1);
+  }
+  if (!Number.isInteger(opts.count) || opts.count < 1 || opts.count > 5) {
+    console.error('--count must be an integer 1-5');
+    process.exit(1);
+  }
+
+  const outDir = path.resolve(opts.out || path.join(REPO_ROOT, 'tmp'));
+
+  // A verbatim prompt (from --prompt-file or --prompt) overrides the
+  // profile-derived prompt entirely — use it for hand-authored / external prompts.
+  const rawPrompt = opts.promptFile
+    ? fs.readFileSync(opts.promptFile, 'utf8').trim()
+    : (opts.prompt || null);
+
+  // Build personas from profiles (profile still supplies the output id/name).
+  const personas = opts.profiles.map((p) => {
+    const md = fs.readFileSync(p, 'utf8');
+    const fallbackId = path.basename(p, '.md');
+    const persona = extractPersona(md, fallbackId);
+    return { ...persona, prompt: rawPrompt || buildPrompt(persona, opts.appearance) };
+  });
+
+  if (opts.dryRun) {
+    for (const p of personas) {
+      console.log(`\n──────── ${p.id} ────────\n${p.prompt}\n`);
+    }
+    console.log(`(dry run — ${personas.length} profile(s), would generate ${opts.count} each; model ${MODEL})`);
+    return;
+  }
+
+  if (!OPENAI_API_KEY) {
+    console.error('OPENAI_API_KEY is not set (add it to .env at the repo root).');
+    process.exit(1);
+  }
+  fs.mkdirSync(outDir, { recursive: true });
+
+  const total = personas.length * opts.count;
+  console.log(`engsys team avatars — model ${MODEL}, ${opts.count} variation(s) × ${personas.length} profile(s) = ${total} image(s)`);
+  console.log(`output: ${outDir}\n`);
+
+  let ok = 0, fail = 0;
+  for (const persona of personas) {
+    for (let i = 0; i < opts.count; i++) {
+      const version = nextVersion(outDir, persona.id);
+      try {
+        await generate(persona, outDir, version);
+        ok++;
+        if (ok + fail < total) await new Promise((r) => setTimeout(r, 1500));
+      } catch (e) {
+        console.error(`  ✗ ${persona.id}: ${e.message}`);
+        fail++;
+      }
+    }
+  }
+
+  console.log(`\ndone — ${ok}/${total} generated${fail ? `, ${fail} failed` : ''}.`);
+  console.log('Pick a winner, then move it to team-images/<id>.png.');
+}
+
+main().catch((e) => { console.error(e); process.exit(1); });

package/lib/manifest.js

@@ -0,0 +1,155 @@
+'use strict';
+
+const { path, exists, fs } = require('./util');
+
+// Resolve which stack packs a config selects, as [category, value] paths
+// under stacks/. Order matters only for display.
+function selectedPacks(config) {
+  const stack = config.stack || {};
+  const packs = [];
+  const seen = new Set();
+  const add = (cat, val) => {
+    if (!val || val === 'none') return;
+    const rel = path.join(cat, String(val));
+    if (seen.has(rel)) return;
+    seen.add(rel);
+    packs.push(rel);
+  };
+  // Every stack dimension accepts a scalar OR a list — mixed stacks compose.
+  for (const c of [].concat(stack.cloud || [])) add('cloud', c);
+  for (const i of [].concat(stack.iac || [])) add('iac', i);
+  for (const d of [].concat(stack.db || [])) add('db', d);
+  for (const l of [].concat(stack.lang || [])) add('lang', l);
+  for (const p of [].concat(stack.platform || [])) add('platform', p);
+  for (const d of [].concat(stack.domain || [])) add('domain', d);
+  // Issue tracker resolves as a pack too. Defaults to github (zero-config keeps
+  // today's behavior); set `issue_tracker: none` to opt out entirely.
+  for (const t of [].concat(config.issue_tracker || 'github')) {
+    if (t && t !== 'none') add('tooling', `issue-tracker-${t}`);
+  }
+  return packs;
+}
+
+function listMd(dir) {
+  if (!exists(dir)) return [];
+  return fs.readdirSync(dir).filter((f) => f.endsWith('.md'));
+}
+
+// Build the full install plan: every copy operation + every fragment to merge.
+function buildManifest(engsysRoot, config) {
+  const core = path.join(engsysRoot, 'core');
+  const plan = {
+    agents: [],      // { src, name }
+    commands: [],    // { src, name, description }
+    skillDirs: [],   // { src(dir), name }  -> copied into .claude/skills/<name>
+    workflows: [],   // { src, name }
+    packHooks: [],   // { src, name } -> copied verbatim into .claude/hooks/
+    claudeFragments: [], // { pack, text }
+    settingsFragments: [], // parsed json objects
+    mcpServers: {},  // merged
+    packs: selectedPacks(config),
+    warnings: [],
+  };
+
+  const seenAgent = new Set();
+  const addAgent = (src, name) => {
+    if (seenAgent.has(name)) { plan.warnings.push(`duplicate agent '${name}' skipped (${src})`); return; }
+    seenAgent.add(name);
+    plan.agents.push({ src, name });
+  };
+
+  // --- core agents ---
+  const agentSel = (config.agents && config.agents.core) || 'all';
+  const coreAgentsDir = path.join(core, 'agents');
+  const coreAgentFiles = agentSel === 'all'
+    ? listMd(coreAgentsDir)
+    : [].concat(agentSel).map((n) => `${n}.md`);
+  for (const f of coreAgentFiles) {
+    const src = path.join(coreAgentsDir, f);
+    if (!exists(src)) { plan.warnings.push(`core agent not found: ${f}`); continue; }
+    addAgent(src, f);
+  }
+
+  // --- extra (optional) agents ---
+  const extra = (config.agents && config.agents.extra) || [];
+  for (const n of [].concat(extra)) {
+    const src = path.join(engsysRoot, 'optional-agents', `${n}.md`);
+    if (!exists(src)) { plan.warnings.push(`optional agent not found: ${n}`); continue; }
+    addAgent(src, `${n}.md`);
+  }
+
+  // --- commands ---
+  const cmdSel = config.commands || 'all';
+  const coreCmdDir = path.join(core, 'commands');
+  const cmdFiles = cmdSel === 'all'
+    ? listMd(coreCmdDir)
+    : [].concat(cmdSel).map((n) => `${n}.md`);
+  const { frontmatterDescription } = require('./util');
+  for (const f of cmdFiles) {
+    const src = path.join(coreCmdDir, f);
+    if (!exists(src)) { plan.warnings.push(`command not found: ${f}`); continue; }
+    plan.commands.push({ src, name: f, description: frontmatterDescription(src) });
+  }
+
+  // --- core skills (always all) ---
+  const coreSkillsDir = path.join(core, 'skills');
+  if (exists(coreSkillsDir)) {
+    for (const d of fs.readdirSync(coreSkillsDir, { withFileTypes: true })) {
+      if (d.isDirectory()) plan.skillDirs.push({ src: path.join(coreSkillsDir, d.name), name: d.name });
+    }
+  }
+
+  // --- core workflows ---
+  const wfDir = path.join(core, 'workflows');
+  for (const f of listMd(wfDir)) plan.workflows.push({ src: path.join(wfDir, f), name: f });
+
+  // --- stack packs ---
+  const seenSkill = new Set(plan.skillDirs.map((s) => s.name));
+  for (const rel of plan.packs) {
+    const packDir = path.join(engsysRoot, 'stacks', rel);
+    if (!exists(packDir)) { plan.warnings.push(`pack not found: ${rel}`); continue; }
+
+    const skillsDir = path.join(packDir, 'skills');
+    if (exists(skillsDir)) {
+      for (const d of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+        if (!d.isDirectory()) continue;
+        if (seenSkill.has(d.name)) { plan.warnings.push(`duplicate skill '${d.name}' from ${rel} skipped`); continue; }
+        seenSkill.add(d.name);
+        plan.skillDirs.push({ src: path.join(skillsDir, d.name), name: d.name });
+      }
+    }
+
+    const agentsDir = path.join(packDir, 'agents');
+    for (const f of listMd(agentsDir)) addAgent(path.join(agentsDir, f), f);
+
+    const hooksDir = path.join(packDir, 'hooks');
+    if (exists(hooksDir)) {
+      for (const f of fs.readdirSync(hooksDir)) {
+        plan.packHooks.push({ src: path.join(hooksDir, f), name: f });
+      }
+    }
+
+    const frag = path.join(packDir, 'claude.fragment.md');
+    if (exists(frag)) plan.claudeFragments.push({ pack: rel, text: require('./util').readText(frag).trim() });
+
+    const sfrag = path.join(packDir, 'settings.fragment.json');
+    if (exists(sfrag)) {
+      try {
+        const obj = JSON.parse(require('./util').readText(sfrag));
+        plan.settingsFragments.push(obj);
+        Object.assign(plan.mcpServers, obj.mcpServers || {});
+      } catch (e) {
+        plan.warnings.push(`invalid settings.fragment.json in ${rel}: ${e.message}`);
+      }
+    }
+  }
+
+  // Merge any MCP servers declared directly in naturalize config.
+  if (config.naturalize && config.naturalize.mcp_servers) {
+    Object.assign(plan.mcpServers, config.naturalize.mcp_servers);
+  }
+
+  return plan;
+}
+
+module.exports = { buildManifest, selectedPacks };

package/lib/render.js

@@ -0,0 +1,135 @@
+'use strict';
+
+const { path, readText, exists, uniq } = require('./util');
+
+const PF_START = '<!-- ENGSYS:PROJECT-FACTS:START -->';
+const PF_END = '<!-- ENGSYS:PROJECT-FACTS:END -->';
+
+function fill(tmpl, vars) {
+  return tmpl.replace(/\{\{(\w+)\}\}/g, (_, k) => (k in vars ? vars[k] : `{{${k}}}`));
+}
+
+function renderCommandsList(commands) {
+  if (!commands.length) return '_No commands installed._';
+  return commands
+    .map((c) => {
+      const name = c.name.replace(/\.md$/, '');
+      const desc = c.description ? ` — ${c.description}` : '';
+      return `- \`/${name}\`${desc}`;
+    })
+    .join('\n');
+}
+
+function renderMcpServers(mcpServers) {
+  const keys = Object.keys(mcpServers);
+  if (!keys.length) return '_No MCP servers required by the selected stack._';
+  return keys
+    .map((k) => {
+      const s = mcpServers[k];
+      const loc = s.url || (s.command ? `${s.command} ${(s.args || []).join(' ')}` : '');
+      return `- \`${k}\` — ${s.type || 'stdio'}${loc ? ` (${loc})` : ''}`;
+    })
+    .join('\n');
+}
+
+// Render CLAUDE.md from template. On update, preserve the PROJECT-FACTS region
+// from the existing file.
+function renderClaudeMd(engsysRoot, config, plan, existingClaudeMd, seedFacts) {
+  const tmpl = readText(path.join(engsysRoot, 'core', 'templates', 'CLAUDE.md.tmpl'));
+  const project = config.project || {};
+  const nat = config.naturalize || {};
+
+  const stackFragments = plan.claudeFragments.length
+    ? plan.claudeFragments.map((f) => f.text).join('\n\n')
+    : '## Stack\n\n_No stack packs selected._';
+
+  let projectFacts = nat.project_facts ||
+    '> TODO (naturalize): describe this project — services, runtimes, build/verify toolchain, hard invariants, key paths. Run `/naturalize` or fill this in by hand.';
+
+  // A foreign CLAUDE.md (or imported AI config) seeds the facts on first adoption.
+  if (seedFacts) projectFacts = seedFacts;
+
+  // Preserve hand-edited project facts on update (prior engsys region wins).
+  if (existingClaudeMd) {
+    const s = existingClaudeMd.indexOf(PF_START);
+    const e = existingClaudeMd.indexOf(PF_END);
+    if (s !== -1 && e !== -1 && e > s) {
+      const preserved = existingClaudeMd.slice(s + PF_START.length, e).trim();
+      if (preserved) projectFacts = preserved;
+    }
+  }
+
+  const lessonsCfg = config.lessons || {};
+  const lessonsNote = lessonsCfg.seed === false
+    ? 'Project-specific lessons accrue in `docs/agent-lessons/`.'
+    : `Cross-project lessons are seeded under \`${lessonsCfg.into || 'docs/agent-lessons/library'}\` — consult them before implementing. Project-specific lessons accrue in \`docs/agent-lessons/\` and graduate back to the engsys lessons-library by PR.`;
+
+  return fill(tmpl, {
+    PROJECT_NAME: project.name || 'Project',
+    PROJECT_DESCRIPTION: project.description || '',
+    MODEL_STRATEGY: nat.model_strategy ||
+      'Opus for orchestration, synthesis, and judgement; Sonnet for execution. Escalate to Opus when a task needs cross-file reasoning, security analysis, or design tradeoffs.',
+    STACK_FRAGMENTS: stackFragments,
+    MCP_SERVERS: renderMcpServers(plan.mcpServers),
+    COMMANDS_LIST: renderCommandsList(plan.commands),
+    PROJECT_FACTS: projectFacts,
+    LESSONS_NOTE: lessonsNote,
+  });
+}
+
+// Merge base settings template with pack permission fragments (+ optional
+// existing settings on update, to preserve hand-added permissions).
+function renderSettings(engsysRoot, plan, existingSettings) {
+  const base = JSON.parse(readText(path.join(engsysRoot, 'core', 'templates', 'settings.json.tmpl')));
+  base.permissions = base.permissions || { allow: [], deny: [] };
+  let allow = base.permissions.allow || [];
+  let deny = base.permissions.deny || [];
+
+  for (const frag of plan.settingsFragments) {
+    if (frag.permissions) {
+      allow = allow.concat(frag.permissions.allow || []);
+      deny = deny.concat(frag.permissions.deny || []);
+    }
+  }
+  if (existingSettings && existingSettings.permissions) {
+    allow = allow.concat(existingSettings.permissions.allow || []);
+    deny = deny.concat(existingSettings.permissions.deny || []);
+  }
+
+  base.permissions.allow = uniq(allow).sort();
+  base.permissions.deny = uniq(deny).sort();
+  return JSON.stringify(base, null, 2) + '\n';
+}
+
+function renderSettingsLocal(engsysRoot, plan) {
+  const base = JSON.parse(readText(path.join(engsysRoot, 'core', 'templates', 'settings.local.json.tmpl')));
+  base.enabledMcpjsonServers = Object.keys(plan.mcpServers).sort();
+  return JSON.stringify(base, null, 2) + '\n';
+}
+
+function renderMcpJson(plan, existingMcp) {
+  const servers = Object.assign({}, (existingMcp && existingMcp.mcpServers) || {}, plan.mcpServers);
+  return JSON.stringify({ mcpServers: servers }, null, 2) + '\n';
+}
+
+function renderHook(engsysRoot, config) {
+  const tmpl = readText(path.join(engsysRoot, 'core', 'templates', 'post-edit-reminders.sh.tmpl'));
+  const patterns = (config.naturalize && config.naturalize.hook_patterns) || [];
+  let cases;
+  if (!patterns.length) {
+    cases = '  # No project reminders configured yet. Add them under naturalize.hook_patterns.';
+  } else {
+    cases = patterns
+      .map((p) => {
+        const reminder = String(p.reminder || '').replace(/"/g, '\\"');
+        return `  ${p.glob})\n    echo "↳ ${reminder}" ;;`;
+      })
+      .join('\n');
+  }
+  return fill(tmpl, { REMINDER_CASES: cases });
+}
+
+module.exports = {
+  renderClaudeMd, renderSettings, renderSettingsLocal, renderMcpJson, renderHook,
+  PF_START, PF_END,
+};

package/lib/selftest.js

@@ -0,0 +1,90 @@
+'use strict';
+
+// Tiny zero-dep test harness for the YAML subset parser. Run: npm test
+const assert = require('assert');
+const { parseYaml } = require('./yaml');
+
+let pass = 0;
+function check(name, fn) { fn(); pass++; console.log(`  ok ${name}`); }
+
+check('scalars and inline lists', () => {
+  const c = parseYaml(`
+project:
+  name: Acme Widgets
+  description: A one-liner.
+stack:
+  cloud: aws
+  iac: none
+  lang: [typescript, python]
+  db: none
+commands: all
+`);
+  assert.strictEqual(c.project.name, 'Acme Widgets');
+  assert.strictEqual(c.project.description, 'A one-liner.');
+  assert.strictEqual(c.stack.cloud, 'aws');
+  assert.deepStrictEqual(c.stack.lang, ['typescript', 'python']);
+  assert.strictEqual(c.commands, 'all');
+});
+
+check('quoted strings keep punctuation', () => {
+  const c = parseYaml(`
+naturalize:
+  model_strategy: "Opus for judgement; Sonnet for execution."
+`);
+  assert.strictEqual(c.naturalize.model_strategy, 'Opus for judgement; Sonnet for execution.');
+});
+
+check('block list of maps (hook_patterns)', () => {
+  const c = parseYaml(`
+naturalize:
+  hook_patterns:
+    - glob: "*/schema.prisma"
+      reminder: "Regenerate the client."
+    - glob: "docs/spec.md"
+      reminder: "Bump the version header."
+  invariants: []
+`);
+  assert.strictEqual(c.naturalize.hook_patterns.length, 2);
+  assert.strictEqual(c.naturalize.hook_patterns[0].glob, '*/schema.prisma');
+  assert.strictEqual(c.naturalize.hook_patterns[0].reminder, 'Regenerate the client.');
+  assert.strictEqual(c.naturalize.hook_patterns[1].glob, 'docs/spec.md');
+  assert.deepStrictEqual(c.naturalize.invariants, []);
+});
+
+check('agents block with extra list', () => {
+  const c = parseYaml(`
+agents:
+  core: all
+  extra: [sandy, gary]
+`);
+  assert.strictEqual(c.agents.core, 'all');
+  assert.deepStrictEqual(c.agents.extra, ['sandy', 'gary']);
+});
+
+check('comments and bools', () => {
+  const c = parseYaml(`
+# a comment
+stack:
+  cloud: azure   # trailing comment
+flag: true
+empty: ~
+`);
+  assert.strictEqual(c.stack.cloud, 'azure');
+  assert.strictEqual(c.flag, true);
+  assert.strictEqual(c.empty, null);
+});
+
+check('inline flow maps (single-line stack/lessons)', () => {
+  const c = parseYaml(`
+project: {name: SeedTest, description: x}
+stack: {cloud: aws, lang: [typescript, python], platform: [web]}
+lessons: {seed: false}
+`);
+  assert.strictEqual(c.project.name, 'SeedTest');
+  assert.strictEqual(c.stack.cloud, 'aws');
+  assert.deepStrictEqual(c.stack.lang, ['typescript', 'python']);
+  assert.deepStrictEqual(c.stack.platform, ['web']);
+  assert.strictEqual(c.lessons.seed, false);
+});
+
+console.log(`\n${pass} checks passed.`);