@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/gen-file-map.js

@@ -0,0 +1,337 @@
+#!/usr/bin/env node
+'use strict';
+// gen-file-map.js — generated file-map sections + freshness gate (task 1276 / ADR 0066).
+//
+// WHY. docs/file-map.md was the LAST self-knowledge doc still hand-maintained on the honor system:
+// repo-map (ADR 0063), the onboarding diagrams, and the session-log index (ADR 0062 §8) are all
+// generated AND fitness-enforced, so an agent can't forget to update them. file-map.md wasn't —
+// so a new skill could (and did, task 1274) ship without a map entry and needed a separate
+// doc-hygiene task to fix. Worse, the two enumerable sections had silently drifted into curated
+// SUBSETS (10+ skills and 11 routines existed on disk but weren't listed at all).
+//
+// THE FIX (ADR 0066). The two sections that are genuinely "list every item" sets — .claude/skills/
+// and .claude/scheduled-tasks/ — are now GENERATED from what is on disk. The per-entry one-line
+// notes (the prose after the ←, which no directory walk can know) live in a sidecar,
+// docs/file-map.notes.json, the ONE place a human writes them. The contract enforced by --check:
+//   • every TRACKED skill/routine dir MUST have a note  → a new skill can't land undescribed;
+//   • every note MUST map to a dir that exists           → the map can't carry ghosts;
+//   • the rendered block MUST match what's committed      → no stale tree.
+// MODULE COVERAGE (task 1004066). The same honor system that let a skill land unmapped let a whole
+// MODULE land unmapped: `modules/agents`, `modules/government` and `modules/specialities` were all
+// on disk with nothing in the map, and the two that got fixed before this got fixed BY HAND — which
+// is the point, since hand-patching a drifting map does not stop the drift. The modules/ block is
+// not generated (each entry is a paragraph of prose no directory walk could write, and generating
+// the fenced repo tree is the expensive option this task ruled out), so what is enforced is the
+// cheap half: a set comparison asserting every directory under modules/ is documented SOMEWHERE in
+// the map — either a `modules/<key>/…` path reference or a `<key>/` entry inside the modules block.
+// A new module now fails --check until someone writes its line.
+//
+// scripts/bongos/ is deliberately NOT generated: it is a curated highlight reel of ~20 of ~70 files
+// (generating it would bloat it with low-signal entries), and it sits mid-tree inside the big
+// fenced repo tree where HTML-comment markers can't live cleanly. It stays hand-curated.
+//
+// Zero-dependency, deterministic (dirs sorted by name; no timestamps) — so `--check` is a clean
+// idempotent CI gate, wired into scripts/bongos/fitness.js (Path C) and auto-regenerated + committed
+// at ship by ship.js (regenerateFileMap), exactly like the repo map + session index.
+//
+// Usage:
+//   node scripts/bongos/gen-file-map.js           # regenerate the generated file-map sections
+//   node scripts/bongos/gen-file-map.js --check     # write nothing; exit 2 if anything WOULD change / a note is missing
+//   node scripts/bongos/gen-file-map.js --json       # print the parsed model as JSON (debug)
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { resolveInstanceRoot } = require('../../src/instance-config'); // ADR 0108 §1: configurable-root
+const { sameContent } = require('./gen-freshness'); // eol-insensitive freshness (CRLF checkouts)
+
+// ADR 0108 §Consequences #4 (configurable-root W6 / task 1886) — every target of this generator is
+// INSTANCE-materialized content: the .claude/skills + .claude/scheduled-tasks it lists (materialized
+// per instance, ADR 0108 §3) and the docs/file-map.md + notes it writes. So it resolves entirely
+// against the instance root. Today that's the single checkout (byte-identical); once the core
+// installs from node_modules it stays the host repo (never node_modules). Do NOT reintroduce a
+// hardcoded `path.resolve(__dirname,'..','..')` here — post-split it would point into the package.
+const REPO_ROOT = resolveInstanceRoot();
+const MAP_PATH = path.join(REPO_ROOT, 'docs', 'file-map.md');
+const NOTES_PATH = path.join(REPO_ROOT, 'docs', 'file-map.notes.json');
+
+// The sections this generator owns. Each is an exhaustive, standalone-fenced listing of the
+// immediate subdirectories of `dir` (one entry per subdir). `notesKey` indexes docs/file-map.notes.json.
+const SECTIONS = [
+  { id: 'skills', dir: '.claude/skills', notesKey: 'skills' },
+  { id: 'scheduled-tasks', dir: '.claude/scheduled-tasks', notesKey: 'scheduled-tasks' },
+];
+
+// modules/ is NOT generated (task 1004066): each entry is a paragraph of prose no directory walk
+// could write, and generating it would force the whole fenced repo tree through a generator —
+// explicitly out of scope. What IS enforceable is COVERAGE: every module on disk must be documented
+// somewhere in the map. That set comparison is the cheap half of the same contract the skills
+// section already carries, and it is what stops a whole vertical slice landing unmapped.
+const MODULES_DIR = 'modules';
+
+const begin = (id) => `<!-- BEGIN GENERATED FILE-MAP ${id} (scripts/bongos/gen-file-map.js — do not hand-edit; notes live in docs/file-map.notes.json) -->`;
+const end = (id) => `<!-- END GENERATED FILE-MAP ${id} -->`;
+
+const PLACEHOLDER = '(no note — add one to docs/file-map.notes.json)';
+
+// macOS Finder / iCloud sync-conflict copies ("foo 2") and hidden dotfiles are never real entries.
+const isConflictCopy = (name) => / \d+$/.test(name);
+
+function loadNotes() {
+  try { return JSON.parse(fs.readFileSync(NOTES_PATH, 'utf8')); } catch { return {}; }
+}
+
+// Module-owned skills materialised INTO this checkout (scripts/bongos/claude-materialize.js
+// --module-skills-only, task 1003330) are untracked copies the module documents itself; they
+// are not repo skills needing a note here. One reader of the manifest exists — the
+// materialiser's — so this asks it rather than parsing the file a second way.
+const { readModuleSkillsManifest } = require('./claude-materialize.js');
+function materializedNames(absDir) { return new Set(Object.keys(readModuleSkillsManifest(absDir).skills)); }
+
+// The subdirs of `relDir` holding at least one TRACKED file (task 1004213). An untracked one is the
+// builder's own — a locally-installed plugin skill, or the empty husk a plugin extract leaves — and
+// listing it would publish one machine's tooling into a shared doc on every post-merge regen.
+// tracked: null when `root` is not the top of a git work tree (a packaged install, ADR 0108 §1).
+// gitError: git COULD not answer (task 1004222) — a safe.directory refusal, git off PATH, a broken
+// GIT_DIR, ENOBUFS. That also falls back to the disk listing, but loudly: main() warns and fails --check.
+const GIT_MAX_BUFFER = 64 * 1024 * 1024;
+// Discovery's own refusal. A broken GIT_DIR also exits 128 "not a git repository: '<dir>'", without this tail.
+const NOT_A_REPO = /not a git repository \(or any (of the )?parent/;
+function trackedSubdirs(root, relDir) {
+  // LC_ALL=C: the refusal is matched by its text, which a translated git would not print.
+  const git = (args) => execFileSync('git', args, {
+    cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: GIT_MAX_BUFFER, env: { ...process.env, LC_ALL: 'C' },
+  });
+  try {
+    if (git(['rev-parse', '--show-prefix']).trim() !== '') return { tracked: null, gitError: null };
+    return {
+      tracked: new Set(git(['ls-files', '-z', '--', relDir]).split('\0')
+        .map((p) => p.slice(relDir.length + 1).split('/'))
+        .filter((segs) => segs.length > 1)
+        .map((segs) => segs[0])),
+      gitError: null,
+    };
+  } catch (err) {
+    const stderr = String(err.stderr || '').trim();
+    if (err.status === 128 && NOT_A_REPO.test(stderr)) return { tracked: null, gitError: null };
+    return { tracked: null, gitError: stderr.split('\n')[0] || err.code || err.message };
+  }
+}
+
+// Immediate subdirectories of an absolute dir, sorted by name (deterministic); materialised
+// module copies excluded.
+function listSubdirs(absDir) {
+  let ents = [];
+  try { ents = fs.readdirSync(absDir, { withFileTypes: true }); } catch { return []; }
+  const materialised = materializedNames(absDir);
+  return ents
+    .filter((e) => e.isDirectory() && !e.name.startsWith('.') && !isConflictCopy(e.name) && !materialised.has(e.name))
+    .map((e) => e.name)
+    .sort((a, b) => a.localeCompare(b));
+}
+
+// Build the model for one section: its entries (name + label + note) plus the two violation
+// classes the freshness contract enforces (a dir with no note; a note with no dir).
+function buildSection(section, notes) {
+  const absDir = path.join(REPO_ROOT, section.dir);
+  const present = listSubdirs(absDir);
+  const { tracked, gitError } = trackedSubdirs(REPO_ROOT, section.dir);
+  const names = tracked ? present.filter((n) => tracked.has(n)) : present;
+  const sectionNotes = (notes && notes[section.notesKey]) || {};
+  const entries = names.map((name) => {
+    // Skills + scheduled-tasks each carry a SKILL.md; label it explicitly when present (matches the
+    // long-standing format), else just the dir.
+    const hasSkillMd = fs.existsSync(path.join(absDir, name, 'SKILL.md'));
+    const label = hasSkillMd ? `${name}/SKILL.md` : `${name}/`;
+    const note = Object.prototype.hasOwnProperty.call(sectionNotes, name) ? sectionNotes[name] : null;
+    return { name, label, note };
+  });
+  const missing = entries.filter((e) => e.note == null).map((e) => `${section.dir}/${e.name}`);
+  // A note is a ghost only when its dir is gone from disk — one not yet `git add`ed is not.
+  const onDisk = new Set(present);
+  const stale = Object.keys(sectionNotes).filter((k) => !onDisk.has(k)).map((k) => `${section.notesKey}.${k}`);
+  return { ...section, absDir, entries, missing, stale, gitError };
+}
+
+function buildModel() {
+  const notes = loadNotes();
+  return SECTIONS.map((s) => buildSection(s, notes));
+}
+
+// ── module coverage (task 1004066) ────────────────────────────────────────────
+// A module counts as documented when the map either references its PATH (`modules/<key>/…`
+// anywhere) or carries a `<key>/` entry line inside the `modules/` tree block. Both forms are in
+// use today, so the check accepts both rather than inventing a third the map would fail on.
+
+// Both matchers CAPTURE the whole path segment rather than testing for a given key. That is what
+// makes the prefix hazard structural instead of something a lookahead has to remember: a mention of
+// `modules/agents-extra` yields the key `agents-extra`, so it can never vouch for `agents`. It also
+// means the map is scanned ONCE per run instead of twice per module.
+const PATH_REF_RE = /modules\/([A-Za-z0-9_.-]+)/g;
+const ENTRY_RE = /[├└]──\s+([A-Za-z0-9_.-]+)\//g;
+
+// The slice of the fenced repo tree between the `├── modules/` header and the next sibling at the
+// same depth. Scoping the entry search here matters: `.claude/skills/` lists dirs in the same
+// `├── name/` shape, so an unscoped match would let a SKILL named after a module vouch for it.
+function modulesBlock(mapText) {
+  const lines = String(mapText).split(/\r?\n/);
+  const start = lines.findIndex((l) => new RegExp(`^[├└]── ${MODULES_DIR}/`).test(l));
+  if (start === -1) return '';
+  let stop = lines.length;
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (/^[├└]── /.test(lines[i])) { stop = i; break; }
+  }
+  return lines.slice(start, stop).join('\n');
+}
+
+// Every module key the map documents: any `modules/<key>` path reference anywhere, plus any
+// `<key>/` entry line inside the modules block. Both forms are in use today, so both count.
+function documentedModuleKeys(mapText, block) {
+  const keys = new Set();
+  for (const m of String(mapText).matchAll(PATH_REF_RE)) keys.add(m[1]);
+  for (const m of String(block).matchAll(ENTRY_RE)) keys.add(m[1]);
+  return keys;
+}
+
+// The single-key form — the readable one to assert against.
+function isModuleDocumented(mapText, block, key) {
+  return documentedModuleKeys(mapText, block).has(key);
+}
+
+// Every immediate subdirectory of modules/, or [] when the tree carries no modules/ at all (a
+// consumer instance that enabled none — nothing to document).
+function listModules() {
+  return listSubdirs(path.join(REPO_ROOT, MODULES_DIR));
+}
+
+// The set comparison. Returns { onDisk, undocumented, defects } — `defects` is the non-vacuity
+// channel: this check breaks by comparing two empty sets and reporting nothing, so a state that
+// makes the comparison meaningless (modules on disk but no readable map, or no modules/ block to
+// read entries out of) is reported as a SCAN DEFECT rather than passing quietly.
+function moduleCoverage(mapText) {
+  const onDisk = listModules();
+  const defects = [];
+  if (!onDisk.length) return { onDisk, undocumented: [], defects };
+  const text = typeof mapText === 'string' ? mapText : (fs.existsSync(MAP_PATH) ? fs.readFileSync(MAP_PATH, 'utf8') : '');
+  if (!text.trim()) {
+    defects.push(`${onDisk.length} module(s) on disk but docs/file-map.md is missing or empty — the module-coverage check cannot run`);
+    return { onDisk, undocumented: [], defects };
+  }
+  const block = modulesBlock(text);
+  if (!block) defects.push('docs/file-map.md has no `modules/` block in its repo tree — module entries cannot be read (path references are still checked)');
+  const documented = documentedModuleKeys(text, block);
+  const undocumented = onDisk.filter((key) => !documented.has(key));
+  return { onDisk, undocumented, defects };
+}
+
+// Render one section's fenced tree block (the bytes that live between its markers). Arrows are
+// column-aligned to the longest label, matching the hand-formatted look of the rest of the map.
+function renderSection(model) {
+  const labelWidth = model.entries.reduce((m, e) => Math.max(m, e.label.length), 0);
+  const L = [];
+  L.push(begin(model.dir + '/'));
+  L.push('```');
+  L.push(`${model.dir}/`);
+  model.entries.forEach((e, i) => {
+    const connector = i === model.entries.length - 1 ? '└──' : '├──';
+    const pad = ' '.repeat(labelWidth - e.label.length);
+    L.push(`${connector} ${e.label}${pad}  ← ${e.note == null ? PLACEHOLDER : e.note}`);
+  });
+  L.push('```');
+  L.push(end(model.dir + '/'));
+  return L.join('\n');
+}
+
+// Replace the marked region for one section in file-map.md (mirrors gen-session-index.injectSnippet).
+function injectSection(existing, model) {
+  const B = begin(model.dir + '/');
+  const E = end(model.dir + '/');
+  const b = existing.indexOf(B);
+  const e = existing.indexOf(E);
+  const block = renderSection(model);
+  if (b !== -1 && e !== -1 && e > b) {
+    return existing.slice(0, b) + block + existing.slice(e + E.length);
+  }
+  return existing; // markers absent → leave untouched (file-map.md seeds them once)
+}
+
+function computeWrites() {
+  const model = buildModel();
+  const missing = model.flatMap((m) => m.missing);
+  const stale = model.flatMap((m) => m.stale);
+  const gitErrors = [...new Set(model.map((m) => m.gitError).filter(Boolean))];
+  const writes = [];
+  let markersMissing = [];
+  let mapText = '';
+  if (fs.existsSync(MAP_PATH)) {
+    let cur = fs.readFileSync(MAP_PATH, 'utf8');
+    let next = cur;
+    for (const m of model) {
+      if (next.indexOf(begin(m.dir + '/')) === -1) { markersMissing.push(m.dir); continue; }
+      next = injectSection(next, m);
+    }
+    if (!sameContent(next, cur)) writes.push({ full: MAP_PATH, content: next, rel: 'docs/file-map.md' });
+    mapText = next; // coverage reads the POST-generation text, so a regen never changes the verdict
+  }
+  const modules = moduleCoverage(mapText);
+  return { model, writes, missing, stale, gitErrors, markersMissing, modules };
+}
+
+function main() {
+  const checkOnly = process.argv.includes('--check');
+  if (process.argv.includes('--json')) {
+    process.stdout.write(JSON.stringify(buildModel(), null, 2) + '\n');
+    return;
+  }
+  const { writes, missing, stale, gitErrors, markersMissing, modules } = computeWrites();
+
+  // A missing note (dir without a note) or a stale note (note without a dir) is a hard failure in
+  // BOTH modes: in --check it fails CI; in write mode we still report it (and render a visible
+  // placeholder) so the author sees exactly what to add. Markers absent is a one-time setup issue.
+  const problems = [];
+  if (missing.length) problems.push(`notes MISSING for: ${missing.join(', ')} — add a one-line note to docs/file-map.notes.json`);
+  if (stale.length) problems.push(`notes are STALE (no such dir) — remove from docs/file-map.notes.json: ${stale.join(', ')}`);
+  for (const e of gitErrors) problems.push(`git could not list tracked files (${e}) — every dir on disk was listed, untracked plugin installs included; fix git (PATH, safe.directory) and re-run (task 1004222)`);
+  if (markersMissing.length) problems.push(`docs/file-map.md is missing generated markers for: ${markersMissing.join(', ')}`);
+  if (modules.undocumented.length) problems.push(`modules with NO docs/file-map.md entry: ${modules.undocumented.map((k) => `${MODULES_DIR}/${k}`).join(', ')} — add an entry to the modules/ block of docs/file-map.md (task 1004066)`);
+  for (const d of modules.defects) problems.push(`module-coverage SCAN DEFECT — ${d}`);
+
+  if (checkOnly) {
+    if (writes.length || problems.length) {
+      if (writes.length) console.error(`gen-file-map --check: STALE — would update ${writes.map((w) => w.rel).join(', ')}`);
+      for (const p of problems) console.error(`gen-file-map --check: ${p}`);
+      console.error('  run: node scripts/bongos/gen-file-map.js  (and commit)');
+      process.exit(2);
+    }
+    console.log('gen-file-map --check: up to date.');
+    return;
+  }
+
+  for (const w of writes) fs.writeFileSync(w.full, w.content);
+  if (writes.length) console.log(`gen-file-map: wrote ${writes.length} file(s): ${writes.map((w) => w.rel).join(', ')}`);
+  else console.log('gen-file-map: file-map sections already current — no changes.');
+  for (const p of problems) console.error(`gen-file-map: WARN ${p}`);
+  // Non-zero so a write-mode run that left placeholders (missing notes) is visible to a caller that
+  // checks status, but ONLY for genuine note problems — a clean no-op stays exit 0.
+  if (problems.length) process.exitCode = 2;
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  materializedNames,
+  SECTIONS,
+  MODULES_DIR,
+  listModules,
+  modulesBlock,
+  documentedModuleKeys,
+  isModuleDocumented,
+  moduleCoverage,
+  begin,
+  end,
+  buildModel,
+  buildSection,
+  renderSection,
+  injectSection,
+  computeWrites,
+};

