swarm-house/docs/improvement/ci-rules.md

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 reads scripts/docs_rules.yaml.

Workflow: .github/workflows/release.yaml job Verify documentation.

Tracked from issue #1 and the 2026-07-10 audit.

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
ADR immutability	error	No modifications to existing docs/adr/ADR-*.md (compare origin/main); add new ADR to supersede

Warnings are printed in the job log but do not fail CI. Errors exit non-zero and block merge.

PR workflow

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

python scripts/check_docs.py
python scripts/check_adrs.py --base origin/main
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.