@bongos/core 1.21.175 → 1.21.177

package/scripts/gds/fitness-ratchets.js

@@ -1,565 +1,7 @@
 #!/usr/bin/env node
-// scripts/gds/fitness-ratchets.js — quality budgets that only tighten (task
-// 1003129, goal 1000076; docs/audits/ai-dev-redteam-baseline.md §4).
-//
-// The audit's modularity finding was measurement without thresholds: sizes,
-// dead code, and doc entropy were all TRACKED and nothing failed when they
-// grew. This module gives each metric a committed BASELINE
-// (config/fitness-baselines.json) with RATCHET semantics:
-//   value > baseline  → violation (fitness hardFail — the number got worse)
-//   value < baseline  → warning nudge to lower the baseline (an ordinary PR)
-// GitClear's measured trend (AI-assisted code duplicates instead of reusing)
-// is the reason the gate exists; the baseline records today's debt without
-// bricking today's tree.
-//
-// Metrics (all hermetic — git + fs only, no network):
-//   oversized_file_count / excess_lines_total — tracked first-party .js files
-//     over OVERSIZE_LINES lines, and their total excess (growth anywhere over
-//     the threshold trips the sum even when the count is flat)
-//   duplicate_window_count — normalized WINDOW-line blocks appearing in 2+
-//     distinct files (the in-house jscpd: cross-file copy/paste)
-//   require_cycle_count — strongly-connected components (size >1) in the
-//     relative-require graph (the in-house madge)
-//   console_call_count — console.* call sites in SERVER paths (src/ + modules/
-//     minus their browser public/ trees); task 1003130 converts the core path
-//     to structured logging and shrinks this baseline
-//   doc_stale_links / doc_broken_anchors / doc_duplicate_prose — the
-//     docs-entropy scanner's three counts, reused as a library
-//
-// The knip dead-code ratchet needs node_modules + ~seconds, so it is NOT part
-// of the in-suite check: CI runs `node scripts/gds/fitness-ratchets.js --knip`
-// as its own step (fail-open when knip cannot run, fail-closed on regression).
-//
-// Refresh floors: node scripts/gds/fitness-ratchets.js --update-baselines
-
+// scripts/gds/fitness-ratchets.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/fitness-ratchets.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
 'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const crypto = require('crypto');