package/scripts/bongos/gen-freshness.js

@@ -0,0 +1,32 @@
+// gen-freshness.js — how the doc generators decide "is the committed copy stale?"
+//
+// Shared by gen-repo-map / gen-session-index / gen-file-map / gen-api-docs, whose
+// `--check` / `--check-block` modes back the fitness.js `generated artifacts fresh`
+// hard gate.
+//
+// Why this exists: the generators render their blocks with `join('\n')` — always
+// LF — but read the working copy with readFileSync, which on a `core.autocrlf=true`
+// checkout (every default Windows clone) returns CRLF. A byte-wise `next !== cur`
+// then reports STALE forever, and regenerating never clears it: the write lands as
+// LF, git normalizes it back to CRLF on the next checkout, and the gate is red
+// again. That is worse than noisy — a permanently-failing hard gate trains builders
+// to ignore it, and it hides REAL drift, since the check is red either way.
+//
+// Freshness is a question about content, so compare content. Written bytes are
+// unaffected: callers still write exactly the string they built, and git applies
+// its own eol policy on commit.
+'use strict';
+
+// CRLF → LF. Lone-CR (classic Mac) is not normalized; no generator emits it and
+// no checkout policy produces it, so treating it as content keeps this honest.
+function normalizeEol(s) {
+  return String(s == null ? '' : s).replace(/\r\n/g, '\n');
+}
+
+// True when two documents are identical apart from line-ending convention.
+// Use this for every freshness comparison — never `===` on raw file bytes.
+function sameContent(a, b) {
+  return normalizeEol(a) === normalizeEol(b);
+}
+
+module.exports = { normalizeEol, sameContent };

