doc-consistency

Detect documentation drift by running an audit from the repository root that enforces mechanical checks for single ground-truth facts and semantic consistency across the mandatory-sync four-file policy. It compares authored docs like CLAUDE.md, README.md, and architecture.md to quantify mismatches.

Documentation drift occurs when sync-locked files disagree, skill counts go stale, or test lists fall behind. Audit markdown files by running a systematic review that mechanically computes ground-truth facts and reports coherence across authored documents, replacing unguided manual passes.

Run a docs consistency audit before committing changes to the pipeline, a skill, the test suite, or the FSM. Also run it after editing CLAUDE.md, README.md, docs/architecture.md, or any file governed by the mandatory-sync four-file policy to catch drift.

You cannot automatically fix documentation consistency issues. Mechanical findings are computed and compared directly, but semantic findings require human judgment to verify before asserting, meaning the audit reports drift and coherence without auto-fixing contradictions.

The audit scope is limited to authored docs like CLAUDE.md, AGENTS.md, README.md, and docs/architecture.md. It explicitly excludes docs/maxi/specs/ and docs/maxi/adr/ directories because those are point-in-time artifacts that intentionally drift.

The best way to keep CLAUDE.md and architecture.md in sync is using a systematic audit that mechanically checks ground-truth facts and reports coherence. An unguided pass catches some drift by luck but misses table-level mismatches that a reproducible review catches.