feat: CI-enforced doc drift merge gate (#117/#141)

[marcusglee11]

Objective

Implements the approved v3 spec from #117 — CI-enforced documentation drift control.

What changed

New files

• tools/validate_doc_drift_gate.py (719 lines) — Validator that checks PRs against config/docs/authority_registry.yaml:

  • Check A: Canonical doc changes require reconciliation packet or valid exemption (reason: other rejected)
  • Check B: Authority registry transitions require approval evidence (GitHub URL + verdict: approved)
  • Check C: Derived surfaces must be fresh when canonical docs change
  • Check D: Emergency manual repairs need follow-up issue URL (not pending)

• .github/workflows/doc_drift_gate.yml — GitHub Actions workflow running the validator on PRs/pushes touching docs/** or config/docs/**. Handles both PR and push events.

• tests/test_doc_drift_gate.py (361 lines) — 12 test cases covering all gate checks + edge cases. All passing.

Parent Hermes fixes (post-EA implementation)

• classify_file: paths listed as derived_surfaces by any group are classified as derived, not canonical
• check_derived_freshness: excludes reconciliation packet paths from canonical check
• check_emergency_repair: derived files updated alongside canonical sources are normal regeneration, not emergency

EA review fixes (AMEND → fixed)

• Critical: workflow base-ref handles push events where github.base_ref is empty
• Warning: removed dead has_valid_packet variable
• Warning: emergency repair check uses per-file source check

Verification

12 passed in 1.82s

EA dispatch evidence

• Plan: DeepSeek Pro v4, $0.0562, 198s
• Implement: DeepSeek Flash v4
• Review: DeepSeek Pro v4, $0.0349, 80s, verdict: AMEND (6 findings, all addressed)
• Parent verification: GLM-5.2, 12/12 tests passing, diff inspected

Control plane

• Tracking issue: Tracking: Doc-Drift Merge Gate (#117 + #122 + #125) #141
• Spec issue: Spec: make documentation drift control merge-enforced #117 (approved v3 spec)
• Related: Implement advisory documentation drift sweep issue creator #122 (advisory sweep — next), Add doc-entrypoint freshness check to maintenance sweeps #125 (entrypoint check — after Implement advisory documentation drift sweep issue creator #122)

Non-goals

• Does not modify existing authority registry or schema
• Does not modify existing CI workflows
• Does not implement Implement advisory documentation drift sweep issue creator #122 or Add doc-entrypoint freshness check to maintenance sweeps #125 — those are next in the sequence