@mindrian_os/install 1.13.0-beta.16 → 1.13.0-beta.19

package/lib/core/room-receipt-emit.cjs

@@ -0,0 +1,63 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 121-03 Task 2 -- emit helper for room_receipt_written events (D-09 surface 2).
+ *
+ * Called from the Phase 119 receipt-write surface (lib/core/room-auto-create.cjs
+ * after autoCreatePlaceholderRoom finishes scaffolding the room directory + registry
+ * entry + room_auto_created memory_event). One line per receipt-write, routed
+ * through writer.emit() (Canon Part 9 chokepoint), validated by Canon Part 8.
+ *
+ * Per Canon Part 10 sub-claim 3 ("rooms are receipts, not entry points"): every
+ * room creation IS a receipt of conversation work. This module emits the
+ * trajectory-telemetry counterpart of the room_auto_created memory_event, so
+ * SEED-002 consumers can correlate receipt cadence with engagement quality.
+ *
+ * Non-throwing by contract: validation breaches and disk errors are swallowed
+ * so the Phase 119 receipt-write surface is never blocked by telemetry. The
+ * pipeline must not crash because telemetry storage is unavailable (mirrors
+ * the writer.cjs best-effort silent-swallow policy).
+ *
+ * Hash discipline:
+ *   - room_slug_sha256:     sha256(slug) -- 64-char hex; if slug falsy, sha256('').
+ *   - conversation_id_hash: sha256(conversationId) first 16 chars -- shorter hash
+ *                           (matches schema.cjs MAX_CONTEXT_HASH_LEN convention).
+ *   - generated_at_ts:      ISO-8601 timestamp string (Date.toISOString()).
+ *
+ * Pure CJS, node built-ins only. Zero new runtime deps.
+ */
+'use strict';
+
+const crypto = require('node:crypto');
+const telemetry = require('./telemetry/writer.cjs');
+
+function _sha256(s) {
+  return crypto.createHash('sha256').update(String(s || '')).digest('hex');
+}
+
+/**
+ * emitReceiptWritten(roomSlug, conversationId) -> void
+ *
+ * Best-effort emit of one room_receipt_written event. Falsy arguments are
+ * defensively normalized to empty-string hashes so the Phase 119 wire-in
+ * never blocks on missing scaffolding metadata.
+ *
+ * @param {string|null|undefined} roomSlug      placeholder slug (e.g. 'untitled-2026-05-19-1234')
+ * @param {string|null|undefined} conversationId Phase 119 source_material_id or session id
+ */
+function emitReceiptWritten(roomSlug, conversationId) {
+  try {
+    telemetry.emit('room_receipt_written', {
+      room_slug_sha256: _sha256(roomSlug),
+      conversation_id_hash: _sha256(conversationId).slice(0, 16),
+      generated_at_ts: new Date().toISOString(),
+    });
+  } catch (_e) {
+    // Best-effort. Per Canon Part 9 (memory locality) and the writer's
+    // silent-swallow policy: telemetry MUST NEVER block the surface it
+    // observes. A missing telemetry row is recoverable; a crashed room
+    // creation is not.
+  }
+}
+
+module.exports = { emitReceiptWritten: emitReceiptWritten };

package/lib/core/room-skeleton-scaffold.cjs

