@bongos/core 1.23.22 → 1.24.1

package/tests/cost_write_guard.mjs

@@ -0,0 +1,200 @@
+// tests/cost_write_guard.mjs — POST /cost refuses what a builder may not book
+// (task 1004959, security report 1000029).
+//
+// The real route runs over a stubbed doorway: requireBuilder admits a builder
+// whose id and rank the test sets, the pool answers the claims lookup from a
+// set of (task, builder) pairs, and logCost is a recorder injected through the
+// router's deps. So every case goes through the route's own wiring (the guard,
+// the claims SQL, the error envelope), not a hand-built input to the guard.
+//
+// The legitimate callers are pinned by the payloads they really send:
+// session-cost.js (session:* rows, and cron:* rows on a scheduled run),
+// ship-grade-steps.js (source 'grader' on the caller's own task), cost.js
+// (manual, optional --task-id) and backfill-cost.js (art_pipeline, no task).
+//
+// Run:  node --test tests/cost_write_guard.mjs
+
+import assert from 'node:assert/strict';
+import { test, before, after, beforeEach } from 'node:test';
+import http from 'node:http';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const express = require('express');
+
+const apiPath = require.resolve('../src/module-api.js');
+const realApi = require(apiPath);
+
+let caller = { id: 7, rank: 'xenos' };
+let claimed = new Set(); // "taskId:builderId"
+let logged = [];
+const queries = [];
+
+const pool = {
+  async query(sql, params) {
+    queries.push({ sql, params });
+    if (/FROM claims/.test(sql)) {
+      return { rows: claimed.has(`${params[0]}:${params[1]}`) ? [{ '?column?': 1 }] : [] };
+    }
+    throw new Error(`unscripted query: ${sql.trim().slice(0, 60)}`);
+  },
+};
+require.cache[apiPath].exports = {
+  ...realApi,
+  pool,
+  requireBuilder: (req, _res, next) => { req.builder = { ...caller }; next(); },
+};
+
+const buildCostRouter = require('../modules/economy/routes/cost.js');
+const { MAX_ROW_USD } = require('../modules/economy/cost-write-guard.js');
+const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
+
+const app = express();
+app.use(express.json());
+app.use(attachFail);
+app.use('/api/bongos', buildCostRouter({
+  logCost: async (row) => { logged.push(row); return { id: logged.length, recorded_at: new Date().toISOString() }; },
+}));
+
+let server, port;
+before(async () => {
+  server = http.createServer(app);
+  await new Promise((r) => server.listen(0, '127.0.0.1', r));
+  port = server.address().port;
+});
+after(async () => { await new Promise((r) => server.close(r)); });
+beforeEach(() => { caller = { id: 7, rank: 'xenos' }; claimed = new Set(); logged = []; queries.length = 0; });
+
+function post(body) {
+  return new Promise((resolve, reject) => {
+    const payload = JSON.stringify(body);
+    const req = http.request({
+      host: '127.0.0.1', port, path: '/api/bongos/cost', method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) },
+    }, (res) => {
+      let data = '';
+      res.on('data', (c) => { data += c; });
+      res.on('end', () => resolve({ status: res.statusCode, body: data ? JSON.parse(data) : null }));
+    });
+    req.on('error', reject);
+    req.end(payload);
+  });
+}
+
+const errCode = (r) => r.body && (r.body.error?.code || r.body.error || r.body.code);
+
+// --- the three attacks from the report -------------------------------------
+
+test('an agent: row is refused from every rank, Archon included (only the server writes them)', async () => {
+  for (const rank of ['xenos', 'metic', 'archon']) {
+    caller = { id: 7, rank };
+    const r = await post({ amount_usd: 50, category: 'api', source: 'agent:anything', source_ref: `x-${rank}` });
+    assert.equal(r.status, 403, `${rank}: agent spend must not come through HTTP`);
+    assert.equal(errCode(r), 'reserved_source');
+  }
+  assert.equal(logged.length, 0, 'nothing reached the ledger');
+});
+
+test('a market-watch: row is refused from every rank too (the weekly run writes it in-process, task 1004937)', async () => {
+  for (const rank of ['xenos', 'metic', 'archon']) {
+    caller = { id: 7, rank };
+    const r = await post({ amount_usd: 5, category: 'api', source: 'Market-Watch:12', source_ref: `item-${rank}` });
+    assert.equal(r.status, 403, `${rank}: Market Watch spend must not come through HTTP`);
+    assert.equal(errCode(r), 'reserved_source');
+  }
+  assert.equal(logged.length, 0, 'nothing reached the ledger');
+});
+
+test('the prefix check ignores case and leading spaces', async () => {
+  const r = await post({ amount_usd: 50, category: 'api', source: '  AGENT:x', source_ref: 'x1' });
+  assert.equal(r.status, 403);
+  assert.equal(logged.length, 0);
+});
+
+test('a cron: row is refused below Metic and accepted from Metic+', async () => {
+  for (const rank of ['xenos', 'thetes']) {
+    caller = { id: 7, rank };
+    const r = await post({ amount_usd: 2, category: 'api', source: 'cron:nightly:interactive', source_ref: `s-${rank}` });
+    assert.equal(r.status, 403, `${rank} may not book scheduled-run spend`);
+    assert.equal(errCode(r), 'reserved_source');
+  }
+  assert.equal(logged.length, 0);
+  for (const rank of ['metic', 'archon']) {
+    caller = { id: 7, rank };
+    const r = await post({ amount_usd: 2, category: 'api', source: 'cron:nightly:interactive', source_ref: `s-${rank}` });
+    assert.equal(r.status, 201, `${rank} runs the scheduled jobs and must still log them`);
+  }
+  assert.equal(logged.length, 2);
+});
+
+test('a task the caller never claimed is refused; one they claimed (even released) is booked', async () => {
+  const r1 = await post({ task_id: 555, amount_usd: 1, category: 'api', source: 'grader', source_ref: 'g1' });
+  assert.equal(r1.status, 403);
+  assert.equal(errCode(r1), 'task_not_yours');
+  assert.equal(logged.length, 0);
+  const q = queries.find((x) => /FROM claims/.test(x.sql));
+  assert.deepEqual(q.params, [555, 7], 'the lookup is keyed on the task AND the authed caller');
+
+  claimed.add('555:7');
+  const r2 = await post({ task_id: 555, amount_usd: 1, category: 'api', source: 'grader', source_ref: 'g2' });
+  assert.equal(r2.status, 201);
+  assert.equal(logged[0].taskId, 555);
+});
+
+test('someone else\'s claim on the task does not let this caller charge it', async () => {
+  claimed.add('555:8');
+  const r = await post({ task_id: 555, amount_usd: 1, category: 'other', source_ref: 'm1' });
+  assert.equal(r.status, 403);
+  assert.equal(errCode(r), 'task_not_yours');
+});
+
+test('an Archon may log against any task (backfills) without the claims lookup', async () => {
+  caller = { id: 3, rank: 'archon' };
+  const r = await post({ task_id: 555, amount_usd: 1, category: 'other', source: 'manual', source_ref: 'a1' });
+  assert.equal(r.status, 201);
+  assert.equal(queries.filter((x) => /FROM claims/.test(x.sql)).length, 0);
+});
+
+test('one row is capped at MAX_ROW_USD, on the total and on every tier', async () => {
+  const over = MAX_ROW_USD + 1;
+  for (const field of ['amount_usd', 'fresh_input_usd', 'cache_read_usd', 'cache_write_usd', 'output_usd']) {
+    const body = { amount_usd: 1, category: 'api', source: 'session:interactive', source_ref: `c-${field}` };
+    body[field] = over;
+    const r = await post(body);
+    assert.equal(r.status, 400, `${field} over the cap must be refused`);
+  }
+  const ok = await post({ amount_usd: MAX_ROW_USD, category: 'api', source: 'session:interactive', source_ref: 'c-at' });
+  assert.equal(ok.status, 201, 'exactly the cap is allowed');
+  assert.ok(MAX_ROW_USD >= 1000, 'the cap stays far above a real session');
+});
+
+test('the claims lookup leads on task_id, which a full (not partial) index serves', async () => {
+  // The only partial claims index is WHERE released_at IS NULL, which this lookup
+  // cannot use (a released claim must count). core_263's idx_claims_task_all is the
+  // one that keeps it off a table scan; if either side drifts, this fails.
+  const fs = require('node:fs');
+  const route = fs.readFileSync(new URL('../modules/economy/routes/cost.js', import.meta.url), 'utf8');
+  assert.match(route, /FROM claims WHERE task_id = \$1 AND builder_id = \$2/);
+  const mig = fs.readFileSync(new URL('../migrations/core_263_closeness_history_indexes.sql', import.meta.url), 'utf8');
+  assert.match(mig, /idx_claims_task_all\s+ON claims \(task_id\);/);
+});
+
+// --- the real callers keep working ----------------------------------------
+
+test('session-cost.js rows (no task, session:* sources) still book for any rank', async () => {
+  for (const source of ['session:interactive', 'session:subagent']) {
+    const r = await post({ amount_usd: 12.5, category: 'api', source, source_ref: `sess-${source}`,
+      fresh_input_usd: 1, cache_read_usd: 10, cache_write_usd: 1, output_usd: 0.5 });
+    assert.equal(r.status, 201, source);
+  }
+  assert.equal(logged.length, 2);
+  assert.equal(logged[0].builderId, 7, 'attributed to the authed caller');
+});
+
+test('the art backfill and a plain manual row (no task) still book', async () => {
+  const art = await post({ amount_usd: 0.04, category: 'art', source: 'art_pipeline', source_ref: 'art-1', recorded_at: '2026-10-01T00:00:00Z' });
+  assert.equal(art.status, 201);
+  const manual = await post({ amount_usd: 3, category: 'other', source_ref: 'man-1' });
+  assert.equal(manual.status, 201);
+  assert.equal(logged[1].source, 'manual');
+});

