oma-docs

# oma-docs - Documentation Drift Detector

## Scheduling

### Goal
Detect broken references in repo markdown — default glob `**/*.md` (verify mode), propose LLM-generated patch proposals for docs affected by recent code changes (sync mode), detect structural drift between English source docs and their translations (i18n mode), and lint translated docs for CJK style anti-patterns (lint mode). All 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.
- User asks whether translations are stale, which i18n docs drifted from the English source, or to lint translated docs for style issues (em-dashes in CJK targets, etc.).
- 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.
- After updating English source docs (`web/docs`), to find translations (`web/i18n/{lang}/...`) that drifted or went missing.
- Before a docs release, to lint CJK translations for content-level anti-patterns.
- Routine drift check on any docs-heavy repo.

### When NOT to use
- Generating docs from scratch for undocumented features → v2 create mode.
- Actually translating or restructuring docs → use `oma-translation` (`oma docs i18n` / `oma docs lint` only detect; they never edit translations).
- Symbol-level semantic drift (function signature changes not reflected in prose) → v2 L3 mode.
- CI-blocking enforcement → v2 block mode (v1 is warn-only).
- Explaining a code change as an educational document → use `oma-explanation` (this skill detects drift; it does not author explainers).

### 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`).

**i18n mode**: Optional `--min-severity <CRITICAL|HIGH|MEDIUM|LOW>` (default `MEDIUM`), optional `--json`.

**lint mode**: Optional `--locales <list>` (comma-separated CJK locales for the `cjk-em-dash` rule, default `ko,ja,zh`), optional `--json`. The default `wrong-language` rule always scans every locale under `web/i18n/` and is not narrowed by `--locales`.

### 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.

**i18n mode**:
- Per-pair structural drift signals (line count, heading count, EN-newer recency flag) with severity, as markdown summary or `--json`. Report-only: drifting pairs are handed to `oma-translation` in diff-sync mode.

**lint mode**:
- Style issues grouped by rule / language / file, as markdown summary or `--json`. Report-only: restructuring goes through `oma-translation`.

### 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).
- `cli/commands/docs/i18n-drift.ts`: EN↔translation structural drift detector (line/heading counts, last-commit recency; no LLM call).
- `cli/commands/docs/lint-i18n.ts`: translated-doc linter for selected-locale CJK em-dash style and all-locale wrong-language placeholders (no LLM call, no auto-fix).
- `docs/generated/doc-refs.json`: single-direction reference index, regenerated on every verify run. Gitignored — the CLI force-adds `docs/generated/` to `.gitignore` so generated artifacts are never committed.
- `docs/generated/url-drift.json`: lychee-produced URL drift report (written by background lychee spawn; gitignored under the same `docs/generated/` rule).
- `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), `docs.check_urls` (URL checking on/off, default true), and `docs.exclude` (glob list of markdown trees the walker must not scan — benchmark artifacts, translation mirrors, etc.; default `[]`) toggles.

### Control-flow features
- Mode is selected from the first argument: `verify`, `sync`, `i18n`, or `lint`.
- 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.
- i18n / lint: fully deterministic CLI reports; host LLM routes drifting pairs / style issues to `oma-translation`.
- 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` | `i18n` | `lint`). 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 dependencie