@@ -0,0 +1,315 @@
+'use strict';
+/*
+ * Phase 119-02 -- Room skeleton scaffold generator.
+ *
+ * Fills a placeholder room (created by Plan 119-00's autoCreatePlaceholderRoom)
+ * with the canonical 8-section ICM structure + STATE.md + MINTO.md + USER.md +
+ * per-directory ROOM.md identity files (Canon decision 15: ICM Layer 0 everywhere).
+ *
+ * Idempotent + reentrant: never overwrites human-authored content. When STATE.md
+ * already has auto_created:false in its frontmatter (OR the frontmatter lacks the
+ * auto_created key entirely -- treated as human-authored), the regenerable
+ * STATE.md is skipped while the missing identity files are still created
+ * (Canon Part 9 "files preserve meaning" invariant).
+ *
+ * Atomic writes per Phase 124-02 precedent (tmp + rename).
+ *
+ * Canon Part 8 invariant: pure-local; no Brain MCP, no fetch, no telemetry.
+ * Canon Part 9 invariant: no direct room-db.cjs require (this module touches
+ *   only files; memory_event emission stays in Plan 119-00 and Plan 119-01).
+ * Canon Part 10 sub-claim 3: rooms are receipts -- the receipt's substrate
+ *   materializes the instant the auto-explore finding lands, never gated on
+ *   material quality (D-05).
+ * Canon decision 15: every directory in the Data Room MUST have ROOM.md;
+ *   the IDENTITY_DIRECTORIES table covers the 5 non-ICM cases.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const TEMPLATES_DIR = path.resolve(__dirname, '..', '..', 'templates', 'room-skeleton');
+
+/**
+ * The 8 ICM sections. Lookup table extracted from commands/new-project.md
+ * Section Definitions. Single source of truth here; renames cascade.
+ */
+const SECTION_NAMES = Object.freeze([
+  'problem-definition',
+  'market-analysis',
+  'solution-design',
+  'business-model',
+  'competitive-analysis',
+  'team-execution',
+  'legal-ip',
+  'financial-model',
+]);
+
+const SECTION_METADATA = Object.freeze({
+  'problem-definition':   { purpose: 'Define the core problem this venture addresses.',         stage_relevance: ['Pre-Opportunity', 'Discovery'],   default_methodologies: ['domain-explorer', 'beautiful-question', 'trending-to-absurd'] },
+  'market-analysis':      { purpose: 'Map market size, trends, and customer segments.',         stage_relevance: ['Discovery', 'Validation'],        default_methodologies: ['domain-explorer', 'scenario-analysis'] },
+  'solution-design':      { purpose: 'Design the solution, technology, and architecture.',      stage_relevance: ['Validation', 'Design'],           default_methodologies: ['structure-argument', 'think-hats'] },
+  'business-model':       { purpose: 'Define revenue model, unit economics, go-to-market.',     stage_relevance: ['Design', 'Investment'],           default_methodologies: ['structure-argument', 'scenario-analysis'] },
+  'competitive-analysis': { purpose: 'Analyze competition, positioning, differentiation.',      stage_relevance: ['Discovery', 'Design'],            default_methodologies: ['challenge-assumptions', 'find-bottlenecks'] },
+  'team-execution':       { purpose: 'Document team, advisors, and execution plan.',            stage_relevance: ['Validation', 'Design'],           default_methodologies: ['think-hats', 'analyze-needs'] },
+  'legal-ip':             { purpose: 'Track legal structure, agreements, IP protection.',       stage_relevance: ['Design', 'Investment'],           default_methodologies: ['structure-argument'] },
+  'financial-model':      { purpose: 'Build financial projections and metrics.',                stage_relevance: ['Design', 'Investment'],           default_methodologies: ['scenario-analysis', 'build-thesis'] },
+});
+
+/**
+ * Non-ICM directories that still need ROOM.md per Canon decision 15.
+ */
+const IDENTITY_DIRECTORIES = Object.freeze({
+  'team':         { directory_type: 'team',          purpose: 'The people layer of the Data Room. Members, mentors, advisors -- created on demand from meetings or user input.' },
+  'assets':       { directory_type: 'assets',        purpose: 'Binary file storage (PDFs, images, videos) organized by section. Subdirectories appear when scripts/file-asset is invoked.' },
+  '.intelligence':{ directory_type: '.intelligence', purpose: 'Sentinel-generated alerts and digests (health checks, deadline reports, competitor watch).' },
+  '.snapshots':   { directory_type: '.snapshots',    purpose: 'Weekly STATE.md copies for drift detection by sentinel-health-check.' },
+  '.context':     { directory_type: '.context',      purpose: 'Per-session conversational state (last-session, rejection-log, methodology-history, weekly-digest).' },
+});
+
+/**
+ * Render a template with {{KEY}} string substitutions. Pure function.
+ *
+ * @param {string} templateContent  the raw template file contents
+ * @param {object} substitutions    map of KEY -> value (any type coerced via String())
+ * @returns {string}                the substituted output
+ */
+function renderTemplate(templateContent, substitutions) {
+  let rendered = templateContent;
+  for (const key of Object.keys(substitutions || {})) {
+    const re = new RegExp('\\{\\{' + key + '\\}\\}', 'g');
+    rendered = rendered.replace(re, String(substitutions[key]));
+  }
+  return rendered;
+}
+
+/**
+ * Atomic write: tmp + rename. Returns true on success, false on failure.
+ * Mirrors Phase 124-02 timeline-runner.cjs invariant. The tmp file path
+ * includes pid + random suffix so concurrent invocations do not collide.
+ */
+function atomicWrite(filePath, content) {
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o755 });
+    const tmpPath = filePath + '.tmp.' + process.pid + '.' + Math.random().toString(36).slice(2, 10);
+    fs.writeFileSync(tmpPath, content, 'utf8');
+    fs.renameSync(tmpPath, filePath);
+    return true;
+  } catch (_e) {
+    return false;
+  }
+}
+
+function readTemplate(name) {
+  try {
+    return fs.readFileSync(path.join(TEMPLATES_DIR, name), 'utf8');
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * Detect whether STATE.md has been authored by a human (or by a non-Phase-119
+ * source). Returns true if the file:
+ *   - Exists AND
+ *   - Has frontmatter AND
+ *   - Frontmatter contains `auto_created: false` OR lacks the `auto_created` key.
+ *
+ * Returns false if STATE.md doesn't exist OR has `auto_created: true` (the
+ * Phase 119 auto-scaffold signal).
+ */
+function isStateAuthored(roomDir) {
+  try {
+    const statePath = path.join(roomDir, 'STATE.md');
+    if (!fs.existsSync(statePath)) return false;
+    const raw = fs.readFileSync(statePath, 'utf8');
+    const m = raw.match(/^---\n([\s\S]*?)\n---/);
+    if (!m) return false;
+    // If frontmatter has auto_created: false, treat as authored.
+    if (/^\s*auto_created:\s*false\s*$/m.test(m[1])) return true;
+    // If frontmatter LACKS auto_created entirely, treat as authored (human
+    // crafted from scratch -- the absence of the key is the signal).
+    if (!/^\s*auto_created:\s*/m.test(m[1])) return true;
+    return false;
+  } catch (_e) {
+    return false;
+  }
+}
+
+/**
+ * scaffoldRoomSkeleton(roomDir, opts) -- the entry point.
+ *
+ * Fills a placeholder room with the canonical skeleton: STATE.md + MINTO.md +
+ * USER.md + 8 ICM section folders (each with ROOM.md) + 5 identity directories
+ * (each with ROOM.md per Canon decision 15).
+ *
+ * Idempotent. Reentrancy invariant: existing files are NEVER overwritten;
+ * human-authored STATE.md is byte-preserved.
+ *
+ * @param {string} roomDir                    absolute path to the placeholder room
+ * @param {object} opts
+ * @param {string} [opts.placeholder_slug]    e.g. 'untitled-2026-05-16-1845'
+ * @param {string} [opts.source_material_id]  32-char hex from Phase 117
+ * @param {object} [opts.auto_explore_finding]  the Phase 117 JSON output (used
+ *                                              for the thinness pass-through)
+ * @returns {{ok: boolean,
+ *            sections_created: string[],
+ *            identity_files_created: string[],
+ *            state_written: boolean,
+ *            minto_written: boolean,
+ *            user_written: boolean,
+ *            thinness_acknowledged: boolean,
+ *            errors: string[]}}
+ */
+function scaffoldRoomSkeleton(roomDir, opts) {
+  const options = opts || {};
+  const result = {
+    ok: true,
+    sections_created: [],
+    identity_files_created: [],
+    state_written: false,
+    minto_written: false,
+    user_written: false,
+    thinness_acknowledged: false,
+    errors: [],
+  };
+
+  if (!roomDir || typeof roomDir !== 'string') {
+    result.ok = false;
+    result.errors.push('invalid_room_dir');
+    return result;
+  }
+  if (!fs.existsSync(roomDir)) {
+    result.ok = false;
+    result.errors.push('room_dir_does_not_exist');
+    return result;
+  }
+
+  // Substitutions used across templates.
+  const subs = {
+    AUTO_CREATED_AT_ISO: new Date().toISOString(),
+    PLACEHOLDER_SLUG: options.placeholder_slug || path.basename(roomDir),
+    SOURCE_MATERIAL_ID: options.source_material_id || 'unknown',
+  };
+
+  const authored = isStateAuthored(roomDir);
+
+  // Render STATE.md (skip if authored by human).
+  if (!authored) {
+    const stateTpl = readTemplate('STATE.md.tmpl');
+    if (stateTpl) {
+      const stateContent = renderTemplate(stateTpl, subs);
+      if (atomicWrite(path.join(roomDir, 'STATE.md'), stateContent)) {
+        result.state_written = true;
+      } else {
+        result.errors.push('state_write_failed');
+      }
+    } else {
+      result.errors.push('state_template_missing');
+    }
+  } else {
+    process.stderr.write('[room-skeleton] STATE.md already authored; skipping\n');
+  }
+
+  // Render MINTO.md (skip if file exists -- the sentinel-bounded content is the contract).
+  const mintoPath = path.join(roomDir, 'MINTO.md');
+  if (!fs.existsSync(mintoPath)) {
+    const mintoTpl = readTemplate('MINTO.md.tmpl');
+    if (mintoTpl) {
+      if (atomicWrite(mintoPath, mintoTpl)) {
+        result.minto_written = true;
+      } else {
+        result.errors.push('minto_write_failed');
+      }
+    } else {
+      result.errors.push('minto_template_missing');
+    }
+  }
+
+  // Render USER.md (skip if exists).
+  const userPath = path.join(roomDir, 'USER.md');
+  if (!fs.existsSync(userPath)) {
+    const userTpl = readTemplate('USER.md.tmpl');
+    if (userTpl) {
+      if (atomicWrite(userPath, userTpl)) {
+        result.user_written = true;
+      } else {
+        result.errors.push('user_write_failed');
+      }
+    } else {
+      result.errors.push('user_template_missing');
+    }
+  }
+
+  // 8 ICM sections with per-section ROOM.md.
+  const sectionTpl = readTemplate('ROOM.md.section.tmpl');
+  if (sectionTpl) {
+    for (const section of SECTION_NAMES) {
+      const sectionDir = path.join(roomDir, section);
+      const sectionRoomMd = path.join(sectionDir, 'ROOM.md');
+      if (!fs.existsSync(sectionRoomMd)) {
+        const meta = SECTION_METADATA[section];
+        const titleCase = section.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+        const sectionSubs = {
+          SECTION_NAME: section,
+          SECTION_NAME_TITLE_CASE: titleCase,
+          SECTION_PURPOSE: meta.purpose,
+          STAGE_RELEVANCE_LIST: meta.stage_relevance.map(s => '  - ' + s).join('\n'),
+          DEFAULT_METHODOLOGIES_LIST: meta.default_methodologies.map(m => '  - ' + m).join('\n'),
+        };
+        const sectionContent = renderTemplate(sectionTpl, sectionSubs);
+        if (atomicWrite(sectionRoomMd, sectionContent)) {
+          result.sections_created.push(section);
+        } else {
+          result.errors.push('section_write_failed:' + section);
+        }
+      }
+    }
+  } else {
+    result.errors.push('section_template_missing');
+  }
+
+  // Non-ICM identity directories with ROOM.md (Canon decision 15).
+  const identityTpl = readTemplate('ROOM.md.identity.tmpl');
+  if (identityTpl) {
+    for (const dirName of Object.keys(IDENTITY_DIRECTORIES)) {
+      const dirPath = path.join(roomDir, dirName);
+      const identityRoomMd = path.join(dirPath, 'ROOM.md');
+      if (!fs.existsSync(identityRoomMd)) {
+        const meta = IDENTITY_DIRECTORIES[dirName];
+        const identitySubs = {
+          DIRECTORY_TYPE: meta.directory_type,
+          DIRECTORY_PURPOSE: meta.purpose,
+        };
+        const identityContent = renderTemplate(identityTpl, identitySubs);
+        if (atomicWrite(identityRoomMd, identityContent)) {
+          result.identity_files_created.push(dirName);
+        }
+      }
+    }
+  } else {
+    result.errors.push('identity_template_missing');
+  }
+
+  // Thinness pass-through (Plan 119-01 reads result.thinness_acknowledged
+  // to decide whether to render the Larry voice line at F.1 selector time).
+  try {
+    const tha = require('./larry-thinness-acknowledgment.cjs');
+    result.thinness_acknowledged = tha.shouldAcknowledgeThinness(options.auto_explore_finding || null);
+  } catch (_e) {
+    result.thinness_acknowledged = true; // fail-safe: default to acknowledging thinness
+  }
+
+  // ok is true if no errors OR if at least the regenerable surface (state or
+  // sections) made it through. Errors are still recorded for observability.
+  result.ok = result.errors.length === 0;
+  return result;
+}
+
+module.exports = {
+  SECTION_NAMES: SECTION_NAMES,
+  SECTION_METADATA: SECTION_METADATA,
+  IDENTITY_DIRECTORIES: IDENTITY_DIRECTORIES,
+  scaffoldRoomSkeleton: scaffoldRoomSkeleton,
+  renderTemplate: renderTemplate,
+  isStateAuthored: isStateAuthored,
+};

package/lib/core/room-skeleton-scaffold.test.cjs

@@ -0,0 +1,291 @@
+'use strict';
+/*
+ * Phase 119-02 Task 2 -- test suite for room-skeleton-scaffold.cjs.
+ *
+ * Verifies the 14 behaviors from
+ * .planning/phases/119-room-as-receipt-invariant/119-02-PLAN.md Task 2.
+ *
+ * Each test uses an isolated tmp roomDir via os.tmpdir() + crypto-random
+ * suffix; tear-down via fs.rmSync(.., {recursive:true, force:true}).
+ *
+ * Canon Part 8 invariant: zero Brain MCP coupling (Test 12).
+ * Canon Part 9 invariant: zero room-db.cjs require (Test 13 -- this module
+ *   writes files only; memory_event emission stays in Plan 119-00 + 119-01).
+ * Em-dash HARD RULE: zero `--` chars in source (Test 14).
+ */
+
+const assert = require('node:assert');
+const test = require('node:test');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const {
+  scaffoldRoomSkeleton,
+  SECTION_NAMES,
+  SECTION_METADATA,
+  IDENTITY_DIRECTORIES,
+  renderTemplate,
+  isStateAuthored,
+} = require('./room-skeleton-scaffold.cjs');
+
+const PROJECT_ROOT = path.resolve(__dirname, '..', '..');
+
+function makeTmpRoom() {
+  const dir = path.join(os.tmpdir(), 'phase119-02-' + crypto.randomBytes(4).toString('hex'));
+  fs.mkdirSync(dir, { recursive: true });
+  fs.mkdirSync(path.join(dir, '.mindrian'), { recursive: true });
+  // Mark as placeholder room (matches Plan 119-00 contract).
+  fs.writeFileSync(path.join(dir, '.room-root'), '');
+  return dir;
+}
+
+function rmTmp(dir) {
+  try { fs.rmSync(dir, { recursive: true, force: true }); } catch (_e) { /* ignore */ }
+}
+
+test('Test 1: 8 ICM sections present after scaffolding', () => {
+  const roomDir = makeTmpRoom();
+  try {
+    const r = scaffoldRoomSkeleton(roomDir, {});
+    assert.strictEqual(r.ok, true, 'scaffold did not return ok');
+    const expectedSections = [
+      'problem-definition', 'market-analysis', 'solution-design', 'business-model',
+      'competitive-analysis', 'team-execution', 'legal-ip', 'financial-model',
+    ];
+    for (const section of expectedSections) {
+      const sectionDir = path.join(roomDir, section);
+      const roomMd = path.join(sectionDir, 'ROOM.md');
+      assert.ok(fs.existsSync(sectionDir), `missing section dir: ${section}`);
+      assert.ok(fs.existsSync(roomMd), `missing ROOM.md in ${section}/`);
+    }
+  } finally { rmTmp(roomDir); }
+});
+
+test('Test 2: non-ICM identity directories present with ROOM.md (Canon decision 15)', () => {
+  const roomDir = makeTmpRoom();
+  try {
+    scaffoldRoomSkeleton(roomDir, {});
+    const identityDirs = ['team', 'assets', '.intelligence', '.snapshots', '.context'];
+    for (const d of identityDirs) {
+      const dirPath = path.join(roomDir, d);
+      const roomMd = path.join(dirPath, 'ROOM.md');
+      assert.ok(fs.existsSync(dirPath), `missing identity dir: ${d}`);
+      assert.ok(fs.existsSync(roomMd), `missing ROOM.md in ${d}/`);
+    }
+  } finally { rmTmp(roomDir); }
+});
+
+test('Test 3: STATE.md rendered with substitutions', () => {
+  const roomDir = makeTmpRoom();
+  try {
+    scaffoldRoomSkeleton(roomDir, {
+      placeholder_slug: 'untitled-test-slug',
+      source_material_id: 'deadbeefcafef00d',
+    });
+    const state = fs.readFileSync(path.join(roomDir, 'STATE.md'), 'utf8');
+    assert.match(state, /phase: scoping/, 'phase scoping not rendered');
+    assert.match(state, /journey_stage: ordinary-world/, 'journey_stage not rendered');
+    assert.match(state, /placeholder_slug: 'untitled-test-slug'/, 'placeholder_slug substitution failed');
+    assert.match(state, /source_material_id: 'deadbeefcafef00d'/, 'source_material_id substitution failed');
+  } finally { rmTmp(roomDir); }
+});
+
+test('Test 4: MINTO.md is sentinel-bounded', () => {
+  const roomDir = makeTmpRoom();
+  try {
+    scaffoldRoomSkeleton(roomDir, {});
+    const minto = fs.readFileSync(path.join(roomDir, 'MINTO.md'), 'utf8');
+    assert.ok(minto.includes('<!-- mos:minto-begin -->'), 'missing minto-begin sentinel');
+    assert.ok(minto.includes('<!-- mos:minto-end -->'), 'missing minto-end sentinel');
+  } finally { rmTmp(roomDir); }
+});
+
+test('Test 5: USER.md present with non-zero size', () => {
+  const roomDir = makeTmpRoom();
+  try {
+    scaffoldRoomSkeleton(roomDir, {});
+    const userPath = path.join(roomDir, 'USER.md');
+    assert.ok(fs.existsSync(userPath), 'USER.md not created');
+    const stat = fs.statSync(userPath);
+    assert.ok(stat.size > 0, 'USER.md is empty');
+  } finally { rmTmp(roomDir); }
+});
+
+test('Test 6: per-section ROOM.md has YAML frontmatter with required fields', () => {
+  const roomDir = makeTmpRoom();
+  try {
+    scaffoldRoomSkeleton(roomDir, {});
+    const content = fs.readFileSync(path.join(roomDir, 'problem-definition', 'ROOM.md'), 'utf8');
+    const m = content.match(/^---\n([\s\S]*?)\n---/);
+    assert.ok(m, 'no frontmatter delimiter');
+    const fm = m[1];
+    assert.match(fm, /section: problem-definition/, 'section field missing');
+    assert.match(fm, /purpose:/, 'purpose field missing');
+    assert.match(fm, /stage_relevance:/, 'stage_relevance missing');
+    assert.match(fm, /default_methodologies:/, 'default_methodologies missing');
+    assert.match(fm, /icm_layer: 0/, 'icm_layer 0 missing');
+    assert.match(fm, /auto_scaffolded: true/, 'auto_scaffolded missing');
+  } finally { rmTmp(roomDir); }
+});
+
+test('Test 7: each of 8 sections has section-matching ROOM.md identity', () => {
+  const roomDir = makeTmpRoom();
+  try {
+    scaffoldRoomSkeleton(roomDir, {});
+    for (const section of SECTION_NAMES) {
+      const content = fs.readFileSync(path.join(roomDir, section, 'ROOM.md'), 'utf8');
+      assert.match(content, new RegExp('section: ' + section), `wrong section identity in ${section}/ROOM.md`);
+    }
+  } finally { rmTmp(roomDir); }
+});
+
+test('Test 8: REENTRANCY -- human-authored STATE.md preserved across re-invocation', () => {
+  const roomDir = makeTmpRoom();
+  try {
+    // Pre-author STATE.md with auto_created: false (human signal).
+    const humanState = '---\nphase: validation\nauto_created: false\nventure_name: my-venture\n---\n\n# Human STATE\n';
+    fs.writeFileSync(path.join(roomDir, 'STATE.md'), humanState);
+    const before = fs.readFileSync(path.join(roomDir, 'STATE.md'), 'utf8');
+
+    // Capture stderr to verify the skip message.
+    const origWrite = process.stderr.write.bind(process.stderr);
+    let stderrCapture = '';
+    process.stderr.write = (chunk) => { stderrCapture += String(chunk); return true; };
+    try {
+      const r = scaffoldRoomSkeleton(roomDir, {});
+      const after = fs.readFileSync(path.join(roomDir, 'STATE.md'), 'utf8');
+      assert.strictEqual(after, before, 'human-authored STATE.md was overwritten');
+      assert.strictEqual(r.state_written, false, 'state_written should be false on skip path');
+      assert.ok(stderrCapture.includes('STATE.md already authored'), 'expected skip message on stderr');
+      // Sections + identity files STILL created (idempotent fill).
+      assert.ok(fs.existsSync(path.join(roomDir, 'problem-definition', 'ROOM.md')), 'sections not filled on re-entry');
+    } finally {
+      process.stderr.write = origWrite;
+    }
+  } finally { rmTmp(roomDir); }
+});
+
+test('Test 9: atomic-write idiom -- tmp file removed on success (no leftover .tmp files)', () => {
+  const roomDir = makeTmpRoom();
+  try {
+    scaffoldRoomSkeleton(roomDir, {});
+    // Walk roomDir; no .tmp.* files should remain.
+    const walk = (dir) => {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      const results = [];
+      for (const e of entries) {
+        const p = path.join(dir, e.name);
+        if (e.isDirectory()) results.push(...walk(p));
+        else results.push(p);
+      }
+      return results;
+    };
+    const files = walk(roomDir);
+    const leftovers = files.filter(f => /\.tmp\./.test(f));
+    assert.strictEqual(leftovers.length, 0, `leftover tmp files: ${leftovers.join(',')}`);
+  } finally { rmTmp(roomDir); }
+});
+
+test('Test 10: return shape has all expected fields', () => {
+  const roomDir = makeTmpRoom();
+  try {
+    const r = scaffoldRoomSkeleton(roomDir, {});
+    assert.ok(Object.prototype.hasOwnProperty.call(r, 'ok'));
+    assert.ok(Object.prototype.hasOwnProperty.call(r, 'sections_created'));
+    assert.ok(Object.prototype.hasOwnProperty.call(r, 'identity_files_created'));
+    assert.ok(Object.prototype.hasOwnProperty.call(r, 'state_written'));
+    assert.ok(Object.prototype.hasOwnProperty.call(r, 'minto_written'));
+    assert.ok(Object.prototype.hasOwnProperty.call(r, 'user_written'));
+    assert.ok(Object.prototype.hasOwnProperty.call(r, 'thinness_acknowledged'));
+    assert.ok(Array.isArray(r.sections_created));
+    assert.ok(Array.isArray(r.identity_files_created));
+    assert.strictEqual(typeof r.state_written, 'boolean');
+    assert.strictEqual(typeof r.minto_written, 'boolean');
+    assert.strictEqual(typeof r.user_written, 'boolean');
+    assert.strictEqual(typeof r.thinness_acknowledged, 'boolean');
+  } finally { rmTmp(roomDir); }
+});
+
+test('Test 11: thinness pass-through -- null finding => thinness_acknowledged true', () => {
+  const roomDir = makeTmpRoom();
+  try {
+    const r = scaffoldRoomSkeleton(roomDir, { auto_explore_finding: null });
+    assert.strictEqual(r.thinness_acknowledged, true);
+  } finally { rmTmp(roomDir); }
+
+  const roomDir2 = makeTmpRoom();
+  try {
+    const substantive = { findings: [{ source_pipeline: 'whitespace', hsi_score: 0.7 }, { source_pipeline: 'cross-domain', hsi_score: 0.6 }] };
+    const r = scaffoldRoomSkeleton(roomDir2, { auto_explore_finding: substantive });
+    assert.strictEqual(r.thinness_acknowledged, false);
+  } finally { rmTmp(roomDir2); }
+});
+
+test('Test 12: no Brain MCP coupling in scaffold module', () => {
+  const src = fs.readFileSync(path.join(PROJECT_ROOT, 'lib', 'core', 'room-skeleton-scaffold.cjs'), 'utf8');
+  assert.ok(!/require\([^)]*brain-client/.test(src), 'brain-client require found');
+  assert.ok(!/fetch\([^)]*brain\.mindrian/.test(src), 'brain.mindrian fetch found');
+});
+
+test('Test 13: no direct room-db.cjs require (Canon Part 9 chokepoint preserved)', () => {
+  const src = fs.readFileSync(path.join(PROJECT_ROOT, 'lib', 'core', 'room-skeleton-scaffold.cjs'), 'utf8');
+  assert.ok(!/require\([^)]*room-db\.cjs/.test(src), 'room-db.cjs require found');
+});
+
+test('Test 14: em-dash invariant -- zero U+2014 in source files', () => {
+  // Construct the em-dash via charCode so this test file itself does not
+  // contain the literal char (which would self-trip the invariant).
+  const EMDASH = String.fromCharCode(0x2014);
+  const sources = [
+    path.join(PROJECT_ROOT, 'lib', 'core', 'room-skeleton-scaffold.cjs'),
+    path.join(PROJECT_ROOT, 'lib', 'core', 'room-skeleton-scaffold.test.cjs'),
+  ];
+  for (const file of sources) {
+    const src = fs.readFileSync(file, 'utf8');
+    assert.ok(!src.includes(EMDASH), 'em-dash U+2014 found in ' + file);
+  }
+});
+
+test('Bonus Test 15: SECTION_NAMES has exactly 8 entries; IDENTITY_DIRECTORIES has exactly 5', () => {
+  assert.strictEqual(SECTION_NAMES.length, 8, 'SECTION_NAMES not 8');
+  assert.strictEqual(Object.keys(IDENTITY_DIRECTORIES).length, 5, 'IDENTITY_DIRECTORIES not 5');
+});
+
+test('Bonus Test 16: renderTemplate substitutes {{KEY}} tokens correctly', () => {
+  const out = renderTemplate('hello {{NAME}}, you are {{ROLE}}.', { NAME: 'Larry', ROLE: 'pedagogical guide' });
+  assert.strictEqual(out, 'hello Larry, you are pedagogical guide.');
+});
+
+test('Bonus Test 17: isStateAuthored detects auto_created:false in frontmatter', () => {
+  const roomDir = makeTmpRoom();
+  try {
+    // auto_created:true => not authored (auto-scaffold output)
+    fs.writeFileSync(path.join(roomDir, 'STATE.md'), '---\nphase: scoping\nauto_created: true\n---\n');
+    assert.strictEqual(isStateAuthored(roomDir), false);
+
+    // auto_created:false => authored (human override)
+    fs.writeFileSync(path.join(roomDir, 'STATE.md'), '---\nphase: validation\nauto_created: false\n---\n');
+    assert.strictEqual(isStateAuthored(roomDir), true);
+
+    // No auto_created key => treat as authored (human authored from scratch)
+    fs.writeFileSync(path.join(roomDir, 'STATE.md'), '---\nphase: validation\n---\n');
+    assert.strictEqual(isStateAuthored(roomDir), true);
+  } finally { rmTmp(roomDir); }
+});
+
+test('Bonus Test 18: invalid roomDir returns ok:false with error', () => {
+  const r = scaffoldRoomSkeleton('/this/path/definitely/does/not/exist/xyzpdq', {});
+  assert.strictEqual(r.ok, false);
+  assert.ok(r.errors.includes('room_dir_does_not_exist'));
+});
+
+test('Bonus Test 19: SECTION_METADATA covers all 8 sections', () => {
+  for (const section of SECTION_NAMES) {
+    assert.ok(SECTION_METADATA[section], `missing metadata for ${section}`);
+    assert.ok(SECTION_METADATA[section].purpose, `missing purpose for ${section}`);
+    assert.ok(Array.isArray(SECTION_METADATA[section].stage_relevance), `stage_relevance not array for ${section}`);
+    assert.ok(Array.isArray(SECTION_METADATA[section].default_methodologies), `default_methodologies not array for ${section}`);
+  }
+});