@bongos/core 1.21.175 → 1.21.176

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

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+// scripts/bongos/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/bongos 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.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { trackedMarkdown } = require('./doc-cli-guard.js');
+const { currentScriptPath } = require('./forwarder.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|bongos)|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/bongos/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/bongos/ci-grade.js)'],
+  ['docs/adr/0111-instance-hosting-provisioning-module.md::scripts/bongos/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/bongos/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)) {
+        // A frozen ADR still says scripts/gds/ (task 1004848, rename-keep); judge the file that holds the code.
+        const artifact = currentScriptPath(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/bongos/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,
+};

package/scripts/bongos/docs-entropy.js

@@ -0,0 +1,453 @@
+#!/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/bongos/docs-entropy.js              # scan + print summary
+//   node scripts/bongos/docs-entropy.js --json       # machine-readable JSON
+//   node scripts/bongos/docs-entropy.js --verbose    # print each finding
+//   node scripts/bongos/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)
+
+'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 { currentScriptPath } = require('./forwarder.js');
+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(/\/$/, '');
+      // A frozen record (an ADR, a session log) is never rewritten, so its links still point
+      // into scripts/gds/, which now holds only forwarders (task 1004848; rename-keep). Follow the move: the
+      // file the link names is still in the repo, one folder over.
+      const targetRel = path.relative(REPO_ROOT, targetAbs).split(path.sep).join('/');
+      if (!fs.existsSync(targetAbs) && currentScriptPath(targetRel) !== targetRel) {
+        targetAbs = path.join(REPO_ROOT, currentScriptPath(targetRel));
+      }
+
+      // 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 };