feat: add CI documentation rules checker and docs-verify job

Enforce link resolution, glossary anchors, and readability rules on every push and PR; docs-only pushes to main still run docs-verify while skipping the simulator gate.
2026-07-10 10:54:28 +01:00
parent 9bec50e8f7
commit e6e57843cb
8 changed files with 422 additions and 9 deletions
@@ -0,0 +1,56 @@
+# CI documentation rules
+
+Automated checks for markdown in this repository. Enforced on every **pull request** and on **push to `main`** (including docs-only pushes that skip the simulator gate).
+
+Implementation: [`scripts/check_docs.py`](../../scripts/check_docs.py) reads [`scripts/docs_rules.yaml`](../../scripts/docs_rules.yaml).
+
+Workflow: [`.github/workflows/release.yaml`](../../.github/workflows/release.yaml) job **`Verify documentation`**.
+
+Tracked from [issue #1](https://git.produktor.io/eSlider/swarm-house/issues/1) and the [2026-07-10 audit](2026-07-10-audit.md).
+
+## Gates
+
+| Rule | Severity | What it checks |
+| --- | --- | --- |
+| Relative links | error | Every `[text](path)` and `[text](path#anchor)` to a local `.md` file resolves to an existing file |
+| Fragment anchors | error | `#anchor` fragments match a `##` or `###` heading in the target file (GitHub-style slug) |
+| Banned targets | error | Known-bad paths (e.g. deleted `03-storage-design.md`) are not linked |
+| Glossary fragments | error | All `00-glossary.md#…` links use anchors that exist in the glossary |
+| Section vs term links | warning | Links to glossary *section* headers (`#swarm--robotics`, …) are listed; prefer `###` term anchors where they exist |
+| Bare cross-refs | error | Prose cross-references to numbered docs without a proper markdown link |
+
+Warnings are printed in the job log but do not fail CI. Errors exit non-zero and block merge.
+
+## PR workflow
+
+```mermaid
+flowchart LR
+  PR[Pull request] --> DV[docs-verify]
+  PR --> V[verify simulator]
+  V --> S[Trivy scan]
+  DV --> OK{All required green?}
+  V --> OK
+  S --> OK
+  OK -->|yes| Merge[Mergeable]
+```
+
+| Event | `docs-verify` | `verify` + `scan` |
+| --- | --- | --- |
+| PR → `main` | always | always |
+| Push → `main` (code paths) | always | runs |
+| Push → `main` (docs/README/AGENTS only) | always | skipped (`paths-ignore`) |
+
+Docs-only changes therefore still get link and glossary validation on `main`; they do not trigger a semantic release.
+
+## Local run
+
+```bash
+python scripts/check_docs.py
+python scripts/check_docs.py --warnings-as-errors   # treat section-link warnings as failures
+```
+
+## Changing rules
+
+1. Edit `scripts/docs_rules.yaml` (paths, banned targets, preferred anchors).
+2. Adjust `scripts/check_docs.py` only when adding a new rule *type*.
+3. Add a row to the table above and mention it in the audit/improvement record if the change is significant.