package/scripts/bongos/gen-interaction-posture.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+'use strict';
+// gen-interaction-posture.js — the CLAUDE.md §2 communication posture, generated
+// (task 1002515; clauses 2/3/7 of criterion `accessibility-fluency-profile`).
+//
+// WHY. Until this generator, the posture existed TWICE: as hand-written prose in the
+// always-loaded root CLAUDE.md §2, and as the injectable contract fragments in
+// modules/builder-settings/interaction-prefs.js. Two copies of one rule is a drift
+// machine — task 1002514 changed the knob's defaults and §2 did not move, which is
+// exactly the failure clause 2 of the criterion names. Prose that a human keeps in
+// sync with code is prose that will eventually lie.
+//
+// THE FIX, and why a generator rather than a deletion. The obvious move is to delete
+// §2's prose and let the injected profile carry everything. It cannot: the injector
+// (.claude/hooks/conductor.js) relays a profile resolved SERVER-SIDE, so a session
+// with no Bongos session — a fresh clone, an offline checkout, a box that cannot
+// reach the API — receives NOTHING, and deleting the prose would leave exactly the
+// reader the criterion is about with no posture at all. So §2 keeps a fallback, and
+// the fallback is GENERATED from the knob's own defaults: one source of truth, a
+// bounded copy in the kernel, and a CI gate (scripts/bongos/fitness.js) that fails the
+// build the moment they disagree.
+//
+// The emitted text is the contract fragments VERBATIM — the same strings a session
+// is handed. Nothing is paraphrased here, because a paraphrase is a second copy
+// wearing a generator's clothes.
+//
+// Zero-dependency and deterministic (no timestamps, no disk scan) — so `--check` is a
+// clean idempotent CI gate, the gen-session-index.js / gen-repo-map.js pattern
+// (ADR 0062 §8, ADR 0063).
+//
+// Usage:
+//   node scripts/bongos/gen-interaction-posture.js          # rewrite the CLAUDE.md §2 block
+//   node scripts/bongos/gen-interaction-posture.js --check   # write nothing; exit 2 if the block would change
+//   node scripts/bongos/gen-interaction-posture.js --print   # print the rendered block (debug)
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { resolveInstanceRoot } = require('../../src/instance-config'); // ADR 0108 §1: configurable-root
+const { sameContent } = require('./gen-freshness'); // eol-insensitive freshness (CRLF checkouts)
+
+// The SOURCE is core content (the knob ships with Cloud Bongos); the TARGET is the
+// INSTANCE's own always-loaded kernel. Requiring the lib relative to __dirname keeps
+// the source pinned to the core even on a standalone instance where the core lives in
+// node_modules/@bongos/core, while resolveInstanceRoot() puts the block in the host's
+// CLAUDE.md rather than the vendored core's (the task-1002314 trap).
+const prefs = require('../../modules/builder-settings/interaction-prefs.js');
+
+const CLAUDE_PATH = path.join(resolveInstanceRoot(), 'CLAUDE.md');
+
+const BEGIN = '<!-- BEGIN GENERATED INTERACTION POSTURE (scripts/bongos/gen-interaction-posture.js — do not hand-edit) -->';
+const END = '<!-- END GENERATED INTERACTION POSTURE -->';
+
+// The fallback posture = every DEFAULT field value's contract fragment, verbatim.
+// A field whose default carries no fragment contributes nothing — the same rule
+// contractFor() applies, so the block can never claim a posture a session is not
+// actually given (today that exemption is `machinery: show`, which means "behave as
+// you otherwise would" and so has no text to state).
+function renderBlock() {
+  const eff = prefs.effectiveProfile({});
+  const bullets = [];
+  for (const field of prefs.FIELD_KEYS) {
+    const fragment = prefs.FIELDS[field].values[eff[field]].contract;
+    if (fragment) bullets.push(`> - ${fragment}`);
+  }
+  return [
+    BEGIN,
+    '**When no profile is injected** (no Bongos session — a fresh clone, an offline checkout), fall back to the knob’s own defaults. Generated from [`modules/builder-settings/interaction-prefs.js`](modules/builder-settings/interaction-prefs.js), so this can never drift from what a session is actually handed:',
+    '',
+    ...bullets,
+    END,
+  ].join('\n');
+}
+
+// Splice the block between its markers. Markers ABSENT → leave the file untouched and
+// say so: an instance whose CLAUDE.md predates this generator (or one that deliberately
+// authored its own §2) must not have a block injected into it at an arbitrary offset.
+function injectBlock(existing, block) {
+  const b = existing.indexOf(BEGIN);
+  const e = existing.indexOf(END);
+  if (b === -1 || e === -1 || e < b) return existing;
+  return existing.slice(0, b) + block + existing.slice(e + END.length);
+}
+
+function computeWrite() {
+  if (!fs.existsSync(CLAUDE_PATH)) return null;
+  const current = fs.readFileSync(CLAUDE_PATH, 'utf8');
+  if (current.indexOf(BEGIN) === -1) return { missingMarkers: true };
+  const next = injectBlock(current, renderBlock());
+  if (sameContent(current, next)) return null;
+  return { full: CLAUDE_PATH, content: next, rel: 'CLAUDE.md' };
+}
+
+function main() {
+  if (process.argv.includes('--print')) {
+    process.stdout.write(renderBlock() + '\n');
+    return;
+  }
+  const write = computeWrite();
+  if (write && write.missingMarkers) {
+    console.error('gen-interaction-posture: WARN CLAUDE.md has no posture markers — skipping injection.');
+    return;
+  }
+  if (process.argv.includes('--check')) {
+    if (write) {
+      console.error('gen-interaction-posture --check: STALE — would update CLAUDE.md');
+      console.error('  run: node scripts/bongos/gen-interaction-posture.js  (and commit CLAUDE.md)');
+      process.exit(2);
+    }
+    console.log('gen-interaction-posture --check: up to date.');
+    return;
+  }
+  if (!write) {
+    console.log('gen-interaction-posture: CLAUDE.md posture block already current — no changes.');
+    return;
+  }
+  fs.writeFileSync(write.full, write.content);
+  console.log('gen-interaction-posture: wrote CLAUDE.md');
+}
+
+if (require.main === module) main();
+
+module.exports = { renderBlock, injectBlock, computeWrite, BEGIN, END };