docs: repair strict docs-build link/anchor warnings + disposition the rest (age-y0ww)

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.
This commit is contained in:
boshu
2026-07-08 22:42:41 -04:00
parent 9903300788
commit 3fe37b1867
16 changed files with 264 additions and 23 deletions
+1 -1
View File
@@ -88,7 +88,7 @@ tree.
**When to use:** Coordinating N autonomous workers through shared memory (stigmergy) without central orchestration.
**Complexity:** High (advanced, multi-session)
**Key skills:** /swarm
**Deep dive:** [meta-observer/](meta-observer/) (pattern guide, examples, showcase)
**Deep dive:** [meta-observer/](meta-observer/README.md) (pattern guide, examples, showcase)
## Flowchart