Hash-Based Drift Detection & Targeted Regeneration
Software documentation inevitably drifts as systems evolve. DOCCAD uses mechanical content hashing to detect drift automatically without requiring engineers to manually track every downstream derived view.
How Content Hashing Works
- When a derived page is generated (e.g.
docs/generated/recruiter/project-overview.mdx), the generator computes thesha256hash of every canonical file consulted:generation:source_documents:- id: architecture-system-overviewpath: docs/source/architecture/system-overview.mdcontent_hash: sha256:e3b0c44... - When a pull request edits
docs/source/architecture/system-overview.md, its byte sequence changes, resulting in a newsha256digest. - CI runs
scripts/detect_changes.py --allto compare on-disk hashes against the recorded hashes in each derived page. - If a hash mismatch is detected, the page is flagged
STALEinimpact.json.
Targeted vs Full-Corpus Regeneration
Full-corpus regeneration on every commit is expensive, wasteful, and noisy. DOCCAD adheres to the Incrementality Rule:
- Only the specific derived pages flagged as stale in
impact.jsonare scheduled for regeneration. - Unaffected derived views remain untouched, preserving stable Git history and minimizing AI compute costs.
- Full-corpus regeneration exists solely as an explicit manual trigger (
workflow_dispatchwithconfirm: all).