-const { execFileSync, execSync } = require('child_process');
-
-const ROOT = path.resolve(__dirname, '..', '..');
-const BASELINE_PATH = path.join(ROOT, 'config', 'fitness-baselines.json');
-
-const OVERSIZE_LINES = 1500;
-const WINDOW = 30; // normalized lines per duplication window
-
-// Vendored / generated / third-party JS the budgets must not count.
-const EXCLUDE_RE = /(^|\/)(node_modules|public-docs)\/|\.min\.js$|redoc\.standalone\.js$|(^|\/)vendor\//;
-
-function trackedJsFiles() {
-  const out = execFileSync('git', ['ls-files', '*.js'], { cwd: ROOT, encoding: 'utf8' });
-  return out.split('\n').map((s) => s.trim()).filter(Boolean).filter((f) => !EXCLUDE_RE.test(f));
-}
-
-function readRepoFile(rel) {
-  return fs.readFileSync(path.join(ROOT, rel), 'utf8');
-}
-
-// ---------- size ----------
-
-function sizeMetrics(files, read = readRepoFile) {
-  let count = 0;
-  let excess = 0;
-  for (const f of files) {
-    const lines = read(f).split('\n').length;
-    if (lines > OVERSIZE_LINES) {
-      count++;
-      excess += lines - OVERSIZE_LINES;
-    }
-  }
-  return { oversized_file_count: count, excess_lines_total: excess };
-}
-
-// ---------- duplication (in-house jscpd) ----------
-
-function normalizeLines(text) {
-  return text
-    .split('\n')
-    .map((l) => l.trim())
-    .filter((l) => l.length > 0 && !l.startsWith('//') && !l.startsWith('*') && !l.startsWith('/*'));
-}
-
-// contentsByFile: Map(rel → text). Counts window-hashes seen in ≥2 DISTINCT files.
-function duplicateWindowCount(contentsByFile, window = WINDOW) {
-  const filesByHash = new Map();
-  for (const [file, text] of contentsByFile) {
-    const lines = normalizeLines(text);
-    for (let i = 0; i + window <= lines.length; i++) {
-      const h = crypto.createHash('sha1').update(lines.slice(i, i + window).join('\n')).digest('base64');
-      let set = filesByHash.get(h);
-      if (!set) filesByHash.set(h, (set = new Set()));
-      set.add(file);
-    }
-  }
-  let dupes = 0;
-  for (const set of filesByHash.values()) if (set.size >= 2) dupes++;
-  return dupes;
-}
-
-// ---------- require cycles (in-house madge) ----------
-
-const REQUIRE_RE = /require\(\s*(['"])(\.{1,2}\/[^'"]+)\1\s*\)/g;
-
-function resolveRelative(fromRel, spec, exists) {
-  const base = path.posix.normalize(path.posix.join(path.posix.dirname(fromRel), spec));
-  for (const cand of [base, `${base}.js`, `${base}/index.js`]) {
-    if (exists(cand)) return cand;
-  }
-  return null;
-}
-
-// edges: Map(rel → [rel...]). Returns the number of SCCs with size > 1 (Tarjan).
-function countCycles(edges) {
-  let index = 0;
-  const idx = new Map();
-  const low = new Map();
-  const onStack = new Set();
-  const stack = [];
-  let cycles = 0;
-
-  function strongconnect(v) {
-    idx.set(v, index); low.set(v, index); index++;
-    stack.push(v); onStack.add(v);
-    for (const w of edges.get(v) || []) {
-      if (!edges.has(w)) continue;
-      if (!idx.has(w)) { strongconnect(w); low.set(v, Math.min(low.get(v), low.get(w))); }
-      else if (onStack.has(w)) low.set(v, Math.min(low.get(v), idx.get(w)));
-    }
-    if (low.get(v) === idx.get(v)) {
-      let size = 0; let w;
-      do { w = stack.pop(); onStack.delete(w); size++; } while (w !== v);
-      if (size > 1) cycles++;
-    }
-  }
-  for (const v of edges.keys()) if (!idx.has(v)) strongconnect(v);
-  return cycles;
-}
-
-function requireGraph(contentsByFile) {
-  const known = new Set(contentsByFile.keys());
-  const exists = (rel) => known.has(rel);
-  const edges = new Map();
-  for (const [file, text] of contentsByFile) {
-    const deps = [];
-    // Scan line by line and skip WHOLE-LINE comments. A comment that merely
-    // NAMES a require — "// re-exports every name, so no require('./db') call
-    // site had to change" — used to create a phantom edge, and during the task
-    // 1003204 carve one such header comment on twelve new files fabricated a
-    // twelve-file cycle and reddened CI. Only a `//`- or `*`-leading line is
-    // dropped, so an inline trailing comment still counts, which is the safe
-    // direction: a missed real edge would hide a cycle.
-    for (const line of text.split('\n')) {
-      if (/^\s*(\/\/|\*)/.test(line)) continue;
-      for (const m of line.matchAll(REQUIRE_RE)) {
-        const target = resolveRelative(file, m[2], exists);
-        if (target && target !== file) deps.push(target);
-      }
-    }
-    edges.set(file, deps);
-  }
-  return edges;
-}
-
-// ---------- console.* in server paths ----------
-
-const CONSOLE_RE = /console\.(log|error|warn|info|debug)\s*\(/g;
-
-function isServerPath(rel) {
-  if (!(rel.startsWith('src/') || rel.startsWith('modules/') || rel === 'server.js')) return false;
-  if (rel.includes('/public/')) return false; // browser surfaces are a different concern
-  if (rel.includes('/test')) return false;
-  return true;
-}
-
-function consoleCallCount(contentsByFile) {
-  let n = 0;
-  for (const [file, text] of contentsByFile) {
-    if (!isServerPath(file)) continue;
-    n += (text.match(CONSOLE_RE) || []).length;
-  }
-  return n;
-}
-
-// ---------- doc entropy (reuse the scanner as a library) ----------
-
-function docMetrics() {
-  const de = require('./docs-entropy.js');
-  const relFiles = de.collectMarkdownFiles();
-  const linkFindings = de.scanStaleLinks(relFiles);
-  return {
-    doc_stale_links: linkFindings.filter((f) => f.issue === 'missing_file').length,
-    doc_broken_anchors: linkFindings.filter((f) => f.issue === 'missing_anchor').length,
-    doc_duplicate_prose: de.scanDuplicateProse(relFiles).length,
-  };
-}
-
-// ---------- knip (CI-only, fail-open on infra) ----------
-
-// WHY A LOCAL knip IS REQUIRED BEFORE SCORING (task 1003987).
-//
-// `npx --no-install` does not only look in THIS project: it walks up the directory
-// tree. A git worktree has no node_modules of its own, so the lookup climbs out and
-// finds the main checkout's copy — the command succeeds, and the number it produces is
-// wrong in a specific, repeatable way.
-//
-// MEASURED, not inferred, on 2026-09-17 against one tree:
-//   main checkout (knip local)   -> 221
-//   worktree      (knip ambient) -> 222, the extra being `binaries: package.json knip`
-// Diffed by name, the exports lists were IDENTICAL (221 both sides). knip was
-// reporting ITSELF as an unlisted binary, because from the worktree's point of view it
-// is not a declared dependency of anything resolvable.
-//
-// So the ratchet failed CLOSED on a phantom: 222 > baseline 221, on a tree whose real
-// findings had not moved. That cost a full elimination pass on task 1003848, where the
-// count was the loudest signal pointing away from the actual defect.
-//
-// This module's contract is fail-OPEN on infrastructure and fail-CLOSED on findings.
-// A count measured through an ambient knip is an infrastructure artefact, not a
-// finding, so it must not be scored at all. CI is unaffected: `npm ci` puts knip in
-// the project's own node_modules, which is exactly what this checks for.
-//
-// The row also offered "compare findings by NAME" as the fuller cure. That is a
-// baseline-format change (one integer today) and is deliberately NOT done here; naming
-// the unresolvable case is the "at minimum" it asked for, and it removes the false
-// failure without pretending the count is now environment-proof.
-function localKnipPath() {
-  for (const rel of ['node_modules/knip/package.json', 'node_modules/.bin/knip']) {
-    const p = path.join(ROOT, rel);
-    try { if (fs.existsSync(p)) return p; } catch { /* unreadable → treat as absent */ }
-  }
-  return null;
-}
-
-// Why the last knip score was skipped, or null when it was scored. Module-scoped so
-// the caller can NAME the cause instead of printing one generic line for every
-// unrelated reason knip might not run.
-let knipSkipReason = null;
-function lastKnipSkipReason() { return knipSkipReason; }
-
-function knipIssueCount() {
-  knipSkipReason = null;
-  if (!localKnipPath()) {
-    // Not "knip is missing" — an ambient one may well run. The point is that its
-    // answer is not comparable to the baseline, which was measured with a local one.
-    knipSkipReason = `no knip in ${path.join(ROOT, 'node_modules')} — `
-      + 'npx would resolve one from outside this tree and report it as an unlisted '
-      + 'binary, scoring one higher than the same code scores in CI (task 1003987)';
-    return null;
-  }
-  let raw;
-  try {
-    raw = execSync('npx --no-install knip --reporter json --no-exit-code', {
-      cwd: ROOT, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'],
-    });
-  } catch (e) {
-    if (e && e.stdout) { raw = e.stdout.toString(); }
-    else { knipSkipReason = `npx knip failed to run in ${ROOT}`; return null; }
-  }
-  try {
-    const j = JSON.parse(raw);
-    // knip's json reporter: { files: [...], issues: [{ file, owners, exports:[], types:[], ... }] }
-    const files = Array.isArray(j.files) ? j.files.length : 0;
-    let items = 0;
-    for (const issue of j.issues || []) {
-      for (const key of ['dependencies', 'devDependencies', 'optionalPeerDependencies', 'unlisted', 'binaries', 'unresolved', 'exports', 'types', 'nsExports', 'nsTypes', 'duplicates']) {
-        const v = issue[key];
-        items += Array.isArray(v) ? v.length : 0;
-      }
-    }
-    return files + items;
-  } catch {
-    knipSkipReason = 'knip produced output this script could not parse as JSON';
-    return null;
-  }
-}
-
-// ---------- baseline + ratchet ----------
-
-// readBaselines — task 1003227. Returns { metrics, error }: `error` is a reason
-// string when the file cannot be trusted, null when it read cleanly.
-//
-// This used to `catch { return {}; }`, which made the gate FAIL OPEN. An empty
-// baseline map leaves every `floor === undefined`, and compareToBaselines classifies
-// an absent floor as a WARNING — so a checkout with no config/ reported the ratchet
-// as PASSED. Measured: with the baselines gone, a planted 5,000-line and 94-cycle
-// regression produced 0 violations. That was not a hypothetical checkout — a sparse
-// checkout without `config/` once left the builders who most needed the gate
-// silently exempt from it, learning from red CI instead.
-//
-// Distinguish the two absences, because they are not the same fact:
-//   - the FILE is missing/malformed  -> cannot verify anything -> hard fail (here);
-//   - a KEY is missing for one metric -> a genuinely new metric -> stays a warning
-//     in compareToBaselines, so adding a metric does not break the build.
-//
-// The file's own header says raising a baseline to pass CI is out of policy;
-// deleting the file must not be the loophole that raising it is not.
-//
-// `baselinePath` is injectable for TESTS ONLY (task 1003351) and defaults to the
-// real file, so every production caller is unchanged. The three task-1003227
-// cases used to prove the three unreadable shapes by renaming and overwriting the
-// repo's OWN config/fitness-baselines.json, restoring in a finally — and
-// run-unit-tests.js runs each file under a 90s execFileSync timeout, whose
-// SIGTERM skips the finally and leaves the last payload on disk. That is how a
-// real checkout ended up with {"_comment":"no metrics key"} committed-adjacent
-// and the sibling case dying on `Cannot read properties of undefined`. A test
-// must not have to survive being killed to leave the repo intact.
-function readBaselines(baselinePath = BASELINE_PATH) {
-  let raw;
-  try {
-    raw = fs.readFileSync(baselinePath, 'utf8');
-  } catch (e) {
-    const missing = e && e.code === 'ENOENT';
-    return {
-      metrics: {},
-      error: missing
-        ? `config/fitness-baselines.json is MISSING — the quality ratchet cannot verify anything, so it fails CLOSED rather than reporting a pass it did not check. `
-          + `If this is a sparse or partial checkout, take the whole tree (\`git sparse-checkout disable\`). `
-          + `To bootstrap a fresh baseline deliberately: node scripts/gds/fitness-ratchets.js --update-baselines`
-        : `config/fitness-baselines.json is unreadable (${e && e.message}) — failing CLOSED.`,
-    };
-  }
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch (e) {
-    return { metrics: {}, error: `config/fitness-baselines.json is not valid JSON (${e && e.message}) — failing CLOSED.` };
-  }
-  const metrics = parsed && typeof parsed.metrics === 'object' && parsed.metrics !== null
-    ? parsed.metrics
-    : null;
-  if (!metrics) {
-    return { metrics: {}, error: 'config/fitness-baselines.json has no "metrics" object — failing CLOSED.' };
-  }
-  // `parsed` rides along so --update-baselines can PRESERVE the non-metric keys it
-  // used to overwrite — see the writer in main().
-  return { metrics, error: null, parsed };
-}
-
-// Pure ratchet verdict — exported for the hermetic test.
-// A metric whose name does not, by itself, tell the builder who tripped it what
-// to do gets one line of guidance here. Appended to the regression message only
-// — the ratchet-down warning already says exactly what to do.
-const METRIC_HINTS = {
-  legacy_gds_literals:
-    ' — a NEW "GDS" literal entered the tree (goal 1000073 C5: the rename cannot come back). '
-    + 'Write Bongos instead. Run `node scripts/gds/gds-literal-scan.js` to see every counted file. '
-    + 'Version ids (GDS-V##), docs/adr, docs/session-logs, docs/audits, limitations and migrations '
-    + 'are excluded by construction — if your literal is history, it belongs in one of those.',
-  legacy_api_gds_callers:
-    ' — a NEW in-repo caller was written against the permanent `/api/gds` alias (task 1004064, '
-    + 'idea 1001030). Ask for `/api/bongos` instead: the alias exists for callers we CANNOT update '
-    + '(shipped binaries, live instances), not for code in this repo. Run '
-    + '`node scripts/gds/api-alias-caller-scan.js --files` to see every counted line. The alias '
-    + 'contract, the pinned OAuth callbacks, the uptime poller + smoke, the rename guardrails, '
-    + 'tests/, docs/, migrations/ and captured fixtures are excluded by construction — and so is '
-    + 'any line that also names /api/bongos or carries the words alias / legacy / permanent / forever, '
-    + 'so if your line is ABOUT the alias rather than a call to it, say so on the line.',
-};
-
-function compareToBaselines(metrics, baselines) {
-  const violations = [];
-  const warnings = [];
-  for (const [name, value] of Object.entries(metrics)) {
-    if (value === null || value === undefined) continue; // metric skipped (e.g. knip off-CI)
-    const floor = baselines[name];
-    if (floor === undefined) {
-      warnings.push(`no baseline for "${name}" (value ${value}) — run --update-baselines`);
-    } else if (value > floor) {
-      violations.push(`${name} regressed: ${value} > baseline ${floor} — fix the regression; never raise the baseline to pass${METRIC_HINTS[name] || ''}`);
-    } else if (value < floor) {
-      warnings.push(`ratchet-down available: ${name} improved to ${value} (baseline ${floor}) — lower the baseline in config/fitness-baselines.json`);
-    }
-  }
-  return { violations, warnings };
-}
-
-// legacy_gds_literals — criterion C5 of goal 1000073, "the rename cannot come
-// back" (task 1003669). A shrink-only count of the GDS acronym outside the
-// frozen record, so a NEW literal reds the build the way any other regression
-// does. It rides the ratchet machinery rather than being its own check on
-// purpose: --update-baselines, the floors, and baseline-staleness then all
-// apply to it for free, and a metric outside `metrics` would be silently
-// dropped the next time anyone refreshed the file. Detector + the reasons for
-// every exclusion: scripts/gds/gds-literal-scan.js.
-function gdsMetrics() {
-  const { scanGdsLiterals } = require('./gds-literal-scan.js');
-  return { legacy_gds_literals: scanGdsLiterals().total };
-}
-
-// legacy_api_gds_callers — the LOWERCASE half of the same rename (task 1004064, idea 1001030).
-// `legacy_gds_literals` above is case-sensitive on the shouting acronym, so it read 1135 both
-// before and after task 1003707 moved 665 in-repo callers off `/api/gds` — correct for what it
-// measures, and exactly why a caller written against the alias tomorrow moves no number and reds
-// no build. This counts that spelling instead. Detector + the reason for every exclusion:
-// scripts/gds/api-alias-caller-scan.js.
-//
-// It FAILS CLOSED on a collapsed enumeration. A static scan breaks by finding nothing, and a
-// green run looks identical to a working one — so if the scanner scanned no files at all, the
-// metric is OMITTED with a reason on stderr rather than reported as a flattering 0 that would
-// invite someone to ratchet the baseline down to it.
-function apiAliasCallerMetrics() {
-  const { scanAliasCallers } = require('./api-alias-caller-scan.js');
-  const { total, scanned } = scanAliasCallers();
-  if (!scanned) {
-    process.stderr.write('fitness-ratchets: legacy_api_gds_callers NOT MEASURED — the caller scan enumerated ZERO files, which is a scan defect, not a clean tree\n');
-    return {};
-  }
-  return { legacy_api_gds_callers: total };
-}
-
-// skill_listing_chars — the resident cost of the skill listing (every name +
-// description, both skill homes). Ratcheted rather than merely warned about
-// because this number has now been trimmed three times (tasks 1003548, 1003587,
-// 1003620) and grown back each time: a warning that accumulates is a warning
-// nobody acts on. Every char here sits in EVERY session, so growth is a context
-// tax on all work, not a lint nit.
-//
-// Fails OPEN if the linter cannot load — this ratchet must never be the reason
-// a build cannot run.
-function skillListingMetrics() {
-  try {
-    const lint = require('./skill-lint.js');
-    // Resident skills only (task 1004470): a skill owned by a module this checkout leaves
-    // off (pixel-art, design-styles — both default: false) is in no session's listing here.
-    // listingChars also leaves out HIDDEN skills (disable-model-invocation: true, task 1004471):
-    // Claude Code keeps their descriptions out of the model's context entirely.
-    const files = lint.listSkillFiles();
-    return { skill_listing_chars: lint.lintSkills(files, { resident: lint.residentSkillFiles(undefined, { files }) }).listingChars };
-  } catch (e) {
-    // Fail open, but never SILENTLY: an unenforced ratchet that says nothing is
-    // indistinguishable from a passing one, which is how a budget stops being a
-    // budget. The metric is omitted (so compareToBaselines skips it) and the
-    // reason is on stderr.
-    process.stderr.write(`fitness-ratchets: skill_listing_chars NOT MEASURED — skill-lint unavailable (${e && e.message}); the listing budget is unenforced this run\n`);
-    return {};
-  }
-}
-
-function computeMetrics({ withDocs = true } = {}) {
-  const files = trackedJsFiles();
-  const contents = new Map(files.map((f) => [f, readRepoFile(f)]));
-  return {
-    ...sizeMetrics(files, (f) => contents.get(f)),
-    duplicate_window_count: duplicateWindowCount(contents),
-    require_cycle_count: countCycles(requireGraph(contents)),
-    console_call_count: consoleCallCount(contents),
-    ...gdsMetrics(),
-    ...apiAliasCallerMetrics(),
-    ...skillListingMetrics(),
-    ...(withDocs ? docMetrics() : {}),
-  };
-}
-
-// The fitness.js check (in-suite, hermetic — everything except knip).
-//
-// Both options are injectable for TESTS ONLY (task 1003351); fitness.js calls
-// this through `CHECKS.map((fn) => fn())`, with no arguments, so the defaults are
-// what production runs. `metrics` matters as much as `baselinePath` here: a test
-// that only wanted to prove an unreadable baseline file still paid for a full
-// computeMetrics() sweep — git ls-files plus every tracked .js plus the
-// docs-entropy scan, measured at 23.7s + 2.5s + 2.8s, i.e. ~29s of this file's
-// 29s runtime, which is what pushed it into the 90s timeout in the first place.
-function checkQualityRatchets({ baselinePath = BASELINE_PATH, metrics: injectedMetrics = null } = {}) {
-  const metrics = injectedMetrics === null ? computeMetrics() : injectedMetrics;
-  const { metrics: baselines, error: baselineError } = readBaselines(baselinePath);
-  const { violations, warnings } = compareToBaselines(metrics, baselines);
-  // task 1003227: an unreadable baseline file is a hard failure, not silence. Put it
-  // FIRST so it is the headline rather than buried under per-metric noise.
-  if (baselineError) violations.unshift(baselineError);
-  return {
-    name: 'quality ratchets — size, duplication, cycles, console, doc entropy, legacy GDS literals only tighten (task 1003129)',
-    hardFail: violations.length > 0,
-    violations,
-    warnings,
-    note: `budgets: ${Object.entries(metrics).map(([k, v]) => `${k}=${v}`).join(' · ')} vs config/fitness-baselines.json (knip runs as its own CI step)`,
-  };
-}
-
-function main() {
-  const update = process.argv.includes('--update-baselines');
-  const knipOnly = process.argv.includes('--knip');
-
-  if (update) {
-    const metrics = computeMetrics();
-    const knip = knipIssueCount();
-    if (knip !== null) metrics.knip_issue_count = knip;
-    // The bootstrap path deliberately tolerates an absent file — writing it is the
-    // whole point — so it reads the metrics and ignores any error (task 1003227).
-    const { metrics: existing, parsed: existingFile } = readBaselines();
-    if (knip === null && existing.knip_issue_count !== undefined) metrics.knip_issue_count = existing.knip_issue_count;
-    // PRESERVE everything that is not a metric. This used to write a fixed object
-    // literal, so one --update-baselines silently destroyed both the accumulated
-    // `_comment` (which documents WHY each number is where it is) and, once task
-    // 1003210 added them, the `floors` — the written claims that exempt a metric
-    // from the staleness check. Losing a floor is not cosmetic: the metric silently
-    // becomes "stale forever" and its reason is gone from the repo. Only `metrics`
-    // is recomputed; unknown keys pass through untouched, so a later addition to
-    // this file cannot be eaten by a refresh either.
-    const preserved = existingFile && typeof existingFile === 'object' ? { ...existingFile } : {};
-    delete preserved.metrics;
-    if (!preserved._comment) {
-      preserved._comment = 'fitness-ratchets baselines (task 1003129): quality debt recorded at gate-adoption. Shrink-only — lower a value when the metric improves; raising one to pass CI is out of policy.';
-    }
-    const { _comment, ...rest } = preserved;
-    fs.writeFileSync(
-      BASELINE_PATH,
-      JSON.stringify({ _comment, metrics, ...rest }, null, 2) + '\n',
-    );
-    console.log(`fitness-ratchets: baselines written — ${Object.entries(metrics).map(([k, v]) => `${k}=${v}`).join(' · ')}`);
-    return;
-  }
-
-  if (knipOnly) {
-    const value = knipIssueCount();
-    if (value === null) {
-      // Name WHY (task 1003987). "not runnable here" sent readers looking for a
-      // broken install when the real answer was that the number would have been
-      // wrong — a different problem with a different fix.
-      console.warn(`fitness-ratchets: WARN — knip not scored: ${lastKnipSkipReason() || 'knip unavailable'}; failing OPEN.`);
-      process.exit(0);
-    }
-    const { metrics: knipBaselines, error: knipBaselineError } = readBaselines();
-    const { violations, warnings } = compareToBaselines({ knip_issue_count: value }, knipBaselines);
-    if (knipBaselineError) violations.unshift(knipBaselineError);
-    for (const w of warnings) console.warn(`fitness-ratchets: ${w}`);
-    if (violations.length) {
-      for (const v of violations) console.error(`fitness-ratchets: FAIL — ${v}`);
-      process.exit(1);
-    }
-    console.log(`fitness-ratchets: PASS — knip_issue_count=${value}.`);
-    return;
-  }
-
-  const r = checkQualityRatchets();
-  for (const w of r.warnings) console.warn(`! ${w}`);
-  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 = {
-  checkQualityRatchets,
-  // Exported for tests/fitness_ratchets.mjs (task 1003351), which proves the
-  // injected baselinePath is honoured rather than silently falling back.
-  readBaselines,
-  computeMetrics,
-  compareToBaselines,
-  duplicateWindowCount,
-  normalizeLines,
-  countCycles,
-  requireGraph,
-  resolveRelative,
-  sizeMetrics,
-  consoleCallCount,
-  isServerPath,
-  knipIssueCount,
-  localKnipPath,
-  lastKnipSkipReason,
-  OVERSIZE_LINES,
-  WINDOW,
-  BASELINE_PATH,
-};
+require('../bongos/forwarder.js').forward(module, 'fitness-ratchets.js');