@bongos/core 1.21.175 → 1.21.176

package/scripts/gds/do-api.js

@@ -1,109 +1,6 @@
-// scripts/gds/do-api.js — a thin DigitalOcean API v2 client for the control plane.
-//
-// Control-plane client (ADR 0111 §2, task #1943): the DO client the
-// instance-provisioning runner (scripts/gds/provision.js) and its teardown
-// (provision-teardown.js) use. It is operator-CLI code (never the web tier), so it
-// lives in the control-plane tier alongside its callers. Originally #598.
-//
-// Everything that touches DO goes through here so the provisioning code stays
-// testable without a live account.
-//
-// Design:
-//   - Injectable transport (`fetchImpl`) so tests pass a fake fetch and assert
-//     the request shape without hitting the network.
-//   - `dryRun` mode (the DEFAULT for the CLI): NO request is sent. Each method
-//     logs the call it WOULD make and returns a synthetic, clearly-marked
-//     result (`{ dryRun: true, ... }`) so the orchestrator's control flow runs
-//     end-to-end against a throwaway plan. This mirrors how provision-staging.sh
-//     and stale-claim-release ship runnable logic whose LIVE leg is a separate,
-//     explicit operator action.
-//   - Live mode requires a token (DO_API_TOKEN); the constructor throws clearly
-//     if asked to run live without one — it never silently no-ops a real call.
-//
-// We implement only the calls provisioning needs:
-//   createDroplet · getDroplet · deleteDroplet · settleDroplet (poll to active)
-
-const { JsonHttpApi, makeApiError } = require('./http-api-client');
-
-const DO_API_BASE = 'https://api.digitalocean.com/v2';
-
-const DoApiError = makeApiError('DoApiError', 'DO_API_ERROR');
-
-class DoApi extends JsonHttpApi {
-  // opts: { token, dryRun=true, fetchImpl=globalThis.fetch, base, log }
-  constructor(opts = {}) {
-    super(opts, { base: DO_API_BASE, logTag: 'DO', ErrorClass: DoApiError });
-    if (!this.dryRun && !this.token) {
-      throw new DoApiError(
-        'live DigitalOcean call requested but DO_API_TOKEN is not set — ' +
-        'export DO_API_TOKEN or run without --apply (dry-run)'
-      );
-    }
-    if (!this.dryRun && typeof this.fetchImpl !== 'function') {
-      throw new DoApiError('no fetch implementation available for live mode');
-    }
-  }
-
-  // _req (the dry-run/live request skeleton) is inherited from JsonHttpApi. DoApi
-  // uses the base error detection (non-2xx → message/id) and adds no fetch init.
-
-  // ---- droplets --------------------------------------------------------------
-
-  // image: a base image slug (e.g. 'ubuntu-24-04-x64').
-  async createDroplet({ name, region, size, image, userData, tags, sshKeys }) {
-    const body = {
-      name, region, size, image,
-      user_data: userData || undefined,
-      tags: tags || undefined,
-      ssh_keys: sshKeys || undefined,
-      ipv6: false,
-      monitoring: true,
-    };
-    return this._req('POST', '/droplets', body, {
-      dryRunResult: { droplet: { id: `dryrun-droplet-${name}`, status: 'new' } },
-    });
-  }
-
-  async getDroplet(dropletId) {
-    return this._req('GET', `/droplets/${dropletId}`, null, {
-      dryRunResult: { droplet: { id: dropletId, status: 'active', networks: { v4: [] } } },
-    });
-  }
-
-  async deleteDroplet(dropletId) {
-    return this._req('DELETE', `/droplets/${dropletId}`, null, { dryRunResult: { deleted: true } });
-  }
-
-  // Poll primitive behind settleDroplet (#1092). Calls step(i) each round; step
-  // returns { done:true, value } to stop, or a falsy value to keep polling.
-  // Returns the stopping value, or { timedOut:true } after `tries` rounds.
-  // `sleepFn` lets tests drive the loop with no real clock.
-  async _poll({ tries = 60, sleepMs = 5000, sleepFn } = {}, step) {
-    const sleep = sleepFn || ((ms) => new Promise((r) => setTimeout(r, ms)));
-    for (let i = 0; i < tries; i++) {
-      const r = await step(i);
-      if (r && r.done) return r.value;
-      await sleep(sleepMs);
-    }
-    return { timedOut: true };
-  }
-
-  // Wait until a freshly-created droplet is 'active' and return its public IPv4.
-  // dry-run returns no IP (it never created a real droplet).
-  async settleDroplet(dropletId, { tries = 60, sleepMs = 5000, sleepFn } = {}) {
-    if (this.dryRun) return { ip: null };
-    const out = await this._poll({ tries, sleepMs, sleepFn }, async () => {
-      const { droplet } = await this.getDroplet(dropletId);
-      if (droplet && droplet.status === 'active') {
-        const v4 = (droplet.networks && droplet.networks.v4) || [];
-        const pub = v4.find((n) => n.type === 'public');
-        return { done: true, value: { ip: pub ? pub.ip_address : null } };
-      }
-      return null;
-    });
-    if (out && out.timedOut) throw new Error(`droplet ${dropletId} did not reach 'active' in time`);
-    return out;
-  }
-}
-
-module.exports = { DoApi, DoApiError, DO_API_BASE };
+// scripts/gds/do-api.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/do-api.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';
+require('../bongos/forwarder.js').forward(module, 'do-api.js');

