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.

### Dependencies
- `cli/commands/docs/extract.ts`: markdown AST + L2 pattern extractor.
- `cli/commands/docs/resolve.ts`: deterministic broken-ref checker.
- `cli/commands/docs/reporter.ts`: deterministic markdown/JSON report renderer (no LLM call; host LLM does narrative synthesis).
- `cli/commands/docs/sync-propose.ts`: git diff intake, reverse lookup, candidate-doc selector with secret redaction (no LLM call; host LLM drafts patches).
- `docs/generated/doc-refs.json`: single-direction reference index (git-tracked, regenerated on every verify run).
- `docs/generated/url-drift.json`: lychee-produced URL drift report (written by background lychee spawn; gitignored or tracked at user discretion).
- `lychee`: external Rust tool for URL link checking. Detected on PATH; install via `brew install lychee` or see https://github.com/lycheeverse/lychee#installation. Optional but recommended.
- `.agents/oma-config.yaml`: `docs.auto_verify` (workflow hook opt-in) and `docs.check_urls` (URL checking on/off, default true) toggles.

### Control-flow features
- Mode is selected from the first argument: `verify` or `sync`.
- verify: extract → resolve → report (fully deterministic CLI; host LLM adds narrative summary on top of the JSON/markdown output).
- sync: git diff → reverse lookup → candidate list (CLI) → host-LLM patch proposals → interactive accept/reject.
- Branches on `--json`, `--report-file`, LLM availability, and network reachability.
- Never blocks workflow completion in v1 (warn-only hook policy).

## Structural Flow

### Entry
1. Read first argument to select mode (`verify` | `sync`). If absent, print help and exit.
2. Load `oma-config.yaml` to check `docs.auto_verify` when invoked from a workflow hook.
3. Confirm required CLI dependencies (`oma docs verify`, `oma docs sync`) are on PATH.

### Scenes
1. **PREPARE**: Determine mode, resolve path/diff-range arguments, confirm tool availability.
2. **ACQUIRE**: Run extractor (`extract.ts`) to regenerate `doc-refs.json` from `docs/**/*.md` (verify) or build in-memory reverse index from existing `doc-refs.json` (sync).
3. **REASON**: Resolve each reference deterministically (verify) or correlate changed files to candidate docs via reverse lookup (sync).
4. **ACT**: Render the deterministic drift report (verify) or list candidate docs with matched refs (sync). Host LLM does any natural-language synthesis or patch drafting on top of this output.
5. **VERIFY**: Confirm output shape is valid (JSON schema check for `--json`; structured candidate list for sync).
6. **FINALIZE**: Print to stdout, write report file if requested, emit exit code.

### Transitions
- verify mode: PREPARE → ACQUIRE (extract) → REASON (resolve) → ACT (report) → FINALIZE.
- sync mode: PREPARE → ACQUIRE (reverse index) → REASON (candidate matching) → ACT (LLM proposals) → VERIFY (interactive) → FINALIZE (apply approved).
- If LLM is unavailable in verify: skip reporter summary, emit raw JSON drift report.
- If LLM is unavailable in sync: emit candidate-list-only output (no patch proposals); user reviews manually.
- If `doc-refs.json` is stale or missing in sync: run extractor first, then continue.

### Failure and recovery
- Extractor parse error on a single doc: skip doc + warn, continue with remaining docs.
- lychee unavailable or URL check incomplete: print install hint, skip URL checking, continue (core check is unaffected).
- Host-LLM context limit exceeded while drafting patches: process candidate docs in smaller batches.
- `oma docs` CLI not found: skip with installation hint (workflow hook: skip silently).
- `doc-refs.json` write failure: abort and report the write error; do not emit partial index.

### Exit
- Success (verify): drift report emitted; exit 0 if clean, exit 1 if broken refs found.
- Success (sync): approved patches applied; `doc-refs.json` regenerated; session summary printed.
- Partial success: extractor or resolver errors are explicit in the report; no silent failures.

## Logical