docs: #1075 tranche-2 doc-file audit — 24 fixes across 16 files

[robotrocketscience]

Completes tranche 2 of the #1075 v4.0.0 documentation-audit release gate: the remaining doc-file buckets deferred by the doc-file-surface pass (DOCS-AUDIT-2026-07-04.md) and the two in-code ledgers (-incode.md, -tests-bench.md).

Refs #1075 — does NOT close it. The umbrella stays open until the v4.0.0 tag; this PR lands the last documentation tranche, leaving only the release cut.

What this is

An 8-batch multi-agent audit of all 95 remaining doc files at HEAD 13f7d0b4: CHANGELOG.md + CHANGELOG/v0–v3.md (verified against code at the corresponding tags), docs/design/* (58 current + 13 historical/), docs/adr/*, docs/experiments/*, prior docs/audits/* snapshots, tests/ READMEs, .github/pull_request_template.md, CITATION.cff. Every doc-bearing line read and checked; each HIGH independently re-verified and every refreshed source line-pointer re-grepped at HEAD before landing. Doc-text only; no code behavior changed. One atomic signed commit per file.

Ledger: docs/audits/DOCS-AUDIT-2026-07-04-docfiles.md (fourth and final companion to the doc-file, src/ in-code, and tests/bench in-code ledgers).

Coverage & tally

• 95 / 95 files audited (100%); 71 verified-clean, 24 findings.
• 24 findings: 0 CRITICAL, 2 HIGH, 14 MEDIUM, 8 LOW — all 24 fixed/annotated in place; 0 deferred, 0 code-side.

The two HIGHs

1. docs/audits/README.md omitted DOCS-AUDIT-2026-07-04-tests-bench.md from the index (a present record missing from the index fails the coverage rule) → indexed.
2. docs/design/context_rebuilder.md still documented the rebuilder as a PreCompact hook emitting additionalContext; superseded by fix(hook): PreCompact rebuild block rejected by harness — move injection to SessionStart(source=compact) #1031 (now session_start(source=="compact")) → delivery-channel banner added, design narrative + rebuild_v14 path unchanged.

Recurring drift fixed

#1031 PreCompact→SessionStart(compact) move (context_rebuilder, relevance-signal) · under-doc'd post-ship additions (claude_memory 7th ingest source kind in the replay-soak corpus; expand_bfs symbol; BFS_EDGE_WEIGHTS module location) · stale [Unreleased] compare link (v3.7.0→v3.8.0) · a dangling docs/no_embeddings_first.md link → PHILOSOPHY.md · CITATION.cff missing version/date-released · source line-pointer drift (dropped to symbol names where purely positional).

Frozen snapshots (historical/, ADRs, prior audits) corrected via banner/annotation only, never body rewrites. Per-file commits let each correction be reviewed and reverted independently.

After this tranche

Only the v4.0.0 release cut to PyPI remains on #1075.

[sourcery-ai]

Sorry @robotrocketscience, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

Important

Review skipped

Ignore keyword(s) in the title.

⛔ Ignored keywords (2)

• docs:
• release:

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 48a4a8b2-4fbd-4ce7-8750-c07085a1f1e1

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/issue-1075-tranche2-docfiles

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

PR-size soft cap

This PR is over the advisory size threshold:

• 197 changed lines (limit: 200)
• 17 changed files (limit: 3)

Bigger PRs collide with more open work, which under the parallel-session workflow tends to produce repeated attn:merge-conflict cycles (see #602). When practical, split into smaller PRs that each touch a focused surface.

This is advisory only — nothing is blocked. If the size is intentional (large refactor, module removal, generated code), apply the size:override label and this comment will be removed on the next push.

[github-actions]

merge-train: blocked

branch is not fast-forward on main (branch base 6770fdc937cea8670c4c9abb8484e839c5e373eb, current main 69417ce6e4c07e08666a414d0be49e60ff022200). Rebase locally (git rebase github/main), force-push, and re-add the label.

The ready-to-merge label has been removed. Address the issue above and re-add the label when you're ready for another attempt.

[github-actions]

merge-train: merged 40ecfbe → main via FF push.