package/scripts/gds/doc-cli-guard.js

@@ -1,268 +1,7 @@
 #!/usr/bin/env node
-// scripts/gds/doc-cli-guard.js — a doc that NAMES a CLI invocation must match the
-// real CLI (task 1003165 / G01, goal 1000077; criterion guards-doc-names-a-command).
-//
-// WHY. Task 1002931 shipped a skill instructing `capture.js --full --fields-file`
-// while those flags lived on an unlanded branch. Its test passed, because the test
-// pinned the skill's PROSE — it asserted the file said the words, never that the
-// words worked. So the skill confidently told agents to run a command that
-// silently ignored both flags and filed the wrong thing. That is the whole class:
-// AN UNRECOGNISED FLAG IS NOT AN ERROR. `arg('--x')`/`hasFlag('--x')` return null
-// and the command proceeds, so a doc can name a flag that does nothing and every
-// test stays green (learning 1000198). It happened TWICE in one session: the
-// second time /workspace ran an older capture.js and the same documented flags
-// were dropped on the floor again.
-//
-// WHAT IT CHECKS, deliberately narrow: for every `node scripts/gds/<x>.js` in a
-// tracked .md, (a) the script exists, and (b) each `--flag` written next to it
-// appears in that script's source (or in a same-directory module it requires — a CLI may be carved into phase files). Nothing else — this is not a prose linter.
-//
-// STATIC ONLY, NEVER EXECUTED. The reason matters: running every documented CLI
-// would be slow, would need a session, and a command that blocks on a prompt
-// would hang CI forever — the exact failure R151's TTY gate exists to prevent.
-//
-// It lives in its OWN FILE rather than in fitness.js because fitness.js is already
-// over the size ratchet (config/fitness-baselines.json) — the control-manifest.js
-// precedent. fitness.js requires it in CHECKS.
-
+// scripts/gds/doc-cli-guard.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/doc-cli-guard.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 { execFileSync } = require('node:child_process');
-
-const REPO_ROOT = path.resolve(__dirname, '..', '..');
-
-// Check 22 in fitness.js's CHECKS. The why, the narrowness and the static-only
-// rule are all in the file header above — not restated here.
-
-const DOC_CLI_ALLOW = new Map([
-  ['.claude/skills/paint/SKILL.md::scripts/gds/art-stage.js',
-    'art-stage.js ships with the art-pipeline HOST module, which publish-manifest.js excludes from core — absent from a core-only checkout by design; the skill says so inline.'],
-  ['modules/pixel-art/skills/otb-tile-generate/SKILL.md::scripts/gds/art-stage.js',
-    'same as paint/SKILL.md — the art staging CLI travels with the excluded art-pipeline module, not the portable core.'],
-  ['docs/session-logs/2026-09-10-task-1003507-the-box-that-could-not-be-reaped.md::scripts/gds/box.js',
-    'a dated session log — the historical record, never rewritten — of work on a CLI the dev-box removal deleted (task 1003893); it describes what was run then, not what to run now.'],
-]);
-
-// `node scripts/gds/foo.js` … up to the end of the line/segment, so the flags that
-// follow travel with the script that owns them.
-const DOC_CLI_RE = /node\s+(scripts\/gds\/[A-Za-z0-9._-]+\.js)([^\n`]*)/g;
-// A long flag only. Short flags and bare words are ignored: too many false
-// positives from prose, and the failure this guards is long-flag drift.
-const DOC_FLAG_RE = /(?<![\w-])--([A-Za-z][A-Za-z0-9-]*)/g;
-
-// Flags every CLI inherits from shared arg plumbing rather than naming itself.
-const UNIVERSAL_FLAGS = new Set(['quiet', 'help', 'dry-run', 'json']);
-
-// Does `script` know about `--flag` AT ALL?
-//
-// This deliberately asks the WEAK question — does the literal appear anywhere in
-// the source — and not the strong one ("is it wired into arg parsing"). The first
-// draft of this check asked the strong question, matching `arg('--x')` and
-// `hasFlag('--x')`, and produced FIVE false positives out of nine hits on its
-// first real run: triage.js parses via `argv.indexOf('--development')`,
-// provision.js via `hasFlag(args, '--apply')`, oauth-secret.js via
-// `argVal(args, '--client-id')`, status.js via `a === '--widget'`, and
-// validate-design.js via `ARGS.has('--strict')`. Every one of those is correct
-// code that the strong check called broken.
-//
-// The set of ways to read an argv in JavaScript is open-ended, so a check that
-// enumerates them will keep growing false positives forever — and a fitness check
-// that cries wolf gets muted, which costs more than the drift it was catching.
-// The weak question is ONE-DIRECTIONAL and therefore sound: a script whose source
-// never contains the string `--full` cannot possibly honour `--full`, whatever
-// idiom it uses. That is exactly the failure this exists for (learning 1000198:
-// /workspace ran a capture.js from before those flags existed, and both were
-// silently dropped). A stale usage comment naming a removed flag slips through —
-// accepted, deliberately: guessing which mentions are "real" is how the strong
-// version went wrong.
-function scriptMentionsFlag(src, flag) {
-  const f = flag.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  // Trailing guard so `--client` does not match `--client-id`.
-  return new RegExp(`--${f}(?![\\w-])`).test(src);
-}
-
-// The scan CORE. IO is injected — `readDoc(path)` and `readScript(path)` both
-// return source or null — so a test can exercise a DRIFTED doc without writing
-// a broken file into the tree (the control-manifest.js `evaluate` precedent).
-// A check that cannot be shown to fail is not evidence of anything, which is
-// precisely how task 1002931's prose-pinning test let the bad skill through.
-function scanDocs(docs, { readDoc, readScript, allow = DOC_CLI_ALLOW } = {}) {
-  const violations = [];
-  const warnings = [];
-  let invocations = 0;
-  const srcCache = new Map();
-  const script = (rel) => {
-    if (!srcCache.has(rel)) srcCache.set(rel, readScript(rel));
-    return srcCache.get(rel);
-  };
-  // Memoized alongside srcCache: stripLineComments is two regex passes over a
-  // whole script, and it was being recomputed for EVERY flag on every invocation
-  // of that script. Invariant per file, so compute it once (grader, task 1003165).
-  const codeCache = new Map();
-  const codeOnly = (rel, src) => {
-    if (!codeCache.has(rel)) codeCache.set(rel, stripLineComments(src));
-    return codeCache.get(rel);
-  };
-
-  for (const doc of docs) {
-    const text = readDoc(doc);
-    if (text === null) continue;
-    DOC_CLI_RE.lastIndex = 0;
-    let m;
-    while ((m = DOC_CLI_RE.exec(text))) {
-      const scriptRel = m[1];
-      const tail = m[2] || '';
-      invocations += 1;
-      const src = script(scriptRel);
-      if (src === null) {
-        if (!allow.has(`${doc}::${scriptRel}`)) {
-          violations.push(
-            `${doc} → \`node ${scriptRel}\` names a script that does not exist. `
-            + 'An agent following this doc gets MODULE_NOT_FOUND. Fix the path, or allowlist it in DOC_CLI_ALLOW with a reason.'
-          );
-        }
-        continue;
-      }
-      // A whole-invocation allowlist covers its flags too — the script isn't here to check them against.
-      if (allow.has(`${doc}::${scriptRel}`)) continue;
-      DOC_FLAG_RE.lastIndex = 0;
-      let f;
-      while ((f = DOC_FLAG_RE.exec(tail))) {
-        const flag = f[1];
-        if (UNIVERSAL_FLAGS.has(flag)) continue;
-        if (allow.has(`${doc}::--${flag}`)) continue;
-        if (scriptMentionsFlag(src, flag)) {
-          // The criterion asks that the flag be PARSED, not merely present. The
-          // hard check can only prove presence (see scriptMentionsFlag), so the
-          // residual gap — a flag surviving in a usage comment after the code that
-          // read it was deleted — is reported as a WARNING, not a failure. Warning
-          // rather than failing is the deliberate choice: a usage banner is the
-          // ONLY place some scripts name a flag they genuinely handle via a helper,
-          // so failing here would resurrect the false positives that sank draft 1.
-          if (!scriptMentionsFlag(codeOnly(scriptRel, src), flag)) {
-            warnings.push(
-              `${doc} → \`node ${scriptRel} --${flag}\`: ${scriptRel} names \`--${flag}\` only in comments/usage text, `
-              + 'never in code — it may be a flag whose implementation was deleted. Verify it is still handled.'
-            );
-          }
-        } else {
-          violations.push(
-            `${doc} → \`node ${scriptRel} --${flag}\`: ${scriptRel} never mentions \`--${flag}\` anywhere in its source, so it cannot honour it. `
-            + 'An unrecognised flag is silently IGNORED, not an error — so the documented command does the wrong thing while every test stays green. '
-            + 'Add the flag, fix the doc, or allowlist it in DOC_CLI_ALLOW with a reason.'
-          );
-        }
-      }
-    }
-  }
-  return { violations, warnings, invocations };
-}
-
-// Drop `//` line comments and `/* */` blocks — enough to tell "named in code" from
-// "named only in a usage banner". Not a JS parser, and it does not need to be: a
-// false split here downgrades a warning, never a failure.
-function stripLineComments(src) {
-  return String(src)
-    .replace(/\/\*[\s\S]*?\*\//g, '')
-    .split('\n')
-    .map((l) => l.replace(/(^|\s)\/\/.*$/, '$1'))
-    .join('\n');
-}
-
-// Tracked markdown, via an argv ARRAY and never a shell string: `git ls-files
-// '*.md'` as a string goes through cmd.exe on Windows, where the quotes are
-// literal, git matches nothing, and the scan silently reports on zero files
-// (task 1002526).
-function trackedMarkdown() {
-  const out = execFileSync('git', ['ls-files', '*.md'], {
-    cwd: REPO_ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
-  });
-  return String(out || '').split('\n').map((f) => f.trim()).filter(Boolean);
-}
-
-const readFileOrNull = (rel) => {
-  try { return fs.readFileSync(path.join(REPO_ROOT, rel), 'utf8'); } catch { return null; }
-};
-
-const NAME = 'a doc that names a CLI matches the real CLI (G01)';
-
-// readCliSource — a CLI's source PLUS the source of the same-directory modules
-// it requires, concatenated.
-//
-// A big CLI is allowed to be more than one file: task 1003205 carved
-// scripts/gds/ship.js into ship-*.js phase modules, and the flag parsing for
-// e.g. `--no-surprise` moved with the phase that reads it. Scanning ship.js
-// alone then reports a documented, genuinely-honoured flag as a violation —
-// a false alarm that pushes the next agent toward silencing the rule via
-// DOC_CLI_ALLOW, which is exactly the outcome the rule exists to prevent.
-//
-// One level of relative requires is enough and keeps the read bounded — either a
-// same-directory sibling (where a carve puts things), or the module-hosted CLI a
-// scripts/gds/ SHIM forwards to: task 1003324 moved the design CLIs into
-// modules/ui-design/scripts/ and left `require('../../modules/ui-design/…')`
-// shims behind, so the flag a doc names is parsed in the module file. Nothing
-// else is followed — a require into src/ is not a CLI phase. A missing target is
-// skipped: the point is to find the flag, not to prove the require graph.
-const MODULE_CLI_RE = /^modules[\\/][^\\/]+[\\/]/;
-function readCliSource(rel) {
-  const src = readFileOrNull(rel);
-  if (src === null) return null;
-  const dir = path.dirname(rel);
-  const seen = new Set([rel]);
-  const parts = [src];
-  const RE = /require\(\s*['"](\.\.?\/[^'"]+)['"]\s*\)/g;
-  let m;
-  while ((m = RE.exec(src))) {
-    let sib = path.join(dir, m[1]);
-    if (!sib.endsWith('.js')) sib += '.js';
-    if (path.dirname(sib) !== path.normalize(dir) && !MODULE_CLI_RE.test(sib)) continue; // normalize: join() flips separators on Windows
-    if (seen.has(sib)) continue;
-    seen.add(sib);
-    const sibSrc = readFileOrNull(sib);
-    if (sibSrc !== null) parts.push(sibSrc);
-  }
-  return parts.join('\n');
-}
-
-function checkDocNamesRealCli({ files = null } = {}) {
-  const docs = files || trackedMarkdown();
-  // A lint that reports on nothing is worse than one that fails (the
-  // docs-entropy precedent) — this repo tracks hundreds of .md files, so an
-  // empty enumeration is a broken scan, not a clean result.
-  if (!docs.length) {
-    return {
-      name: NAME, ok: false, hardFail: true,
-      violations: ['scan defect — enumerated 0 tracked markdown files; a broken enumeration, not a clean result.'],
-      warnings: [], note: 'static scan of documented `node scripts/gds/*.js` invocations.',
-    };
-  }
-
-  const { violations, warnings, invocations } = scanDocs(docs, {
-    readDoc: readFileOrNull, readScript: readCliSource,
-  });
-
-  return {
-    name: NAME,
-    ok: violations.length === 0,
-    hardFail: violations.length > 0,
-    violations,
-    warnings,
-    note: `${invocations} documented \`node scripts/gds/*.js\` invocation(s) across ${docs.length} tracked .md file(s): the script exists and every long flag it is written with appears in that script's source. Static — never executes a CLI (a documented command that blocks on a prompt would hang CI). ${DOC_CLI_ALLOW.size} allowlisted.`,
-  };
-}
-
-function main() {
-  const r = checkDocNamesRealCli();
-  for (const v of r.violations) console.error(`\u2717 ${v}`);
-  console.log(`${r.hardFail ? 'FAIL' : 'PASS'}  ${r.note}`);
-  process.exit(r.hardFail ? 1 : 0);
-}
-
-if (require.main === module) main();
-
-module.exports = {
-  checkDocNamesRealCli, scanDocs, trackedMarkdown, scriptMentionsFlag, stripLineComments, readCliSource,
-  DOC_CLI_ALLOW, DOC_CLI_RE, DOC_FLAG_RE, UNIVERSAL_FLAGS,
-};
+require('../bongos/forwarder.js').forward(module, 'doc-cli-guard.js');

package/scripts/gds/doc-comment-coverage.js

@@ -1,139 +1,7 @@
 #!/usr/bin/env node
+// scripts/gds/doc-comment-coverage.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/doc-comment-coverage.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';
-// scripts/gds/doc-comment-coverage.js — the ADVISORY nudge behind the ADR 0095
-// doc-comment convention (task 1001654).
-//
-// WHY. ADR 0095 ratified one convention: every module and public symbol carries a
-// short doc-comment saying WHAT it does and WHY it exists, because agents navigate
-// this repo by literal text search and meaning written into the source is the only
-// findability layer with no index to keep fresh. A convention nobody measures decays
-// silently, so this reports the one part of it a machine can honestly check — does a
-// source file open with a module header at all.
-//
-// IT WARNS; IT NEVER FAILS. That ceiling is deliberate and is stated in the ADR: a
-// doc-comment gate that blocks a ship trains builders to write a filler line to get
-// past it, which is worse than no comment because it LOOKS like documentation.
-// Promoting this to hard-fail is an owner decision and needs its own ADR.
-//
-// What it cannot check: whether the prose is any good. Presence is a proxy. The
-// convention itself — what to write, and the worked examples — lives in
-// docs/code-conventions.md.
-
-const fs = require('fs');
-const path = require('path');
-const { execFileSync } = require('child_process');
-
-const ROOT = path.resolve(__dirname, '..', '..');
-
-// First-party server/CLI/module source. Deliberately NOT scanned:
-//   *.test.js            — a test's subject is named by its filename and its cases
-//   **/public/**         — browser assets; a worthwhile but separate sweep
-//   vendor / node_modules / *.min.js / *.generated.js — not ours to annotate
-const INCLUDE_RE = /^(src|scripts|modules)\//;
-const EXCLUDE_RE = /(^|\/)(node_modules|vendor|public|public-docs)\/|\.test\.js$|\.min\.js$|\.generated\.js$/;
-
-// A header is prose that appears BEFORE any code. A shebang and a 'use strict'
-// prologue are allowed to precede it — they are not code a reader learns from.
-const SKIP_PROLOGUE_RE = /^(#!.*|['"]use strict['"];?)?$/;
-
-// Minimum words for a header to count as saying something. A bare
-// `// config.js — config` restates the filename and teaches nobody anything;
-// the threshold is low on purpose so the check stays about ABSENCE, not style.
-const MIN_WORDS = 12;
-
-// Enumerate the files to scan. The glob goes to git as an argv ARRAY, never a
-// shell string — quoting a glob as `'*.js'` is literal on cmd.exe and matches
-// nothing, which is exactly how docs-entropy.js once "passed" on every Windows
-// checkout by scanning zero files (task 1002526).
-//
-// A zero-file result is therefore treated as a SCAN DEFECT and thrown, not
-// returned: this repo tracks hundreds of source files, so an empty enumeration is
-// never real, and a lint that silently proves nothing is worse than no lint.
-function trackedSourceFiles({ run } = {}) {
-  const exec = run || ((args) => execFileSync('git', args, { cwd: ROOT, encoding: 'utf8' }));
-  const out = exec(['ls-files', '*.js']);
-  const all = String(out).split('\n').map((s) => s.trim()).filter(Boolean);
-  if (!all.length) {
-    throw new Error('doc-comment-coverage scan defect: git ls-files returned no tracked .js files — the enumeration is broken, not the repo.');
-  }
-  return all.filter((f) => INCLUDE_RE.test(f) && !EXCLUDE_RE.test(f));
-}
-
-// Extract the leading comment block of a file, or '' when the first real token is
-// code. Handles both `//` runs and a `/* … */` block, and is CRLF-safe (every line
-// is trimmed before it is classified).
-function leadingComment(text) {
-  const lines = text.replace(/\r\n/g, '\n').split('\n');
-  let i = 0;
-  while (i < lines.length && SKIP_PROLOGUE_RE.test(lines[i].trim())) i++;
-
-  const block = [];
-  if (lines[i] && lines[i].trim().startsWith('/*')) {
-    for (; i < lines.length; i++) {
-      block.push(lines[i]);
-      if (lines[i].includes('*/')) break;
-    }
-  } else {
-    for (; i < lines.length && lines[i].trim().startsWith('//'); i++) block.push(lines[i]);
-  }
-  return block.join('\n');
-}
-
-function wordCount(comment) {
-  return comment.replace(/[/*]/g, ' ').trim().split(/\s+/).filter(Boolean).length;
-}
-
-// Returns { scanned, missing:[rel], thin:[{file,words}] }.
-function scanHeaders(files = trackedSourceFiles(), read = (rel) => fs.readFileSync(path.join(ROOT, rel), 'utf8')) {
-  const missing = [];
-  const thin = [];
-  for (const f of files) {
-    let words;
-    try {
-      words = wordCount(leadingComment(read(f)));
-    } catch (_) {
-      continue; // a file listed by git but unreadable here is not this check's problem
-    }
-    if (words === 0) missing.push(f);
-    else if (words < MIN_WORDS) thin.push({ file: f, words });
-  }
-  return { scanned: files.length, missing, thin };
-}
-
-const MAX_LISTED = 15; // keep the warning readable; the count carries the rest
-
-// Fitness-check entry point. ALWAYS returns ok:true / hardFail:false — see the
-// header. Findings surface as warnings so a red board still means something real.
-function checkDocCommentCoverage() {
-  const { scanned, missing, thin } = scanHeaders();
-  const warnings = [];
-
-  if (missing.length) {
-    const shown = missing.slice(0, MAX_LISTED).join(', ');
-    const more = missing.length > MAX_LISTED ? ` (+${missing.length - MAX_LISTED} more)` : '';
-    warnings.push(`${missing.length} source file(s) open with no module header — give each a line saying what it does and WHY it exists (docs/code-conventions.md, ADR 0095): ${shown}${more}`);
-  }
-  if (thin.length) {
-    const shown = thin.slice(0, MAX_LISTED).map((t) => `${t.file} (${t.words}w)`).join(', ');
-    const more = thin.length > MAX_LISTED ? ` (+${thin.length - MAX_LISTED} more)` : '';
-    warnings.push(`${thin.length} header(s) under ${MIN_WORDS} words — likely a restatement of the filename rather than the reason the file exists: ${shown}${more}`);
-  }
-
-  const covered = scanned - missing.length;
-  return {
-    name: 'module header doc-comments (ADR 0095)',
-    ok: true,
-    hardFail: false, // ADVISORY BY DECISION — promoting this to blocking needs owner sign-off (ADR 0095)
-    violations: [],
-    warnings,
-    note: `${covered}/${scanned} first-party source file(s) under src/·scripts/·modules/ open with a module header saying what they do and why (ADR 0095, task 1001654). ADVISORY — this check never fails the build; tests, browser assets and vendored code are out of scope.`,
-  };
-}
-
-if (require.main === module) {
-  const r = checkDocCommentCoverage();
-  process.stdout.write(`${r.note}\n`);
-  for (const w of r.warnings) process.stdout.write(`! ${w}\n`);
-}
-
-module.exports = { checkDocCommentCoverage, scanHeaders, leadingComment, wordCount, MIN_WORDS };
+require('../bongos/forwarder.js').forward(module, 'doc-comment-coverage.js');