doc-freshness-gate

Detect documentation drift during git phase merges by running a non-blocking advisory gate that compares mtime and git-blame against the merge SHA to surface mismatches across five planning surfaces.

Doc drift occurs when documentation fails to reflect recent code changes. A dual-check mechanism uses file modification time (mtime) and git-blame to verify if documentation updates align with the current merge SHA.

No, the doc freshness gate is a non-blocking advisory mechanism. It filters real phase-merges, detects drift, emits greppable markers for audit trails, and returns a structured verdict without halting pipeline progress.

Track stale documentation across multiple project surfaces by targeting STATE, ROADMAP, PROJECT, CAPTURED, and LEARNINGS_SUMMARY files. The gate surfaces drift using mtime and blame checks at each phase merge.

Use an advisory gate for documentation freshness when teams risk misalignment from stale narratives at phase merges. It provides lightweight governance by detecting and recording drift without blocking development progress.

Using mtime and git-blame for drift detection relies on accurate filesystem timestamps and commit history. The gate mitigates false positives by filtering for real phase-merges and optionally consulting a drift-probe before returning verdicts.