@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/scope-map-guard.js

@@ -0,0 +1,300 @@
+'use strict';
+
+// scripts/bongos/scope-map-guard.js — the enforcement tooling owns itself (task 1003949).
+//
+// THE DRIFT THIS STOPS. MODULE_SCOPE_MAP's `devsecops` key enumerates the
+// enforcement tooling by exact path, and the house style since fitness.js hit its
+// line ratchet is that every new check gets its OWN file beside it. Those two facts
+// disagree once per new check: the file appears, nobody adds it to the map, and
+// scopeSubset() resolves it to no module territory — so a goal scoped to devsecops
+// is refused out_of_scope for touching the very tooling it exists to own. That is
+// the same class as tasks 1002690 / 1002736 / 1003124 / 1003655, and it WIDENS with
+// every check added.
+//
+// WHY A GUARD RATHER THAN A LONGER LIST. The list was appended to this time too —
+// but a list that needs appending is the defect, not the fix. Note the evidence:
+// the task that filed this named fourteen unowned files, and fitness.js requires more than that, and the number moves
+// with every check added — which is why this reads the file instead of citing a count. The list was already stale again by the time
+// somebody wrote it down.
+//
+// WHY NOT A PREFIX OR A DIRECTORY MOVE. The scope-map format has no wildcards, so
+// owning the family by prefix means moving the guards into scripts/bongos/fitness/ —
+// and those filenames are named in workflows, skills, ADRs, session logs, the file
+// map and the docs tree (40+ files). That is a real refactor with a wide blast
+// radius, and it is deliberately NOT bundled here; this makes the drift impossible
+// first, which is what the goal wall actually needs.
+//
+// WHY THE LIST STAYS EXPLICIT. MODULE_SCOPE_MAP feeds an AUTHORIZATION decision.
+// Deriving it at runtime from a static scan of another file would mean what a goal
+// may touch depends on a regex over source text — a worse property than a list a
+// human can read. So the list stays literal and CI keeps it honest.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const FITNESS = path.join('scripts', 'bongos', 'fitness.js');
+
+// Every `require('./x.js')` in fitness.js — the files it actually runs, which is
+// the definition of "the enforcement tooling" that matters here.
+//
+// PURE, and exported, so the extraction is testable without the real file: a
+// scanner that quietly matches nothing looks exactly like a clean result, and this
+// one's whole job is to produce a non-empty set.
+// THE EXTENSION IS OPTIONAL, and requiring it was a real gap (grade round 1). Node
+// resolves `require('./run-routine')` to run-routine.js, and fitness.js writes FOUR of
+// its sibling requires that way — gen-api-docs, migration-namespace, run-routine,
+// skill-lint. A pattern anchored on `.js` found none of them, so four check files
+// stayed unowned while this guard reported the set clean.
+//
+// That is the failure shape this file exists to end, committed by the guard itself: a
+// scan that matches less than it should reports a healthy repo, and healthy is exactly
+// what a broken scan looks like.
+function siblingRequires(source) {
+  const out = new Set();
+  for (const m of String(source || '').matchAll(/require\(['"]\.\/([A-Za-z0-9._-]+?)(\.js)?['"]\)/g)) {
+    out.add(`scripts/bongos/${m[1]}.js`);
+  }
+  return [...out].sort();
+}
+
+// PURE — which of those files no module key claims. A DIRECTORY entry owns everything
+// beneath it, which is why `dirs` is a parameter rather than something the caller
+// pre-filters: forgetting it would report every file under an owned directory as
+// unowned.
+function unownedBy(siblings, ownedPaths, dirs = []) {
+  const owned = new Set(ownedPaths);
+  return siblings.filter((p) => !owned.has(p) && !dirs.some((d) => p.startsWith(d)));
+}
+
+function checkDevsecopsOwnsItsChecks() {
+  const name = 'the enforcement tooling owns itself (task 1003949)';
+  const src = fs.readFileSync(path.join(REPO_ROOT, FITNESS), 'utf8');
+  const siblings = siblingRequires(src);
+
+  // A scanner that finds nothing passes for free. fitness.js is BUILT out of
+  // sibling requires, so an empty set means the pattern broke, not that the tooling
+  // became self-contained — this check must not be able to pass vacuously.
+  if (siblings.length === 0) {
+    return {
+      name,
+      ok: false,
+      hardFail: true,
+      violations: [`${FITNESS}: found NO sibling require() calls. That is a broken scan, not a `
+        + 'clean result — the extraction pattern in scope-map-guard.js needs looking at.'],
+      warnings: [],
+      note: 'the scan produced an empty set, which cannot be right.',
+    };
+  }
+
+  const { MODULE_SCOPE_MAP } = require('../../src/bongos/module-scope-map.js');
+  // Each value is { globs: [...], protected?: bool } — not a bare array.
+  const globsOf = (v) => (Array.isArray(v) ? v : (v && v.globs) || []);
+  const allOwned = [];
+  for (const v of Object.values(MODULE_SCOPE_MAP)) allOwned.push(...globsOf(v));
+  // Any key may own a check file — what matters is that SOME key does, so a goal can
+  // be scoped to it. A directory entry owns everything beneath it.
+  const dirs = allOwned.filter((p) => p.endsWith('/'));
+  const owned = new Set(allOwned);
+  // Through the exported helper rather than a second inline copy of the same filter:
+  // two spellings of one rule is how the enumerated list this guard polices drifted in
+  // the first place.
+  const unowned = unownedBy(siblings, allOwned, dirs);
+
+  const violations = unowned.map((p) => `${p} is required by ${FITNESS} but no MODULE_SCOPE_MAP key `
+    + 'owns it — scopeSubset() resolves it to no territory, so a goal scoped to devsecops is denied '
+    + 'out_of_scope for touching the tooling it exists to own. Add it to the devsecops key.');
+
+  return {
+    name,
+    ok: unowned.length === 0,
+    hardFail: unowned.length > 0,
+    violations,
+    warnings: [],
+    // Printed on the PASS path too: the count is the evidence the scan ran at all.
+    note: `${siblings.length} file(s) required by ${FITNESS}, all owned by a MODULE_SCOPE_MAP key. `
+      + 'The house style gives each new check its own file, so this list drifts once per check '
+      + 'unless CI says otherwise (task 1003949).',
+  };
+}
+// PURE — every module directory on disk, by key. A module is a modules/<key>/ dir
+// carrying module.json (the ADR 0083 manifest), which is the same structural test
+// the loader's discoverModules() uses: a key is what has a manifest, never a
+// hand-kept roster. Exported so the scan is testable against a fixture tree —
+// an empty result here looks identical to a clean repo, which is the failure the
+// sibling check above exists to refuse.
+function moduleDirsOnDisk(modulesRoot) {
+  let entries = [];
+  try { entries = fs.readdirSync(modulesRoot, { withFileTypes: true }); } catch { return []; }
+  return entries
+    .filter((e) => e.isDirectory() && fs.existsSync(path.join(modulesRoot, e.name, 'module.json')))
+    .map((e) => e.name)
+    .sort();
+}
+
+// A carved module whose own directory no MODULE_SCOPE_MAP key claims (task 1004132).
+//
+// THE DRIFT THIS STOPS, and it is the sibling of the check above rather than a new
+// idea: modules/specialities/ shipped a full module — manifest, db slice, routes, two
+// migrations — with no key here at all. scopeSubset() therefore resolved every file in
+// it to no territory, so a goal scoped to `specialities` was refused out_of_scope for
+// touching the module it is named after. It was the ONLY on-disk module in that state,
+// which is exactly why nobody noticed: 21 of 22 were fine.
+//
+// The rule is deliberately narrow. It does NOT require every repo path to have an
+// owner — src/, scripts/ and bin/ are unowned ON PURPOSE (ADR 0086: a goal grants
+// authority BOUNDED to module territory, and POST /tasks stays Archon-only for
+// ungoverned creation), so a broader "every root is owned" check would encode the
+// opposite of the design. What must hold is narrower and absolute: if a directory
+// declares itself a module, a goal must be able to be scoped to it.
+function checkEveryModuleDirIsScoped() {
+  const name = 'every carved module owns its own directory (task 1004132)';
+  const dirs = moduleDirsOnDisk(path.join(REPO_ROOT, 'modules'));
+
+  // Same anti-vacuity rule as the check above: this repo HAS modules, so an empty
+  // scan means the manifest test broke, not that the tree is clean.
+  if (dirs.length === 0) {
+    return {
+      name,
+      ok: false,
+      hardFail: true,
+      violations: ['modules/: found NO directory carrying a module.json. That is a broken scan, '
+        + 'not a clean result — moduleDirsOnDisk() in scope-map-guard.js needs looking at.'],
+      warnings: [],
+      note: 'the scan produced an empty set, which cannot be right.',
+    };
+  }
+
+  const { MODULE_SCOPE_MAP } = require('../../src/bongos/module-scope-map.js');
+  const globsOf = (v) => (Array.isArray(v) ? v : (v && v.globs) || []);
+  const claimed = new Set();
+  for (const v of Object.values(MODULE_SCOPE_MAP)) {
+    // A key may claim another module's dir (a cross-cutting owner), so collect every
+    // modules/<key>/ glob from EVERY key rather than only from the same-named one.
+    for (const g of globsOf(v)) {
+      const m = /^modules\/([^/]+)\/$/.exec(g);
+      if (m) claimed.add(m[1]);
+    }
+  }
+
+  const unscoped = dirs.filter((k) => !claimed.has(k));
+  const violations = unscoped.map((k) => `modules/${k}/ carries a module.json but no MODULE_SCOPE_MAP `
+    + `key claims it — scopeSubset() resolves the whole module to no territory, so a goal scoped to `
+    + `'${k}' is denied out_of_scope for touching the module it is named after. Add a '${k}' key `
+    + `owning 'modules/${k}/'.`);
+
+  return {
+    name,
+    ok: unscoped.length === 0,
+    hardFail: unscoped.length > 0,
+    violations,
+    warnings: [],
+    note: `${dirs.length} carved module(s) on disk, each claimed by a MODULE_SCOPE_MAP key.`,
+  };
+}
+
+// PURE — every tracked top-level root, as `name` or `name/`. Exported so the scan
+// is testable against a fixture list rather than only against this repo.
+function trackedRoots(files) {
+  const out = new Set();
+  for (const f of files || []) {
+    if (!f) continue;
+    const i = f.indexOf('/');
+    out.add(i === -1 ? f : `${f.slice(0, i)}/`);
+  }
+  return [...out].sort();
+}
+
+// PURE — does ANY glob reach into this root? A root is "carved" the moment one
+// does; src/ and scripts/ are partially owned and that is the normal in-progress
+// state ADR 0086 §4 describes ("auto-tightens as ADR 0083 moves code into
+// modules/<key>/"). What this answers is the narrower question: is this root
+// territory the scope map has never heard of at all?
+function rootIsTouched(root, globs) {
+  return (globs || []).some((g) => g === root || g.startsWith(root) || root.startsWith(g));
+}
+
+// New unowned territory, and stale entries in the record of the old (task 1004132).
+//
+// THE GAP THIS CLOSES, and it is the one the grade round caught me leaving open.
+// I had argued that because the core is unowned BY DESIGN (ADR 0086: authority is
+// bounded to module territory, POST /tasks stays Archon-only for ungoverned
+// creation), no general check should exist. That is half right and wholly
+// insufficient: the design says WHICH roots may be unowned, it does not stop the
+// set growing. Without this, a new top-level directory lands tomorrow, no module
+// claims it, and nothing anywhere fails — the exact shape that let
+// modules/specialities/ sit unowned for its whole life.
+//
+// So the decision is recorded as DATA (UNOWNED_ROOTS in module-scope-map.js) and
+// this check enforces it in BOTH directions, the discipline
+// tests/host_topology_skips.mjs uses for its own allowlist:
+//   - a root that is neither carved nor listed  -> new territory, fail
+//   - a listed root that is now carved or gone  -> stale entry, fail
+// A one-directional check would let the list rot into a rubber stamp.
+function checkNoNewUnownedRoot(fileList) {
+  const name = 'no new unowned top-level root (task 1004132)';
+  let files = fileList;
+  if (!files) {
+    files = require('node:child_process')
+      .execFileSync('git', ['ls-files'], { cwd: REPO_ROOT, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 })
+      .trim().split('\n').filter(Boolean);
+  }
+  const roots = trackedRoots(files);
+
+  // Same anti-vacuity rule as its two siblings: this repo HAS tracked files, so an
+  // empty scan is a broken `git ls-files`, not a clean tree.
+  if (roots.length === 0) {
+    return {
+      name,
+      ok: false,
+      hardFail: true,
+      violations: ['git ls-files returned NO tracked files. That is a broken scan, not a clean '
+        + 'result — trackedRoots() in scope-map-guard.js needs looking at.'],
+      warnings: [],
+      note: 'the scan produced an empty set, which cannot be right.',
+    };
+  }
+
+  const map = require('../../src/bongos/module-scope-map.js');
+  const globs = [...map.globsForModules(map.moduleKeys()), ...map.SHARED_GLOBS];
+  const listed = map.UNOWNED_ROOTS || {};
+
+  const violations = [];
+  for (const r of roots) {
+    if (rootIsTouched(r, globs)) {
+      if (Object.prototype.hasOwnProperty.call(listed, r)) {
+        violations.push(`'${r}' is listed in UNOWNED_ROOTS but a module glob now reaches it — the `
+          + 'entry is stale. Delete it; a root leaving that list is the map tightening as intended.');
+      }
+      continue;
+    }
+    if (!Object.prototype.hasOwnProperty.call(listed, r)) {
+      violations.push(`'${r}' is tracked but NO module glob and no SHARED_GLOBS entry reaches it, and `
+        + 'it is not in UNOWNED_ROOTS. New unowned territory: no goal can ever authorize a task that '
+        + `touches it. Give it an owning module, or add it to UNOWNED_ROOTS in module-scope-map.js `
+        + 'with the reason it has none.');
+    }
+  }
+  for (const r of Object.keys(listed)) {
+    if (!roots.includes(r)) {
+      violations.push(`UNOWNED_ROOTS lists '${r}', which is not a tracked root any more — stale entry, `
+        + 'delete it so the list keeps meaning something.');
+    }
+  }
+
+  return {
+    name,
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: `${roots.length} tracked root(s); ${Object.keys(listed).length} recorded as deliberately `
+      + 'unowned (ADR 0086 — core is Archon territory). Shrink-only: an entry may leave, not appear silently.',
+  };
+}
+
+module.exports = {
+  checkDevsecopsOwnsItsChecks, siblingRequires, unownedBy, FITNESS,
+  checkEveryModuleDirIsScoped, moduleDirsOnDisk,
+  checkNoNewUnownedRoot, trackedRoots, rootIsTouched,
+};

package/scripts/bongos/scope-roster-guard.js

@@ -0,0 +1,118 @@
+// scripts/bongos/scope-roster-guard.js
+//
+// WHAT. The fitness check behind the module scope roster (task 1002900): every module
+// discovered at modules/<key>/module.json must have a covering key in MODULE_GLOBS
+// (src/bongos/module-scope-map.js).
+//
+// WHY IT IS A HARD FAIL, when the runtime symptom is a denial rather than a crash.
+// The roster is maintained by HAND. A module lands, nobody adds the entry, and any goal
+// scoped to that work hits an authorize-NOTHING wall: goal-scope-check.check() denies
+// with empty_scope / unknown_scope. Nothing announces it — it surfaces only when someone
+// tries to set a goal's wall and cannot, which is long after the module landed and far
+// from the edit that caused it. CI is the only place the gap is visible at the moment it
+// is created.
+//
+// It has happened three times by hand: task 1002690 (provisioning + public-landing,
+// goal 1000059), task 1002322 (platform-identity, goal 1000046) and `agents`, the
+// instance this check was filed for. Each was fixed after someone tripped over it.
+//
+// WHY SUBSET AND NOT EQUALITY. The roster legitimately carries keys with no
+// modules/<key>/ directory, for two different reasons, and equality would fail on all
+// five of them in this tree:
+//   - NON-MODULE SCOPES — `kernel`, `methodology`, `devsecops` are surfaces, not modules.
+//   - ABSENT MODULES — `art-pipeline`, `game` are rostered but not present in this
+//     instance (ADR 0108: a host may carry a different module set).
+// So the invariant is one-directional: every DISCOVERED module must be rostered; a
+// rostered key with no module is not a fault. Getting that backwards would produce a
+// check nobody can keep green, which is worse than no check.
+//
+// Extracted from fitness.js (which the size ratchet caps) following the
+// role-pack-guard.js precedent. The pure scanner is exported for tests/fitness_scope_roster.mjs.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// The machinery already existed — fitness.js's discoveredModuleKeys() feeds the
+// kernel-machinery check — but nothing cross-checked it against moduleKeys().
+// checkScopeMapImportsProtected guards HOW `protected` is derived, not WHETHER every
+// module is listed.
+
+// SCOPE: modules/ ONLY — the two named orphans, decided rather than left open.
+// Task 1002900 asked for a ruling on two files said to be covered by no glob. Both
+// answers changed when checked against origin/main on 2026-09-22:
+//   - scripts/bongos/fitness.js  — NOT uncovered. The `devsecops` key matches it. The row's
+//                               claim was stale.
+//   - src/server.js           — does not exist any more.
+//   - src/platform-server.js  — genuinely uncovered, and DELIBERATELY still is.
+// This check asserts what its name says: every carved MODULE has a roster key. Widening
+// it to arbitrary src/ entrypoints is a different question about a different registry —
+// `kernel` lists individual files by hand, so "should platform-server join it" is a call
+// for whoever owns that scope, not a side effect of adding a module-coverage lint. Left
+// as a recorded decision rather than an exemption entry, because there is nothing to
+// exempt: modules/ is the stated scope and platform-server.js was never in it.
+
+const SCOPE_ROSTER_REL = 'src/bongos/module-scope-map.js';
+
+function scanScopeRosterCoverage({ discovered, rostered, globs, exists }) {
+  const missing = discovered.filter((k) => !rostered.includes(k)).sort();
+  const violations = missing.map((k) =>
+    `module '${k}' (modules/${k}/module.json) has no key in ${SCOPE_ROSTER_REL} MODULE_GLOBS — `
+    + 'any goal scoped to it will deny with empty_scope/unknown_scope');
+
+  // The mirror-image rot, reported as a WARNING rather than a failure: a roster glob that
+  // names an exact FILE which no longer exists. It cannot wall anything off, so it is a
+  // silent hole in a scope rather than a build breakage — and unlike a missing key it has
+  // no runtime symptom at all. Only exact file paths are checked; a directory glob may
+  // legitimately point at an absent optional module (see SUBSET above).
+  const warnings = [];
+  for (const [key, list] of Object.entries(globs || {})) {
+    for (const g of list || []) {
+      if (g.endsWith('/') || g.includes('*')) continue;
+      if (!exists(g)) warnings.push(`${SCOPE_ROSTER_REL}: scope '${key}' lists '${g}', which does not exist — dead entry, walls nothing`);
+    }
+  }
+  return { violations, warnings };
+}
+
+// REPO_ROOT and discoveredModuleKeys come from fitness.js, which owns module discovery
+// (it unions across MODULE_ROOTS per ADR 0108). Passed in rather than re-derived so the
+// two can never disagree about what a module is.
+function checkScopeRosterCoversModules({ repoRoot, discoveredModuleKeys }) {
+  let res;
+  try {
+    const scopeMap = require(path.join(repoRoot, SCOPE_ROSTER_REL));
+    res = scanScopeRosterCoverage({
+      discovered: discoveredModuleKeys(),
+      rostered: scopeMap.moduleKeys(),
+      globs: scopeMap.MODULE_GLOBS,
+      exists: (g) => fs.existsSync(path.join(repoRoot, g)),
+    });
+  } catch (e) {
+    // FAILS OPEN, deliberately and narrowly. This catch fires only if requiring the scope
+    // map throws — i.e. the file is syntactically broken — and that is not this check's
+    // job to report: src/bongos/module-scope-map.js has its own unit coverage, and every
+    // sibling scope check (checkScopeMapImportsProtected, the ownership checks) would red
+    // on the same input. A coverage lint that hard-fails on someone else's syntax error
+    // adds a second confusing message to a build that is already failing for the real
+    // reason. The skip is surfaced as a warning rather than swallowed.
+    return {
+      name: 'every discovered module has a scope-roster key (task 1002900)',
+      ok: true, hardFail: false, violations: [], warnings: [`skipped: ${e.message}`],
+      note: `could not load ${SCOPE_ROSTER_REL} — check skipped.`,
+    };
+  }
+  return {
+    name: 'every discovered module has a scope-roster key (task 1002900)',
+    ok: res.violations.length === 0,
+    hardFail: res.violations.length > 0,
+    violations: res.violations,
+    warnings: res.warnings,
+    note: `every modules/<key>/ carrying module.json has a MODULE_GLOBS entry, so a goal can be `
+      + `scoped to it. Subset, not equality: a rostered key with no module is legitimate `
+      + `(non-module scopes like kernel/methodology/devsecops, and modules absent from this instance).`,
+  };
+}
+
+module.exports = { checkScopeRosterCoversModules, scanScopeRosterCoverage, SCOPE_ROSTER_REL };