@bongos/core 1.19.815 → 1.19.817

package/scripts/gds/stale-worktrees.js

@@ -13,6 +13,28 @@
 // deleted it). Both are pure git facts, so this runs in well under a second at
 // SessionStart. The primary checkout is never listed.
 //
+// THE THIRD LEAK — UNSTARTED CLAIM TREES (task 1003912). "Ancestor of origin/main"
+// is also true of a branch that is origin/main, which is exactly what
+// `worktree.js add` leaves behind: it branches off origin/main and commits
+// nothing. So between `worktree.js add` and the builder's FIRST COMMIT, a live
+// claim's worktree was reported as "merged into main". Observed 2026-09-13: the
+// session working task 1002594 saw its own tree listed as stale. The classifier
+// had the git fact right and the intent wrong — nothing had landed, nothing had
+// even started.
+//
+// That window is small and the consequence is not: /worktree-clean removes every
+// name on the stale list, so a cleanup run by another session (or the SessionStart
+// nag) inside it would take a live claim's tree. `worktree.js remove` refuses a
+// dirty tree, which bounds the damage — but a claim worktree that is still empty
+// is precisely the one that is NOT dirty, so the guard does not cover this case.
+//
+// The fix stays a pure git fact, keeping the "no API call" property this header is
+// explicit about wanting: a branch whose TIP EQUALS origin/main is zero commits
+// ahead, so it cannot have landed anything, and is reported live-but-unstarted.
+// The alternative — cross-checking branch names against active claims — would put
+// a network round trip in a SessionStart probe to learn something git already
+// knows.
+//
 // THE SECOND LEAK — HUSKS (task 1002594). Under OneDrive, `git worktree remove`
 // often errors 'Permission denied' / 'Device or resource busy' but still
 // DEREGISTERS the worktree, so `worktree.js remove` treats deregistration as
