@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/route-shadow-guard.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+// scripts/bongos/route-shadow-guard.js — a `:param` route must not swallow a LITERAL
+// route mounted after it (task 1003747).
+//
+// THE BUG THIS EXISTS TO STOP. `GET /inbox/rotting` — the rot feed behind the
+// hall's "Going quiet" section (modules/lifecycle/routes/rot.js) — answered
+// `400 bad_id` in production for releases. Nothing was wrong with the handler: it
+// was never reached. `mountModuleRoutes` (src/module-loader/loader.js) mounts each
+// enabled module's route factories in DISCOVERY order, so `ideas` mounted its
+// `GET /inbox/:id` before `lifecycle` mounted `GET /inbox/rotting`; Express matched
+// the param route first, failed to parse "rotting" as an id, and ended the request.
+// The entire 30-day rot cadence (ADR 0232 — "work must not decay in silence") was
+// dead, and its only caller swallowed the error, so the section rendered empty and
+// looked healthy.
+//
+// WHY A FITNESS CHECK AND NOT A TEST. The collision is a property of the MOUNT
+// ORDER ACROSS MODULES, which no single module's tests can see — each module's
+// routes are correct in isolation, and modules/ideas/CLAUDE.md's "declare literals
+// before :id" convention only governs collisions inside one file. The defect only
+// exists in the assembled router, and it presents as a plausible 400 rather than a
+// crash, so nothing goes red. A static scan at the assembly altitude is the only
+// place this is visible before a user reports an empty page.
+//
+// WHAT COUNTS AS SHADOWING. Same HTTP method, same segment count, every segment
+// equal up to one position where the earlier route has a `:param` and the later
+// route has a literal. Same-arity is required because Express only matches a
+// pattern against a path of equal depth (no wildcards are in play here), and the
+// param must sit where the literal is or the two never compete.
+//
+// THE FIX IT POINTS AT. Constrain the param so a non-numeric segment falls
+// THROUGH — `router.get('/inbox/:id(\\d+)', …)` — which works regardless of mount
+// order. Reordering declarations is NOT a general fix: it cannot reach a route
+// another module contributes.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const NAME = 'no `:param` route shadows a literal route mounted after it (task 1003747)';
+
+// Route declarations, as written. Matches the `router.<method>('<path>'` form every
+// route factory in this repo uses.
+const ROUTE_DECL = /router\.(get|post|patch|put|delete)\(\s*['"`]([^'"`]+)['"`]/g;
+
+// A param segment already constrained by an inline Express pattern — `:id(\d+)` —
+// cannot match a non-matching literal, so it shadows nothing. Recognising this is
+// what makes the check pass once the fix is applied rather than demanding a
+// reorder it cannot verify.
+function isConstrainedParam(seg) {
+  return seg.startsWith(':') && seg.includes('(');
+}
+
+function isBareParam(seg) {
+  return seg.startsWith(':') && !seg.includes('(');
+}
+
+// The mount sequence: for each module with a module.json, its contributes.routes in
+// declared order, and within each file its route declarations in source order. This
+// mirrors mountModuleRoutes' iteration — modules in readdir order, route keys in
+// manifest order — so the sequence this returns is the order Express sees.
+function mountSequence({ modulesDir, readdir, readFile } = {}) {
+  const md = modulesDir || path.join(REPO_ROOT, 'modules');
+  const rd = readdir || ((d) => { try { return fs.readdirSync(d); } catch { return []; } });
+  const read = readFile || ((f) => { try { return fs.readFileSync(f, 'utf8'); } catch { return null; } });
+  const seq = [];
+  for (const key of rd(md)) {
+    const manRaw = read(path.join(md, key, 'module.json'));
+    if (manRaw == null) continue;
+    let man;
+    try { man = JSON.parse(manRaw); } catch { continue; }
+    for (const rk of ((man.contributes || {}).routes) || []) {
+      const rel = path.join('modules', key, 'routes', `${rk}.js`);
+      const src = read(path.join(md, key, 'routes', `${rk}.js`));
+      if (src == null) continue;
+      ROUTE_DECL.lastIndex = 0;
+      let m;
+      while ((m = ROUTE_DECL.exec(src))) {
+        seq.push({ module: key, file: rel, method: m[1], route: m[2] });
+      }
+    }
+  }
+  return seq;
+}
+
+const segments = (p) => p.split('/').filter(Boolean);
+
+// findShadowPairs(seq) — every (param route, later literal route) pair where the
+// param route wins the match. Pure + exported so tests pin the rule without a
+// filesystem.
+function findShadowPairs(seq) {
+  const pairs = [];
+  for (let i = 0; i < seq.length; i += 1) {
+    const early = seq[i];
+    const a = segments(early.route);
+    if (!a.some(isBareParam)) continue;
+    for (let j = i + 1; j < seq.length; j += 1) {
+      const later = seq[j];
+      const b = segments(later.route);
+      if (early.method !== later.method || a.length !== b.length) continue;
+      let shadows = true;
+      let viaParam = false;
+      for (let k = 0; k < a.length; k += 1) {
+        if (isBareParam(a[k])) {
+          // A param only eats a LITERAL. Two params at the same position are the
+          // same route shape, not a shadowing pair.
+          if (b[k].startsWith(':')) { shadows = false; break; }
+          viaParam = true;
+        } else if (isConstrainedParam(a[k])) {
+          shadows = false; // constrained: it cannot match an arbitrary literal
+          break;
+        } else if (a[k] !== b[k]) {
+          shadows = false;
+          break;
+        }
+      }
+      if (shadows && viaParam) pairs.push({ early, later });
+    }
+  }
+  return pairs;
+}
+
+function checkNoRouteShadowing(opts = {}) {
+  const seq = opts.sequence || mountSequence(opts);
+  if (!seq.length) {
+    return {
+      name: NAME,
+      ok: false,
+      hardFail: true,
+      violations: ['scan defect — enumerated 0 route declarations across modules/*/routes; '
+        + 'a broken enumeration, not a clean result.'],
+      warnings: [],
+      note: 'static scan of the cross-module route mount order.',
+    };
+  }
+  const pairs = findShadowPairs(seq);
+  const violations = pairs.map(({ early, later }) => (
+    `${early.method.toUpperCase()} ${early.route} (${early.file}) is mounted BEFORE `
+    + `${later.method.toUpperCase()} ${later.route} (${later.file}) and swallows it — `
+    + `a request for ${later.route} never reaches its handler. `
+    + `Constrain the param so a non-matching segment falls through `
+    + `(e.g. '${early.route.replace(/:(\w+)(?![\w(])/, ':$1(\\\\d+)')}'); reordering cannot fix a `
+    + 'cross-module pair, because mount order follows module discovery.'
+  ));
+  return {
+    name: NAME,
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: `${seq.length} route declaration(s) scanned in mount order: no bare \`:param\` route may `
+      + 'precede a literal route of the same method and depth. The rot feed shipped dead for releases '
+      + 'this way (GET /inbox/:id ate GET /inbox/rotting across a module boundary) and presented as a '
+      + 'plausible 400, so no test went red.',
+  };
+}
+
+function main() {
+  const r = checkNoRouteShadowing();
+  for (const v of r.violations) console.error(`✗ ${v}`);
+  console.log(`${r.hardFail ? 'FAIL' : 'PASS'}  ${r.note}`);
+  process.exit(r.hardFail ? 1 : 0);
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  checkNoRouteShadowing,
+  findShadowPairs,
+  mountSequence,
+  isBareParam,
+  isConstrainedParam,
+  ROUTE_DECL,
+};