package/tests/craft_achievements.mjs

@@ -114,10 +114,16 @@ function fakeLedger({ failReconcile = false } = {}) {
           rowCount: 1,
         };
       }
-      if (q.startsWith('SELECT DISTINCT builder_id FROM credit_log')) {
+      if (q.startsWith('SELECT builder_id, MAX(id) AS last_id FROM credit_log')) {
+        // the backfill read: craft-paid builders with a row newer than the watermark ($5)
         const pats = params.slice(0, 4).map(likeRe);
-        const ids = [...new Set(ledger.filter((r) => r.delta > 0 && pats.some((re) => re.test(r.reason))).map((r) => r.builder_id))].sort();
-        return { rows: ids.map((builder_id) => ({ builder_id })) };
+        const since = Number(params[4]);
+        const last = new Map();
+        for (const r of ledger) {
+          if (r.id > since && r.delta > 0 && pats.some((re) => re.test(r.reason))) last.set(r.builder_id, Math.max(last.get(r.builder_id) || 0, r.id));
+        }
+        const ids = [...last.keys()].sort().slice(0, Number(params[5]));
+        return { rows: ids.map((builder_id) => ({ builder_id, last_id: String(last.get(builder_id)) })) };
       }
       if (q.startsWith('SELECT COUNT(*)::int AS n FROM credit_log')) return { rows: [{ n: 0 }], rowCount: 1 };
       if (q.startsWith('SELECT total_credits FROM builders')) return { rows: [{ total_credits: 0 }], rowCount: 1 };
@@ -274,7 +280,7 @@ await test('a builder holding every craft badge costs one read and nothing more'
 
 // ---- 4. the backfill ------------------------------------------------------------------
 
-await test('A Whole Surface is backfilled by the once-per-start sweep, for the artists the ledger has paid', async () => {
+await test('A Whole Surface is backfilled by the hourly incremental sweep, for the artists the ledger has paid', async () => {
   seams._reset();
   let asked = [];
   seams.registerProvider('copy-desk.artistStats', async (id) => { asked.push(String(id)); return { surfaces: [{ tweaked: 4, total: 4 }] }; });
@@ -289,17 +295,34 @@ await test('A Whole Surface is backfilled by the once-per-start sweep, for the a
   assert.deepEqual(asked, ['2001'], 'the studio is asked about the artist only');
   const again = await achievements.backfillCraftAchievements({ client: c });
   assert.equal(again.unlocked, 0, 'a second run unlocks nothing');
+  assert.equal(out.watermark, 1001, 'the watermark is the highest CRAFT credit_log id covered (pay() numbers rows from 1000; the engineer row 1002 is not craft)');
+
+  // task 1004965: INCREMENTAL — a caught-up run reads only past the watermark and checks nobody
+  const reads = () => c.sql.filter((q) => q.startsWith('SELECT builder_id, MAX(id) AS last_id FROM credit_log'));
+  const before = c.sql.length;
+  const caughtUp = await achievements.backfillCraftAchievements({ client: c, sinceId: out.watermark });
+  assert.deepEqual(caughtUp, { checked: 0, unlocked: 0, watermark: out.watermark }, 'caught up: nobody re-checked, watermark held');
+  assert.equal(c.sql.length - before, 1, 'one statement in all — no per-builder reads');
+  assert.match(reads().at(-1), /WHERE id > \$5 AND/, 'bounded by the watermark, never a full scan');
+  pay(c, '2003', 'idea.credit.task_ship:8:102');
+  const fresh = await achievements.backfillCraftAchievements({ client: c, sinceId: out.watermark });
+  assert.equal(fresh.checked, 1, 'only the builder paid since the watermark');
+  assert.ok(fresh.watermark > out.watermark, 'and the watermark moves past them');
+  const capped = await achievements.backfillCraftAchievements({ client: c, limit: 1 });
+  assert.equal(capped.watermark, 0, 'a run that hit its limit keeps the old watermark, skipping nobody past it');
 
   const reconciler = require('../modules/lifecycle/publish-reconciler.js');
-  const calls = [];
-  const reward = { backfillCraftAchievements: async () => { calls.push(1); return { checked: 1, unlocked: 1 }; } };
+  const sinceAsked = [];
+  const reward = { backfillCraftAchievements: async (o) => { sinceAsked.push(o.sinceId); return { checked: 1, unlocked: 1, watermark: 42 }; } };
   const quiet = { logFn: () => {}, errFn: () => {} };
-  await reconciler.runCraftAchievementBackfill({ reward, ...quiet, forceCraftBackfill: true });
   await reconciler.runCraftAchievementBackfill({ reward, ...quiet });
-  assert.equal(calls.length, 1, 'once per process start, not on every tick');
-  const failing = await reconciler.runCraftAchievementBackfill({ reward: { backfillCraftAchievements: async () => { throw new Error('db down'); } }, ...quiet, forceCraftBackfill: true });
+  await reconciler.runCraftAchievementBackfill({ reward, ...quiet });
+  assert.deepEqual(sinceAsked, [0, 42], 'the first run scans from 0; the next starts at the watermark it was handed');
+  const failing = await reconciler.runCraftAchievementBackfill({ reward: { backfillCraftAchievements: async () => { throw new Error('db down'); } }, ...quiet });
   assert.equal(failing.skipped, 'error', 'a failure is logged and swallowed');
-  assert.match(read('modules/lifecycle/publish-reconciler.js'), /runCraftAchievementBackfill\(deps\)\.catch\(crashHandler\('craft achievement backfill'\)\)/, 'the tick runs it');
+  await reconciler.runCraftAchievementBackfill({ reward, ...quiet });
+  assert.equal(sinceAsked.at(-1), 42, 'a failed run keeps the watermark');
+  assert.match(read('modules/lifecycle/publish-reconciler.js'), /\['craft achievement backfill', runCraftAchievementBackfill, HOURLY_MS\]/, 'the tick runs it HOURLY (an entry in the guarded SWEEPS list, tasks 1004924 + 1004965)');
   seams._reset();
 });
 

package/tests/criterion_goal_attach.mjs

@@ -562,7 +562,7 @@ await test('setGoalStatus writes on the transaction client (task 1003840)', asyn
   // reintroduce the very pool-vs-transaction deadlock this test guards.
   assert.equal(seen.length, 2, 'the UPDATE and the request sweep reached the injected client');
   assert.match(seen[0].sql, /UPDATE goals/);
-  assert.deepEqual(seen[0].params, [3, 'achieved']);
+  assert.deepEqual(seen[0].params, [3, 'achieved', null]);
   assert.match(seen[1].sql, /UPDATE goal_membership_requests/);
 });
 

package/tests/db_backup_nightly.mjs

@@ -13,7 +13,7 @@
 
 import assert from 'node:assert/strict';
 import { test } from 'node:test';
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -111,6 +111,78 @@ test('it runs the same on macOS, where stat refuses -c and wc pads its numbers (
   assert.match(r.stdout, /ok · 1 dump\(s\) retained/);
 });
 
+// task 1004966 — the nightly unit and the hall's "Back up now" both run this script, and
+// the script takes a per-database flock under the backup dir, so a second run while one
+// is dumping exits 0 with a SKIPPED line instead of starting a concurrent pg_dump. Needs
+// flock (util-linux): skipped on Windows and wherever flock is not on PATH.
+const hasFlock = process.platform !== 'win32' && spawnSync('bash', ['-c', 'command -v flock'], { encoding: 'utf8' }).status === 0;
+const lockSkip = skip || (hasFlock ? false : 'needs flock (util-linux; runs in CI)');
+
+// A slow fake pg_dump that counts its starts, so a test can see whether a second run
+// began a dump while the first was still inside one.
+function slowBackupDir() {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'db-backup-lock-'));
+  const bin = path.join(tmp, 'bin');
+  const dir = path.join(tmp, 'backups');
+  fs.mkdirSync(bin);
+  fs.mkdirSync(dir);
+  const starts = path.join(tmp, 'starts');
+  fs.writeFileSync(path.join(bin, 'pg_dump'), [
+    '#!/bin/bash',
+    `echo started >> "${starts}"`,
+    'sleep 3',
+    "printf -- '--\\n-- PostgreSQL database dump\\n--\\n--\\n-- PostgreSQL database dump complete\\n--\\n'",
+    '',
+  ].join('\n'), { mode: 0o755 });
+  const env = (db) => ({ ...process.env, PATH: `${bin}:${process.env.PATH}`, [`${ENV}DB`]: db, [`${ENV}DIR`]: dir });
+  const startCount = () => (fs.existsSync(starts) ? fs.readFileSync(starts, 'utf8').trim().split('\n').length : 0);
+  return { dir, env, startCount };
+}
+
+async function waitFor(pred, ms = 5000) {
+  const until = Date.now() + ms;
+  while (!pred()) {
+    if (Date.now() > until) throw new Error('timed out waiting for the first run to start its dump');
+    await new Promise((r) => setTimeout(r, 50));
+  }
+}
+
+function runAsync(env) {
+  const child = spawn('bash', [SCRIPT], { env });
+  let stdout = '';
+  child.stdout.on('data', (c) => { stdout += c; });
+  child.stderr.resume();
+  return new Promise((resolve) => child.on('close', (status) => resolve({ status, stdout })));
+}
+
+test('a second run while one is dumping does not start a concurrent dump (task 1004966)', { skip: lockSkip }, async () => {
+  const { dir, env, startCount } = slowBackupDir();
+  const first = runAsync(env('smallproj'));
+  await waitFor(() => startCount() === 1);
+  const second = spawnSync('bash', [SCRIPT], { encoding: 'utf8', env: env('smallproj') });
+  assert.equal(second.status, 0, 'the second run exits cleanly');
+  assert.match(second.stdout, /gds-db-backup: SKIPPED another backup of smallproj is already running/);
+  assert.equal(startCount(), 1, 'the second run never started pg_dump');
+  const r = await first;
+  assert.equal(r.status, 0);
+  assert.equal(fs.readdirSync(dir).filter((f) => f.endsWith('.sql.gz')).length, 1, 'exactly one dump landed');
+  // Released on exit: the next run dumps normally.
+  const third = spawnSync('bash', [SCRIPT], { encoding: 'utf8', env: env('smallproj') });
+  assert.equal(third.status, 0, third.stderr);
+  assert.equal(startCount(), 2);
+});
+
+test('the lock is per database: another project sharing the backup dir still dumps', { skip: lockSkip }, async () => {
+  const { env, startCount } = slowBackupDir();
+  const first = runAsync(env('smallproj'));
+  await waitFor(() => startCount() === 1);
+  const other = spawnSync('bash', [SCRIPT], { encoding: 'utf8', env: env('otherproj') });
+  assert.equal(other.status, 0, other.stderr);
+  assert.doesNotMatch(other.stdout, /SKIPPED/);
+  assert.equal(startCount(), 2);
+  assert.equal((await first).status, 0);
+});
+
 test('no fixed size floor is baked in for every instance', () => {
   const src = fs.readFileSync(SCRIPT, 'utf8');
   assert.doesNotMatch(src, new RegExp(`${ENV}MIN_BYTES:-[1-9]`), 'a default floor fails every database smaller than it');

package/tests/deploy_divergence_line.mjs

@@ -84,6 +84,13 @@ test('the line says who sees a merge, not a blanket rule in either direction', (
   assert.match(s, /Never call work live until that instance's \/version shows it/);
 });
 
+test('the line tells the agent not to relay it to the builder (task 1004952)', () => {
+  // Owner, 2026-10-28: agents repeated this note in replies every session.
+  const s = line(behind);
+  assert.match(s, /This note is for you, not the builder: do not repeat it to them unless they ask whether work is live/);
+  assert.ok(!s.includes('\n'), 'still one line');
+});
+
 test('the line says whether main\'s latest merge is in a release yet', () => {
   // task 1004873: the first question behind "is it live?" is "is it released?".
   const none = line({ ...behind, behind: false, hasUnreleased: true, unreleased: { count: 4 }, tip: { short: '0f39e344', version: null } });

package/tests/effective_visibility_predicate.mjs

@@ -160,6 +160,18 @@ const NON_PUBLIC_READS = [
     fn: 'getAccountByLogin',
     why: 'resolves a github_login for the Archon-gated invite path (POST /projects/invite). Inviting a person is not publishing them: the caller already knows the login and the result never reaches a public body.',
   },
+  {
+    fn: 'findPersonByLogin',
+    why: 'the sign-in lookup (task 1004992, ADR 0393): which account a provider identity reaches, so a sign-in through Google lands on the right person. It returns only the account id and person key to the sign-in route that minted the session; nothing it returns reaches a public body, and gating it on visibility would lock a private account out of its own sign-in.',
+  },
+  {
+    fn: 'signInWithLogin',
+    why: 'the Google sign-in (task 1004993, ADR 0396): after finding or creating the person by the provider id, it reads their handle and any linked GitHub login for the core sign-in route that mints their session. Nothing it returns reaches a public body, and a private account must still be able to sign in.',
+  },
+  {
+    fn: 'listLoginsForPerson',
+    why: 'the own-scope read behind GET /me/sign-in-methods (task 1004992): which ways in the signed-in person has, keyed on their authenticated key only. It returns their own providers and addresses to themselves; a private account must still see its own sign-in methods.',
+  },
   {
     fn: 'hiddenGithubIds',
     why: 'the closeness-graph consent gate — it answers only "which of these accounts set hide_stats", the OPPOSITE question to visibility. Its callers are requireBuilder-gated and it must stay fail-closed on hide alone (ADR 0171 D4); joining addressability would silently empty the graph of every private account for readers who are allowed to see the edge.',

package/tests/fitness.mjs

@@ -74,6 +74,25 @@ test('the live CLAUDE.md delegates the charter to the rule file', () => {
   assert.ok(kernel.includes(CHARTER_RULE_REL), 'the heading must point somewhere, or it is decoration');
 });
 
+// task 1004933 trimmed quick-nav rows that only repeated a section's own pointer.
+// The pointer itself must survive somewhere in the kernel, and still resolve.
+test('the kernel still points at every detail file a trimmed quick-nav row named', () => {
+  const kernel = fs.readFileSync(path.join(ROOT, 'CLAUDE.md'), 'utf8');
+  for (const rel of ['docs/architecture.md', 'docs/file-map.md', 'docs/canonical-permissions.md',
+    'docs/handoff-template.md', 'docs/project-context.template.md', 'config/branding.neutral.json', 'docs/branding-contract.md']) {
+    assert.ok(kernel.includes(`](${rel})`), `CLAUDE.md lost its link to ${rel}`);
+    assert.ok(fs.existsSync(path.join(ROOT, rel)), `${rel} is linked but missing`);
+  }
+});
+
+test('every section rule in the kernel sits after a blank line (a trim must not make a heading)', () => {
+  // Text directly above a `---` is a Setext H2 in CommonMark: the paragraph becomes a
+  // heading and the section break disappears. A substring check on links stays green.
+  const lines = fs.readFileSync(path.join(ROOT, 'CLAUDE.md'), 'utf8').split(/\r?\n/);
+  const glued = lines.flatMap((l, i) => (l === '---' && i > 0 && lines[i - 1].trim() !== '' ? [i + 1] : []));
+  assert.deepEqual(glued, [], `CLAUDE.md has a --- with text directly above it at line(s) ${glued.join(', ')}`);
+});
+
 test('a hollow charter heading hard-fails (the heading alone is not the charter)', () => {
   const r = fitness.checkClaudeMdBudget({ text: `${CHARTER_HEADING}\n` });
   assert.equal(r.hardFail, true, 'a heading with neither inline rules nor a pointer must fail');