docs-instrument

docs-instrument

A repository has adopted the docs-quality rule set. Most of its rules carry a runnable verification, and none of those verifications runs yet. This skill turns that rule set into a gate that actually fails.

Work in cost order. The declaration retrofit is first because eight other families read the declaration, and none of their checks can classify a page until it lands.

Stop condition

Stop when all five hold. Do not keep going, and do not add rules.

1. Every checks/ script the repo wires up exits 0 with --self-test.
2. Every wired check has been seen red once, on a planted violation you reverted.
3. Every file path named in a runner target, a lint config or a rule row resolves on disk.
4. The signal manifest names every signal, including the deferred ones and their preconditions.
5. The whole-tree warning counts are recorded as the ratchet baseline.

A check that cannot go red is not coverage. A path that does not resolve is not a check. Both are the failure this whole gate exists to prevent.

Before you start

• Read rules/docs-quality/checks.md. It carries one row per script: what it checks, how to run it, its exit codes and its fixtures. Every flag beyond the common four lives there. Never invent a script name or a flag.
• Every Python check shares one interface: python3 checks/<name>.py [--root DIR] [PATH ...] [--format text|json] [--self-test]. Exit 0 is clean, 1 is findings, 2 is a usage error or missing input. Findings print as path:line: DOC-XXX-nn: message.
• Find the generator config: mkdocs.yml, book.toml, .vitepress/config.*, docusaurus.config.*, astro.config.*, docs/conf.py. The answer decides most of the wiring. See references/wiring-by-generator.md.
• Do not rewrite prose in this skill's work. Retrofits and configs only. A content fix belongs in its own change.

The procedure

Step 1. Build the published-file list

Every check reads this list. Getting it wrong is how a prose lint ends up reporting on research notes and agent config (DOC-PLAIN-23).