@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/fitness-ratchets.js

@@ -0,0 +1,594 @@
+#!/usr/bin/env node
+// scripts/bongos/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
+//   source_text_only_tests — test files that only read source text and match
+//     its wording, never running the code (task 1004868)
+//
+// The knip dead-code ratchet needs node_modules + ~seconds, so it is NOT part
+// of the in-suite check: CI runs `node scripts/bongos/fitness-ratchets.js --knip`
+// as its own step (fail-open when knip cannot run, fail-closed on regression).
+//
+// Refresh floors: node scripts/bongos/fitness-ratchets.js --update-baselines
+
+'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/bongos/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/bongos/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/bongos/api-alias-caller-scan.js --files` to see every counted line. The alias '
+    + 'contract, the pinned OAuth callbacks, the deploy 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.',
+  source_text_only_tests:
+    ' — a NEW test file checks code only by reading its source text and matching the wording '
+    + '(task 1004868). That breaks on harmless rewording and misses real bugs. Write a behaviour test '
+    + 'instead: require/import the module and call the function; spawn the CLI and assert its output and '
+    + 'exit code; serve the route and check the response; or, for a page, run its script in node:vm '
+    + 'against a stubbed DOM. If the script does its work the moment it loads, move that work into an '
+    + 'exported function guarded by `if (require.main === module)` so a test can call it. Run '
+    + '`node scripts/bongos/source-text-test-scan.js --files` to see every counted file and the rule.',
+};
+
+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/bongos/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/bongos/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 };
+}
+
+// source_text_only_tests — test files whose ONLY checks are reads of source-file
+// text (task 1004868, goal 1000135, code audit 2026-10-25 R11). The owner ruled no
+// mass rewrite: hold the count, convert files as they are touched. Detector + the
+// rule: scripts/bongos/source-text-test-scan.js. Like legacy_api_gds_callers it
+// FAILS CLOSED on a collapsed enumeration — zero files scanned omits the metric
+// with a reason, rather than reporting a 0 someone could ratchet down to.
+// `files`/`read` are injectable for tests only.
+function sourceTextTestMetrics({ files = null, read = null } = {}) {
+  const { scanSourceTextTests } = require('./source-text-test-scan.js');
+  const { total, scanned } = scanSourceTextTests({ files, read });
+  if (!scanned) {
+    process.stderr.write('fitness-ratchets: source_text_only_tests NOT MEASURED — the test scan enumerated ZERO files, which is a scan defect, not a clean tree\n');
+    return {};
+  }
+  return { source_text_only_tests: 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(),
+    ...sourceTextTestMetrics(),
+    ...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, source-text-only tests 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,
+  sourceTextTestMetrics,
+  duplicateWindowCount,
+  normalizeLines,
+  countCycles,
+  requireGraph,
+  resolveRelative,
+  sizeMetrics,
+  consoleCallCount,
+  isServerPath,
+  knipIssueCount,
+  localKnipPath,
+  lastKnipSkipReason,
+  OVERSIZE_LINES,
+  WINDOW,
+  BASELINE_PATH,
+};