hermes - 💡(How to fix) Fix Proposal: Optional post-commit hook for detecting single-source-of-truth drift in repo docs

Summary

I'd like to gauge interest in upstreaming a small, optional post-commit hook that detects when the same fact is restated in multiple places across repo docs / config and the copies drift apart — e.g., cli-config.yaml.example says gateway_timeout: 600 but docs/configuration.md still says 300.

I've been running a lightweight version in production for ~2 weeks. It's 0 LLM, ~800 LoC, pure regex + git stdlib, and ships as a stand-alone hook (no long-running process).

Why

In any repo with multiple long-form docs that LLM agents consume as authoritative context (CLAUDE.md, AGENTS.md, CONTRIBUTING.md, docs/, cli-config.yaml.example, README, skill SKILL.md files), it's easy for the same fact to drift:

• A default value gets bumped in the example yaml but the docs prose still cites the old number
• A skill description in skills/X/SKILL.md and the README go out of sync
• A config key gets renamed but only one of the docstring / example / migration note updates

For Hermes specifically, agents read CLAUDE.md / AGENTS.md / skill SKILL.md files as ground truth — drift becomes a silent failure mode where the agent acts on stale info.

Design sketch

A declarative drift detector configured via a small YAML:

single_source_of_truth:
  - fact: default_gateway_timeout
    canonical: docs/configuration.md
    canonical_pattern: 'gateway_timeout[:\s]+(\d+)'
    propagation:
      - cli-config.yaml.example
      - README.md
    propagation_pattern: 'gateway_timeout[:\s]+(\d+)'
    rule: values_must_match

On post-commit, the hook scans each propagation path. If the captured value differs from canonical, it prints a one-line warning naming both files. No fail, no block — just a hint to the committer.

What this is NOT

• Not a runtime check (gateway behavior unaffected)
• Not LLM-based (pure regex)
• Not a replacement for tests
• Not designed for source code (docs / config files only)

Questions before I do anything

1. In scope for upstream? Or better as an opt-in skill / stand-alone tool you point users at from CONTRIBUTING?
2. Location — tools/ / scripts/ / optional-skills/ if you like the skill route?
3. Hook install UX — auto-install via a hermes CLI subcommand, or just document and let users symlink it themselves?

Not opening a PR yet — checking interest first. Related: I've also just opened #31385 for the subprocess executor bridge; happy to sequence these however you prefer.

Thanks!