How-to: gate CI on docs

mimus check is the mechanical tier — deterministic, offline, safe to gate. Exit 1 when any error-severity violation exists.

The gate

mimus check

Wire it like a test: run in CI on every PR. Doc paths, commands, symbols and your rules/*.toml conventions all gate the same way.

--no-cmd — never execute anything

The cmd checker verifies documented commands exist on PATH — it does not run them. But if you want to be explicit that a job runs nothing executable:

mimus check --no-cmd

--no-cmd skips the command checker entirely; path/symbol/rules checks still run.

Severity is the gate boundary

• error — mechanical, reproducible: dead paths, missing binaries, rule violations marked severity = "error".
• warn — env-dependent or heuristic: shown in output and --format json, never fails the run.

Tune per rule in rules/*.toml (severity = "warn").

Report for humans

mimus report                    # always exits 0 — full list
mimus check --format json       # machine-readable for tooling

report is the audit-view command: same violations, never a gate. reconcile-style tooling consumes the JSON.

Recommended setup

# whatever your CI is
- run: mimus check --no-cmd

Docs that can drift silently are docs that will. One line keeps them honest.

Gating only new drift (large backlogs)

mimus check --diff <spec> runs the same checkers but only over claims in files matching git diff --name-only <spec> — PR checks fail on new drift while the existing backlog is paid down:

- run: mimus check --diff "origin/${{ github.base_ref }}...HEAD"

--diff needs a git checkout — outside a repo it exits 2.

See claims & tiers for why the semantic tier can never be this gate.