package/scripts/bongos/routine-schedule.js

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+// scripts/bongos/routine-schedule.js — a declared cadence must have something that
+// fires it (task 1003209, goal 1000079; docs/audits/ai-dev-redteam-followup.md §7).
+//
+// THE GAP THIS CLOSES. Goal 1000076 shipped the redteam-weekly patrol, wired it
+// into the control manifest, and documented it — and then nothing ever ran it.
+// The follow-up audit's §7 named all three halves of the failure:
+//
+//   1. no committed scheduler for .claude/scheduled-tasks/ at all;
+//   2. the SKILL.md declared `mode` and `steps` but no cadence — "nothing for a
+//      scheduler to read even if one looked";
+//   3. control-manifest.js called the patrol "wired" on a substring (the SKILL.md
+//      mentions its own scanner), so the manifest was GREEN while the patrol was
+//      dormant.
+//
+// (2) is now a real frontmatter field (run-routine.js parseRoutineFrontmatter),
+// (1) is .github/workflows/redteam-patrol.yml, and THIS file is (3): the check
+// that refuses the combination of a declared cadence and nothing firing it.
+//
+// WHY A DEDICATED CHECK RATHER THAN ANOTHER MANIFEST ROW. The manifest's
+// predicates are deliberately shallow — file exists, one wiring substring. That
+// shape is exactly what let the patrol read as wired while dormant, and this goal
+// has now hit the same failure five times: an enforcement surface that NAMES a
+// file goes VACUOUS, not red, when the thing it names moves or stops. So the
+// predicate here is relational, not existential: it reads the cadence each
+// routine declares, reads the cron each scheduler actually carries, and fails
+// when the two disagree in EITHER direction —
+//
+//   • a routine declares `cadence:` and no scheduler fires it   → red
+//   • a scheduler fires a routine that no longer exists         → red (rename rot)
+//   • the cron's real period differs from the declared cadence  → red
+//
+// The third is the one a substring check can never catch: edit the cron from
+// weekly to yearly and every "is it wired?" predicate stays green.
+//
+// TWO-REPO TOLERANCE. Scheduled routines are TOPOLOGY — `bongos init/upgrade`
+// materializes .claude/scheduled-tasks/ into each instance (claude-materialize.js),
+// but .github/workflows/ is the CORE repo's and does not travel. So an instance
+// checkout legitimately has routines and no workflows directory. There, the
+// unscheduled routines are reported as WARNINGS (the instance's operator owns its
+// own scheduler); in a repo that HAS workflows, they are violations. That keeps
+// the check honest in the core without red-building every instance.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const TASKS_DIR = path.join(ROOT, '.claude', 'scheduled-tasks');
+const WORKFLOWS_DIR = path.join(ROOT, '.github', 'workflows');
+
+const { parseRoutineFrontmatter } = require('./run-routine.js');
+
+// The NAMED cadences a routine may declare. The value is the period a cron
+// expression must resolve to for the two to agree. Add a name here and
+// cronCadence() below must be able to produce it, or the pair can never match.
+const CADENCES = new Set(['hourly', 'daily', 'weekly', 'monthly']);
+
+// Sub-hourly cadences are open-ended rather than enumerated: '15min', '5min',
+// '30min'. Task 1003674 found the vocabulary topped out at `hourly`, so a
+// routine an operator wants to fire every 15 minutes could not SAY so — the
+// step cron that realizes it classified as unclassifiable and hard-failed the
+// check, which left "declare nothing and stay dormant" as the only green
+// option. That is the exact failure mode this file exists to refuse.
+//
+// N MUST DIVIDE 60. A cron step restarts each hour, so only a divisor of 60
+// yields a genuinely uniform period: `*/15` fires at :00 :15 :30 :45 (every 15
+// minutes, always), but `*/7` fires at :00 …:56 and then waits 4 — a "7min"
+// cadence that is not one. Refusing the non-divisors keeps the declared period
+// and the realized period the same claim.
+const SUBHOURLY_RE = /^([1-9]\d*)min$/;
+
+// The one definition of "is N a real sub-hourly period" — both the cadence NAME
+// ('15min') and the cron STEP (*/15) are validated through here, so the two can
+// never drift apart and disagree about the same number.
+function isUniformDivisor(n) {
+  return Number.isInteger(n) && n > 0 && n < 60 && 60 % n === 0;
+}
+
+function subhourlyMinutes(name) {
+  const m = SUBHOURLY_RE.exec(String(name == null ? '' : name));
+  if (!m) return null;
+  const n = Number(m[1]);
+  return isUniformDivisor(n) ? n : null;
+}
+
+// The validity predicate the check asks. Kept separate from CADENCES so the
+// named set stays a plain enumerable list for the error message.
+function isCadence(name) {
+  return CADENCES.has(name) || subhourlyMinutes(name) !== null;
+}
+
+// The minute-field step spelling, hoisted so it is compiled once rather than per
+// classified cron: `*/15` and the equivalent `0/15`.
+const STEP_RE = /^(?:\*|0)\/([1-9]\d*)$/;
+
+// Pure: classify a 5-field cron expression into the cadence it actually realizes.
+// Returns null for anything this vocabulary cannot describe (step values, lists,
+// ranges) — a cadence can then never "match" it, which is the safe direction: an
+// exotic cron must be described some other way rather than silently accepted.
+//
+//   min hour dom mon dow
+//   17   6    *   *   1   → weekly   (a specific day-of-week)
+//   17   6    *   *   *   → daily    (a specific hour, every day)
+//   17   6    3   *   *   → monthly  (a specific day-of-month)
+//   17   *    *   *   *   → hourly   (a specific minute, every hour)
+//   */15 *    *   *   *   → 15min    (a uniform sub-hourly step)
+function cronCadence(expr) {
+  const f = String(expr == null ? '' : expr).trim().split(/\s+/);
+  if (f.length !== 5) return null;
+  const [min, hour, dom, mon, dow] = f;
+  const fixed = (v) => /^\d+$/.test(v);
+  const any = (v) => v === '*';
+
+  // Sub-hourly: a step in the minute field with every coarser field wide open.
+  // (STEP_RE is module-scope — see above.)
+  // Anything narrower (a step confined to one hour, or to weekdays) is NOT the
+  // period it looks like, so it stays unclassifiable.
+  const step = STEP_RE.exec(min);
+  if (step) {
+    if (!(any(hour) && any(dom) && any(mon) && any(dow))) return null;
+    const n = Number(step[1]);
+    return isUniformDivisor(n) ? `${n}min` : null;
+  }
+
+  if (!fixed(min)) return null;          // every cadence below pins the minute
+  if (!any(mon)) return null;            // a specific month is a yearly shape
+  if (any(hour)) return any(dom) && any(dow) ? 'hourly' : null;
+  if (!fixed(hour)) return null;
+  if (fixed(dow) && any(dom)) return 'weekly';
+  if (fixed(dom) && any(dow)) return 'monthly';
+  if (any(dom) && any(dow)) return 'daily';
+  return null;
+}
+
+// Pure: every cron expression a workflow file declares under `on: schedule:`.
+// A focused subset of YAML (the repo has no js-yaml dep and the parser in
+// run-routine.js is the same shape): the `cron:` keys are unambiguous enough to
+// read directly, and a workflow that hides one behind an anchor would simply
+// read as unscheduled — the safe direction.
+function workflowCrons(yamlText) {
+  const out = [];
+  for (const line of String(yamlText == null ? '' : yamlText).split('\n')) {
+    const m = /^\s*-?\s*cron:\s*['"]?([^'"#\n]+?)['"]?\s*(?:#.*)?$/.exec(line);
+    if (m) out.push(m[1].trim());
+  }
+  return out;
+}
+
+// Pure: does `yamlText` actually invoke routine `name`? Either the canonical
+// dispatcher form (`run-routine.js <name>`) or one of the routine's own step
+// commands verbatim. Both are real invocations; a mere mention in prose is not,
+// which is the whole point — the substring predicate this replaces was satisfied
+// by a comment.
+function invokesRoutine(yamlText, name, steps = []) {
+  const hay = String(yamlText == null ? '' : yamlText);
+  const dispatched = new RegExp(`run-routine\\.js\\s+(?:--\\S+\\s+)*${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\w-])`);
+  if (dispatched.test(hay)) return true;
+  return steps.some((s) => s.command && hay.includes(s.command));
+}
+
+// Read every routine that declares a cadence, plus the ones that don't.
+function readRoutines(dir = TASKS_DIR) {
+  const withCadence = [];
+  const withoutCadence = [];
+  let names = [];
+  try {
+    names = fs.readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
+  } catch (_) { return { withCadence, withoutCadence }; }
+  for (const name of names.sort()) {
+    let md;
+    try { md = fs.readFileSync(path.join(dir, name, 'SKILL.md'), 'utf8'); } catch (_) { continue; }
+    const { cadence, steps } = parseRoutineFrontmatter(md);
+    if (cadence) withCadence.push({ name, cadence, steps });
+    else withoutCadence.push({ name });
+  }
+  return { withCadence, withoutCadence };
+}
+
+function readWorkflows(dir = WORKFLOWS_DIR) {
+  let files = [];
+  try { files = fs.readdirSync(dir).filter((f) => f.endsWith('.yml') || f.endsWith('.yaml')); }
+  catch (_) { return null; } // null = no workflows directory at all (instance repo)
+  return files.sort().map((f) => ({ file: f, text: fs.readFileSync(path.join(dir, f), 'utf8') }));
+}
+
+// Pure evaluation — exported for the test, which drives it with fixtures.
+// `workflows === null` means "this checkout has no CI to schedule with", which
+// downgrades unscheduled routines from violations to warnings (see the two-repo
+// note in the header).
+function evaluate({ withCadence, withoutCadence }, workflows) {
+  const violations = [];
+  const warnings = [];
+  const hasCI = workflows !== null;
+  const wf = workflows || [];
+
+  for (const r of withCadence) {
+    if (!isCadence(r.cadence)) {
+      violations.push(`routine '${r.name}': unknown cadence "${r.cadence}" (want ${[...CADENCES].join('|')}, or <N>min where N divides 60)`);
+      continue;
+    }
+    const firing = wf.filter((w) => invokesRoutine(w.text, r.name, r.steps));
+    if (!firing.length) {
+      const msg = `routine '${r.name}' declares cadence: ${r.cadence} but NOTHING fires it — no scheduled workflow invokes it`;
+      (hasCI ? violations : warnings).push(msg);
+      continue;
+    }
+    // It is invoked somewhere. At least one of those invocations must be on a
+    // schedule whose real period is the declared cadence. A workflow_dispatch-only
+    // lane is a human running it — exactly the state §7 called "decorative".
+    const seen = [];
+    let matched = false;
+    for (const w of firing) {
+      for (const expr of workflowCrons(w.text)) {
+        const actual = cronCadence(expr);
+        seen.push(`${w.file}: "${expr}" → ${actual || 'unclassifiable'}`);
+        if (actual === r.cadence) matched = true;
+      }
+    }
+    if (!matched) {
+      violations.push(
+        seen.length
+          ? `routine '${r.name}' declares cadence: ${r.cadence} but no scheduler fires it at that period — ${seen.join('; ')}`
+          : `routine '${r.name}' declares cadence: ${r.cadence} but ${firing.map((w) => w.file).join(', ')} carries no 'on: schedule:' cron (manual dispatch only)`
+      );
+    }
+  }
+
+  // Rename rot, the other direction: a scheduler that dispatches a routine name
+  // no longer on disk. run-routine.js exits 2 on a missing SKILL.md, so this
+  // would be a weekly red job nobody watches; catch it at merge time instead.
+  // Deduped: a workflow legitimately names its own invocation more than once (the
+  // step itself plus the header comment explaining why it dispatches rather than
+  // calling the script), and one rename should read as one problem.
+  const known = new Set([...withCadence, ...withoutCadence].map((r) => r.name));
+  const dangling = new Set();
+  for (const w of wf) {
+    for (const m of w.text.matchAll(/run-routine\.js\s+(?:--\S+\s+)*([A-Za-z0-9_-]+)/g)) {
+      if (!known.has(m[1])) dangling.add(`${w.file} dispatches routine '${m[1]}', which has no .claude/scheduled-tasks/${m[1]}/SKILL.md`);
+    }
+  }
+  violations.push(...dangling);
+
+  for (const r of withoutCadence) {
+    warnings.push(`routine '${r.name}' declares no cadence: — it can only ever be run by hand`);
+  }
+  return { violations, warnings };
+}
+
+// The fitness.js check.
+function checkRoutineCadencesScheduled() {
+  const routines = readRoutines();
+  const workflows = readWorkflows();
+  const { violations, warnings } = evaluate(routines, workflows);
+  const scheduled = routines.withCadence.length - violations.filter((v) => v.startsWith("routine '")).length;
+  return {
+    name: 'a declared cron cadence has something that fires it (task 1003209)',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings,
+    note: violations.length
+      ? 'a scheduled routine is declared but dormant — add/repair the scheduler, or drop the cadence: field and stop claiming it runs'
+      : `${scheduled}/${routines.withCadence.length} cadence-declaring routine(s) fired by a committed scheduler at the declared period; ${routines.withoutCadence.length} manual-only.`,
+  };
+}
+
+function main() {
+  const r = checkRoutineCadencesScheduled();
+  for (const v of r.violations) console.error(`✗ ${v}`);
+  for (const w of r.warnings) console.warn(`⚠ ${w}`);
+  console.log(`${r.hardFail ? 'FAIL' : 'PASS'}  ${r.note}`);
+  process.exit(r.hardFail ? 1 : 0);
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  checkRoutineCadencesScheduled, evaluate, cronCadence, workflowCrons,
+  invokesRoutine, readRoutines, readWorkflows, CADENCES,
+  isCadence, subhourlyMinutes, isUniformDivisor,
+};