mirror of
https://github.com/boshu2/agentops.git
synced 2026-09-14 15:08:13 +08:00
boshu
3fe37b1867
Make `scripts/docs-build.sh --check` a MEANINGFUL signal instead of advisory noise (was 82 strict-mode warnings, always ignored). Root cause: mkdocs --strict fails on 82 links that leave docs/ (the knowledge graph deliberately links out to skills/, scripts/, schemas/, evals/, and canonical repo-root docs). All 82 were verified to resolve to REAL repo files on disk — zero accidental breaks — so they are intentional cross-references, not bugs. Fixes (category A + B, INFO-level drift, verified against built HTML anchors): - Anchors: GLOSSARY SKILLS.md#beads->#beads-br; INCIDENT-RUNBOOK scenario-C double->single hyphen (x2); pawls.md directive-precedence / diversity-mode / escalation double->single (referrers in ADR-0007, autonomy-ladder, pawls self); catch-derived-fuel membrane update anchor (single + date suffix). - Suffixes: levels L1-L4 README next-level links + workflows meta-observer -> explicit README.md targets. Dispositions (category C + D): the 82 intentional external cross-refs are enumerated in tests/docs/mkdocs-strict-allowlist.txt and explained per-class in docs/docs-build-dispositions.md. `docs-build.sh --check` now runs mkdocs --strict end-to-end (nothing weakened, no --no-strict) and fails on any warning NOT on the allowlist — proven: a fresh broken link still fails the check; the 82 pass. Result: `docs-build.sh --check` is CLEAN-or-dispositioned (exit 0). Wired doc into nav + CONTRIBUTING pointer.