0004: Docs point at code, never the reverse
Context: Docs rot when code changes. Need a checkable link between the two.
Decision: Frontmatter code: lists path or path::Symbol. One direction only.
Changing or moving anything listed → update the doc in the same commit.
Consequences: A checker can resolve every ref and find docs touching a diff (touching).
Code stays free of doc pointers.
→ reflected in architecture: docs layout.
Alternatives: | option | why not | |---|---| | code comments link to docs | two directions to maintain; clutters code | | bidirectional links | doubles the drift surface | | no explicit links, rely on search | not checkable; misses renames |