acedergren/doc-sync

Documentation Sync Audit

Audit project docs against codebase reality. Report drift or fix it.

NEVER

• Never update a doc based on what the code should look like — only sync to what it actually is now.
• Never fix docs for a section you didn't audit — partial fixes create false confidence.
• Never mark a roadmap item complete based on code presence alone — check git log for the deliberate completion commit.
• Never skip auditing CLAUDE.md / agent instructions — stale agent instructions cause cascading errors in future sessions.

Drift Classification: What Actually Goes Stale

Most doc-code drift falls into four categories with different detection approaches:

| Drift Type | Detection Signal | False Positive Risk | |------------|-----------------|---------------------| | Structural drift | Directory tree, plugin/middleware chain order | Low — filesystem is ground truth | | Path rot | File paths in docs that no longer exist | Low — use check-doc-paths.js | | Count drift | Test counts, permission counts, route counts | Medium — recount from actual files | | Roadmap lag | Completed work not reflected in docs | High — confirm git log intent |

Decision: Audit vs Fix

• $ARGUMENTS = empty or audit → report only, no edits
• $ARGUMENTS = fix → report then apply targeted edits, commit

When fixing: edit the minimum to correct drift. Don't rewrite prose, restructure sections, or add new content — this is sync, not authoring.

What to Audit

Architecture docs — plugin/middleware chain order, route module list, monorepo package list, directory structure tree.

Security docs — security plugins listed vs what's registered, permission counts, any security-related commits since last doc update (git log --oneline --since="$(git log -1 --format=%ai docs/SECURITY.md)" -- src/).

Test docs — actual test file count vs documented count, pass/fail counts (run suite to get current numbers).

Roadmap/changelog — git log for completed work not reflected in any phase. Flag commits with feat: or fix: prefixes that postdate the last roadmap update.

CLAUDE.md / agent instructions — naming conventions match actual patterns, documented file paths exist, anti-patterns section is current.

Scripts

bash scripts/list-doc-targets.sh
node scripts/check-doc-paths.js README.md docs/ARCHITECTURE.md

Report Format

| Doc | Section | Issue | Severity |
|-----|---------|-------|----------|

Severity: Critical (broken paths, missing security docs), Warning (stale counts, missing routes), Info (minor wording drift, outdated roadmap phases).

Commit (fix mode only)

docs: sync documentation with codebase [doc-sync]