@@ -65,7 +87,12 @@ function parseWorktreeList(porcelain) {
 
 // Pure classifier so the decision is unit-testable without a repo: `isMerged(branch)`
 // and `branchExists(branch)` are the two git facts it needs.
-function classifyWorktrees(worktrees, { isMerged, branchExists }) {
+// `isUnstarted(branch)` is the task 1003912 guard: branch tip === origin/main tip.
+// It is checked BEFORE isMerged because every unstarted branch is also trivially
+// "merged" — that coincidence is the whole bug, and order is what separates them.
+// Optional, so a caller that does not supply it gets the old behaviour rather than
+// a crash.
+function classifyWorktrees(worktrees, { isMerged, branchExists, isUnstarted = () => false }) {
   const stale = [];
   const live = [];
   for (const wt of worktrees) {
@@ -73,6 +100,7 @@ function classifyWorktrees(worktrees, { isMerged, branchExists }) {
     const name = path.basename(wt.path);
     if (!wt.branch) { live.push({ name, path: wt.path, branch: null }); continue; } // detached: not ours to judge
     if (!branchExists(wt.branch)) stale.push({ name, path: wt.path, branch: wt.branch, why: 'branch gone' });
+    else if (isUnstarted(wt.branch)) live.push({ name, path: wt.path, branch: wt.branch, why: 'unstarted (no commits yet)' });
     else if (isMerged(wt.branch)) stale.push({ name, path: wt.path, branch: wt.branch, why: 'merged into main' });
     else live.push({ name, path: wt.path, branch: wt.branch });
   }
@@ -93,22 +121,38 @@ function classifyHusks({ dirNames, worktreePaths, worktreesRoot }) {
     .map((name) => ({ name, path: path.join(worktreesRoot, name) }));
 }
 
-// Three git calls total, whatever the worktree count: the list, every local branch,
-// every branch already merged into origin/main. Per-worktree subprocesses would be
-// N+1 over exactly the number this probe exists to shrink.
+// FOUR git calls total, whatever the worktree count: the worktree list, every local
+// branch WITH ITS TIP (one read, both facts — task 1003912), every branch already
+// merged into origin/main, and origin/main's own tip. Per-worktree subprocesses
+// would be N+1 over exactly the number this probe exists to shrink.
 function refNames(out) {
   return new Set(String(out).split('\n').map((s) => s.trim()).filter(Boolean));
 }
 
 function scan(cwd) {
   const worktrees = parseWorktreeList(git(['worktree', 'list', '--porcelain'], cwd));
-  const existing = refNames(git(['for-each-ref', '--format=%(refname:short)', 'refs/heads/'], cwd));
+  // ONE read of refs/heads/, carrying both facts it is asked for: which branches
+  // exist, and where each one points. The tip is what the task 1003912 guard needs
+  // (equal to origin/main's ⇒ zero commits ahead ⇒ nothing has landed from it,
+  // because nothing has been written in it) and asking for it separately would
+  // have spawned a second subprocess over the identical ref set — in the one file
+  // whose header makes a promise about its git-call count.
+  const tipOf = new Map();
+  for (const line of git(['for-each-ref', '--format=%(refname:short) %(objectname)', 'refs/heads/'], cwd).split('\n')) {
+    const [name, sha] = line.trim().split(/\s+/);
+    if (name && sha) tipOf.set(name, sha);
+  }
+  const existing = new Set(tipOf.keys());
   let merged;
   try { merged = refNames(git(['branch', '--merged', MAIN_REF, '--format=%(refname:short)'], cwd)); }
   catch { merged = new Set(); } // no origin/main yet (fresh clone, no fetch) → nothing is provably stale
+  let mainTip = null;
+  try { mainTip = git(['rev-parse', MAIN_REF], cwd).trim(); }
+  catch { mainTip = null; } // same fail-open as `merged`: unknown ⇒ claim nothing
   const r = classifyWorktrees(worktrees, {
     branchExists: (b) => existing.has(b),
     isMerged: (b) => merged.has(b),
+    isUnstarted: (b) => Boolean(mainTip) && tipOf.get(b) === mainTip,
   });
   // The main checkout is always the first porcelain entry, so the husk directory is
   // derivable without a second git call.
@@ -157,7 +201,7 @@ function main() {
   console.log(`  Worktrees: ${r.live.length} live, ${r.stale.length} stale, ${husks.length} husks`);
   for (const s of r.stale) console.log(`    stale  ${s.name}  (${s.why})`);
   for (const h of husks) console.log(`    husk   ${h.name}  (on disk, not registered)`);
-  for (const l of r.live) console.log(`    live   ${l.name}  [${l.branch || 'detached'}]`);
+  for (const l of r.live) console.log(`    live   ${l.name}  [${l.branch || 'detached'}]${l.why ? `  (${l.why})` : ''}`);
   if (r.stale.length) console.log('  Remove with: node scripts/gds/worktree.js remove <name>   (or /worktree-clean)');
   if (husks.length) console.log('  Sweep husks with: node scripts/gds/worktree.js prune-husks');
   if (r.stale.length || husks.length) process.exit(1);

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.815'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.817'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/capture_goal_routing.mjs

@@ -181,7 +181,11 @@ await test('no --goal: the active-claim default fires and names how to opt out',
     me: { ok: true, data: { active_claims: [{ task_id: 55, title: 'Fix the thing' }] } },
     task: { ok: true, data: { task: { id: 55, goal_id: 1000071, title: 'Fix the thing' } } },
   });
-  const r = await capture.resolveGoalForCapture({ goalArg: null, version: 'BV1', title: 't', client });
+  // The captured text shares 'thing' with the claim — the ordinary case the
+  // default exists for. (It used to be the bare title 't'; since task 1003859 the
+  // default only fires on a shared subject word, so a placeholder no longer
+  // exercises this path.)
+  const r = await capture.resolveGoalForCapture({ goalArg: null, version: 'BV1', title: 'the thing is broken', client });
   assert.equal(r.goalId, 1000071);
   assert.equal(r.lines.length, 1);
   assert.match(r.lines[0], /1000071/);
@@ -239,4 +243,64 @@ await test('WIRING: a routing refusal is surfaced through the existing verbatim
   assert.match(CAPTURE_SRC, /console\.error\(formatCaptureFailure\(r\.status, r\.data\)\);/);
 });
 
+// ---------------------------------------------------------------------------
+// the active-claim default must not mint UNRELATED work into the claim's goal
+// (task 1003859)
+// ---------------------------------------------------------------------------
+//
+// The default fired unconditionally, so filing an unrelated bug mid-session
+// routed it into whatever goal you happened to be holding — task 1003859 itself
+// was filed from a security claim and landed in Working area 10, and had to be
+// moved by hand. ADR 0234: a guess must not mint work into a goal.
+
+await test('no --goal, claim shares NO subject with the filing: does not inherit, and says why', async () => {
+  const { client, calls } = stubClient({
+    me: { ok: true, data: { active_claims: [{ task_id: 55, title: 'Harden the OAuth callback against replay' }] } },
+    task: { ok: true, data: { task: { id: 55, goal_id: 1000094, title: 'Harden the OAuth callback against replay' } } },
+    suggestions: { ok: true, data: { suggestions: [] } },
+  });
+  const r = await capture.resolveGoalForCapture({
+    goalArg: null, version: 'BV1', title: 'The goal suggester returns zero suggestions for every idea', client,
+  });
+  assert.equal(r.goalId, null, 'an unrelated claim must not decide where this work lives');
+  assert.equal(r.lines.length, 1, 'staying homeless silently would be the same bug with no evidence');
+  assert.match(r.lines[0], /NOT defaulting/);
+  assert.match(r.lines[0], /1000094/, 'it must name the goal it declined, so --goal can override it');
+  assert.equal(calls.suggestions.length, 1, 'with no default, the suggester still gets its turn');
+});
+
+await test('a declined default still yields to a real suggestion, keeping both lines', async () => {
+  const { client } = stubClient({
+    me: { ok: true, data: { active_claims: [{ task_id: 55, title: 'Harden the OAuth callback against replay' }] } },
+    task: { ok: true, data: { task: { id: 55, goal_id: 1000094, title: 'Harden the OAuth callback against replay' } } },
+    suggestions: { ok: true, data: { suggestions: [{ id: 1000091, title: 'Working area 7', score: 3 }] } },
+  });
+  const r = await capture.resolveGoalForCapture({
+    goalArg: null, version: 'BV1', title: 'The goal suggester returns zero suggestions', client,
+  });
+  assert.equal(r.goalId, null);
+  assert.equal(r.lines.length, 2, 'the refusal and the hint are different facts — both are printed');
+  assert.match(r.lines[0], /NOT defaulting/);
+  assert.match(r.lines[1], /1000091/);
+});
+
+await test('--goal N still wins outright over the guard (it is not a veto)', async () => {
+  const { client, calls } = stubClient({
+    me: { ok: true, data: { active_claims: [{ task_id: 55, title: 'Something else entirely' }] } },
+    task: { ok: true, data: { task: { id: 55, goal_id: 1000094 } } },
+  });
+  const r = await capture.resolveGoalForCapture({ goalArg: '1000094', version: 'BV1', title: 'unrelated words here', client });
+  assert.deepEqual(r, { goalId: 1000094, lines: [] });
+  assert.equal(calls.me, 0);
+});
+
+await test('a claim title with no subject words at all still inherits — the guard only fires on real disagreement', async () => {
+  const { client } = stubClient({
+    me: { ok: true, data: { active_claims: [{ task_id: 55, title: 'a' }] } },
+    task: { ok: true, data: { task: { id: 55, goal_id: 1000071, title: 'a' } } },
+  });
+  const r = await capture.resolveGoalForCapture({ goalArg: null, version: 'BV1', title: 'anything at all', client });
+  assert.equal(r.goalId, 1000071, 'nothing to compare against is not evidence of a mismatch');
+});
+
 summary();

package/tests/goal_suggest.mjs

@@ -199,13 +199,23 @@ await test('the handler clamps limit into a sane range', async () => {
 // confident answer and declines whenever "confident" is not available.
 // =========================================================================
 
-const fakeDb = ({ versions = [], goals = [], throws = null, calls = null } = {}) => ({
+const fakeDb = ({ versions = [], goals = [], throws = null, calls = null, criteria = null } = {}) => ({
   listVersions: async () => { if (throws === 'versions') throw new Error('boom'); return versions; },
   listGoals: async (args) => {
     if (calls) calls.push(args);
     if (throws === 'goals') throw new Error('boom');
     return goals;
   },
+  // task 1003859: the criterion prose the ranker reads alongside the title.
+  // Omitted (criteria: null) it is absent from the fake ENTIRELY, which is also
+  // the pinned shape for a db that predates this read.
+  ...(criteria ? {
+    listCriterionTextForGoals: async (ids) => {
+      if (throws === 'criteria') throw new Error('boom');
+      if (calls) calls.push({ criteriaFor: ids.map(String) });
+      return new Map(Object.entries(criteria));
+    },
+  } : {}),
 });
 
 const BUILDING = { id: 'BONGOS-V1', status: 'building' };
@@ -298,4 +308,141 @@ await test('suggestGoalForCapture: the catch-all is never offered as a home', as
   assert.equal(got, null, 'a bucket is not a workspace — dropped for EVERY open version, not just one');
 });
 
+// ---------------------------------------------------------------------------
+// ranking on DONE-WHEN CRITERIA (task 1003859)
+// ---------------------------------------------------------------------------
+//
+// The real failure: since ADR 0264 every open BONGOS-V2 goal is titled
+// 'Working area N — <subject>'. A subject word in a draft had nothing to overlap
+// in the title, every goal scored 0, and the suggester returned [] for every idea
+// walked at the 2026-09-12 triage — which also left suggested_goal_id NULL on
+// every filing. These reproduce that board rather than a convenient one.
+
+const WORKING_AREAS = [
+  { id: 1000091, title: 'Working area 7', scope_modules: [], version_id: 'BONGOS-V2' },
+  { id: 1000094, title: 'Working area 10', scope_modules: [], version_id: 'BONGOS-V2' },
+];
+const WA_CRITERIA = {
+  1000091: 'A release is published and an instance can move its pin to it. The grader runs and its findings are readable.',
+  1000094: 'Every authenticated route re-checks the caller rank. A credential never reaches a log.',
+};
+
+await test('the real board: title-only ranking scores every Working area goal ZERO', () => {
+  const got = suggestGoals(WORKING_AREAS, { title: 'the grader returns no findings' }, { versionId: 'BONGOS-V2', includeZero: true });
+  assert.deepEqual(got.map((g) => g.score), [0, 0],
+    'this is the bug, pinned: the naming convention left the ranker nothing to match');
+  assert.deepEqual(suggestGoals(WORKING_AREAS, { title: 'the grader returns no findings' }, { versionId: 'BONGOS-V2' }), [],
+    'and so the suggester returned nothing at all');
+});
+
+await test('with criteria, the same draft finds its goal, with the matched terms shown', () => {
+  const got = suggestGoals(
+    WORKING_AREAS,
+    { title: 'the grader returns no findings' },
+    { versionId: 'BONGOS-V2', criteriaByGoal: new Map(Object.entries(WA_CRITERIA)) }
+  );
+  assert.equal(got.length, 1, 'only the goal whose criteria talk about grading');
+  assert.equal(got[0].id, 1000091);
+  assert.ok(got[0].score > 0);
+  assert.ok(got[0].matched_terms.includes('grader'), `expected 'grader' among ${JSON.stringify(got[0].matched_terms)}`);
+});
+
+await test('a criterion match weighs LESS than the same word in the title', () => {
+  const byTitle = { id: 10, title: 'Grader health', scope_modules: [], version_id: 'BONGOS-V2' };
+  const byCriteria = { id: 11, title: 'Working area 7', scope_modules: [], version_id: 'BONGOS-V2' };
+  const got = suggestGoals(
+    [byCriteria, byTitle],
+    { title: 'grader' },
+    { versionId: 'BONGOS-V2', criteriaByGoal: new Map([['11', 'the grader runs nightly']]) }
+  );
+  assert.equal(got[0].id, 10, 'a goal NAMED for the subject still outranks one that merely mentions it');
+  assert.ok(got[0].score > got[1].score);
+});
+
+await test('a term in both title and criteria is counted ONCE, at the title weight', () => {
+  const g = { id: 12, title: 'Grader health', scope_modules: [], version_id: 'BONGOS-V2' };
+  const withCriteria = suggestGoals([g], { title: 'grader' }, { versionId: 'BONGOS-V2', criteriaByGoal: new Map([['12', 'grader grader grader']]) });
+  const without = suggestGoals([g], { title: 'grader' }, { versionId: 'BONGOS-V2' });
+  assert.equal(withCriteria[0].score, without[0].score, 'repeating itself must not inflate a goal');
+});
+
+await test('no criteriaByGoal: ranking is EXACTLY what it was before (the pure function stays DB-free)', () => {
+  const draft = { title: 'the hall sidebar collapses on mobile' };
+  const a = suggestGoals([HALL_GOAL, ECON_GOAL], draft, { versionId: 'BONGOS-V1' });
+  const b = suggestGoals([HALL_GOAL, ECON_GOAL], draft, { versionId: 'BONGOS-V1', criteriaByGoal: null });
+  assert.deepEqual(a, b);
+  assert.equal(a[0].id, 81);
+});
+
+await test('suggestGoalForCapture reads the criteria, so suggested_goal_id is populated on the real board', async () => {
+  const calls = [];
+  const got = await suggestGoalForCapture(
+    { title: 'the grader returns no findings', body: '' },
+    { db: fakeDb({ versions: [{ id: 'BONGOS-V2', status: 'building' }], goals: WORKING_AREAS, criteria: WA_CRITERIA, calls }) }
+  );
+  assert.ok(got, 'this returned NULL before task 1003859 — which is why suggested_goal_id was null on every filing');
+  assert.equal(got.id, 1000091);
+  assert.equal(got.version_id, 'BONGOS-V2');
+  assert.ok(calls.some((c) => c && c.criteriaFor), 'the criteria read must actually be issued');
+});
+
+await test('a criteria read that THROWS degrades to title-only ranking, never to a lost filing', async () => {
+  const got = await suggestGoalForCapture(
+    { title: 'the hall sidebar collapses on mobile', body: '' },
+    { db: fakeDb({ versions: [BUILDING], goals: [HALL_GOAL, ECON_GOAL], criteria: {}, throws: 'criteria' }) }
+  );
+  assert.ok(got, 'a bug report must survive a criteria read that fails');
+  assert.equal(got.id, 81, 'and still rank on what it can see');
+});
+
+await test('a db with NO listCriterionTextForGoals at all still works (older core, or a lean fake)', async () => {
+  const got = await suggestGoalForCapture(
+    { title: 'the hall sidebar collapses on mobile', body: '' },
+    { db: fakeDb({ versions: [BUILDING], goals: [HALL_GOAL, ECON_GOAL] }) }
+  );
+  assert.equal(got.id, 81);
+});
+
+// ---------------------------------------------------------------------------
+// a PRIVATE goal's criteria are never ranked on (task 1003859, grade round 1)
+// ---------------------------------------------------------------------------
+//
+// score + matched_terms make a ranker into a word-guessing oracle: one candidate
+// word per request tells you whether that word appears in the ranked text. The
+// suggester already exposes private goals' TITLES (GET /goals does too — a wider
+// status quo this task does not settle), but their done-when prose is a different
+// order of exposure, so the criteria read stops at the visibility line.
+
+const PRIVATE_GOAL = { id: 900, title: 'Working area 12', scope_modules: [], version_id: 'BONGOS-V2', visibility: 'private' };
+const PUBLIC_GOAL = { id: 901, title: 'Working area 13', scope_modules: [], version_id: 'BONGOS-V2', visibility: 'public' };
+
+await test('the criteria of a PRIVATE goal are never fetched — not even to rank', async () => {
+  const asked = [];
+  const db = {
+    listGoals: async () => [PRIVATE_GOAL, PUBLIC_GOAL],
+    listCriterionTextForGoals: async (ids) => { asked.push(...ids.map(String)); return new Map(); },
+  };
+  const res = fakeRes();
+  await goalSuggestHandler({ db, LIMITS: { TITLE: 200 } })(
+    { query: { version: 'BONGOS-V2', title: 'embargo' } }, res
+  );
+  assert.deepEqual(asked, ['901'], 'only the public goal may contribute criterion text');
+  assert.ok(!asked.includes('900'), 'a private goal must not be probeable one word at a time');
+});
+
+await test('a private goal still ranks on its TITLE — this narrows nothing that already worked', () => {
+  const got = suggestGoals([PRIVATE_GOAL], { title: 'working area 12' }, { versionId: 'BONGOS-V2' });
+  assert.equal(got.length, 1, 'the title-level status quo is a separate decision, left exactly as it was');
+});
+
+await test('every goal private ⇒ no criteria read is issued at all', async () => {
+  let called = 0;
+  const db = {
+    listGoals: async () => [PRIVATE_GOAL],
+    listCriterionTextForGoals: async () => { called++; return new Map(); },
+  };
+  await goalSuggestHandler({ db, LIMITS: { TITLE: 200 } })({ query: { version: 'BONGOS-V2', title: 'x y z' } }, fakeRes());
+  assert.equal(called, 0, 'a query with nothing rankable must not be issued');
+});
+
 summary();

package/tests/government_require_permission.mjs

@@ -24,6 +24,10 @@ const seams = require(path.join(ROOT, 'src', 'module-seams.js'));
 const { attachFail } = require(path.join(ROOT, 'src', 'bongos', 'middleware', 'error-envelope.js'));
 const { classify } = require(path.join(ROOT, 'src', 'bongos', 'api-errors.js'));
 const catalog = require(path.join(ROOT, 'modules', 'government', 'catalog.js'));
+// The same stripper the category guard scans with, rather than a second copy: both
+// checks are answering "which text here is executable", and two answers in one tree
+// is how one of them quietly stops agreeing with the other (task 1003832).
+const { stripComments } = require(path.join(ROOT, 'scripts', 'gds', 'category-advisory-guard.js'));
 
 // Minimal res double capturing status + body, with res.fail() installed exactly
 // as the router installs it (mirrors tests/rank_gate.mjs).
@@ -479,29 +483,101 @@ test('a throwing isOwnershipScoped does not admit and does not crash the gate',
   assert.equal(res._status, 403);
 });
 
-test('no route in the tree is gated on an ownership-scoped key today', () => {
-  // The enumeration the fix was written against, kept honest. A new gate mounted on
-  // an own-scoped atom would now 403 at runtime; this fails at BUILD time instead,
-  // naming the file, so nobody ships a route that can only ever deny.
-  const owned = catalog.permissionKeys().filter((k) => catalog.isOwnershipScoped(k));
-  const dirs = [path.join(ROOT, 'src', 'bongos', 'routes'), path.join(ROOT, 'modules')];
+// The scan, with its file list and its reader INJECTED — the shape
+// category-advisory-guard's scanGates() uses, and for the same reason. A scan run
+// only against the live tree proves nothing about what it would REFUSE, because the
+// tree is clean today by construction; and a scan that can only be run against the
+// live tree cannot be shown to ignore a comment without dirtying a real file.
+//
+// Comments are stripped before the match because a gate is a CALL. This repo's guards
+// routinely CITE the spelling they forbid — that is how the rule stays legible at the
+// site it governs — and in task 1003194 exactly such a comment reds CI, on a file whose
+// executable text was clean. Stripping makes a citation legal and judges only code.
+function scanForOwnedGates(files, read, ownedKeys) {
+  // A gate is a call: requirePermission('<key>'), in any of its spellings. Compiled
+  // once per key rather than once per (file, key) pair.
+  const patterns = ownedKeys.map((key) => [
+    key,
+    new RegExp(`requirePermission\\s*\\([^)]*['"\`]${key.replace(/\./g, '\\.')}['"\`]`),
+  ]);
   const offenders = [];
+  for (const rel of files) {
+    const src = read(rel);
+    if (src == null) continue;
+    const code = stripComments(src);
+    for (const [key, re] of patterns) {
+      if (re.test(code)) offenders.push(`${rel} :: ${key}`);
+    }
+  }
+  return offenders;
+}
+
+// ROOT-relative .js paths under `dirs`, so the reader and the offender labels speak
+// the same language the injected corpus below does.
+function jsFilesUnder(dirs) {
+  const out = [];
   const walk = (dir) => {
     if (!fs.existsSync(dir)) return;
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
       const full = path.join(dir, entry.name);
       if (entry.isDirectory()) { if (entry.name !== 'node_modules') walk(full); continue; }
-      if (!entry.name.endsWith('.js')) continue;
-      const text = fs.readFileSync(full, 'utf8');
-      for (const key of owned) {
-        // A gate is a call: requirePermission('<key>'), in any of its spellings.
-        if (new RegExp(`requirePermission\\s*\\([^)]*['"\`]${key.replace(/\./g, '\\.')}['"\`]`).test(text)) {
-          offenders.push(`${path.relative(ROOT, full)} :: ${key}`);
-        }
-      }
+      if (entry.name.endsWith('.js')) out.push(path.relative(ROOT, full));
     }
   };
   dirs.forEach(walk);
+  return out;
+}
+
+test('the own-gate scan reads a citation as prose and a call as a gate', () => {
+  // The half the live scan below cannot assert about itself. A scanner breaks by
+  // quietly finding NOTHING — a stripper that over-matches blanks the source and every
+  // file passes, which looks exactly like a clean tree. So this pins BOTH directions in
+  // one assertion: the two citations must be ignored AND the two calls must still be
+  // caught. Dropping either half is what makes the guard a green light over nothing.
+  const KEY = 'task.abandon.own';
+  const corpus = {
+    'cited-in-a-line-comment.js':
+      `// never mount requirePermission('${KEY}') here — it would admit unconditionally\n`
+      + "router.post('/a', requirePermission('task.abandon'), handler);\n",
+    'cited-in-a-block-comment.js':
+      `/*\n * requirePermission('${KEY}') cannot answer an ownership question.\n */\n`
+      + "router.post('/b', requirePermission('idea.triage'), handler);\n",
+    'a-real-gate.js': `router.post('/c', requirePermission('${KEY}'), handler);\n`,
+    // The over-strip canary: a line comment must end at its newline. If stripping ate
+    // the rest of the file this gate would vanish and the scan would report clean.
+    'a-real-gate-below-a-comment.js':
+      `// this module is documented first\nrouter.post('/d', requirePermission('${KEY}'), handler);\n`,
+    // The blind spot that failed this task's first grade. A `//` inside an ordinary
+    // STRING is not a comment, and a stripper that thinks it is erases the rest of the
+    // line — here, the live gate sitting right after it. The guard then reports clean
+    // over a real violation, which reads exactly like a clean tree.
+    'a-real-gate-after-a-string-holding-a-slash-slash.js':
+      `router.post('//legacy', requirePermission('${KEY}'), handler);\n`,
+    'a-real-gate-after-a-string-holding-a-block-open.js':
+      `const note = '/* not a comment */';\nrouter.post('/e', requirePermission('${KEY}'), handler);\n`,
+  };
+  const found = scanForOwnedGates(Object.keys(corpus), (rel) => corpus[rel], [KEY]);
+  assert.deepEqual(found.sort(), [
+    `a-real-gate-after-a-string-holding-a-block-open.js :: ${KEY}`,
+    `a-real-gate-after-a-string-holding-a-slash-slash.js :: ${KEY}`,
+    `a-real-gate-below-a-comment.js :: ${KEY}`,
+    `a-real-gate.js :: ${KEY}`,
+  ], 'a citation is documentation; a call is a gate');
+});
+
+test('no route in the tree is gated on an ownership-scoped key today', () => {
+  // The enumeration the fix was written against, kept honest. A new gate mounted on
+  // an own-scoped atom would now 403 at runtime; this fails at BUILD time instead,
+  // naming the file, so nobody ships a route that can only ever deny.
+  const owned = catalog.permissionKeys().filter((k) => catalog.isOwnershipScoped(k));
+  assert.ok(owned.length > 0, 'no ownership-scoped atoms — the scan would pass vacuously');
+  const files = jsFilesUnder([path.join(ROOT, 'src', 'bongos', 'routes'), path.join(ROOT, 'modules')]);
+  // A mis-pointed root is the other way this passes while scanning nothing, and it
+  // reads identically to a clean tree. Pin the corpus so the roots must still resolve.
+  assert.ok(files.length > 100, `expected the route corpus; scanned only ${files.length} files`);
+  const offenders = scanForOwnedGates(files, (rel) => {
+    try { return fs.readFileSync(path.join(ROOT, rel), 'utf8'); } catch { return null; }
+  }, owned);
   assert.deepEqual(offenders, [],
     'requirePermission cannot answer an ownership-scoped key — the handler must call ' +
     'authorizeOwned() with the row\'s owner instead');

package/tests/migration_allocation.mjs

@@ -168,6 +168,76 @@ function shouldReserveMigrationNumber(task) {
     }
   });
 
+  // ---- task 1003910: "schema" must be QUALIFIED to flag ------------------
+  //
+  // The live false positive (task 1003902, flagged though it alters no table) was
+  // NOT caused by the `--json-schema` flag the bug report blamed — that compound
+  // was already stripped. It was a bare back-reference later in the same
+  // paragraph. The first case below is that exact sentence, so a regression
+  // reintroducing a bare-"schema" rule fails on the wording that actually shipped
+  // the bug rather than on a paraphrase of it.
+  await test('a BARE "schema" no longer flags — the live task 1003902 wording (task 1003910)', () => {
+    const falsePositives = [
+      '`result` is EMPTY when a schema is in play, which reads as a failure if you parse the wrong field',
+      'Require a structured verdict via --json-schema',
+      'a JSON Schema for the payload',
+      'see the schema.org markup',
+      'the --output-schema flag takes a path',
+      'the worker returns a schema',
+    ];
+    for (const text of falsePositives) {
+      assert.equal(detectsMigration(text), false, `must NOT flag: ${JSON.stringify(text)}`);
+    }
+  });
+
+  await test('a DB noun or a change verb is what makes "schema" count (task 1003910)', () => {
+    const truePositives = [
+      'DB schema change',
+      'the database schema for tasks',
+      'table-schema drift',
+      'schema bump for the counter',
+      'change the schema of tasks',
+      'altering the task schema',
+    ];
+    for (const text of truePositives) {
+      assert.equal(detectsMigration(text), true, `must flag: ${JSON.stringify(text)}`);
+    }
+  });
+
+  // The direction of the failure is the point: an unrecognised phrasing must fall
+  // to NOT-flagged. A false positive reserves a migration number that is never
+  // used (task 1002614 burned 213), floors the task at Metic (ADR 0270) and halts
+  // an unattended chain; a missed one is a PATCH, the same correction a false one
+  // always needed.
+  await test('an unknown "schema" phrasing fails SAFE, not loud (task 1003910)', () => {
+    assert.equal(detectsMigration('the widget-schema thing nobody has named yet'), false);
+    assert.equal(detectsMigration('schema'), false, 'the bare noun alone decides nothing');
+  });
+
+  // A change VERB is not evidence on its own. The first cut of task 1003910's
+  // allowlist let any verb legitimise any noun, so 'update the response schema'
+  // flagged — the exact false-positive class task 1002648 fixed for the old
+  // blocklist, reintroduced by the mechanism that replaced it. The noun slot now
+  // excludes API/transport nouns, and these pin that it stays excluded.
+  await test('a change verb does NOT legitimise an API noun (task 1003910)', () => {
+    const falsePositives = [
+      'update the response schema',
+      'modify the API schema',
+      'change the request schema',
+      'updating the json schema',
+      'extend the payload schema',
+    ];
+    for (const text of falsePositives) {
+      assert.equal(detectsMigration(text), false, `must NOT flag: ${JSON.stringify(text)}`);
+    }
+  });
+
+  await test('the same verbs still flag a DB-shaped or unqualified noun (task 1003910)', () => {
+    for (const text of ['change the schema of tasks', 'alter the table schema', 'altering the task schema', 'change the schema']) {
+      assert.equal(detectsMigration(text), true, `must flag: ${JSON.stringify(text)}`);
+    }
+  });
+
   await test('classifier still flags real schema work (regression)', () => {
     const truePositives = [
       'add a migration to backfill the marker',