feat(docs): forge docs impact — reusable documentation-impact graph

[CodeWithJuber]

What & why

docs check reconciles a fixed list of registries and docs sync sweeps a diff for raw identifiers. forge docs impact is the general, reusable version of the same idea: it answers "I changed X — which documented surfaces mention X and are now potentially stale?" as a proper documentation-reference graph instead of a per-file rule.

Built as a three-stage pipeline:

1. Entity extraction — a pluggable extractor registry derives the typed entities the project documents (command names, CLI flags, FORGE_* env vars, MCP tool names, exported symbols, brand tokens, the version, package.json fields) from their canonical sources, reusing docs_check's envVarsRead/srcFiles scanning and the COMMANDS/TOOLS registries. Adding a new entity type is one record in the registry.
2. Reference index — a word-boundary- and code-fence-aware scan of every doc surface (all tracked *.md, CITATION.cff, plugin manifests, the landing page, package.json) builds an inverted index: entity → every file:line that names it. Bare English-word-shaped entities only count inside backticks/fenced code so prose doesn't false-positive.
3. Impact query — from a git diff of the canonical sources, computes which entities changed (renamed command, added/removed flag, removed env var, touched export, version bump) and returns every doc location referencing them, ranked by confidence.

New command: forge docs impact

• Advisory by default (prints findings, exits 0); --strict exits non-zero for CI enforcement
• --since <ref> sets the diff base (default: session baseline, then HEAD)
• --staged reads the index instead of the working tree
• --min-confidence <n> drops low-signal hits
• --json for tooling/CI consumption
• docs check now prints a one-line pointer to docs impact when the working tree touches a documented entity

Honest limits (documented in docs/GUIDE.md): a token index catches a doc that names a changed entity — it can't see a paraphrase with no textual anchor, a screenshot/diagram, or a pure wording choice.

This PR also folds in an unrelated CI fix cherry-picked from claude/parallel-solving-3dc0ji (5e4fa79): .github/workflows/security.yml now runs the gitleaks binary directly instead of the licensed gitleaks-action@v3, which flakily fails CI. Included so this PR's own secret-scan check is green.

Adds src/docs_impact.js (~600 lines: extractor registry, inverted index, diff query) and test/docs_impact.test.js (~257 lines), and wires the command into src/cli.js / src/commands.js / src/docs_check.js, plus README.md, docs/GUIDE.md, CHANGELOG.md.

Checklist

• npm test passes (1068 passed, 0 failed, 2 skipped)
• npm run check passes (Biome lint + format — 0 errors, pre-existing unrelated warnings only)
• New public functions have a test
• Conventional commit message (feat:/fix:/docs: …)
• CHANGELOG.md updated under ## [Unreleased]
• No new runtime dependency (dev deps ok — zero runtime deps maintained)
• Substrate/docs updated (forge docs impact is new — README, GUIDE, CHANGELOG all updated)

Risk & rollback

• Risk level: low — new, isolated command; no changes to existing command behavior other than one extra advisory line in docs check output.
• Rollback plan: revert this PR; no data migrations or persisted state involved.

Extra checks (tick if applicable)

• npm run typecheck passes
• Input validated at boundaries; errors handled (no swallowing)
• Authorization/ownership checked (if it touches access) — n/a, local CLI tool
• Logs contain no secrets/PII
• If AI-assisted: I understand it, verified the package APIs, and it has tests

Test plan

• npm test — 1068/1068 passing (2 pre-existing skips)
• npx biome check — clean (0 errors)
• npm run typecheck — clean
• node src/cli.js docs check — reports docs and code agree

Co-Authored-By: Claude Opus 4.8 noreply@anthropic.com

---

Generated by Claude Code