oma-docs

oma-docs - Documentation Drift Detector

Scheduling

Goal

Detect broken references in docs/**/*.md (verify mode) and propose LLM-generated patch proposals for docs affected by recent code changes (sync mode). Both modes run on-demand; sync is always interactive.

Intent signature

• User asks to check if docs are up to date, find broken doc links, verify file paths referenced in docs, or detect documentation drift.
• User asks to update docs after a code change, propose doc patches for a git diff, or sync affected docs.
• A workflow hook checks docs.auto_verify: true and runs oma docs verify --json at completion.

When to use

• After a refactor, rename, or file deletion, to find stale references in docs.
• Before a release, to confirm that CLI commands, file paths, and config keys in docs still exist.
• After a significant git diff, to discover which docs reference the changed files and may need updating.
• Routine drift check on any docs-heavy repo.

When NOT to use

• Generating docs from scratch for undocumented features → v2 create mode.
• Multilingual translation of docs → use oma-translator.
• Symbol-level semantic drift (function signature changes not reflected in prose) → v2 L3 mode.
• CI-blocking enforcement → v2 block mode (v1 is warn-only).

Expected inputs

verify mode: Optional glob path (default **/*.md), optional --json flag, optional --report-file <path>.

sync mode: Optional git diff range (default --cached, fallback HEAD~1..HEAD).

Expected outputs

verify mode:

• Markdown drift report to stdout (default), or raw JSON with --json, or full markdown written to file with --report-file.
• Exit code 0 if clean, 1 if any broken refs found.

sync mode:

• Per-doc patch proposals drafted by the host LLM from the CLI's candidate-doc list, confirmed per doc ([y] apply [n] skip [d] diff [s] full proposal style).
• Docs modified only on explicit user approval; doc-refs.json regenerated after applies.