@getarbiter/cli 0.5.0

package/dist/templates/scripts/check-test-pyramid.mjs.ejs

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// CATALOG: INV-124 enforcement. Reads test-pyramid.json at repo root; fails when a
+// CATALOG:   declared `required` level has zero matching test files (glob-based, OR semantics).
+// CATALOG:   Requires `n/a` levels to carry a rationale ≥20 chars. Fails if ALL levels
+// CATALOG:   are n/a (fully-skipped pyramid defeats the gate). SKIP when manifest absent.
+// CATALOG:   Boundary: file PRESENCE only — assertion quality is INV-118 / check-anti-proforma.mjs.
+// CATALOG:   Rejected fold-in into check-anti-proforma.mjs (different axis: level coverage vs quality).
+// Exit codes: 0=PASS/SKIP, 1=policy violation, 2=schema/walk/path-traversal error
+// Usage: node scripts/check-test-pyramid.mjs [--help]
+import { readFileSync, existsSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { globMatch, validateGlob, walkRepo } from './lib/glob-walk.mjs'
+
+const ROOT = resolve(process.cwd())
+const MANIFEST_PATH = join(ROOT, 'test-pyramid.json')
+const ARBITER_PATH = join(ROOT, 'arbiter.json')
+const REASON_MIN_LEN = 20
+
+const HELP = `Usage: node scripts/check-test-pyramid.mjs [--help]
+
+Enforces that every declared test level in test-pyramid.json is populated
+with at least one real test file (INV-124).
+
+Rules:
+  status:"required"  — at least one glob must match ≥1 file in the repo tree.
+                       OR semantics: passes if ANY glob matches.
+  status:"n/a"       — must carry a rationale ≥${REASON_MIN_LEN} chars (auditable).
+  All n/a            — exit 1 (a fully-skipped pyramid defeats the gate).
+
+SKIP:
+  When test-pyramid.json is absent (e.g. non-governed projects), gate exits 0.
+  Re-init with arbiter init to generate the manifest.
+
+Exit codes:
+  0 — pass or SKIP (manifest absent)
+  1 — policy violation
+  2 — schema error, walk error, or path-traversal glob detected`
+
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  process.stdout.write(`${HELP}\n`)
+  process.exit(0)
+}
+
+function globCount(pattern, allFiles) {
+  return allFiles.filter((f) => globMatch(pattern, f)).length
+}
+
+async function main() {
+  if (!existsSync(MANIFEST_PATH)) {
+    process.stdout.write('[check-test-pyramid] SKIP — test-pyramid.json not found\n')
+    // #2052: recognized marker so runCheck surfaces SKIP, not PASS, in the gate summary.
+    process.stdout.write('[SKIP] test-pyramid.json not found\n')
+    process.exit(0)
+  }
+
+  let manifest
+  try {
+    manifest = JSON.parse(readFileSync(MANIFEST_PATH, 'utf-8'))
+  } catch (err) {
+    process.stderr.write(`[check-test-pyramid] ERROR — invalid JSON: ${err.message}\n`)
+    process.exit(2)
+  }
+
+  if (!Array.isArray(manifest.levels)) {
+    process.stderr.write(
+      '[check-test-pyramid] ERROR — manifest.levels must be an array (schema error)\n',
+    )
+    process.exit(2)
+  }
+
+  // Archetype mismatch guard: stale manifests detectable at gate time
+  if (existsSync(ARBITER_PATH)) {
+    try {
+      const arbiter = JSON.parse(readFileSync(ARBITER_PATH, 'utf-8'))
+      if (arbiter.archetype && manifest.archetype && arbiter.archetype !== manifest.archetype) {
+        process.stderr.write(
+          `[check-test-pyramid] FAIL — manifest generated for archetype ${manifest.archetype} ` +
+            `but arbiter.json declares ${arbiter.archetype} — run arbiter update to regenerate\n`,
+        )
+        process.exit(1)
+      }
+    } catch {
+      // arbiter.json parse error — non-fatal; skip mismatch check
+    }
+  }
+
+  // Collect all repo files once
+  const allFiles = walkRepo(ROOT)
+
+  let violations = 0
+  let naCount = 0
+  const totalLevels = manifest.levels.length
+
+  for (const level of manifest.levels) {
+    const id = typeof level.id === 'string' ? level.id : '?'
+    const name = typeof level.name === 'string' ? level.name : id
+    const status = level.status
+
+    if (status === 'n/a') {
+      naCount++
+      const rationale = typeof level.rationale === 'string' ? level.rationale.trim() : ''
+      if (rationale.length < REASON_MIN_LEN) {
+        process.stderr.write(
+          `[check-test-pyramid] FAIL — level ${id} (${name}) is n/a but rationale is ` +
+            `${rationale.length} chars (min ${REASON_MIN_LEN}): "${rationale}"\n`,
+        )
+        violations++
+      }
+      continue
+    }
+
+    if (status !== 'required') continue
+
+    const globs = Array.isArray(level.globs) ? level.globs : []
+    if (globs.length === 0) {
+      process.stderr.write(
+        `[check-test-pyramid] FAIL — required level ${id} (${name}) has no glob patterns ` +
+          `— add patterns or mark as n/a with rationale\n`,
+      )
+      violations++
+      continue
+    }
+
+    // Validate globs for path traversal
+    for (const g of globs) {
+      if (!validateGlob(g)) {
+        process.stderr.write(
+          `[check-test-pyramid] ERROR — glob "${g}" in level ${id} contains path traversal ` +
+            `or is absolute — only relative, non-traversal globs are allowed\n`,
+        )
+        process.exit(2)
+      }
+    }
+
+    // OR semantics: passes if ANY glob matches at least one file
+    const found = globs.some((g) => globCount(g, allFiles) > 0)
+    if (!found) {
+      process.stderr.write(
+        `[check-test-pyramid] FAIL — level ${id} (${name}) declared but empty ` +
+          `— no files matched: ${globs.join(', ')}\n`,
+      )
+      violations++
+    }
+  }
+
+  // All-n/a hard fail
+  if (naCount > 0 && naCount === totalLevels) {
+    process.stderr.write(
+      `[check-test-pyramid] FAIL — all ${totalLevels} declared level(s) are n/a — ` +
+        `a fully-skipped pyramid defeats the gate\n`,
+    )
+    process.exit(1)
+  }
+
+  if (violations > 0) {
+    process.stderr.write(`[check-test-pyramid] FAIL — ${violations} violation(s) found\n`)
+    process.exit(1)
+  }
+
+  process.stdout.write(`[check-test-pyramid] OK — ${totalLevels} level(s) verified\n`)
+  process.exit(0)
+}
+
+try {
+  await main()
+} catch (err) {
+  process.stderr.write(`[check-test-pyramid] ERROR — unexpected: ${err.message}\n`)
+  process.exit(2)
+}

