@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/do-api.js

@@ -0,0 +1,109 @@
+// scripts/bongos/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/bongos/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 };

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

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+// scripts/bongos/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/bongos/<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.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('node:child_process');
+const { currentScriptPath } = require('./forwarder.js');
+
+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/bongos/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/bongos/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/bongos/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.'],
+  ['docs/adr/0227-a-task-network-map-is-refused-the-goal-graph-is-the-map.md::scripts/bongos/spike-task-map.js',
+    'an accepted ADR recording how its evidence was measured; the spike harness was deleted once the verdict stood (task 1004857) and the ADR names the commit to recover it from.'],
+  ['docs/session-logs/2026-08-28-goal-1000072-stale-timer-and-network-map-spike.md::scripts/bongos/spike-task-map.js',
+    'a dated session log — the historical record, never rewritten — of the spike whose harness task 1004857 deleted; it describes what was run then, not what to run now.'],
+]);
+
+// `node scripts/bongos/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|bongos)\/[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))) {
+      // A frozen record (an ADR, a session log) still says scripts/gds/; judge the real script. rename-keep
+      const scriptRel = currentScriptPath(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/bongos/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/bongos/ 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/bongos/*.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/bongos/*.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,
+};

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

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+'use strict';
+// scripts/bongos/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 };