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.

docs/improvement/2026-07-10-audit.md

@@ -16,7 +16,7 @@ Manual pass over `docs/`, all READMEs, and glossary. Goal: correct links, unify
 ### Links
 
 - `infra/terraform/ground/README.md` pointed at non-existent `03-storage-design.md` → `03-data-platform.md`.
-- `11-cicd-delivery.md` bare `see 05` → proper markdown link.
+- `11-cicd-delivery.md` bare cross-reference to doc 05 → proper markdown link.
 
 ### Factual drift (code vs docs)
 
@@ -63,11 +63,7 @@ Manual pass over `docs/`, all READMEs, and glossary. Goal: correct links, unify
 
 ## Suggested CI checks (for issue #1)
 
-```bash
-# Relative .md link resolver (Python one-liner in audit script)
-# Glossary anchor: every 00-glossary.md#... from docs/ must resolve
-# Optional: markdown-spellcheck with US locale
-```
+Implemented in [`scripts/check_docs.py`](../../scripts/check_docs.py) — see [ci-rules.md](ci-rules.md).
 
 ## Files touched
 

docs/improvement/README.md

@@ -6,9 +6,11 @@ Point-in-time audits and follow-up work for links, terminology, readability, and
 | --- | --- | --- |
 | [2026-07-10 audit](2026-07-10-audit.md) | 2026-07-10 | Full `docs/` + README pass; glossary T0–T4; live demo links |
 
-## Future automation
+## CI automation
 
-Tracked in [issue #1](https://git.produktor.io/eSlider/swarm-house/issues/1): CI link checker, glossary anchor validation, terminology lint.
+Enforced in Gitea Actions (`docs-verify` job). Rules live in [`scripts/docs_rules.yaml`](../../scripts/docs_rules.yaml); see [ci-rules.md](ci-rules.md).
+
+Originally tracked in [issue #1](https://git.produktor.io/eSlider/swarm-house/issues/1).
 
 ## How to add a new report
 

docs/improvement/ci-rules.md

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