package/dist/templates/scripts/check-test-scope-tier.mjs.ejs

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// scripts/check-test-scope-tier.mjs — generated by arbiter (anti-fake-green A4, INV-89 / INV-124).
+//
+// Test-scope ↔ tier integrity. Cross-checks every `required` test level declared in
+// test-pyramid.json against the gate surface (scripts/check-all.mjs + any
+// .github/workflows/*.yml + Makefile). A declared category that NO gate step executes is a
+// silent false-green — "we run contract tests" with no CI tier that ever does. A level marked
+// n/a (deferred — its rationale is enforced by check-test-pyramid) is exempt. Wiring is proven
+// by an explicit category signal (test:<cat> / keyword step / runner) OR a broad no-path suite
+// (`npm test`, `vitest run`, `pytest`, `go test ./...`) over a default test root.
+// NO-DATA (no manifest, or no gate surface) is a SKIP.
+//
+// Usage: node scripts/check-test-scope-tier.mjs [--dir <path>] [--help]
+// Exit codes (INV-53): 0=PASS/SKIP, 1=declared-but-unwired category, 2=ERROR (self).
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+const args = process.argv.slice(2)
+if (args.includes('--help') || args.includes('-h')) {
+  process.stdout.write(
+    [
+      'Usage: node scripts/check-test-scope-tier.mjs [--dir <path>]',
+      '',
+      'Test-scope ↔ tier integrity. Fails when a test category declared `required` in',
+      'test-pyramid.json is wired into NO gate step (a check-all.mjs check or a CI',
+      'workflow) — a silently-absent declared category is a false-green. A level marked',
+      'n/a (deferred) is exempt. NO-DATA (no manifest / no gate surface) is a SKIP.',
+      '',
+      'Options:',
+      '  --dir <path>   Root directory to scan (default: cwd)',
+      '  --help, -h     Show this help and exit',
+      '',
+    ].join('\n'),
+  )
+  process.exit(0)
+}
+
+const dirIdx = args.indexOf('--dir')
+const ROOT = dirIdx >= 0 && args[dirIdx + 1] ? resolve(args[dirIdx + 1]) : resolve(process.cwd())
+const MANIFEST = join(ROOT, 'test-pyramid.json')
+
+// Default test roots a broad, no-path runner executes wholesale. A required level with
+// a glob rooted here is run by such a suite even without a category-named step.
+const DEFAULT_ROOTS = new Set(['__tests__', 'tests', 'test', 'src', 'spec'])
+
+// Ordered category vocabulary. nameRe identifies the category from the level name;
+// signalRe proves it is invoked somewhere on the gate surface. Order = specific→generic
+// so "Hardware Integration" → hardware and "CLI Integration" → integration.
+const CATEGORIES = [
+  { id: 'e2e', nameRe: /e2e|end[\s-]?to[\s-]?end/i, signalRe: /test:e2e|\be2e\b|playwright|cypress|selenium/i },
+  // signal = specific contract-test forms, NOT bare `contract` (collides with the always-present
+  // check-exit-code-contract.mjs reference on the gate surface → false WIRED, #1499).
+  { id: 'contract', nameRe: /contract/i, signalRe: /test:contract|contract[ _-]?tests?|contract\/|\bpact\b/i },
+  {
+    id: 'performance',
+    nameRe: /performance|\bperf\b|load|stress/i,
+    signalRe: /test:perf|\bperf(ormance)?\b|\bk6\b|gatling|locust|\bjmeter\b/i,
+  },
+  {
+    id: 'property',
+    nameRe: /property|fuzz|generative/i,
+    signalRe: /test:fuzz|test:property|\bproperty\b|fast-check|hypothesis|proptest|quickcheck/i,
+  },
+  {
+    id: 'behavioral',
+    nameRe: /behaviou?ral|\bbdd\b/i,
+    signalRe: /test:behavioral|test:bdd|\bbehaviou?ral\b|\bbdd\b|cucumber/i,
+  },
+  {
+    id: 'component',
+    nameRe: /component/i,
+    signalRe: /test:component|\bcomponent\b|testing-library|storybook/i,
+  },
+  {
+    id: 'hardware',
+    nameRe: /hardware|emulat|simulat/i,
+    signalRe: /test:hardware|\bhardware\b|qemu|renode|\bjtag\b/i,
+  },
+  { id: 'integration', nameRe: /integration/i, signalRe: /test:integration|\bintegration\b|testcontainers/i },
+  { id: 'unit', nameRe: /unit/i, signalRe: /test:unit|\bunit tests?\b|['"]unit['"]/i },
+]
+
+// A broad, no-path test runner that executes the whole default suite (no path filter).
+const BROAD_SUITE_RE =
+  /['"]npm['"]\s*,\s*\[\s*['"]test['"]\s*[\],]|['"]vitest['"]\s*,\s*['"]run['"]\s*\]|['"]pytest['"]\s*[\]),]|['"]go['"]\s*,\s*\[\s*['"]test['"]\s*,\s*['"]\.\/\.\.\.['"]|['"]cargo['"]\s*,\s*\[\s*['"]test['"]\s*\]/i
+
+function readSafe(p) {
+  try {
+    return readFileSync(p, 'utf-8')
+  } catch {
+    return ''
+  }
+}
+
+function collectGateSurface() {
+  let text = ''
+  for (const rel of ['check-all.mjs', join('scripts', 'check-all.mjs'), 'Makefile', 'makefile']) {
+    const p = join(ROOT, rel)
+    if (existsSync(p)) text += readSafe(p) + '\n'
+  }
+  const wfDir = join(ROOT, '.github', 'workflows')
+  if (existsSync(wfDir)) {
+    let entries = []
+    try {
+      entries = readdirSync(wfDir)
+    } catch {
+      entries = []
+    }
+    for (const name of entries) {
+      if (/\.ya?ml$/i.test(name)) text += readSafe(join(wfDir, name)) + '\n'
+    }
+  }
+  return text
+}
+
+function categoryFor(name) {
+  for (const c of CATEGORIES) if (c.nameRe.test(name)) return c
+  return null
+}
+
+function isDefaultRooted(globs) {
+  if (!Array.isArray(globs)) return false
+  return globs.some((g) => typeof g === 'string' && DEFAULT_ROOTS.has(g.split('/')[0]))
+}
+
+function fallbackSignal(name) {
+  const word = (name.split(/\s+/).pop() || '').toLowerCase().replace(/[^a-z0-9]/g, '')
+  if (word.length < 3) return /a^/
+  return new RegExp(`test:${word}|\\b${word}\\b`, 'i')
+}
+
+function main() {
+  if (!existsSync(MANIFEST)) {
+    process.stdout.write('[check-test-scope-tier] SKIP — test-pyramid.json not found (NO-DATA)\n')
+    // #2052: recognized marker so runCheck surfaces SKIP, not PASS, in the gate summary.
+    process.stdout.write('[SKIP] test-pyramid.json not found (NO-DATA)\n')
+    return 0
+  }
+  let manifest
+  try {
+    manifest = JSON.parse(readFileSync(MANIFEST, 'utf-8'))
+  } catch (e) {
+    process.stderr.write(
+      `[check-test-scope-tier] ERROR — invalid test-pyramid.json: ${e?.message ?? e}\n`,
+    )
+    return 2
+  }
+  if (!Array.isArray(manifest.levels)) {
+    process.stderr.write('[check-test-scope-tier] ERROR — manifest.levels must be an array\n')
+    return 2
+  }
+
+  const gate = collectGateSurface()
+  if (gate.trim() === '') {
+    process.stdout.write(
+      '[check-test-scope-tier] SKIP — no gate surface (check-all.mjs / workflows) found\n',
+    )
+    // #2052: recognized marker so runCheck surfaces SKIP, not PASS, in the gate summary.
+    process.stdout.write('[SKIP] no gate surface (check-all.mjs / workflows) found\n')
+    return 0
+  }
+  const broadSuite = BROAD_SUITE_RE.test(gate)
+
+  const unwired = []
+  let assessed = 0
+  for (const level of manifest.levels) {
+    if (!level || level.status !== 'required') continue
+    assessed++
+    const name = typeof level.name === 'string' ? level.name : String(level.id ?? '?')
+    const cat = categoryFor(name)
+    const signalRe = cat ? cat.signalRe : fallbackSignal(name)
+    const explicit = signalRe.test(gate)
+    const broadCovered = broadSuite && isDefaultRooted(level.globs)
+    if (!explicit && !broadCovered) {
+      unwired.push({ id: level.id ?? '?', name, cat: cat?.id ?? 'unknown' })
+    }
+  }
+
+  if (unwired.length > 0) {
+    process.stderr.write(
+      '[check-test-scope-tier] FAIL — declared `required` test categor(ies) wired into NO gate ' +
+        'tier (silent false-green):\n',
+    )
+    for (const u of unwired) {
+      process.stderr.write(
+        `    ${u.id} (${u.name}) [${u.cat}] — no check-all step or workflow runs it\n`,
+      )
+    }
+    process.stderr.write(
+      '  Fix: wire the category into a gate (a check-all step or CI job that runs its tests),\n' +
+        '  or mark the level "n/a" in test-pyramid.json with a rationale if deliberately deferred.\n',
+    )
+    return 1
+  }
+
+  process.stdout.write(
+    `[check-test-scope-tier] OK — ${assessed} required level(s) wired into a gate tier\n`,
+  )
+  return 0
+}
+
+try {
+  process.exit(main())
+} catch (e) {
+  process.stderr.write(`[check-test-scope-tier] ERROR — ${e?.message ?? e}\n`)
+  process.exit(2)
+}

package/dist/templates/scripts/check-tier-coverage.mjs.ejs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// <%= projectName %> — CI tier coverage completeness check (INV-89)
+// Validates that the gate script covers all expected tier checks.
+// Exits 0 when tier coverage is complete; exits 1 when gaps are found.
+// Part of the anti-drift validator family (W6).
+//
+// Usage: node scripts/check-tier-coverage.mjs [--gate <path>] [--help]
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+  process.stdout.write(
+    [
+      'Usage: node scripts/check-tier-coverage.mjs [options]',
+      '',
+      'Validates that the gate script covers all expected tier checks.',
+      'Exits 0 when tier coverage is complete; exits 1 when gaps are found.',
+      '',
+      'Options:',
+      '  --gate <path>   Path to gate script (default: scripts/check-all.mjs)',
+      '  --help, -h      Show this help and exit',
+      '',
+    ].join('\n'),
+  );
+  process.exit(0);
+}
+
+const gateArg = args.indexOf('--gate');
+const CWD = process.cwd();
+const gatePath =
+  gateArg >= 0 && args[gateArg + 1]
+    ? resolve(args[gateArg + 1])
+    : join(CWD, 'scripts', 'check-all.mjs');
+
+// Required tier categories that must be wired in the gate script
+const REQUIRED_TIERS = [
+  { name: 'lint', pattern: /'lint'/ },
+  { name: 'unit tests', pattern: /unit tests/ },
+  { name: 'spdx headers', pattern: /spdx headers/ },
+  { name: 'orphan TODOs', pattern: /orphan TODOs/ },
+];
+
+if (!existsSync(gatePath)) {
+  process.stdout.write('check-tier-coverage: SKIP — gate script not found\n');
+  // #2052: recognized marker so runCheck surfaces SKIP, not PASS, in the gate summary.
+  process.stdout.write('[SKIP] gate script not found\n');
+  process.exit(0);
+}
+
+const gateContent = readFileSync(gatePath, 'utf-8');
+let violations = 0;
+
+for (const tier of REQUIRED_TIERS) {
+  if (!tier.pattern.test(gateContent)) {
+    process.stderr.write(`[FAIL] tier "${tier.name}" not found in gate script (INV-89)\n`);
+    violations++;
+  }
+}
+
+if (violations > 0) {
+  process.stderr.write(
+    `check-tier-coverage: FAIL — ${violations}/${REQUIRED_TIERS.length} required tier(s) missing from gate (INV-89)\n`,
+  );
+  process.exit(1);
+}
+process.stdout.write(
+  `check-tier-coverage: OK — all ${REQUIRED_TIERS.length} required tiers present in gate script (INV-89)\n`,
+);
+process.exit(0);

package/dist/templates/scripts/check-todo-max-age.mjs.ejs

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// check-todo-max-age.mjs — INV-133 (generated, Track-B).
+//
+// A TODO(#NNN) whose LINKED ISSUE was created more than MAX_AGE_DAYS ago FAILS the gate.
+// Age is derived from the issue `created_at` ONLY — never from line/blame/git metadata.
+// Graceful-skip when gh is missing / token absent / offline: the gate exits 0 (SKIP) and
+// NEVER false-fails on a network or auth problem.
+//
+// Usage: node scripts/check-todo-max-age.mjs [dir...]
+//   env TODO_MAX_AGE_DAYS  override the 180-day default
+//
+// Exit codes (INV-53):
+//   0  PASS / SKIP (no over-age TODO, or created_at unresolvable — offline)
+//   1  FAIL — one or more linked issues are older than MAX_AGE_DAYS
+//   2  ERROR — invocation error
+import { readFileSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { walkRepo } from './lib/glob-walk.mjs';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+export const DEFAULT_MAX_AGE_DAYS = 180;
+
+const EXTENSIONS = new Set(['.ts', '.tsx', '.mjs', '.js', '.go', '.py', '.java', '.kt', '.rs']);
+const SKIP_DIRS = new Set(['node_modules', 'dist', 'build', 'target', '.git', 'vendor']);
+const TODO_ISSUE = /TODO\(#(\d+)\)/g;
+
+// ── Pure logic ────────────────────────────────────────────────────────────────
+
+export function isOverAge(createdAtIso, nowMs, maxAgeDays) {
+  if (!createdAtIso || typeof createdAtIso !== 'string') return false;
+  const created = Date.parse(createdAtIso);
+  if (Number.isNaN(created)) return false;
+  const ageDays = (nowMs - created) / (24 * 60 * 60 * 1000);
+  return ageDays > maxAgeDays;
+}
+
+export function parseTodoIssueRefs(content) {
+  const refs = [];
+  const lines = String(content ?? '').split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    let m;
+    TODO_ISSUE.lastIndex = 0;
+    while ((m = TODO_ISSUE.exec(lines[i])) !== null) {
+      refs.push({ issueNumber: Number(m[1]), line: i + 1 });
+    }
+  }
+  return refs;
+}
+
+export function classifyOverAge(refs, createdAtMap, nowMs, maxAgeDays) {
+  let anyResolved = false;
+  const overAge = [];
+  for (const ref of refs) {
+    const createdAt = createdAtMap.get(ref.issueNumber);
+    if (createdAt === undefined || createdAt === '') continue;
+    anyResolved = true;
+    if (isOverAge(createdAt, nowMs, maxAgeDays)) overAge.push(ref);
+  }
+  const skipped = refs.length > 0 && !anyResolved;
+  return { skipped, overAge };
+}
+
+// ── gh / fs helpers ───────────────────────────────────────────────────────────
+
+export function resolveOwnerRepo() {
+  const r = spawnSync('git', ['remote', 'get-url', 'origin'], { encoding: 'utf-8' });
+  if (r.status !== 0 || !r.stdout) return null;
+  const url = r.stdout.trim();
+  const m = url.match(/[:/]([^/]+)\/([^/]+?)(?:\.git)?$/);
+  if (!m) return null;
+  return `${m[1]}/${m[2]}`;
+}
+
+function fetchCreatedAt(ownerRepo, issueNumber) {
+  const r = spawnSync(
+    'gh',
+    ['api', `repos/${ownerRepo}/issues/${issueNumber}`, '--jq', '.created_at'],
+    { encoding: 'utf-8', env: process.env },
+  );
+  if (r.status !== 0 || !r.stdout) return '';
+  return r.stdout.trim();
+}
+
+/**
+ * Walk `dir` for TODO(#NNN) refs, appending hits to `acc`. Returns the number of source files
+ * actually opened — the caller sums this across scanDirs to tell "found nothing" apart from
+ * "looked at nothing" (CANON-24; #2561).
+ */
+function scan(dir, baseDir, acc) {
+  // Cycle-safe walk via the shared helper (#1521): walkRepo prunes vendor trees and never recurses
+  // into a symlinked directory. Re-apply this script's own SKIP_DIRS as a path-segment filter so the
+  // visited set is identical, minus the symlink-cycle bug.
+  let filesScanned = 0;
+  for (const rel of walkRepo(dir)) {
+    if (rel.split('/').some((seg) => SKIP_DIRS.has(seg))) continue;
+    const full = join(dir, rel);
+    if (!EXTENSIONS.has(full.slice(full.lastIndexOf('.')))) continue;
+    filesScanned++;
+    const content = readFileSync(full, 'utf-8');
+    for (const ref of parseTodoIssueRefs(content)) {
+      acc.push({ file: relative(baseDir, full), issueNumber: ref.issueNumber, line: ref.line });
+    }
+  }
+  return filesScanned;
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+export function main(exitFn = process.exit) {
+  const maxAgeDays = Number(process.env.TODO_MAX_AGE_DAYS) || DEFAULT_MAX_AGE_DAYS;
+  const baseDir = process.cwd();
+  const scanDirs = process.argv.slice(2).length > 0 ? process.argv.slice(2) : ['src', 'lib', 'app'];
+
+  const refs = [];
+  let filesScanned = 0;
+  for (const dir of scanDirs) {
+    // #2561 (mirrors arbiter's own #2526 fix for this same gate): resolve(), not join(), against
+    // baseDir. join('/repo', dir) does NOT reset on an absolute `dir` — join('/repo',
+    // '/tmp/fixture/src') silently becomes '/repo/tmp/fixture/src', a path that (almost certainly)
+    // does not exist, so the gate scanned nothing and exited 0: a green that means "I looked
+    // nowhere", not "there is nothing to find". resolve() has POSIX/Node's documented right-to-left
+    // semantics: an absolute segment discards everything to its left, so an absolute `dir` is used
+    // as-is and a relative one is still joined under baseDir exactly as before.
+    filesScanned += scan(resolve(baseDir, dir), baseDir, refs);
+  }
+
+  process.stdout.write(
+    `check-todo-max-age: scanned ${filesScanned} file(s) across ${scanDirs.length} dir(s): ${scanDirs.join(', ')}\n`,
+  );
+
+  // Programme-membership assertion (CANON-24): "nothing found" and "nothing looked at" must
+  // never produce the same green. A resolved scan set of zero files — an empty directory, a
+  // typo'd path, or (pre-fix) an absolute argument silently mis-resolved under baseDir — means
+  // the gate proved nothing, so it fails loudly instead of falling through to the vacuous
+  // "no TODO(#NNN) references — PASS" this defect used to produce. This is distinct from the
+  // case right below: a NON-ZERO scan set with zero refs in it is a legitimate clean state for
+  // this gate (a project can simply have no TODO(#NNN) markers yet), so only an empty FILE SET
+  // aborts — an empty REF set does not.
+  if (filesScanned === 0) {
+    process.stdout.write(
+      `\ncheck-todo-max-age: ABORT — resolved scan set is empty — 0 files found under ${scanDirs.join(', ')}. ` +
+        `A gate that finds nothing must first prove it looked somewhere (CANON-24).\n\n`,
+    );
+    return exitFn(1);
+  }
+
+  if (refs.length === 0) {
+    process.stdout.write('check-todo-max-age: no TODO(#NNN) references — PASS\n');
+    return exitFn(0);
+  }
+
+  const ownerRepo = resolveOwnerRepo();
+  if (!ownerRepo) {
+    process.stdout.write(
+      'check-todo-max-age: SKIP — could not resolve OWNER/REPO from git origin (offline?)\n',
+    );
+    return exitFn(0);
+  }
+
+  const createdAtMap = new Map();
+  for (const ref of refs) {
+    if (createdAtMap.has(ref.issueNumber)) continue;
+    createdAtMap.set(ref.issueNumber, fetchCreatedAt(ownerRepo, ref.issueNumber));
+  }
+
+  const { skipped, overAge } = classifyOverAge(refs, createdAtMap, Date.now(), maxAgeDays);
+
+  if (skipped) {
+    process.stdout.write(
+      'check-todo-max-age: SKIP — no issue created_at could be resolved (gh missing / token absent / offline)\n',
+    );
+    return exitFn(0);
+  }
+
+  if (overAge.length > 0) {
+    process.stdout.write(
+      `check-todo-max-age: FAIL — ${overAge.length} TODO(#NNN) link issue(s) older than ${maxAgeDays} days:\n`,
+    );
+    for (const ref of overAge) {
+      process.stdout.write(`  ${ref.file}:${ref.line}  TODO(#${ref.issueNumber})\n`);
+    }
+    process.stdout.write(
+      '  Resolve the linked issue or split the work — an over-age TODO is stale debt.\n',
+    );
+    return exitFn(1);
+  }
+
+  process.stdout.write(
+    `check-todo-max-age: PASS — ${createdAtMap.size} linked issue(s) within ${maxAgeDays} days\n`,
+  );
+  return exitFn(0);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  try {
+    main();
+  } catch (err) {
+    process.stderr.write(
+      `check-todo-max-age: ERROR — ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+    process.exit(2);
+  }
+}