@bongos/core 1.19.702 → 1.19.704

package/tests/agents_sync.mjs

@@ -0,0 +1,401 @@
+// tests/agents_sync.mjs — the deploy-time file↔DB reconcile (task 1002490,
+// goal 1000038 Phase 1, T6).
+//
+// The four rules this script exists to keep, each tested as the FAILURE it
+// prevents rather than as the happy path:
+//
+//   1. a source=db row is never touched      → an instance-authored agent
+//                                              survives a deploy
+//   2. author_rank is never taken from git    → the committer email is
+//      where it could grant                     attacker-controlled, so it is
+//                                               withheld on any protected scope
+//                                               (ADR 0016)
+//   3. a refused SCOPE imports disabled+flagged → visible and fixable, never armed
+//   4. the sync never ARMS anything           → `git push` cannot switch an
+//                                              agent on
+//
+// Pure: no database, no git, no disk except one tmp dir for the absent/present
+// directory cases. The reconcile's DECISIONS are the thing under test.
+//
+// In tests/ rather than modules/agents/tests/ for the same reason as
+// tests/agents_routes.mjs: the module is default:false and module-local tests
+// are discovered only when the module is ENABLED, so they would never run here.
+//
+// Run:  node tests/agents_sync.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+const sync = require('../scripts/gds/agents-sync.js');
+const validate = require('../modules/agents/lib/validate.js');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try { fn(); console.log(`  PASS  ${name}`); passed += 1; }
+  catch (err) { console.log(`  FAIL  ${name}\n        ${err.message}`); failed += 1; }
+}
+
+const FILE = [
+  '---',
+  'name: historian',
+  'title: The Historian',
+  'trigger: on-demand',
+  'model_tier: routine',
+  'scope_modules: [agents]',
+  '---',
+  '',
+  'You are the historian. Answer with citations.',
+].join('\n');
+
+const def = () => sync.parseAgentFile(FILE, { name: 'historian' });
+
+console.log('\nparsing — the file is a definition, the body is the persona:');
+
+t('frontmatter + body split, with the body as persona', () => {
+  const d = def();
+  assert.equal(d.name, 'historian');
+  assert.equal(d.title, 'The Historian');
+  assert.equal(d.trigger_type, 'on-demand', 'the readable `trigger:` spelling maps to the column');
+  assert.equal(d.model_tier, 'routine');
+  assert.deepEqual(d.scope_modules, ['agents']);
+  assert.match(d.persona, /^You are the historian/);
+  assert.ok(!('trigger' in d), 'the file spelling is consumed, not left to confuse the validator');
+});
+
+t('the FILENAME is the identity when frontmatter omits a name', () => {
+  const d = sync.parseAgentFile('---\ntrigger: on-demand\n---\nbody', { name: 'planner' });
+  assert.equal(d.name, 'planner', 'planner.md is the planner agent without saying so twice');
+});
+
+t('CRLF and a REAL BOM parse — a Windows-authored file is still a definition', () => {
+  // The first draft of this test was named for the BOM and contained none —
+  // only CRLF — so it asserted nothing about the behaviour its name promised.
+  // The second carried a LITERAL U+FEFF, which is invisible and read in review
+  // as no BOM at all. Built from the CODE POINT: unambiguous ASCII in source,
+  // and the charCodeAt assertion below means the fixture cannot quietly lose it
+  // a third time.
+  const withBom = String.fromCharCode(0xFEFF) + '---\r\nname: x\r\ntrigger: on-demand\r\n---\r\nbody';
+  assert.equal(withBom.charCodeAt(0), 0xFEFF, 'the fixture really starts with a BOM');
+  const d = sync.parseAgentFile(withBom, {});
+  assert.equal(d.name, 'x');
+  assert.equal(d.trigger_type, 'on-demand');
+  assert.equal(d.persona, 'body');
+  // And the same file WITHOUT the BOM must still parse — the BOM is optional,
+  // not required, and a regex that demanded it would break every POSIX file.
+  const noBom = sync.parseAgentFile(withBom.slice(1), {});
+  assert.equal(noBom.name, 'x');
+});
+
+t('`event:` becomes the trigger_spec the schema stores', () => {
+  const d = sync.parseAgentFile('---\nname: lens\ntrigger: event\nevent: task.shipped\n---\nb', {});
+  assert.deepEqual(d.trigger_spec, { event: 'task.shipped' });
+  assert.ok(!('event' in d));
+});
+
+t('a file with NO frontmatter yields no definition, and does not throw', () => {
+  const d = sync.parseAgentFile('just prose, no fences', { name: 'loose' });
+  assert.equal(d.name, 'loose');
+  assert.equal(d.trigger_type, undefined, 'nothing is invented from a bare file');
+});
+
+t('an unknown key is KEPT, so a typo is refused rather than defaulted', () => {
+  const d = sync.parseAgentFile('---\nname: x\ntriger: event\n---\nb', {});
+  assert.equal(d.triger, 'event', 'silently dropping it would turn a typo into a default');
+});
+
+console.log('\nrule 1 — a source=db row is never touched:');
+
+t('an instance-authored row owns its name; the file is ignored', () => {
+  const p = sync.planOne(def(), {
+    authorRank: 'archon', allowedModules: ['agents'],
+    existing: { source: 'db', enabled: true },
+  });
+  assert.equal(p.action, 'protected');
+  assert.match(p.reason, /instance-authored/);
+  assert.equal(p.value, undefined, 'no row is produced, so nothing can be written');
+});
+
+t('a source=file row with the same name IS reconciled', () => {
+  const p = sync.planOne(def(), {
+    authorRank: 'archon', allowedModules: ['agents'],
+    existing: { source: 'file', enabled: false },
+  });
+  assert.equal(p.action, 'upsert');
+});
+
+console.log('\nrule 2 — authority comes from the live DB rank, never the file:');
+
+t('a file claiming author_rank cannot promote itself', () => {
+  // The frontmatter says archon; the caller passes the live rank, which is what
+  // the wall consults. If the file could win, writing one line would be a
+  // privilege escalation whose only gate is code review.
+  const claiming = sync.parseAgentFile(
+    '---\nname: x\ntrigger: on-demand\nauthor_rank: archon\nscope_modules: [government]\n---\nbody', {});
+  const p = sync.planOne(claiming, {
+    authorRank: 'xenos', allowedModules: ['government'], protectedModules: ['government'],
+  });
+  assert.equal(p.action, 'flagged', 'the declared rank did not open the protected scope');
+  // NULL, not 'xenos': this definition reaches a protected module, so no
+  // git-derived rank is stamped at all (stampableAuthorRank). The file's claim
+  // loses, and so does the spoofable git value — both by the same rule.
+  assert.equal(p.authorRank, null, 'nothing git-derived is stamped on a protected-scope row');
+  assert.match(p.scopeViolation, /metic\+ author/i);
+});
+
+t('THE ESCALATION PATH: a spoofed git identity cannot arm a protected scope', () => {
+  // git log --format=%ae reports the commit AUTHOR, which any committer sets
+  // with `git config user.email` or `--author` — noreply-shaped values included,
+  // and nothing verifies them against GitHub. So the resolved rank is
+  // attacker-controlled. The wall is that it is never consulted where it could
+  // grant: a definition reaching a protected module is stamped NULL whatever
+  // git said, which the validator treats as insufficient.
+  const d = def(); // scope_modules: [agents]
+  assert.equal(sync.declaresProtectedScope(d, ['agents']), true);
+  assert.equal(sync.stampableAuthorRank(d, { gitRank: 'archon', protectedModules: ['agents'] }), null,
+    'a claimed archon rank must not survive onto a protected-scope definition');
+  const p = sync.planOne(d, {
+    authorRank: 'archon', allowedModules: ['agents'], protectedModules: ['agents'],
+  });
+  assert.equal(p.action, 'flagged', 'so it flags, exactly as an unresolved author would');
+  assert.equal(p.authorRank, null, 'and nothing spoofable is stamped on the row');
+  assert.equal(p.enabled, false);
+});
+
+t('where rank grants nothing, the hint is kept as provenance', () => {
+  // The other side: withholding it everywhere would throw away useful
+  // provenance for no gain, since on an unprotected scope the rank gates nothing.
+  const d = def();
+  assert.equal(sync.stampableAuthorRank(d, { gitRank: 'metic', protectedModules: [] }), 'metic');
+  const p = sync.planOne(d, { authorRank: 'metic', allowedModules: ['agents'], protectedModules: [] });
+  assert.equal(p.action, 'upsert');
+  assert.equal(p.authorRank, 'metic');
+});
+
+t('an UNRESOLVED author is insufficient, not exempt', () => {
+  // A committer who maps to no builder row yields null. Fail-closed: null must
+  // behave like "too low", never like "skip the check".
+  const p = sync.planOne(def(), {
+    authorRank: null, allowedModules: ['agents'], protectedModules: ['agents'],
+  });
+  assert.equal(p.action, 'flagged');
+  assert.equal(p.authorRank, null);
+  assert.equal(p.enabled, false);
+});
+
+console.log('\nrule 3 — a refused scope is IMPORTED, disabled and flagged:');
+
+t('a protected scope below the floor imports flagged, never armed', () => {
+  const p = sync.planOne(def(), {
+    authorRank: 'thetes', allowedModules: ['agents'], protectedModules: ['agents'],
+  });
+  assert.equal(p.action, 'flagged');
+  assert.equal(p.enabled, false, 'the whole point — present, not armed');
+  assert.ok(p.scopeViolation && p.scopeViolation.length > 0, 'the reason is stored so it can be fixed');
+  assert.ok(p.value, 'a flagged row still carries the normalized definition');
+  assert.equal(p.value.name, 'historian');
+});
+
+t('a flagged row keeps its real scope, not a sanitised one', () => {
+  // The re-run that recovers the normalized shape must not be allowed to launder
+  // the scope — what is stored has to be what the file actually asked for, or
+  // the flag names a problem the row no longer shows.
+  const p = sync.planOne(def(), {
+    authorRank: 'thetes', allowedModules: ['agents'], protectedModules: ['agents'],
+  });
+  assert.deepEqual(p.value.scope_modules, ['agents']);
+});
+
+t('a SHAPE error is skipped — there is no definition to import', () => {
+  const p = sync.planOne({ name: 'x', trigger_type: 'telepathy' }, {
+    authorRank: 'archon', allowedModules: ['agents'],
+  });
+  assert.equal(p.action, 'skip');
+  assert.equal(p.value, undefined, 'a partial row must never reach the registry');
+  assert.match(p.reason, /trigger/i);
+});
+
+t('the two are not confused: every SCOPE_CODE is a real validator code', () => {
+  // If a code were renamed in the validator, scope refusals would start being
+  // reported as shape errors and silently stop being imported.
+  const p = validate.validateAgentDefinition(
+    { name: 'x', trigger_type: 'on-demand', persona: 'p', scope_modules: ['nope'] },
+    { authorRank: 'archon', allowedModules: [] }
+  );
+  assert.equal(p.ok, false);
+  assert.ok(p.errors.some((e) => sync.SCOPE_CODES.includes(e.code)),
+    'scope_out_of_bounds must still be spelled the way SCOPE_CODES expects');
+});
+
+console.log('\nrule 4 — the sync never arms anything:');
+
+t('a NEW clean definition inserts DISABLED', () => {
+  const p = sync.planOne(def(), { authorRank: 'archon', allowedModules: ['agents'] });
+  assert.equal(p.action, 'upsert');
+  assert.equal(p.enabled, false, 'arming is an operator act, by the same logic as rule 2');
+});
+
+t("an EXISTING row keeps the operator's own enabled setting", () => {
+  const on = sync.planOne(def(), {
+    authorRank: 'archon', allowedModules: ['agents'], existing: { source: 'file', enabled: true },
+  });
+  assert.equal(on.enabled, true, 'a deploy must not undo an operator switching an agent on');
+  const off = sync.planOne(def(), {
+    authorRank: 'archon', allowedModules: ['agents'], existing: { source: 'file', enabled: false },
+  });
+  assert.equal(off.enabled, false);
+});
+
+t('a flagged row is forced OFF even if it was armed before', () => {
+  // The dangerous ordering: an agent is armed, then its scope is edited to reach
+  // a protected surface. Carrying `enabled` forward would arm the new scope.
+  const p = sync.planOne(def(), {
+    authorRank: 'thetes', allowedModules: ['agents'], protectedModules: ['agents'],
+    existing: { source: 'file', enabled: true },
+  });
+  assert.equal(p.action, 'flagged');
+  assert.equal(p.enabled, false, 'a newly-flagged agent must be disarmed, not left running');
+});
+
+console.log('\nthe absent directory is a legitimate state:');
+
+t('no .claude/agents/ → zero files, no throw', () => {
+  // It does not exist in the core tree at all today, and an instance shipping no
+  // agents must still deploy cleanly.
+  assert.deepEqual(sync.readAgentFiles(path.join(os.tmpdir(), 'agents-sync-absent-xyz')), []);
+});
+
+t('a real directory is read, .md only, sorted', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'agents-sync-'));
+  fs.writeFileSync(path.join(dir, 'zeta.md'), FILE);
+  fs.writeFileSync(path.join(dir, 'alpha.md'), FILE.replace('name: historian', 'name: alpha'));
+  fs.writeFileSync(path.join(dir, 'README.txt'), 'not a definition');
+  const files = sync.readAgentFiles(dir);
+  assert.equal(files.length, 2, 'only .md files are definitions');
+  assert.deepEqual(files.map((f) => f.candidate.name), ['alpha', 'historian'], 'sorted, so a run is reproducible');
+});
+
+console.log('\nplanSync — the whole reconcile, still pure:');
+
+t('one plan entry per file, each carrying its own author rank', () => {
+  const files = [
+    { file: '.claude/agents/a.md', candidate: sync.parseAgentFile(FILE.replace('historian', 'a'), {}) },
+    { file: '.claude/agents/b.md', candidate: sync.parseAgentFile(FILE.replace('historian', 'b'), {}) },
+  ];
+  const plan = sync.planSync(files, {
+    existingByName: new Map([['b', { source: 'db', enabled: true }]]),
+    authorRankFor: (f) => (f.endsWith('a.md') ? 'archon' : 'xenos'),
+    allowedModules: ['agents'],
+    protectedModules: [],
+  });
+  assert.equal(plan.length, 2);
+  assert.equal(plan[0].action, 'upsert');
+  assert.equal(plan[0].authorRank, 'archon', 'rank is resolved PER FILE, not once for the run');
+  assert.equal(plan[1].action, 'protected', 'the db-owned name is left alone');
+});
+
+console.log('\nthe committer mapping — provenance only, and known spoofable:');
+
+t('a GitHub noreply address yields the login; a local name is only a fallback', () => {
+  // Neither form is trustworthy — both come from the commit author, which the
+  // committer sets. The preference is about giving the BEST GUESS at provenance,
+  // not about security; the security is that this value never reaches a decision
+  // (see the escalation-path test above).
+  const login = sync.lastCommitterLogin('x', { runGit: () => '12345+octocat@users.noreply.github.com\nSomeone Else\n' });
+  assert.equal(login, 'octocat', 'the noreply address carries the login and cannot be set locally');
+  // A generic fixture on purpose: a real builder's login baked into a test is
+  // the hardcoded-founder-identity defect audit-authorship.sh exists to catch,
+  // and it caught this line in its first draft.
+  const fallback = sync.lastCommitterLogin('x', { runGit: () => 'someone@example.com\na-builder\n' });
+  assert.equal(fallback, 'a-builder');
+  assert.equal(sync.lastCommitterLogin('x', { runGit: () => { throw new Error('not a repo'); } }), null,
+    'an unreadable history resolves to null, which rule 2 treats as insufficient');
+});
+
+console.log('\nthe path wall is wired to the REAL registry (task 1002492):');
+
+const permissionPaths = require('../src/bongos/permission-path-check.js');
+const realMatcher = (p) => permissionPaths.surfaceFor(p) !== null;
+
+t('the wall is wired to the REAL protected-surface registry', () => {
+  // Not a stub: the same synchronously-loaded registry the pre-push hook, the
+  // grader pre-pass and main-audit.js read (ADR 0043). If a governance re-map
+  // narrows it, this fails rather than silently widening what an agent may reach.
+  assert.equal(realMatcher('modules/government/catalog.js'), true, 'the authority surface');
+  assert.equal(realMatcher('migrations/001_init.sql'), true, 'schema');
+  assert.equal(realMatcher('.claude/hooks/pre-push.js'), true, 'local automation');
+  assert.equal(realMatcher('modules/agents/lib/validate.js'), false, "a module's own code is not protected");
+  // `.claude/agents/` itself is deliberately NOT in the registry — see the note
+  // on ADDED_SINCE_R101 in tests/government_protected_surfaces.mjs. Protecting
+  // it would rank-wall the whole agents module by derivation, which is a
+  // separate decision from the one this wall makes.
+  assert.equal(realMatcher('.claude/agents/historian.md'), false,
+    'not protected — and that is recorded, not accidental');
+});
+
+t('a path scope onto the authority surface is withheld a rank AND flagged', () => {
+  // Both halves of task 1002492 meeting the rule from 1002490: the definition
+  // reaches a protected surface BY PATH, so (a) no git-derived rank is stamped
+  // and (b) the scope wall refuses it — imported, disabled, visible.
+  const d = sync.parseAgentFile(
+    '---\nname: snoop\ntrigger: on-demand\nscope_paths: [modules/government/catalog.js]\n---\nbody', {});
+  assert.equal(sync.declaresProtectedScope(d, [], realMatcher), true);
+  assert.equal(sync.stampableAuthorRank(d, { gitRank: 'archon', isProtectedPath: realMatcher }), null,
+    'a claimed archon rank must not survive a PATH-spelled protected scope either');
+  const p = sync.planOne(d, {
+    authorRank: 'archon', allowedModules: ['agents'], isProtectedPath: realMatcher,
+  });
+  assert.equal(p.action, 'flagged');
+  assert.equal(p.authorRank, null);
+  assert.equal(p.enabled, false);
+  assert.match(p.scopeViolation, /scope_paths|protected surface/i);
+});
+
+t('an unprotected path scope still reconciles normally', () => {
+  // The wall is a floor, not a ban — a tightening that refused every path scope
+  // would pass the test above and break the feature.
+  const d = sync.parseAgentFile(
+    '---\nname: reader\ntrigger: on-demand\nscope_paths: [modules/agents/lib/]\n---\nbody', {});
+  assert.equal(sync.declaresProtectedScope(d, [], realMatcher), false);
+  const p = sync.planOne(d, {
+    authorRank: 'metic', allowedModules: ['agents'], isProtectedPath: realMatcher,
+  });
+  assert.equal(p.action, 'upsert');
+  assert.equal(p.authorRank, 'metic', 'rank gates nothing here, so the provenance hint is kept');
+});
+
+t('declaring paths with NO matcher flags rather than importing clean', () => {
+  // The uncheckable case end to end: the plan must not treat "nobody checked"
+  // as "nothing was protected".
+  const d = sync.parseAgentFile(
+    '---\nname: x\ntrigger: on-demand\nscope_paths: [anything]\n---\nbody', {});
+  assert.equal(sync.declaresProtectedScope(d, [], null), true, 'unanswerable reads as protected');
+  const p = sync.planOne(d, { authorRank: 'archon', allowedModules: ['agents'] });
+  assert.equal(p.action, 'flagged', 'imported and visible, never silently clean');
+  assert.equal(p.enabled, false);
+});
+
+console.log('\nthe reconcile actually RUNS at deploy:');
+
+t('migrate.sh invokes agents-sync, module-gated and fail-open', () => {
+  // A reconcile nothing calls is a script, not a deploy step — review caught
+  // that the first cut shipped the machinery with no caller. migrate.sh is the
+  // one deploy-time hook the portable core owns, and it applies the schema this
+  // writes into a few lines above, so the table exists by the time it runs.
+  const sh = fs.readFileSync(new URL('../scripts/migrate.sh', import.meta.url), 'utf8');
+  assert.match(sh, /scripts\/gds\/agents-sync\.js/, 'the deploy path must call it');
+  assert.match(sh, /isModuleEnabled\('agents'\)/, "gated on the module — it is default:false");
+  // Fail-OPEN: a stale registry is a nuisance, an aborted deploy is an outage,
+  // and the script is already fail-closed about what it imports.
+  assert.match(sh, /agents-sync failed — the registry is stale by one deploy/,
+    'a failed reconcile must not abort the deploy');
+  const call = sh.slice(sh.indexOf('agents-sync'));
+  assert.doesNotMatch(call.slice(0, 200), /exit 1/, 'no exit 1 on the agents-sync path');
+});
+
+console.log(`\nagents_sync: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/agents_validate.mjs

@@ -41,7 +41,15 @@ const OK_DEF = Object.freeze({
   model_tier: 'default',
   scope_modules: ['agents'],
 });
-const OPTS = Object.freeze({ authorRank: 'archon', allowedModules: ['agents'] });
+// task 1002492 added the scope_paths half of the rank wall, and with it the rule
+// that DECLARING paths requires the caller to supply the means to check them —
+// there is no `allowedPaths` counterpart to fail closed on, so an absent matcher
+// would be a silent hole. The baseline options therefore carry a matcher; the
+// uncheckable and protected cases each get their own test below.
+const NOTHING_PROTECTED = () => false;
+const OPTS = Object.freeze({
+  authorRank: 'archon', allowedModules: ['agents'], isProtectedPath: NOTHING_PROTECTED,
+});
 
 const codes = (r) => r.errors.map((e) => e.code);
 const hasCode = (r, code) => codes(r).includes(code);
@@ -241,6 +249,115 @@ await test('a scope_path that escapes the tree is refused', () => {
   assert.equal(validateAgentDefinition({ ...OK_DEF, scope_paths: ['modules/agents/'] }, OPTS).ok, true);
 });
 
+// --- THE scope_paths HALF OF THE WALL (task 1002492) ------------------------
+//
+// The defect this closes: the rank wall ran over scope_modules only, so
+// `scope_modules: ['government']` was refused below Metic while
+// `scope_paths: ['modules/government/']` reached the same code and passed at any
+// rank. One wall, two halves, disagreeing — and the path half was the one an
+// author would reach for to name a specific surface.
+
+const REACHES_GOVERNMENT = (p) => String(p).startsWith('modules/government');
+
+await test('a scope_path onto a protected surface is refused below the floor', () => {
+  const r = validateAgentDefinition(
+    { ...OK_DEF, scope_paths: ['modules/government/catalog.js'] },
+    { authorRank: 'thetes', allowedModules: ['agents'], isProtectedPath: REACHES_GOVERNMENT }
+  );
+  assert.equal(r.ok, false, 'a thetes author may not scope onto the authority surface by path');
+  assert.ok(hasCode(r, 'scope_protected_rank'), JSON.stringify(codes(r)));
+  assert.match(r.errors.find((e) => e.code === 'scope_protected_rank').message, /scope_paths/);
+});
+
+await test('the two halves of the wall now agree', () => {
+  // The asymmetry itself, asserted: the same surface named as a module and as a
+  // path must reach the same verdict for the same author.
+  const asModule = validateAgentDefinition(
+    { ...OK_DEF, scope_modules: ['government'] },
+    { authorRank: 'thetes', allowedModules: ['agents', 'government'], protectedModules: ['government'], isProtectedPath: NOTHING_PROTECTED }
+  );
+  const asPath = validateAgentDefinition(
+    { ...OK_DEF, scope_paths: ['modules/government/'] },
+    { authorRank: 'thetes', allowedModules: ['agents'], isProtectedPath: REACHES_GOVERNMENT }
+  );
+  assert.equal(asModule.ok, false, 'the module spelling was always refused');
+  assert.equal(asPath.ok, false, 'and the path spelling must be too — this is the whole task');
+  assert.ok(hasCode(asModule, 'scope_protected_rank'));
+  assert.ok(hasCode(asPath, 'scope_protected_rank'));
+});
+
+await test('a Metic+ author may scope onto a protected path', () => {
+  // The wall is a FLOOR, not a ban — a tightening that refused everyone would
+  // pass the test above while breaking the feature.
+  const r = validateAgentDefinition(
+    { ...OK_DEF, scope_paths: ['modules/government/catalog.js'] },
+    { authorRank: 'metic', allowedModules: ['agents'], isProtectedPath: REACHES_GOVERNMENT }
+  );
+  assert.equal(r.ok, true, JSON.stringify(codes(r)));
+  assert.deepEqual(r.value.scope_paths, ['modules/government/catalog.js']);
+});
+
+await test('an UNPROTECTED path is unaffected at any rank', () => {
+  const r = validateAgentDefinition(
+    { ...OK_DEF, scope_paths: ['modules/agents/lib/'] },
+    { authorRank: 'xenos', allowedModules: ['agents'], isProtectedPath: REACHES_GOVERNMENT }
+  );
+  assert.equal(r.ok, true, 'the wall must not become a blanket refusal of path scopes');
+});
+
+await test('declaring scope_paths with NO matcher is refused, not admitted', () => {
+  // scope_modules fails closed through `allowedModules` defaulting to empty.
+  // scope_paths has no such counterpart, so an absent matcher would be a silent
+  // hole — "nobody checked" must not read the same as "nothing was protected".
+  const r = validateAgentDefinition(
+    { ...OK_DEF, scope_paths: ['anything/at/all'] },
+    { authorRank: 'archon', allowedModules: ['agents'] }
+  );
+  assert.equal(r.ok, false);
+  assert.ok(hasCode(r, 'scope_paths_uncheckable'), JSON.stringify(codes(r)));
+  // …and an ARCHON is refused too: this is not a rank question, it is a
+  // "we could not answer the question" question.
+  assert.equal(r.value, null);
+});
+
+await test('a THROWING matcher counts as a hit, never as a clean path', () => {
+  const boom = () => { throw new Error('registry unreadable'); };
+  const low = validateAgentDefinition(
+    { ...OK_DEF, scope_paths: ['whatever'] },
+    { authorRank: 'xenos', allowedModules: ['agents'], isProtectedPath: boom }
+  );
+  assert.equal(low.ok, false, 'an unanswered question must not resolve to "not protected"');
+  assert.ok(hasCode(low, 'scope_protected_rank'));
+  // The floor still applies: a Metic+ author is admitted, because the
+  // fail-closed reading is "treat as protected", not "refuse everyone".
+  const high = validateAgentDefinition(
+    { ...OK_DEF, scope_paths: ['whatever'] },
+    { authorRank: 'archon', allowedModules: ['agents'], isProtectedPath: boom }
+  );
+  assert.equal(high.ok, true);
+});
+
+await test('ONLY an explicit false clears a path — ambiguity reads as protected', () => {
+  // The fail-open trap: `answer === true` would read undefined (a matcher that
+  // forgot a return), a truthy string, or null as "not protected" — silently
+  // opening the wall on the exact question it exists to ask. Reading ambiguity
+  // as protected is loud and gets fixed; reading it as clean is not.
+  for (const answer of [undefined, null, 'yes', 0, '']) {
+    const r = validateAgentDefinition(
+      { ...OK_DEF, scope_paths: ['x'] },
+      { authorRank: 'xenos', allowedModules: ['agents'], isProtectedPath: () => answer }
+    );
+    assert.equal(r.ok, false, `a matcher answering ${JSON.stringify(answer)} must not clear the path`);
+    assert.ok(hasCode(r, 'scope_protected_rank'));
+  }
+  // …and a real `false` does clear it, or the wall would refuse everything.
+  const clean = validateAgentDefinition(
+    { ...OK_DEF, scope_paths: ['x'] },
+    { authorRank: 'xenos', allowedModules: ['agents'], isProtectedPath: () => false }
+  );
+  assert.equal(clean.ok, true);
+});
+
 // --- THE RANK WALL (ADR 0016 — authority is the author's LIVE rank) ---------
 
 await test('RANK_ORDER is the ladder low→high, and the scope floor is Metic', () => {