@bongos/core 1.17.0

package/tests/eviction_policy.mjs

@@ -0,0 +1,279 @@
+// tests/eviction_policy.mjs — System 2 (task 1348). Hermetic, DB-free, no I/O:
+// synthetic transcripts in, eviction set + stubs out. Mirrors the pin-the-pure-
+// core approach of tests/context_pack.mjs. Run: node tests/eviction_policy.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const { classifyEviction, estTokens, blockText, stubFor, normalize, readRange, isVolatileBash, salientTokens } = require('../.claude/hooks/eviction-policy.js');
+
+let passed = 0, failed = 0;
+function test(name, fn) {
+  try { fn(); console.log(`  ok  ${name}`); passed++; }
+  catch (err) { console.error(`  FAIL ${name}`); console.error('    ', err.message); failed++; }
+}
+
+// transcript builders
+const user = (blocks) => ({ message: { role: 'user', content: blocks } });
+const asst = (blocks) => ({ message: { role: 'assistant', content: blocks } });
+const tuse = (id, name, input) => ({ type: 'tool_use', id, name, input });
+const tres = (id, content) => ({ type: 'tool_result', tool_use_id: id, content });
+const txt = (t) => ({ type: 'text', text: t });
+const big = (label) => Array.from({ length: 60 }, (_, i) => `${label} line ${i} ${'x'.repeat(20)}`).join('\n');
+
+const NO_RECENCY = { recencyTurns: 0 };
+const evictIds = (out) => out.evict.map((e) => e.tool_use_id);
+
+test('supersession: a Read whose file is later Edited is evicted (reason=superseded)', () => {
+  const out = classifyEviction([
+    user([txt('do it')]),
+    asst([tuse('r1', 'Read', { file_path: 'src/a.js' })]),
+    user([tres('r1', 'old contents of a.js')]),
+    asst([tuse('e1', 'Edit', { file_path: 'src/a.js' })]),
+    user([tres('e1', 'edit applied')]),
+    asst([txt('done')]),
+  ], NO_RECENCY);
+  assert.deepEqual(evictIds(out), ['r1']);
+  assert.equal(out.evict[0].reason, 'superseded');
+  assert.match(out.stubs.r1, /evicted/);
+  assert.match(out.stubs.r1, /src\/a\.js/);
+});
+
+test('duplicate: an older Read is evicted, the newest Read of the same file is kept', () => {
+  const out = classifyEviction([
+    asst([tuse('r1', 'Read', { file_path: 'src/b.js' })]),
+    user([tres('r1', 'b.js v1')]),
+    asst([tuse('r2', 'Read', { file_path: 'src/b.js' })]),
+    user([tres('r2', 'b.js v2')]),
+  ], NO_RECENCY);
+  assert.deepEqual(evictIds(out), ['r1']);
+  assert.equal(out.evict[0].reason, 'duplicate');
+});
+
+test('stale_dump: a big old Grep dump not cited later is evicted', () => {
+  const out = classifyEviction([
+    asst([tuse('g1', 'Grep', { pattern: 'foo' })]),
+    user([tres('g1', big('grep'))]),
+    asst([txt('moving on, unrelated')]),
+  ], { recencyTurns: 0, dumpMinTokens: 5 });
+  assert.deepEqual(evictIds(out), ['g1']);
+  assert.equal(out.evict[0].reason, 'stale_dump');
+});
+
+test('1350: an evicted dump stub carries a one-step /recall query (recovery affordance)', () => {
+  const out = classifyEviction([
+    asst([tuse('g1', 'Grep', { pattern: 'requireRank' })]),
+    user([tres('g1', big('grep'))]),
+    asst([txt('moving on')]),
+  ], { recencyTurns: 0, dumpMinTokens: 5 });
+  assert.deepEqual(evictIds(out), ['g1']);
+  assert.match(out.stubs.g1, /\/recall "requireRank" or re-run Grep/);
+});
+
+test('liveness: a dump whose line is quoted by a LATER assistant turn is kept', () => {
+  const dump = big('grep');
+  const anchor = dump.split('\n')[3]; // a ≥40-char line
+  const out = classifyEviction([
+    asst([tuse('g1', 'Grep', { pattern: 'foo' })]),
+    user([tres('g1', dump)]),
+    asst([txt(`as seen above: ${anchor}`)]),
+  ], { recencyTurns: 0, dumpMinTokens: 5, livenessAnchorChars: 20 });
+  assert.deepEqual(evictIds(out), [], 'cited dump must be kept (backward-ref liveness)');
+});
+
+test('recency: a stale read inside the last N turns is never evicted', () => {
+  const out = classifyEviction([
+    asst([tuse('r1', 'Read', { file_path: 'src/c.js' })]),
+    user([tres('r1', 'c.js')]),
+    asst([tuse('e1', 'Edit', { file_path: 'src/c.js' })]),
+    user([tres('e1', 'ok')]),
+  ], { recencyTurns: 12 }); // only 4 turns → all within recency
+  assert.deepEqual(evictIds(out), []);
+});
+
+test('never-evict: a tool_result carrying context-pack/worktree markers is kept', () => {
+  const out = classifyEviction([
+    asst([tuse('r1', 'Read', { file_path: 'src/d.js' })]),
+    user([tres('r1', 'your context-pack: worktree root is ...')]),
+    asst([tuse('e1', 'Edit', { file_path: 'src/d.js' })]),
+    user([tres('e1', 'ok')]),
+  ], NO_RECENCY);
+  assert.deepEqual(evictIds(out), [], 'context-pack content is load-bearing — never evicted');
+});
+
+test('never targets user text, assistant text, reasoning, or tool_use blocks', () => {
+  const out = classifyEviction([
+    user([txt('a real user instruction')]),
+    asst([{ type: 'thinking', thinking: 'long reasoning' }, txt('narration')]),
+    asst([tuse('r1', 'Read', { file_path: 'src/e.js' })]),
+    user([tres('r1', 'e.js')]),
+    asst([tuse('e1', 'Edit', { file_path: 'src/e.js' })]),
+    user([tres('e1', 'ok')]),
+  ], NO_RECENCY);
+  // only the superseded tool_result r1 is a candidate; nothing else
+  assert.deepEqual(evictIds(out), ['r1']);
+});
+
+test('summary math: evict_tokens + kept_tokens == tool_result_tokens', () => {
+  const out = classifyEviction([
+    asst([tuse('r1', 'Read', { file_path: 'src/f.js' })]),
+    user([tres('r1', 'f.js old')]),
+    asst([tuse('r2', 'Read', { file_path: 'src/f.js' })]),
+    user([tres('r2', 'f.js new')]),
+  ], NO_RECENCY);
+  const s = out.summary;
+  assert.equal(s.evict_tokens + s.kept_tokens, s.tool_result_tokens);
+  assert.equal(s.evict_blocks, 1);
+  assert.ok(s.evict_pct > 0 && s.evict_pct <= 100);
+});
+
+test('orphan tool_result (no matching tool_use) is kept', () => {
+  const out = classifyEviction([user([tres('ghost', 'no matching tool_use')])], NO_RECENCY);
+  assert.deepEqual(evictIds(out), []);
+});
+
+test('pure helpers: estTokens, blockText, stubFor, normalize', () => {
+  assert.equal(estTokens('x'.repeat(40)), 10);
+  assert.equal(blockText([{ type: 'text', text: 'a' }, { type: 'text', text: 'b' }]), 'a\nb');
+  assert.match(stubFor('superseded', { name: 'Read', file: 'src/z.js' }, 100), /recover via re-Read src\/z\.js/);
+  assert.equal(normalize([{ message: { role: 'user', content: 'hi' } }, { not: 'a message' }]).length, 1);
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// task 1364 — harden the three soundness gaps before arming the hook.
+// ──────────────────────────────────────────────────────────────────────────
+
+const DUMP_NOW = { recencyTurns: 0, dumpMinTokens: 5 };
+
+// Fix 1 — a stale_dump from a non-reproducible/side-effectful Bash command is
+// irrecoverable (re-running yields a DIFFERENT value), so it must never be
+// evicted: the "re-run Bash" recovery affordance would be actively wrong.
+
+test('1364 fix1: a big old Bash dump from a non-reproducible command (openssl rand) is kept', () => {
+  const out = classifyEviction([
+    asst([tuse('b1', 'Bash', { command: 'openssl rand -hex 32' })]),
+    user([tres('b1', big('secret'))]),
+    asst([txt('moving on, unrelated')]),
+  ], DUMP_NOW);
+  assert.deepEqual(evictIds(out), [], 'non-reproducible Bash output is irrecoverable — never evicted');
+});
+
+test('1364 fix1: a side-effectful Bash dump (apply migration) is kept', () => {
+  const out = classifyEviction([
+    asst([tuse('b1', 'Bash', { command: 'node scripts/migrate.sh && psql -c "INSERT INTO players ..."' })]),
+    user([tres('b1', big('migration'))]),
+    asst([txt('done, unrelated next step')]),
+  ], DUMP_NOW);
+  assert.deepEqual(evictIds(out), [], 'a one-time migration result cannot be recovered by re-running');
+});
+
+test('1364 fix1: a reproducible read-only Bash dump (cat) is still evictable as stale_dump', () => {
+  const out = classifyEviction([
+    asst([tuse('b1', 'Bash', { command: 'cat src/big.js' })]),
+    user([tres('b1', big('file'))]),
+    asst([txt('moving on, unrelated')]),
+  ], DUMP_NOW);
+  assert.deepEqual(evictIds(out), ['b1']);
+  assert.equal(out.evict[0].reason, 'stale_dump');
+});
+
+test('1364 fix1 unit: isVolatileBash flags randomness/time/mutation, not pure reads', () => {
+  for (const c of [
+    'openssl rand -hex 32', 'uuidgen', 'date +%s', 'echo $RANDOM',
+    'git commit -m wip', 'node scripts/migrate.sh', 'npm install', 'rm -rf build',
+    'echo hi > out.txt', 'head -c 16 /dev/urandom | xxd', 'psql -c "UPDATE tasks SET x=1"',
+  ]) assert.equal(isVolatileBash(c), true, `should flag: ${c}`);
+  for (const c of [
+    'cat src/a.js', 'grep -rn requireRank src', 'ls -la', 'wc -l file.txt',
+    'grep x f 2>&1', 'cat f >/dev/null', 'find . -name "*.js"',
+  ]) assert.equal(isVolatileBash(c), false, `should NOT flag: ${c}`);
+});
+
+// Fix 2 — duplicate/superseded must respect Read offset/limit. A later read only
+// supersedes an earlier one when it COVERS its line range; a partial read is never
+// superseded by a (line-range-less) Edit.
+
+test('1364 fix2: two Reads of DIFFERENT slices of one file — neither is a duplicate', () => {
+  const out = classifyEviction([
+    asst([tuse('r1', 'Read', { file_path: 'src/big.js', offset: 1, limit: 100 })]),
+    user([tres('r1', 'lines 1-100')]),
+    asst([tuse('r2', 'Read', { file_path: 'src/big.js', offset: 500, limit: 100 })]),
+    user([tres('r2', 'lines 500-600')]),
+  ], NO_RECENCY);
+  assert.deepEqual(evictIds(out), [], 'disjoint slices each uniquely hold content');
+});
+
+test('1364 fix2: a later FULL read covers an earlier partial slice → slice is a duplicate', () => {
+  const out = classifyEviction([
+    asst([tuse('r1', 'Read', { file_path: 'src/big.js', offset: 10, limit: 20 })]),
+    user([tres('r1', 'slice 10-29')]),
+    asst([tuse('r2', 'Read', { file_path: 'src/big.js' })]),
+    user([tres('r2', 'whole file')]),
+  ], NO_RECENCY);
+  assert.deepEqual(evictIds(out), ['r1']);
+  assert.equal(out.evict[0].reason, 'duplicate');
+});
+
+test('1364 fix2: a later partial slice does NOT evict an earlier WHOLE read', () => {
+  const out = classifyEviction([
+    asst([tuse('r1', 'Read', { file_path: 'src/big.js' })]),
+    user([tres('r1', 'whole file')]),
+    asst([tuse('r2', 'Read', { file_path: 'src/big.js', offset: 50, limit: 10 })]),
+    user([tres('r2', 'slice 50-59')]),
+  ], NO_RECENCY);
+  assert.deepEqual(evictIds(out), [], 'the whole read still holds content the slice does not');
+});
+
+test('1364 fix2: a 1-line Edit does NOT supersede a PARTIAL prior read (only full reads)', () => {
+  const out = classifyEviction([
+    asst([tuse('r1', 'Read', { file_path: 'src/a.js', offset: 200, limit: 40 })]),
+    user([tres('r1', 'a slice far from the edit')]),
+    asst([tuse('e1', 'Edit', { file_path: 'src/a.js' })]),
+    user([tres('e1', 'edit applied')]),
+    asst([txt('done')]),
+  ], NO_RECENCY);
+  assert.deepEqual(evictIds(out), [], 'a partial read of a possibly-disjoint region is not superseded by a line-range-less edit');
+});
+
+// Fix 3 — backward-reference liveness must also catch a paraphrase: a later turn
+// that reuses the dump's distinctive identifiers/paths without quoting a line.
+
+const TOKEN_DUMP = [
+  'src/bongos/search.js:42  function classifyEviction(transcript) {',
+  'src/bongos/search.js:88  requireRank("archon")',
+  'src/bongos/grader.js:10  const tool_use_id = block.id',
+].join('\n');
+
+test('1364 fix3: a dump paraphrased later (distinctive-token reuse, no verbatim line) is kept', () => {
+  const out = classifyEviction([
+    asst([tuse('g1', 'Grep', { pattern: 'classifyEviction' })]),
+    user([tres('g1', TOKEN_DUMP)]),
+    asst([txt('I should call classifyEviction near requireRank in src/bongos/search.js')]),
+  ], { recencyTurns: 0, dumpMinTokens: 5, livenessAnchorChars: 40 });
+  assert.deepEqual(evictIds(out), [], 'a paraphrase reusing the dump\'s identifiers keeps it');
+});
+
+test('1364 fix3: a dump whose distinctive tokens are NOT reused later is still evicted', () => {
+  const out = classifyEviction([
+    asst([tuse('g1', 'Grep', { pattern: 'classifyEviction' })]),
+    user([tres('g1', TOKEN_DUMP)]),
+    asst([txt('moving on to something completely different now')]),
+  ], { recencyTurns: 0, dumpMinTokens: 5, livenessAnchorChars: 40 });
+  assert.deepEqual(evictIds(out), ['g1']);
+  assert.equal(out.evict[0].reason, 'stale_dump');
+});
+
+test('1364 unit: readRange + salientTokens edges', () => {
+  assert.deepEqual(readRange({}), { start: 1, end: Infinity });
+  assert.deepEqual(readRange({ offset: 10, limit: 5 }), { start: 10, end: 14 });
+  assert.deepEqual(readRange({ offset: 10 }), { start: 10, end: Infinity });
+  const toks = salientTokens('call classifyEviction in src/bongos/search.js with tool_use_id; ignore plain words here');
+  assert.ok(toks.has('classifyEviction'), 'camelCase is distinctive');
+  assert.ok(toks.has('src/bongos/search.js'), 'a path is distinctive');
+  assert.ok(toks.has('tool_use_id'), 'snake_case is distinctive');
+  assert.ok(!toks.has('ignore'), 'a common short word is not distinctive');
+  assert.ok(!toks.has('plain'), 'a common short word is not distinctive');
+});
+
+console.log(`\neviction_policy: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/figma_adapter.mjs

@@ -0,0 +1,199 @@
+// tests/figma_adapter.mjs
+//
+// Unit tests for the Figma round-trip adapter (task 2048, redo of 1379).
+// Covers the pure/IO-testable surface: contract shape, path-escape guard,
+// idempotency, and the snapshot → code translation heuristics (asset vs.
+// code, token-match vs. raw hex). The live Figma MCP push/pull is exercised
+// by the figma-design-sync skill at use-time, not here.
+//
+// Run:  node tests/figma_adapter.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+const require = createRequire(import.meta.url);
+const adapter = require('../src/ui/adapters/figma/index.js');
+
+const REPO_ROOT = path.resolve(process.cwd());
+const SURFACE_ID = `__test_figma_${process.pid}`;
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  return fn().then(() => { passed++; console.log(`  ok  ${name}`); })
+    .catch(err => { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.message}`); });
+}
+
+const DESIGN_SOURCES_PATH = path.join(REPO_ROOT, 'config', 'design-sources.json');
+
+async function cleanup() {
+  await fsp.rm(path.join(REPO_ROOT, 'src', 'ui', SURFACE_ID), { recursive: true, force: true });
+  // export() upserts config/design-sources.json — a tracked file — so undo
+  // that too, or every test run leaves a growing diff on a committed file.
+  const sources = JSON.parse(fs.readFileSync(DESIGN_SOURCES_PATH, 'utf8'));
+  if (sources.surfaces && sources.surfaces[SURFACE_ID]) {
+    delete sources.surfaces[SURFACE_ID];
+    fs.writeFileSync(DESIGN_SOURCES_PATH, JSON.stringify(sources, null, 2) + '\n', 'utf8');
+  }
+}
+
+// ---------- contract shape ----------
+
+await test('exports id "figma" and import/export functions', async () => {
+  assert.equal(adapter.id, 'figma');
+  assert.equal(typeof adapter.import, 'function');
+  assert.equal(typeof adapter.export, 'function');
+});
+
+// ---------- import() (repo → Figma) ----------
+
+await test('import: builds a plan dir with figma-plan.json, tokens.json, surfaces.json', async () => {
+  const result = await adapter.import({ repoRoot: REPO_ROOT });
+  assert.ok(result.planPath && fs.existsSync(result.planPath));
+  const files = fs.readdirSync(result.planPath);
+  assert.ok(files.includes('figma-plan.json'));
+  assert.ok(files.includes('tokens.json'));
+  assert.ok(files.includes('surfaces.json'));
+  assert.ok(Array.isArray(result.surfaceIds));
+  assert.equal(typeof result.summary, 'string');
+});
+
+await test('import: figma-plan.json has a colors frame and a typography frame', async () => {
+  const result = await adapter.import({ repoRoot: REPO_ROOT });
+  const plan = JSON.parse(fs.readFileSync(path.join(result.planPath, 'figma-plan.json'), 'utf8'));
+  const frameNames = plan.frames.map(f => f.frame);
+  assert.ok(frameNames.some(n => n.includes('colors')));
+  assert.ok(frameNames.some(n => n.includes('typography')));
+});
+
+// ---------- export() — Code Connect (files) shape ----------
+
+await test('export: writes files from toolOutput.files under src/ui/<surfaceId>/', async () => {
+  await cleanup();
+  const result = await adapter.export({
+    repoRoot: REPO_ROOT,
+    surfaceId: SURFACE_ID,
+    toolOutput: { files: [{ path: 'Widget.js', content: 'module.exports = {};\n' }] },
+    taskId: '2048',
+  });
+  assert.deepEqual(result.filePaths, [`src/ui/${SURFACE_ID}/Widget.js`]);
+  assert.equal(result.designSourcesUpdated, true);
+  assert.deepEqual(result.warnings, []);
+  assert.ok(fs.existsSync(path.join(REPO_ROOT, 'src', 'ui', SURFACE_ID, 'Widget.js')));
+});
+
+await test('export: is idempotent — identical content on a second call writes nothing', async () => {
+  const result = await adapter.export({
+    repoRoot: REPO_ROOT,
+    surfaceId: SURFACE_ID,
+    toolOutput: { files: [{ path: 'Widget.js', content: 'module.exports = {};\n' }] },
+  });
+  assert.deepEqual(result.filePaths, []);
+});
+
+await test('export: updates config/design-sources.json with tool "figma"', async () => {
+  const sources = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'config', 'design-sources.json'), 'utf8'));
+  assert.equal(sources.surfaces[SURFACE_ID].tool, 'figma');
+  assert.ok(sources.surfaces[SURFACE_ID].lastSyncedAt);
+});
+
+await test('export: path-escape attempt throws and writes nothing', async () => {
+  await assert.rejects(
+    () => adapter.export({
+      repoRoot: REPO_ROOT,
+      surfaceId: SURFACE_ID,
+      toolOutput: { files: [{ path: '../../evil.js', content: 'x' }] },
+    }),
+    /path-escape/,
+  );
+  assert.ok(!fs.existsSync(path.join(REPO_ROOT, 'src', 'ui', 'evil.js')));
+});
+
+await test('export: throws when neither files nor snapshot is provided', async () => {
+  await assert.rejects(
+    () => adapter.export({ repoRoot: REPO_ROOT, surfaceId: SURFACE_ID, toolOutput: {} }),
+  );
+});
+
+// ---------- export() — raw Figma MCP snapshot shape ----------
+
+await test('export: translates a solid-fill FRAME node into code with a raw hex (no token match)', async () => {
+  await cleanup();
+  const result = await adapter.export({
+    repoRoot: REPO_ROOT,
+    surfaceId: SURFACE_ID,
+    toolOutput: { snapshot: { nodes: [{
+      id: '1', name: 'Card', type: 'FRAME',
+      absoluteBoundingBox: { width: 320, height: 120 },
+      fills: [{ type: 'SOLID', color: { r: 0.2, g: 0.2, b: 0.2 } }],
+      children: [{ name: 'Title' }],
+    }] } },
+  });
+  assert.ok(result.filePaths.some(p => p.endsWith('Card.css')));
+  assert.ok(result.filePaths.some(p => p.endsWith('Card.js')));
+  assert.ok(result.warnings.some(w => w.includes('no matching design token')));
+  const css = fs.readFileSync(path.join(REPO_ROOT, 'src', 'ui', SURFACE_ID, 'Card.css'), 'utf8');
+  assert.match(css, /background: #333333;/);
+});
+
+await test('export: an image-fill node is skipped with a warning, not written as code', async () => {
+  await cleanup();
+  const result = await adapter.export({
+    repoRoot: REPO_ROOT,
+    surfaceId: SURFACE_ID,
+    toolOutput: { snapshot: { nodes: [
+      { id: '2', name: 'Hero image', type: 'RECTANGLE', fills: [{ type: 'IMAGE' }] },
+    ] } },
+  });
+  assert.deepEqual(result.filePaths, []);
+  assert.ok(result.warnings.some(w => w.includes('Hero image') && w.includes('asset')));
+});
+
+await test('export: a VECTOR node is skipped with a warning (asset-only type)', async () => {
+  await cleanup();
+  const result = await adapter.export({
+    repoRoot: REPO_ROOT,
+    surfaceId: SURFACE_ID,
+    toolOutput: { snapshot: { nodes: [
+      { id: '3', name: 'Icon', type: 'VECTOR' },
+    ] } },
+  });
+  assert.deepEqual(result.filePaths, []);
+  assert.ok(result.warnings.some(w => w.includes('Icon') && w.includes('asset')));
+});
+
+await test('export: a fill matching a design token is rewritten as a var(--dt-color-*) reference', async () => {
+  await cleanup();
+  // Resolve the same way the adapter does: instance pack overrides the neutral baseline.
+  const neutral = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'config', 'design-tokens.neutral.json'), 'utf8'));
+  let instance = {};
+  try { instance = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'config', 'design-tokens.json'), 'utf8')); } catch { /* no instance pack */ }
+  const accentHex = (instance.colors && instance.colors.accent) || neutral.colors.accent;
+  const r = parseInt(accentHex.slice(1, 3), 16) / 255;
+  const g = parseInt(accentHex.slice(3, 5), 16) / 255;
+  const b = parseInt(accentHex.slice(5, 7), 16) / 255;
+  const result = await adapter.export({
+    repoRoot: REPO_ROOT,
+    surfaceId: SURFACE_ID,
+    toolOutput: { snapshot: { nodes: [{
+      id: '4', name: 'AccentBlock', type: 'FRAME',
+      absoluteBoundingBox: { width: 40, height: 40 },
+      fills: [{ type: 'SOLID', color: { r, g, b } }],
+    }] } },
+  });
+  const css = fs.readFileSync(path.join(REPO_ROOT, 'src', 'ui', SURFACE_ID, 'AccentBlock.css'), 'utf8');
+  assert.match(css, /background: var\(--dt-color-accent\);/);
+  assert.ok(!result.warnings.some(w => w.includes('no matching design token')));
+});
+
+await cleanup();
+
+// ---------- Summary ----------
+
+console.log('');
+console.log(`Figma adapter tests: ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);

package/tests/file_map.mjs

@@ -0,0 +1,91 @@
+// tests/file_map.mjs — generated docs/file-map.md sections + freshness gate
+// (task 1276 / ADR 0066). Mirrors tests/session_index.mjs + tests/repo_map.mjs.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { execFileSync } from 'node:child_process';
+import { readFileSync, existsSync, readdirSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const GEN = path.join(ROOT, 'scripts', 'gds', 'gen-file-map.js');
+const gen = require(GEN); // require.main-guarded → importing runs no main()
+
+function run(args) {
+  try {
+    const stdout = execFileSync(process.execPath, [GEN, ...args], { cwd: ROOT, encoding: 'utf8' });
+    return { code: 0, stdout };
+  } catch (e) {
+    return { code: e.status ?? 1, stdout: (e.stdout || '').toString(), stderr: (e.stderr || '').toString() };
+  }
+}
+
+test('committed file-map sections are current (the Path-C CI gate)', () => {
+  const r = run(['--check']);
+  assert.equal(r.code, 0, `gen-file-map --check should pass on committed artifacts.\n${r.stderr || r.stdout}`);
+  assert.match(r.stdout, /up to date/);
+});
+
+test('EVERY skill + scheduled-task dir on disk is listed AND has a note — no silent omission, no ghost', () => {
+  const model = gen.buildModel();
+  assert.ok(model.length === 2, 'two generated sections');
+  for (const section of model) {
+    const onDisk = readdirSync(path.join(ROOT, section.dir), { withFileTypes: true })
+      .filter((e) => e.isDirectory() && !e.name.startsWith('.'))
+      .map((e) => e.name)
+      .sort();
+    const listed = section.entries.map((e) => e.name).sort();
+    assert.deepEqual(listed, onDisk, `${section.dir}: every dir on disk must be an entry (exhaustive)`);
+    assert.equal(section.missing.length, 0, `${section.dir}: dirs without a note: ${section.missing.join(', ')}`);
+    assert.equal(section.stale.length, 0, `${section.dir}: notes with no dir (ghosts): ${section.stale.join(', ')}`);
+  }
+});
+
+test('the generated blocks live between markers and carry one ← note per entry', () => {
+  const md = readFileSync(path.join(ROOT, 'docs', 'file-map.md'), 'utf8');
+  for (const section of gen.buildModel()) {
+    const B = gen.begin(section.dir + '/');
+    const E = gen.end(section.dir + '/');
+    assert.ok(md.includes(B), `file-map.md has the ${section.dir} start marker`);
+    assert.ok(md.includes(E), `file-map.md has the ${section.dir} end marker`);
+    const between = md.slice(md.indexOf(B), md.indexOf(E));
+    const arrows = (between.match(/←/g) || []).length;
+    assert.equal(arrows, section.entries.length, `${section.dir}: one note arrow per entry`);
+  }
+});
+
+test('--check FAILS (exit 2) when a new skill has no note — a skill can no longer land undescribed', () => {
+  const probe = path.join(ROOT, '.claude', 'skills', '__filemap_test__');
+  try {
+    mkdirSync(probe, { recursive: true });
+    writeFileSync(path.join(probe, 'SKILL.md'), '---\nname: __filemap_test__\n---\n');
+    const r = run(['--check']);
+    assert.equal(r.code, 2, 'an undescribed skill must fail the gate');
+    assert.match(r.stderr, /notes MISSING/);
+    assert.match(r.stderr, /__filemap_test__/);
+  } finally {
+    rmSync(probe, { recursive: true, force: true });
+  }
+  // and clean again once removed
+  assert.equal(run(['--check']).code, 0, 'gate is clean after the probe dir is removed');
+});
+
+test('generation is deterministic + idempotent (a second run is a no-op)', () => {
+  const r1 = run([]);
+  assert.equal(r1.code, 0);
+  const r2 = run([]);
+  assert.equal(r2.code, 0);
+  assert.match(r2.stdout, /already current/);
+});
+
+test('every note maps to a real skill/routine (sidecar has no dangling keys)', () => {
+  const notes = JSON.parse(readFileSync(path.join(ROOT, 'docs', 'file-map.notes.json'), 'utf8'));
+  for (const section of gen.SECTIONS) {
+    const keys = Object.keys(notes[section.notesKey] || {});
+    for (const k of keys) {
+      assert.ok(existsSync(path.join(ROOT, section.dir, k)), `sidecar note '${section.notesKey}.${k}' has no matching dir`);
+    }
+  }
+});

package/tests/first_admin_bootstrap.mjs

@@ -0,0 +1,40 @@
+// tests/first_admin_bootstrap.mjs — config-driven first-admin bootstrap (R62 / task 1201).
+// Covers the DB-free decision logic: firstAdminLogin() config precedence and the
+// maybeSeatFirstAdmin() guards that short-circuit BEFORE any DB call (already an
+// Archon, or login doesn't match the configured firstAdmin). The actual seat
+// (seatFirstAdminIfUnclaimed) is an atomic SQL guard exercised in integration.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import auth from '../src/bongos/auth.js';
+
+const { firstAdminLogin, maybeSeatFirstAdmin } = auth;
+
+function clearEnv() {
+  for (const k of ['OTB_FIRST_ADMIN', 'GDS_FIRST_ADMIN', 'PMS_FIRST_ADMIN', 'CLOUDBONGOS_FIRST_ADMIN']) delete process.env[k];
+}
+
+test('firstAdminLogin: resolves from branding (OTB pack → lars589) when no env override', () => {
+  clearEnv();
+  assert.equal(firstAdminLogin(), 'lars589');
+});
+
+test('firstAdminLogin: env override wins over branding (configured prefix)', () => {
+  clearEnv();
+  process.env.OTB_FIRST_ADMIN = 'someone-else';
+  assert.equal(firstAdminLogin(), 'someone-else');
+  clearEnv();
+});
+
+test('maybeSeatFirstAdmin: no-op when the builder is already an Archon (no DB call)', async () => {
+  clearEnv();
+  const b = { id: 1, github_login: 'lars589', rank: 'archon' };
+  const out = await maybeSeatFirstAdmin(b);
+  assert.equal(out.rank, 'archon');
+});
+
+test('maybeSeatFirstAdmin: no-op when login does not match the configured firstAdmin (no DB call)', async () => {
+  clearEnv();
+  const b = { id: 2, github_login: 'not-the-admin', rank: 'thetes' };
+  const out = await maybeSeatFirstAdmin(b);
+  assert.equal(out.rank, 'thetes');
+});