@bongos/core 1.21.175 → 1.21.177

package/scripts/gds/doc-control-claims.js

@@ -1,168 +1,7 @@
 #!/usr/bin/env node
-// scripts/gds/doc-control-claims.js — prose cannot describe a control that does not
-// exist (task 1003418, audit ref A14 of the 2026-08-29 security audit, goal 1000084).
-//
-// WHY. control-manifest.js exists because ADR 0022 named three controls that had
-// silently stopped existing, and it works — for the 14 controls someone remembered
-// to list. Every phantom-control finding since (A6, A13, B31, B32, the row-8 patrol
-// that read green for months while never running) was the same failure one row
-// outside that list. A hand list only catches what a person already thought of, so
-// the manifest cannot be the whole answer. This check reads the claims FROM THE DOCS:
-// a doc sentence that says an enforcement artifact does something is a claim that
-// the artifact exists, and a claim whose artifact is gone reds the gate by
-// construction, with nobody having to add a row. The README's secrets section was
-// the proof on first run: it still sent readers to a TruffleHog workflow and a
-// pre-commit hook that had not existed since the core extraction — the ADR 0022
-// finding itself, one file over.
-//
-// WHAT COUNTS AS A CLAIM, deliberately narrow:
-//   · a backticked path to an ENFORCEMENT artifact — a hook, a workflow, a script
-//     under scripts/gds or a hooks dir (CONTROL_PATH_RE);
-//   · in a sentence that uses control vocabulary — enforce, gate, guard, block,
-//     refuse, scan, patrol, audit, fail the build (CONTROL_WORDS);
-//   · and does NOT speak of it in the past — removed, retired, replaced, used to,
-//     no longer (HISTORY_WORDS). An ADR recording what was deleted is history,
-//     which is not a claim; the same path in the present tense is.
-// Superseded / deprecated / rejected / withdrawn ADRs are skipped whole, and so are
-// the dated records (session logs, audits, limitations archives), which describe a
-// moment rather than the tree.
-//
-// WHAT IT DOES NOT PROVE: that an existing artifact is WIRED. That stays the
-// manifest's job (a file present but unhooked). The two halves are complementary:
-// this one scales to every doc and asks only "is it there"; the manifest asks
-// "is it connected" for the controls that matter most.
-//
-// ALLOWLIST. A true claim this scan cannot tell from history (an accepted ADR whose
-// design was later retired by a newer ADR) is listed in ALLOW with the reason. It
-// is shrink-only in practice: an entry that no longer matches anything is itself a
-// violation, so a fixed doc cannot leave a dead exception behind to hide the next.
-//
-// Its own file for the size-ratchet reason (the doc-cli-guard.js precedent);
-// fitness.js requires it in CHECKS, and control-manifest.js lists it, so this guard
-// cannot silently stop existing either.
-
+// scripts/gds/doc-control-claims.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/doc-control-claims.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 { trackedMarkdown } = require('./doc-cli-guard.js');
-
-const ROOT = path.resolve(__dirname, '..', '..');
-const NAME = 'a doc cannot describe an enforcement control that does not exist (task 1003418)';
-
-// Two shapes: a script or workflow with its extension, OR a git hook by its bare
-// name. Hooks under .husky/, .githooks/ and scripts/hooks/ carry no extension by
-// convention, and `.husky/pre-commit` is exactly the artifact ADR 0022 lost. The
-// names are git's whole documented set (githooks(5)), not a curated few.
-const GIT_HOOK_NAMES = [
-  'applypatch-msg', 'pre-applypatch', 'post-applypatch', 'pre-commit', 'pre-merge-commit',
-  'prepare-commit-msg', 'commit-msg', 'post-commit', 'pre-rebase', 'post-checkout', 'post-merge',
-  'pre-push', 'pre-receive', 'update', 'proc-receive', 'post-receive', 'post-update',
-  'reference-transaction', 'push-to-checkout', 'pre-auto-gc', 'post-rewrite', 'sendemail-validate',
-  'fsmonitor-watchman', 'p4-changelist', 'p4-prepare-changelist', 'p4-post-changelist',
-  'p4-pre-submit', 'post-index-change',
-];
-const CONTROL_PATH_RE = new RegExp(
-  '`((?:\\.claude/hooks|\\.github/workflows|scripts/gds|scripts/hooks|\\.githooks|\\.husky)/[A-Za-z0-9_.\\-/]+?\\.(?:js|mjs|cjs|sh|yml|yaml|ps1)'
-  + `|(?:\\.husky|\\.githooks|scripts/hooks)/(?:${GIT_HOOK_NAMES.join('|')}))\``,
-  'g',
-);
-const CONTROL_WORDS = /\b(enforc\w*|gates?|gated|gating|guards?|guarded|blocks?|blocked|refuses?|refused|hard[- ]?fails?|fails? (?:the )?(?:build|ci|merge|gate)|compensating control|pre-commit|pre-push|scans?|scanned|patrol\w*|audits?)\b/i;
-const HISTORY_WORDS = /\b(removed|deleted|retired|superseded|no longer|used to|never existed|did not exist|never survived|dropped|replaced|gone|historical|legacy|formerly|renamed)\b/i;
-const INACTIVE_STATUS_RE = /^\s*\**\s*status\s*\**\s*:?\s*\**\s*:?\s*\**\s*(superseded|deprecated|rejected|withdrawn)/im;
-const SKIP_PREFIXES = ['docs/session-logs/', 'docs/audits/', 'limitations/'];
-
-// `${doc}::${artifact}` -> why this present-tense mention is not a phantom control.
-const ALLOW = new Map([
-  ['docs/adr/0025-structured-criterion-task-link.md::scripts/gds/seed-v3-tasks.js',
-    'describes the grep a session HAD to do before this ADR; a seed script, not a control'],
-  ['docs/adr/0042-builder-self-deploy-ci-auto-merge.md::.github/workflows/grade-gate.yml',
-    'the CI grader gate this ADR designed; it was armed in the grader-off variant its own Status line records, and grading runs server-side (scripts/gds/ci-grade.js)'],
-  ['docs/adr/0111-instance-hosting-provisioning-module.md::scripts/gds/box.js',
-    'the dev-box control-plane runner, retired with dev boxes by ADR 0346 (dev-box-guard.js keeps it out)'],
-  ['docs/adr/0150-box-first-boot-bringup-vendored-instances.md::scripts/gds/box.js',
-    'the dev-box control-plane runner, retired with dev boxes by ADR 0346 (dev-box-guard.js keeps it out)'],
-]);
-
-// Sentence-ish units: prose sentences, blank-line paragraphs, and list/table rows.
-function sentencesOf(src) {
-  return String(src).split(/(?<=[.!?])\s+|\n\s*\n|\n(?=\s*(?:[-*|]|\d+\.)\s)/);
-}
-
-// Pure over its deps: docs is a list of repo-relative .md paths.
-function findPhantomClaims(docs, { read, exists }) {
-  const claims = [];
-  for (const doc of docs) {
-    if (SKIP_PREFIXES.some((p) => doc.startsWith(p))) continue;
-    const src = read(doc);
-    if (src == null) continue;
-    if (INACTIVE_STATUS_RE.test(src.slice(0, 2000))) continue;
-    const seen = new Set();
-    for (const s of sentencesOf(src)) {
-      // Judge the WORDING with every code span blanked: a path's own name must not
-      // decide the tense (`gone.yml` reads as "gone", `guard.js` as "guard").
-      const prose = s.replace(/`[^`]*`/g, ' ');
-      for (const m of s.matchAll(CONTROL_PATH_RE)) {
-        const artifact = m[1];
-        if (seen.has(artifact) || exists(artifact)) continue;
-        if (!CONTROL_WORDS.test(prose) || HISTORY_WORDS.test(prose)) continue;
-        seen.add(artifact);
-        claims.push({ doc, artifact, sentence: s.replace(/\s+/g, ' ').trim().slice(0, 160) });
-      }
-    }
-  }
-  return claims;
-}
-
-function evaluate(docs, deps, allow = ALLOW) {
-  const claims = findPhantomClaims(docs, deps);
-  const hit = new Set();
-  const violations = [];
-  for (const c of claims) {
-    const key = `${c.doc}::${c.artifact}`;
-    if (allow.has(key)) { hit.add(key); continue; }
-    violations.push(`${c.doc}: names \`${c.artifact}\` as a live control, and it does not exist — "${c.sentence}"`);
-  }
-  for (const key of allow.keys()) {
-    if (!hit.has(key)) violations.push(`stale allowance: ${key} no longer matches a claim — delete it from ALLOW in scripts/gds/doc-control-claims.js`);
-  }
-  return { violations, claims };
-}
-
-const readRel = (rel) => { try { return fs.readFileSync(path.join(ROOT, rel), 'utf8'); } catch { return null; } };
-const existsRel = (rel) => fs.existsSync(path.join(ROOT, rel));
-
-function checkDocControlClaims({ files = null } = {}) {
-  const docs = files || trackedMarkdown();
-  // A lint that reports on nothing is worse than one that fails (docs-entropy).
-  if (!docs.length) {
-    return { name: NAME, ok: false, hardFail: true, warnings: [],
-      violations: ['scan defect — enumerated 0 tracked markdown files; a broken enumeration, not a clean result.'],
-      note: 'static scan of enforcement artifacts named in docs.' };
-  }
-  const { violations, claims } = evaluate(docs, { read: readRel, exists: existsRel });
-  return {
-    name: NAME,
-    ok: violations.length === 0,
-    hardFail: violations.length > 0,
-    violations,
-    warnings: [],
-    note: violations.length
-      ? 'restore the control, correct the doc to name what really enforces it, or (for an accepted ADR a newer one retired) add an ALLOW entry saying which'
-      : `${docs.length} tracked .md file(s) scanned; every enforcement artifact named in a present-tense control sentence exists (${claims.length} allowlisted, each with its reason).`,
-  };
-}
-
-function main() {
-  const r = checkDocControlClaims();
-  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 = {
-  checkDocControlClaims, findPhantomClaims, evaluate, sentencesOf,
-  ALLOW, GIT_HOOK_NAMES, CONTROL_PATH_RE, CONTROL_WORDS, HISTORY_WORDS, INACTIVE_STATUS_RE,
-};
+require('../bongos/forwarder.js').forward(module, 'doc-control-claims.js');

package/scripts/gds/docs-entropy.js

@@ -1,445 +1,7 @@
 #!/usr/bin/env node
-// docs-entropy.js — markdown entropy scanner: stale links, broken anchors, duplicate prose.
-// Parallel to the knip dead-code scan (V3.R91 / repo-metrics.js); runs against
-// docs/ and all tracked *.md files.
-//
-// Three signal classes (analogous to knip's dead-file / dead-export signals):
-//   stale_links     — internal [text](path) links where the file doesn't exist
-//   broken_anchors  — [text](file.md#heading) where no such heading exists
-//   duplicate_prose — paragraphs (≥120 chars) that appear verbatim in 2+ files
-//
-// Usage:
-//   node scripts/gds/docs-entropy.js              # scan + print summary
-//   node scripts/gds/docs-entropy.js --json       # machine-readable JSON
-//   node scripts/gds/docs-entropy.js --verbose    # print each finding
-//   node scripts/gds/docs-entropy.js --file-ideas # POST findings to idea_inbox
-//
-// Exit codes:
-//   0  scan complete
-//   1  fatal error (including a scan defect: zero markdown files enumerated)
-
+// scripts/gds/docs-entropy.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/docs-entropy.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('node:fs');
-const path = require('node:path');
-const { execFileSync } = require('node:child_process');
-const { hasFlag, cliClient, requireSession, cliExit } = require('./cli-lib');
-
-const REPO_ROOT = path.resolve(__dirname, '..', '..');
-const MIN_DUPE_CHARS = 120;    // minimum paragraph length to flag as duplicate
-const MAX_DUPES_REPORTED = 20; // cap to avoid flooding the report
-
-// ---------- file collection ----------
-
-// argv array, never a shell string: `git ls-files '*.md'` as a string runs
-// through cmd.exe on Windows, where the quotes are literal, so git matched
-// nothing and the whole scan reported on zero files (task 1002526).
-function gitLsFiles(args) {
-  try {
-    return execFileSync('git', args, {
-      cwd: REPO_ROOT,
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'pipe'],
-    });
-  } catch (err) {
-    const detail = String(err.stderr || err.message || '').trim();
-    throw new Error(`docs-entropy: \`git ${args.join(' ')}\` failed in ${REPO_ROOT}: ${detail}`);
-  }
-}
-
-// Throws rather than returning [] — an empty enumeration in a repo that tracks
-// hundreds of .md files is a broken scan, and a lint that silently reports on
-// nothing is worse than one that fails.
-function collectMarkdownFiles({ run = gitLsFiles } = {}) {
-  const out = run(['ls-files', '*.md']);
-  const files = String(out || '').split('\n').map(f => f.trim()).filter(Boolean);
-  if (!files.length) {
-    throw new Error(
-      `docs-entropy: scan defect — enumerated 0 tracked markdown files under ${REPO_ROOT}. ` +
-      'This repo tracks hundreds, so this is a broken scan (bad git invocation or wrong cwd), not a clean result.'
-    );
-  }
-  return files;
-}
-
-// ---------- parsing ----------
-
-// GitHub-style heading → anchor slug.
-// Each space → one hyphen individually (so removed chars like em-dash leave
-// double-hyphens via the adjacent spaces, matching GitHub's actual output).
-function toSlug(heading) {
-  return heading
-    .replace(/<!--.*?-->/g, '')                    // strip HTML comments
-    .replace(/`([^`]+)`/g, '$1')                   // strip code backticks, keep content
-    .replace(/\*\*?|__?/g, '')                     // strip bold/italic markers
-    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')       // links → display text only
-    .toLowerCase()
-    .replace(/[^\w\s-]/g, '')                      // remove special chars (em-dash, ., etc.)
-    .replace(/\s/g, '-')                           // each space → hyphen (preserves --)
-    .replace(/^-+|-+$/g, '');                      // trim leading/trailing hyphens
-}
-
-// Parse a single markdown file.
-// Returns { headings:[{text,slug,line}], links:[{href,line}], paragraphs:[{text,startLine}] }
-function parseFile(absPath) {
-  let raw;
-  try {
-    raw = fs.readFileSync(absPath, 'utf8');
-  } catch (_) {
-    return { headings: [], links: [], paragraphs: [] };
-  }
-
-  // Split on CRLF **or** LF, and drop a leading BOM (task 1003314). A Windows
-  // checkout gets CRLF from git, and splitting on a bare newline then leaves a
-  // trailing carriage return on every line — which the heading regex below
-  // cannot match, because `.` excludes line terminators and `$` is not in
-  // multiline mode. The file parsed as having ZERO headings, so every
-  // [text](file.md#anchor) pointing into it was reported as a broken anchor:
-  // doc_broken_anchors read 21 on Windows and 6 in CI, and the quality ratchet
-  // a Windows builder ran was pure noise. Same failure family as task 1002526's
-  // `git ls-files` quoting bug, one layer in — a gate that reports confidently
-  // and wrongly on one platform.
-  const lines = raw.replace(/^\uFEFF/, '').split(/\r?\n/);
-  const headings = [];
-  const links = [];
-  const paragraphs = [];
-
-  let inCodeFence = false;
-  let paraLines = [];
-  let paraStart = -1;
-
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    const lineNo = i + 1;
-
-    // Track fenced code blocks (``` or ~~~)
-    if (/^(`{3,}|~{3,})/.test(line.trimStart())) {
-      if (inCodeFence) {
-        inCodeFence = false;
-      } else {
-        if (paraLines.length) {
-          paragraphs.push({ text: paraLines.join('\n'), startLine: paraStart });
-          paraLines = [];
-          paraStart = -1;
-        }
-        inCodeFence = true;
-      }
-      continue;
-    }
-    if (inCodeFence) continue;
-
-    // Headings
-    const headingMatch = line.match(/^(#{1,6})\s+(.+)$/);
-    if (headingMatch) {
-      if (paraLines.length) {
-        paragraphs.push({ text: paraLines.join('\n'), startLine: paraStart });
-        paraLines = [];
-        paraStart = -1;
-      }
-      const text = headingMatch[2].trim();
-      headings.push({ text, slug: toSlug(text), line: lineNo });
-      continue;
-    }
-
-    // Blank lines flush paragraph accumulator
-    if (line.trim() === '') {
-      if (paraLines.length) {
-        paragraphs.push({ text: paraLines.join('\n'), startLine: paraStart });
-        paraLines = [];
-        paraStart = -1;
-      }
-    } else {
-      if (!paraLines.length) paraStart = lineNo;
-      paraLines.push(line);
-    }
-
-    // Extract all [text](href) links from the line
-    const linkRe = /\[([^\]]*)\]\(([^)]+)\)/g;
-    let m;
-    while ((m = linkRe.exec(line)) !== null) {
-      const href = m[2].trim();
-      // Skip external URLs, mailto, and obvious non-paths (e.g. ellipsis placeholders)
-      if (/^(https?:|mailto:|ftp:)/.test(href)) continue;
-      // The hall deep-link resolver in its ROOT-RELATIVE form (task 1003542). The
-      // absolute form is already skipped above as external; linkify-refs.js emits
-      // this one whenever the instance origin is absent or loopback — which is now
-      // the normal case on a core checkout, since writing http://localhost:3000 into
-      // a committed doc is the worse bug. It is an APP ROUTE, not a file path, so
-      // counting it as a stale link is a false positive: 28 of them appeared the
-      // moment the linkifier could see this instance's 7-digit ids.
-      // Deliberately NOT a blanket `^/` skip — a genuinely wrong root-relative file
-      // link should still be reported as rot.
-      if (/^\/builders#/.test(href)) continue;
-      if (/^\.{2,}$/.test(href)) continue; // skip ... or .. used as placeholders
-      links.push({ href, line: lineNo });
-    }
-  }
-  // Flush trailing paragraph
-  if (paraLines.length) {
-    paragraphs.push({ text: paraLines.join('\n'), startLine: paraStart });
-  }
-
-  return { headings, links, paragraphs };
-}
-
-// ---------- stale link + broken anchor scan ----------
-
-function scanStaleLinks(relFiles) {
-  const findings = []; // {file, line, href, issue:'missing_file'|'missing_anchor', target, anchor?}
-
-  // Pre-build heading slug index: absPath → Set<slug>
-  const headingIndex = new Map();
-  for (const rel of relFiles) {
-    const abs = path.join(REPO_ROOT, rel);
-    const { headings } = parseFile(abs);
-    headingIndex.set(abs, new Set(headings.map(h => h.slug)));
-  }
-
-  for (const rel of relFiles) {
-    const abs = path.join(REPO_ROOT, rel);
-    const dir = path.dirname(abs);
-    const { links } = parseFile(abs);
-
-    for (const { href, line } of links) {
-      const hashIdx = href.indexOf('#');
-      const filePart = hashIdx === -1 ? href : href.slice(0, hashIdx);
-      const anchor   = hashIdx === -1 ? null  : href.slice(hashIdx + 1);
-
-      if (filePart === '') {
-        // Fragment-only link → self-referential (same file). Check the anchor
-        // against this file's headings.
-        if (anchor) {
-          const slugs = headingIndex.get(abs) || new Set();
-          if (!slugs.has(anchor)) {
-            findings.push({ file: rel, line, href, issue: 'missing_anchor', target: rel, anchor });
-          }
-        }
-        continue;
-      }
-
-      // Resolve target file path
-      let targetAbs;
-      if (path.isAbsolute(filePart)) {
-        targetAbs = path.join(REPO_ROOT, filePart);
-      } else {
-        targetAbs = path.resolve(dir, filePart);
-      }
-      targetAbs = targetAbs.replace(/\/$/, '');
-
-      // Check file existence
-      if (!fs.existsSync(targetAbs)) {
-        findings.push({
-          file: rel, line, href, issue: 'missing_file',
-          target: path.relative(REPO_ROOT, targetAbs),
-        });
-        continue;
-      }
-
-      // Check anchor against headings in the target .md file
-      if (anchor && targetAbs.endsWith('.md')) {
-        let slugs = headingIndex.get(targetAbs);
-        if (!slugs) {
-          const { headings } = parseFile(targetAbs);
-          slugs = new Set(headings.map(h => h.slug));
-          headingIndex.set(targetAbs, slugs);
-        }
-        if (!slugs.has(anchor)) {
-          findings.push({
-            file: rel, line, href, issue: 'missing_anchor',
-            target: path.relative(REPO_ROOT, targetAbs),
-            anchor,
-          });
-        }
-      }
-    }
-  }
-
-  return findings;
-}
-
-// ---------- duplicate prose scan ----------
-
-function scanDuplicateProse(relFiles) {
-  const byText = new Map(); // normalized text → [{file, line}]
-
-  for (const rel of relFiles) {
-    const abs = path.join(REPO_ROOT, rel);
-    const { paragraphs } = parseFile(abs);
-
-    for (const { text, startLine } of paragraphs) {
-      const trimmed = text.trim();
-      if (trimmed.length < MIN_DUPE_CHARS) continue;
-      // Skip content that is intentionally generated/duplicated across files:
-      // generated blocks, and the ui-design module's PLATFORM PREAMBLE, which
-      // its policy requires byte-identical in every skill it ships (ADR 0198 §4;
-      // tests/ui_design_skills.mjs pins the copies against PREAMBLE.md).
-      if (trimmed.startsWith('<!-- BEGIN GENERATED')) continue;
-      if (trimmed.startsWith('<!-- BEGIN PLATFORM PREAMBLE')) continue;
-      // Normalize internal whitespace for comparison
-      const key = trimmed.replace(/\s+/g, ' ');
-      if (!byText.has(key)) byText.set(key, []);
-      byText.get(key).push({ file: rel, line: startLine });
-    }
-  }
-
-  const dupes = [];
-  for (const [text, locs] of byText) {
-    if (locs.length < 2) continue;
-    // Only flag if it appears in 2+ distinct files
-    const files = new Set(locs.map(l => l.file));
-    if (files.size < 2) continue;
-    dupes.push({
-      snippet: text.slice(0, 200) + (text.length > 200 ? '…' : ''),
-      locations: locs,
-    });
-  }
-
-  dupes.sort((a, b) => b.locations.length - a.locations.length);
-  return dupes.slice(0, MAX_DUPES_REPORTED);
-}
-
-// ---------- idea_inbox filing ----------
-
-async function fileToInbox(staleLinks, brokenAnchors, dupes) {
-  await requireSession();
-
-  const items = [];
-
-  if (staleLinks.length) {
-    const body = staleLinks.slice(0, 15).map(f =>
-      `- \`${f.file}\`:${f.line} → \`${f.href}\` (file not found: ${f.target})`
-    ).join('\n') + (staleLinks.length > 15 ? `\n…and ${staleLinks.length - 15} more` : '');
-    items.push({
-      title: `docs-entropy: ${staleLinks.length} stale internal link(s) in markdown`,
-      body_md: body,
-      kind: 'bug',
-    });
-  }
-
-  if (brokenAnchors.length) {
-    const body = brokenAnchors.slice(0, 15).map(f =>
-      `- \`${f.file}\`:${f.line} → \`${f.href}\` (anchor #${f.anchor} missing in ${f.target})`
-    ).join('\n') + (brokenAnchors.length > 15 ? `\n…and ${brokenAnchors.length - 15} more` : '');
-    items.push({
-      title: `docs-entropy: ${brokenAnchors.length} broken heading anchor(s) in markdown`,
-      body_md: body,
-      kind: 'bug',
-    });
-  }
-
-  if (dupes.length) {
-    const body = dupes.slice(0, 8).map(d => {
-      const preview = d.snippet.replace(/\n/g, ' ').slice(0, 100);
-      const locs = d.locations.map(l => `\`${l.file}\`:${l.line}`).join(', ');
-      return `- "${preview}…" in: ${locs}`;
-    }).join('\n');
-    items.push({
-      title: `docs-entropy: ${dupes.length} duplicate prose block(s) across markdown files`,
-      body_md: body,
-      kind: 'cleanup',
-    });
-  }
-
-  const api = await cliClient();
-  for (const item of items) {
-    const r = await api.inbox.postInbox({ body: item });
-    if (r.ok) {
-      console.log(`  → filed idea #${r.data?.idea?.id}: ${item.title}`);
-    } else {
-      console.error(`  ! failed to file idea: ${JSON.stringify(r.data)}`);
-    }
-  }
-}
-
-// ---------- main ----------
-
-// Reusable detectors are exported (below) so gen-repo-map.js can build the doc
-// link-graph + staleness flags from the SAME logic (task 2013). The CLI body
-// only runs when invoked directly (require.main guard) — a `require()` gets the
-// exports without triggering the scan or the --file-ideas write.
-async function docsEntropyMain() {
-  const args = process.argv.slice(2);
-  const asJson    = hasFlag('--json', args);
-  const fileIdeas = hasFlag('--file-ideas', args);
-  const verbose   = hasFlag('--verbose', args);
-
-  let relFiles;
-  try {
-    relFiles = collectMarkdownFiles();
-  } catch (err) {
-    console.error(err.message);
-    return cliExit(1);
-  }
-
-  const linkFindings  = scanStaleLinks(relFiles);
-  const staleLinks    = linkFindings.filter(f => f.issue === 'missing_file');
-  const brokenAnchors = linkFindings.filter(f => f.issue === 'missing_anchor');
-  const dupes         = scanDuplicateProse(relFiles);
-
-  const result = {
-    scanned_files: relFiles.length,
-    stale_links: staleLinks.length,
-    broken_anchors: brokenAnchors.length,
-    duplicate_prose: dupes.length,
-    findings: {
-      stale_links: staleLinks,
-      broken_anchors: brokenAnchors,
-      duplicate_prose: dupes,
-    },
-  };
-
-  if (asJson) {
-    // cliExit, not process.exit: the JSON here can run well past the 64KB pipe
-    // buffer, and process.exit() drops unflushed stdout — CI saw the payload
-    // truncated mid-string (PR 148's flaky unit run). Natural exit flushes.
-    console.log(JSON.stringify(result, null, 2));
-    if (fileIdeas) await fileToInbox(staleLinks, brokenAnchors, dupes);
-    return cliExit(0);
-  }
-
-  console.log('Docs entropy scan');
-  console.log('─────────────────');
-  console.log(`  files scanned   : ${relFiles.length}`);
-  console.log(`  stale links     : ${staleLinks.length}`);
-  console.log(`  broken anchors  : ${brokenAnchors.length}`);
-  console.log(`  duplicate prose : ${dupes.length}`);
-
-  if (verbose) {
-    if (staleLinks.length) {
-      console.log('\n  Stale links (file not found):');
-      for (const f of staleLinks) {
-        console.log(`    ${f.file}:${f.line}  →  ${f.href}`);
-      }
-    }
-    if (brokenAnchors.length) {
-      console.log('\n  Broken anchors (heading not found):');
-      for (const f of brokenAnchors) {
-        console.log(`    ${f.file}:${f.line}  →  ${f.href}  (missing: #${f.anchor} in ${f.target})`);
-      }
-    }
-    if (dupes.length) {
-      console.log('\n  Duplicate prose:');
-      for (const d of dupes) {
-        const preview = d.snippet.replace(/\n/g, ' ').slice(0, 80);
-        console.log(`    "${preview}…"`);
-        for (const l of d.locations) console.log(`      ${l.file}:${l.line}`);
-      }
-    }
-  }
-
-  if (fileIdeas) {
-    console.log('\n  Filing findings to idea_inbox…');
-    await fileToInbox(staleLinks, brokenAnchors, dupes);
-  }
-
-  cliExit(0);
-}
-
-if (require.main === module) {
-  docsEntropyMain().catch((err) => {
-    console.error('fatal:', err);
-    cliExit(1);
-  });
-}
-
-module.exports = { collectMarkdownFiles, parseFile, scanStaleLinks, scanDuplicateProse, toSlug };
+require('../bongos/forwarder.js').forward(module, 'docs-entropy.js');