Operational Freshness & Drift Metrics
Maintaining high documentation fidelity requires continuous measurement of repository freshness, drift ratios, and validation health.
Core Operational Metrics
- Staleness Ratio: The percentage of derived pages whose recorded
content_hashmismatches the current on-disk canonical hash.Staleness Ratio = (Count of Stale Derived Pages / Total Derived Pages) * 100% - Canonical Coverage: The ratio of canonical documents that have opted into automated derivation (
ai_generation.allowed: true). - Validation Pass Rate: The percentage of CI validation runs that pass without schema, link, or hash violations.
Automated Weekly Health Sweeps
Scheduled GitHub Actions workflows execute scripts/detect_changes.py --all weekly:
- Generates an updated
impact.jsonreport. - Opens or updates an advisory GitHub issue summarizing any un-reconciled stale views.
- Triggers automated draft PRs for derived views whose contracts permit automatic maintenance.