[Documentation] Governance hardening: ADR system, canonical rule sourcing, template conformance, CI enforcement #64

Summary

DART's documentation already functions as the project's constitution for AI-assisted development: AGENTS.md (operational law), docs/README.md (mandatory 8-section template), design-assumptions.md (load-bearing trade-offs), per-package contracts, and CHANGELOG.md. An audit of the current system against "constitution-grade" requirements — unambiguous authority, recorded decisions, machine-enforceable rules — found one structural gap and several drift items. This umbrella issue tracks the hardening work; each landing PR references it.

Findings (verified on main)

• A. No decision records. Contract-level decisions (e.g. the member-ID alphabet vs. epoch reframe, the shutdown safe-join contract, the minimalist-assumptions principle) live only in issue/PR discussions. Agents editing code later cannot discover why a rule exists, and rejected alternatives get re-proposed.
• B. Normative rules duplicated across audience files. The verification trio and the docs policy are restated in AGENTS.md, CONTRIBUTING.md, and docs/README.md with no canonical home and no arbitration rule; duplicated text drifts.
• C. Template conformance drift. docs/registry.md lacks the Concurrency and Stability Contract sections; docs/tracker.md lacks Invariants & Guarantees; docs/dart.md (a cmd doc) has only 5 of 8 sections; docs/observability.md uses a two-package structure the template neither blesses nor forbids. (peer.md's "Wire form" covering Concepts is a reasonable heading variant.)
• D. Exported-symbol gaps. Eleven exported identifiers are not named in their package docs: cluster LearnPeer/Run/Self, chunk UnitSep/ErrInvalidConfig, fetch DefaultMaxFlight, engine NewMetrics, peer+registry ServeHTTP, tracker JoinRequest, metrics ErrInvalidName. (Test-list tables, by contrast, have zero drift.)
• E. No enforcement. All of the above were found by one-off scripts; nothing runs them on CI.

Work plan (four sequential PRs)

1. PR: ADR system — docs/adr/ (process README with trigger list T1–T5, template, lifecycle: accepted-on-merge, supersede-by-new-ADR with Binds audit surface, rejected-kept), three backfilled ADRs (minimalist assumptions as contract; visible-ASCII member IDs; shutdown safe-join), an AGENTS.md clause, index rows, Established by: links in design-assumptions.md.
2. PR: canonical rule sourcing — each normative rule gets exactly one canonical home; other files link; safety-critical duplicates (wire-protocol prohibitions in AGENTS.md) are kept but marked "verbatim copy — canonical: ..." with an edit-both reminder; a one-line arbitration clause in AGENTS.md and CONTRIBUTING.md.
3. PR: template conformance + sanctioned variants + symbol gaps — fill the missing sections (registry, tracker, dart), amend docs/README.md to bless machine-readable sanctioned variants (cmd doc, multi-package doc, heading aliases), and document the 11 missing exported symbols.
4. PR: enforcement — scripts/check-docs.sh (index consistency, test-name existence, exported-symbol naming, required sections incl. variants read from the template, ADR integrity, canonical-copy drift), a docs-governance CI job, a PR template, and one-line tool pointer files (CLAUDE.md etc. → AGENTS.md).

Notes

• Docs-only campaign; the standard trio still runs on every PR.
• The ADR trigger list deliberately excludes bug fixes, test additions, and internal refactors — bureaucracy resistance is a design goal.
• Check 3 (exported-symbol naming) is a floor check: it enforces naming, review keeps enforcing quality. No LLM in CI, by design.