@bongos/core 1.17.0

package/tests/reward_gate.mjs

@@ -0,0 +1,284 @@
+// tests/reward_gate.mjs
+//
+// Unit coverage for task 1670 / ADR 0096 + the task 1673 amendment — the reward
+// gate AUTO-ASSIGNS a capped credits_reward at the workable transitions
+// (promote-to-ready + claim) instead of BLOCKING. A task can never become
+// workable paying 0 drachmae, and a promote/claim is never refused for a missing
+// reward — the gate fills in a fair, capped value and proceeds.
+//
+// The decision is one shared pure helper (db.rewardGateAssignment) consumed by
+// the promote route and the claim path (same pattern as deriveRequiredRank). We
+// test the helpers directly (no DB), then read the route + claim + migration
+// sources to pin the enforcement points and the auto-promote revert.
+//
+// Run:  node tests/reward_gate.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const require = createRequire(import.meta.url);
+const db = require('../modules/lifecycle/db.js');
+// createTask reads the shared pool destructured from the module-api doorway. That is
+// the SAME singleton object db.js captured, so mutating its .query stubs the INSERT
+// createTask runs — no database needed.
+const sharedPool = require('../src/module-api.js').pool;
+
+const __dir = dirname(fileURLToPath(import.meta.url));
+const root = join(__dir, '..');
+
+let passed = 0;
+let failed = 0;
+// `fn` may be sync or async. We register each as a thunk and run them sequentially
+// at the end (preserving the interleaved console.log section headers' positions is
+// not required — the count is what gates the exit code), so the async createTask
+// tests below surface their assertions properly.
+const _queue = [];
+function t(name, fn) {
+  _queue.push(async () => {
+    try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+    catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+  });
+}
+
+console.log('rewardMissing (0/NULL detection):');
+
+t('NULL / undefined / 0 / negative are "missing"', () => {
+  assert.equal(db.rewardMissing(null), true);
+  assert.equal(db.rewardMissing(undefined), true);
+  assert.equal(db.rewardMissing(0), true);
+  assert.equal(db.rewardMissing(-5), true);
+});
+
+t('any positive reward is present', () => {
+  assert.equal(db.rewardMissing(1), false);
+  assert.equal(db.rewardMissing(40), false);
+  assert.equal(db.rewardMissing('40'), false); // string ints coerce
+});
+
+console.log('\nsuggestCreditsReward (capped — now PERSISTED at the gate):');
+
+t('scales ~1 drachma/min, floored at 5, weighted by kind', () => {
+  assert.equal(db.suggestCreditsReward({ est_minutes: 40, kind: 'feature' }), 40);
+  // bug weight 1.25 -> 40 * 1.25 = 50
+  assert.equal(db.suggestCreditsReward({ est_minutes: 40, kind: 'bug' }), 50);
+  // tiny task still names a non-zero number (floor 5)
+  assert.equal(db.suggestCreditsReward({ est_minutes: 1, kind: 'cleanup' }), 5);
+});
+
+t('missing/garbage est falls back to a ~30-min default, still positive', () => {
+  assert.ok(db.suggestCreditsReward({ kind: 'feature' }) >= 5);
+  assert.ok(db.suggestCreditsReward({ est_minutes: 0 }) >= 5);
+  assert.ok(db.suggestCreditsReward({}) >= 5);
+});
+
+t('CAPPED at 60 (anti-gaming: est-inflation cannot balloon the auto-assigned pay)', () => {
+  assert.equal(db.REWARD_SUGGESTION_CAP, 60);
+  // a 1000-min estimate would be 1000 drachmae uncapped — clamped to the cap.
+  assert.equal(db.suggestCreditsReward({ est_minutes: 1000, kind: 'feature' }), 60);
+  // bug weight 1.25 on a big est is also clamped, not 1250.
+  assert.equal(db.suggestCreditsReward({ est_minutes: 1000, kind: 'bug' }), 60);
+  // every output is <= the cap.
+  for (const m of [5, 30, 60, 120, 600, 5000]) {
+    assert.ok(db.suggestCreditsReward({ est_minutes: m, kind: 'feature' }) <= 60);
+  }
+});
+
+console.log('\nrewardGateAssignment (the shared AUTO-ASSIGN decision):');
+
+t('an unrewarded task yields an assignment (capped suggestion), never a refusal', () => {
+  const a = db.rewardGateAssignment({ id: 99, credits_reward: 0, kind: 'feature', est_minutes: 40 });
+  assert.ok(a, 'should produce an assignment');
+  assert.equal(a.assign, 40);
+  // no error shape — the gate proceeds.
+  assert.equal(a.code, undefined);
+});
+
+t('a NULL reward also yields an assignment', () => {
+  const a = db.rewardGateAssignment({ id: 1, credits_reward: null, kind: 'feature', est_minutes: 30 });
+  assert.ok(a);
+  assert.equal(a.assign, 30);
+});
+
+t('a positive reward needs no assignment (returns null)', () => {
+  assert.equal(db.rewardGateAssignment({ id: 1, credits_reward: 40 }), null);
+});
+
+t('GRANDFATHERED rows still get a value — reward_gate_exempt is now inert', () => {
+  // The amendment WANTS to value the grandfathered zero-reward tasks, so the
+  // exempt flag no longer suppresses the assignment.
+  const a = db.rewardGateAssignment({ id: 1, credits_reward: 0, reward_gate_exempt: true, kind: 'feature', est_minutes: 20 });
+  assert.ok(a, 'exempt zero-reward task should still be valued');
+  assert.equal(a.assign, 20);
+});
+
+t('the assigned value never exceeds the cap', () => {
+  const a = db.rewardGateAssignment({ id: 1, credits_reward: 0, kind: 'feature', est_minutes: 9999 });
+  assert.ok(a.assign <= db.REWARD_SUGGESTION_CAP);
+});
+
+t('null task is a no-op (no throw, no assignment)', () => {
+  assert.equal(db.rewardGateAssignment(null), null);
+  assert.equal(db.rewardGateAssignment(undefined), null);
+});
+
+// ---------------------------------------------------------------------------
+// Source-wiring assertions: the two enforcement points AUTO-ASSIGN (no longer
+// refuse), and the migration reverts the 177 auto-promote reward clause. These
+// fail closed if a future edit drops a wiring.
+// ---------------------------------------------------------------------------
+console.log('\nenforcement points (source-wiring — AUTO-ASSIGN):');
+
+const tasksRouteSrc = readFileSync(join(root, 'modules/lifecycle/routes/tasks.js'), 'utf8');
+const dbSrc = readFileSync(join(root, 'modules/lifecycle/db.js'), 'utf8');
+const migration178 = readFileSync(join(root, 'migrations/178_reward_gate_auto_assign_revert_autopromote.sql'), 'utf8');
+
+t('promote route AUTO-ASSIGNS then proceeds (no 409 refusal for missing reward)', () => {
+  const start = tasksRouteSrc.indexOf("router.post('/tasks/:id/promote'");
+  assert.ok(start >= 0, 'promote route not found');
+  const body = tasksRouteSrc.slice(start, start + 1600);
+  assert.match(body, /rewardGateAssignment/, 'promote route must consult the auto-assign decision');
+  assert.match(body, /setCreditsReward/, 'promote route must persist the assigned reward');
+  // it must assign BEFORE flipping to ready, and still flip to ready.
+  assert.ok(
+    body.indexOf('rewardGateAssignment') < body.indexOf("updateTaskStatus(id, 'ready')"),
+    'auto-assign must precede the ready flip'
+  );
+  assert.match(body, /updateTaskStatus\(id, 'ready'\)/, 'promote must still flip to ready');
+  // the old hard refusal must be gone — no REWARD_REQUIRED 409 in the promote body.
+  assert.ok(!/REWARD_REQUIRED/.test(body), 'promote must no longer return a REWARD_REQUIRED refusal');
+});
+
+t('claim path AUTO-ASSIGNS inside the FOR UPDATE transaction (never refuses)', () => {
+  const start = dbSrc.indexOf('async function claimTask');
+  assert.ok(start >= 0, 'claimTask not found');
+  const body = dbSrc.slice(start, start + 5000);
+  assert.match(body, /rewardGateAssignment\(task\)/, 'claimTask must consult the auto-assign decision');
+  assert.match(body, /UPDATE tasks SET credits_reward/, 'claimTask must persist the assigned reward in-tx');
+  // it must SELECT the columns the gate needs.
+  assert.match(body, /credits_reward/, 'claimTask FOR UPDATE select must include credits_reward');
+  // no hard throw of the old refusal from the reward gate inside claimTask.
+  assert.ok(!/throw rewardErr/.test(body), 'claimTask must no longer throw a reward refusal');
+});
+
+t('an AUDIT line is logged on each auto-assignment (route + claim)', () => {
+  assert.match(dbSrc, /\[reward-gate\] AUTO-ASSIGN/, 'db.js must log an audit line on auto-assign');
+});
+
+// ---------------------------------------------------------------------------
+// task 1677 / ADR 0096 (2026-06-28): creation is now the PRIMARY assignment point.
+// db.createTask auto-assigns a capped credits_reward at the LOWEST create layer when
+// the caller supplies no positive value, so EVERY create-vector inherits a born-with
+// drachmae value. promote/claim stays the backstop. We pin the behavior with a real
+// invocation of createTask against a stub pool (no DB), then source-wire the route.
+// ---------------------------------------------------------------------------
+console.log('\ncreation-time auto-assign (db.createTask — the PRIMARY point):');
+
+// createTask reads the module-level `pool`; stub its .query so we can capture the
+// credits_reward bound into the INSERT without a database.
+async function withStubbedCreatePool(run) {
+  const captured = {};
+  const realQuery = sharedPool.query;
+  sharedPool.query = async (sql, params) => {
+    if (/INSERT INTO tasks/.test(sql)) {
+      // credits_reward is the 11th bind ($11) — see the createTask INSERT column order.
+      captured.creditsReward = params[10];
+      return { rows: [{ id: 4242, credits_reward: params[10] }] };
+    }
+    return { rows: [] };
+  };
+  try { return await run(captured); }
+  finally { sharedPool.query = realQuery; }
+}
+
+t('a task CREATED with NO reward is born with a positive, capped value', async () => {
+  await withStubbedCreatePool(async (captured) => {
+    const row = await db.createTask({ versionId: 1, title: 't', kind: 'feature', estMinutes: 40 });
+    assert.ok(captured.creditsReward > 0, 'INSERT must bind a positive credits_reward');
+    assert.equal(captured.creditsReward, 40, 'feature @40min -> 40 drachmae');
+    assert.ok(captured.creditsReward <= db.REWARD_SUGGESTION_CAP, 'must respect the cap');
+    assert.equal(row.credits_reward, 40, 'returned row carries the assigned value');
+  });
+});
+
+t('a task CREATED with credits_reward 0 (the route default) is auto-assigned', async () => {
+  await withStubbedCreatePool(async (captured) => {
+    await db.createTask({ versionId: 1, title: 't', creditsReward: 0, kind: 'bug', estMinutes: 40 });
+    // bug weight 1.25 -> 50; 0 is treated as "unset" so the default kicks in.
+    assert.equal(captured.creditsReward, 50);
+  });
+});
+
+t('a huge-est new task is CAPPED at creation, not ballooned', async () => {
+  await withStubbedCreatePool(async (captured) => {
+    await db.createTask({ versionId: 1, title: 't', kind: 'feature', estMinutes: 9999 });
+    assert.equal(captured.creditsReward, db.REWARD_SUGGESTION_CAP);
+  });
+});
+
+t('an EXPLICIT positive credits_reward is PRESERVED (never overridden)', async () => {
+  await withStubbedCreatePool(async (captured) => {
+    await db.createTask({ versionId: 1, title: 't', creditsReward: 17, kind: 'feature', estMinutes: 40 });
+    assert.equal(captured.creditsReward, 17, 'author-set positive value must survive untouched');
+  });
+});
+
+t('createTask logs a [creation] audit line on auto-assign', () => {
+  const start = dbSrc.indexOf('async function createTask');
+  // Scan the REAL createTask body — from its declaration to the next top-level
+  // function (findTaskBySourceRef) — so the assertions hold as createTask grows
+  // rather than depending on a magic window size. A fixed 4800-char window
+  // silently broke when task 1763 added the goal_id fallback before the INSERT,
+  // sliding the [creation] audit line past its end.
+  const end = dbSrc.indexOf('async function findTaskBySourceRef', start);
+  const body = dbSrc.slice(start, end > start ? end : start + 6000);
+  assert.match(body, /suggestCreditsReward/, 'createTask must reuse the capped helper');
+  assert.match(body, /\[reward-gate\] AUTO-ASSIGN.*\[creation\]/s, 'createTask must log a [creation] audit line');
+});
+
+t('POST /tasks surfaces the assigned credits_reward in the 201 response', () => {
+  const start = tasksRouteSrc.indexOf("router.post('/tasks'");
+  assert.ok(start >= 0, 'POST /tasks route not found');
+  // Scan the REAL POST /tasks handler — from its declaration to the NEXT route
+  // registration — so the assertion holds as the handler grows rather than
+  // depending on a magic window size (same fix as the createTask sibling above).
+  // A fixed 11000-char window silently broke when the handler grew and slid the
+  // `credits_reward: task.credits_reward` response line to offset 11027, 27 chars
+  // past the window — failing on main and reddening every PR's `unit` check
+  // (task 2026; supersedes the never-pushed task 1967, same brittleness).
+  const end = tasksRouteSrc.indexOf('router.', start + 'router.post'.length);
+  const body = tasksRouteSrc.slice(start, end > start ? end : start + 13000);
+  assert.match(body, /credits_reward: task\.credits_reward/, 'response must surface the born-with reward');
+});
+
+t('the promote/claim backstop is KEPT (not removed by the creation-time change)', () => {
+  // The backstop fires rarely now but still covers any legacy/edge 0-reward path.
+  assert.match(dbSrc, /\[promote\]/, 'promote backstop audit line must remain');
+  assert.match(dbSrc, /\[claim by builder/, 'claim backstop audit line must remain');
+});
+
+console.log('\nmigration 178 (revert the 177 auto-promote reward clause):');
+
+t('reverts task_is_fully_unblocked to the deps-doneness predicate', () => {
+  assert.match(migration178, /CREATE OR REPLACE FUNCTION task_is_fully_unblocked/);
+  // the dependency gate survives intact.
+  assert.match(migration178, /WITH gating AS/);
+  assert.match(migration178, /SELECT NOT EXISTS/);
+});
+
+t('the 177 reward-gate clause is GONE from the reverted predicate', () => {
+  assert.ok(
+    !/reward_gate_exempt = true OR COALESCE\(t\.credits_reward, 0\) > 0/.test(migration178),
+    'migration 178 must NOT carry the 177 reward clause'
+  );
+});
+
+t('says the reward_gate_exempt column is now inert', () => {
+  assert.match(migration178, /inert|INERT/);
+});
+
+for (const run of _queue) { await run(); }
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/tests/route_rank_check.mjs

@@ -0,0 +1,243 @@
+// tests/route_rank_check.mjs
+//
+// Deterministic route-rank check (#475 / C7). Covers the pure classifier
+// (classifyText), the invariant (checkRouteRanks → findings/hardFail), the
+// pseudo-worker shaping (toWorkerResult), and a LIVE assertion that every
+// route currently declared under src/bongos/routes/ classifies to a known rank
+// (the GET /public/repo-info multi-line-comment parse, fixed here).
+//
+// Run:  node tests/route_rank_check.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const rrc = require('../src/bongos/route-rank-check.js');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`  ok  ${name}`);
+    passed++;
+  } catch (err) {
+    console.error(`  FAIL ${name}`);
+    console.error(`       ${err.message}`);
+    failed++;
+  }
+}
+
+// ---------- classifyText: middleware-chain classification ----------
+
+test('requireRank(archon) → archon', () => {
+  const r = rrc.classifyText(`router.post('/x', auth.requireBuilder, auth.requireRank('archon'), h);`);
+  assert.equal(r[0].rank, 'archon');
+});
+
+test('requireRank(metic, archon) → metic+archon', () => {
+  const r = rrc.classifyText(`router.post('/x', auth.requireRank('metic', 'archon'), h);`);
+  assert.equal(r[0].rank, 'metic+archon');
+});
+
+test('requireRank(xenos,...) → any-builder', () => {
+  const r = rrc.classifyText(`router.post('/x', auth.requireRank('xenos', 'metic', 'archon'), h);`);
+  assert.equal(r[0].rank, 'any-builder');
+});
+
+test('requireBuilder only → any-builder', () => {
+  const r = rrc.classifyText(`router.get('/x', auth.requireBuilder, h);`);
+  assert.equal(r[0].rank, 'any-builder');
+});
+
+test('requireBfgPrincipal → bfg-principal (identity gate wins over the requireBuilder beside it)', () => {
+  const r = rrc.classifyText(`router.post('/x', auth.requireBuilder, auth.requireBfgPrincipal, h);`);
+  assert.equal(r[0].rank, 'bfg-principal', 'the BFG cross-builder write route must classify as the principal gate, not any-builder');
+});
+
+test('multi-line declaration: middleware on the next line still classifies', () => {
+  const r = rrc.classifyText(`router.post('/x',\n  auth.requireRank('archon'),\n  handler);`);
+  assert.equal(r[0].rank, 'archon');
+});
+
+test('a nested requireRank in the HANDLER BODY does not downgrade the route [regression]', () => {
+  // Only the route's own middleware list decides its rank; a requireRank call
+  // inside the handler body (within the 20-line scan window) must be ignored.
+  const src = `router.post('/admin', auth.requireRank('archon'), async (req, res) => {\n` +
+              `  if (foo) bar(auth.requireRank('xenos'));\n` +
+              `  res.end();\n});`;
+  assert.equal(rrc.classifyText(src)[0].rank, 'archon');
+});
+
+test('a route declared with NO middleware does not borrow the NEXT route\'s rank [regression]', () => {
+  // A short GET handler must not bleed into the following route's requireRank.
+  const src = `router.get('/list', async (req, res) => {\n` +
+              `  res.json([]);\n});\n` +
+              `router.post('/list', auth.requireRank('archon'), async (req, res) => {\n` +
+              `  res.end();\n});`;
+  const rows = rrc.classifyText(src);
+  assert.equal(rows.find((x) => x.method === 'GET').rank, 'unknown'); // no middleware, no annotation
+  assert.equal(rows.find((x) => x.method === 'POST').rank, 'archon');
+});
+
+// ---------- classifyText: `rank:` annotation fallback ----------
+
+test('rank: annotation directly above → classifies', () => {
+  const r = rrc.classifyText(`  // rank: public\n  router.get('/x', h);`);
+  assert.equal(r[0].rank, 'public');
+});
+
+test('rank: annotation atop a 6-line comment block (the repo-info case) → classifies', () => {
+  const src = [
+    '  // rank: public — GitHub URL bases for the deployed checkout',
+    '  // line 2 of the block',
+    '  // line 3',
+    '  // line 4',
+    '  // line 5',
+    '  // line 6',
+    "  router.get('/public/repo-info', h);",
+  ].join('\n');
+  const r = rrc.classifyText(src);
+  assert.equal(r[0].rank, 'public', 'whole contiguous comment block must be scanned, not a 5-line window');
+});
+
+test('annotation does not leak across a prior route body (stops at code)', () => {
+  const src = [
+    "  // rank: archon",
+    "  router.post('/a', h);",   // /a → archon, from the annotation directly above it
+    '  });',
+    "  router.get('/b', h);",    // /b → unknown: no annotation, no middleware, prior line is code (the }); above)
+  ].join('\n');
+  const r = rrc.classifyText(src);
+  assert.equal(r[0].rank, 'archon');
+  assert.equal(r[1].rank, 'unknown', 'the /a annotation must not bleed down to /b past the }); code line');
+});
+
+test('typo annotation (not a known rank) → unknown', () => {
+  const r = rrc.classifyText(`  // rank: any-builders\n  router.get('/x', h);`);
+  assert.equal(r[0].rank, 'unknown', 'a misspelled rank surfaces rather than being trusted');
+});
+
+// ---------- checkRouteRanks invariant (via a fixture-free routesDir shim) ----------
+// checkRouteRanks reads files; we exercise the finding logic through the pure
+// path by constructing routes through classifyText + the documented severity
+// rule. (The live filesystem assertion below covers the fs path end-to-end.)
+
+test('toWorkerResult: clean → pass, no issues', () => {
+  const w = rrc.toWorkerResult({ ok: true, hardFail: false, routeCount: 40, routes: [], findings: [] });
+  assert.equal(w.verdict, 'pass');
+  assert.equal(w.kind, 'route-rank');
+  assert.equal(w.issues.length, 0);
+  assert.equal(w.confidence, 1);
+});
+
+test('toWorkerResult: write-unknown → fail with a blocker issue', () => {
+  const findings = [{ severity: 'blocker', file: 'src/bongos/routes/x.js', route: 'POST /x', method: 'POST', rank: 'unknown', summary: 'no gate' }];
+  const w = rrc.toWorkerResult({ ok: false, hardFail: true, routeCount: 40, routes: [], findings });
+  assert.equal(w.verdict, 'fail');
+  assert.equal(w.issues.length, 1);
+  assert.equal(w.issues[0].severity, 'blocker');
+});
+
+test('toWorkerResult: read-unknown only → concerns (not fail)', () => {
+  const findings = [{ severity: 'major', file: 'src/bongos/routes/x.js', route: 'GET /x', method: 'GET', rank: 'unknown', summary: 'confirm public' }];
+  const w = rrc.toWorkerResult({ ok: false, hardFail: false, routeCount: 40, routes: [], findings });
+  assert.equal(w.verdict, 'concerns');
+});
+
+// ---------- EXPECTED_RANKS: exact-rank pin on privileged routes (#999) ----------
+
+test('EXPECTED_RANKS: pins are non-empty and all to known ranks', () => {
+  const keys = Object.keys(rrc.EXPECTED_RANKS);
+  assert.ok(keys.length > 0, 'should pin at least one privileged route');
+  for (const [k, v] of Object.entries(rrc.EXPECTED_RANKS)) {
+    assert.ok(rrc.KNOWN_RANKS.has(v), `pinned expected rank '${v}' for ${k} must be a known rank`);
+  }
+});
+
+test('EXPECTED_RANKS: a DOWNGRADE on a pinned route trips a blocker via a routesDir shim', () => {
+  // Build a synthetic routes dir whose every pinned route is present, but one
+  // archon-pinned route (PATCH /builders/:id/rank) has been silently downgraded
+  // to requireBuilder. The base "must classify" loop would wave this through
+  // (it classifies to a KNOWN rank, 'any-builder') — the pin is what catches it.
+  const os = require('node:os');
+  const fs = require('node:fs');
+  const path = require('node:path');
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'rrc-'));
+  const lines = [];
+  const emit = (key, expected) => {
+    const [method, route] = key.split(' ');
+    const m = method.toLowerCase();
+    if (key === 'PATCH /builders/:id/rank') {
+      // DOWNGRADE: requireBuilder only → classifies any-builder, not archon.
+      lines.push(`  router.${m}('${route}', auth.requireBuilder, h);`);
+    } else if (expected === 'archon') {
+      lines.push(`  router.${m}('${route}', auth.requireBuilder, auth.requireRank('archon'), h);`);
+    } else if (expected === 'metic+archon') {
+      lines.push(`  router.${m}('${route}', auth.requireRank('metic', 'archon'), h);`);
+    } else {
+      lines.push(`  // rank: ${expected}`);
+      lines.push(`  router.${m}('${route}', h);`);
+    }
+    // A blank gap matching a real handler body — keeps classifyRank's 20-line
+    // middleware lookahead on the downgraded route from "borrowing" a NEIGHBOUR
+    // route's requireRank('archon') line.
+    lines.push('  });', '', '', '', '', '', '');
+  };
+  // Emit every pinned route EXCEPT the downgraded one first, then the downgraded
+  // one LAST (so nothing with requireRank('archon') sits within its lookahead).
+  for (const [key, expected] of Object.entries(rrc.EXPECTED_RANKS)) {
+    if (key !== 'PATCH /builders/:id/rank') emit(key, expected);
+  }
+  emit('PATCH /builders/:id/rank', rrc.EXPECTED_RANKS['PATCH /builders/:id/rank']);
+  fs.writeFileSync(path.join(dir, 'shim.js'), lines.join('\n'));
+  const res = rrc.checkRouteRanks({ routesDir: dir });
+  fs.rmSync(dir, { recursive: true, force: true });
+
+  const downgrade = res.findings.find((f) => f.route === 'PATCH /builders/:id/rank');
+  assert.ok(downgrade, 'a downgraded pinned route must surface a finding');
+  assert.equal(downgrade.severity, 'blocker', 'a rank downgrade on a privileged route is a hard fail');
+  assert.equal(res.hardFail, true);
+});
+
+test('EXPECTED_RANKS: a MISSING pinned route trips a blocker (a protected route vanished)', () => {
+  const os = require('node:os');
+  const fs = require('node:fs');
+  const path = require('node:path');
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'rrc-'));
+  // Empty routes dir → every pinned route is "missing".
+  fs.writeFileSync(path.join(dir, 'empty.js'), '// no routes here\n');
+  const res = rrc.checkRouteRanks({ routesDir: dir });
+  fs.rmSync(dir, { recursive: true, force: true });
+  const missing = res.findings.find((f) => f.rank === '(missing)');
+  assert.ok(missing, 'a pinned route absent from the route set must surface a finding');
+  assert.equal(missing.severity, 'blocker');
+  assert.equal(res.hardFail, true);
+});
+
+// ---------- LIVE: every real route classifies to a known rank ----------
+
+test('LIVE: checkRouteRanks() on src/bongos/routes/ has zero unknowns', () => {
+  const res = rrc.checkRouteRanks();
+  assert.ok(res.routeCount > 0, 'should discover routes');
+  const unknowns = res.findings.map((f) => f.route);
+  assert.equal(res.findings.length, 0,
+    `every route must classify to a known rank; unclassified: ${unknowns.join(', ')}`);
+  assert.equal(res.ok, true);
+  assert.equal(res.hardFail, false);
+});
+
+test('LIVE: every pinned privileged route still classifies to its EXPECTED rank', () => {
+  const res = rrc.checkRouteRanks();
+  const byKey = new Map();
+  for (const r of res.routes) if (!byKey.has(r.key)) byKey.set(r.key, r);
+  for (const [key, expected] of Object.entries(rrc.EXPECTED_RANKS)) {
+    const r = byKey.get(key);
+    assert.ok(r, `pinned route ${key} must exist in the live route set`);
+    assert.equal(r.rank, expected, `pinned route ${key} must classify as '${expected}', got '${r.rank}'`);
+  }
+});
+
+console.log('');
+console.log(`Route-rank-check tests: ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);