7c400e9c02
Collapse docs/adr/ and docs/rfc/ into a single docs/rfc/ with proposed/, implemented/, and rejected/ subfolders. Every file is renamed to yyyy-mm-dd-topic-title.md, where the date is when the topic was first proposed (from git history). ADRs and RFCs that covered exactly the same topic are merged (property-based testing, session persistence); the umbrella RFC 005 stays split across its three implemented decisions, and RFC 006's deferred part-3 (API extractor reports) splits into its own proposed RFC. All cross-references become machine-checkable relative links instead of bare "ADR NNNN" / "RFC NNN" prose. Add a verify-md-links doc-sync gate (scripts/verify-md-links.ts) that checks every relative Markdown cross-link resolves, wired into doc-sync alongside verify-md-wrap. This makes the reorganization self-verifying: the same change that rewrote ~forty inter-doc links adds the check that proves none dangle. Document the cross-link convention in a new docs/AGENTS.md and record the gate as an implemented RFC. doc-sync, typecheck, lint, and the full test suite (667) all pass.
1.9 KiB
AGENTS.md — Docs
Conventions for authoring everything under docs/ (architecture, RFCs, cookbook, ADRs-now-RFCs). The repo-wide Markdown rules in the root AGENTS.md § "Type Safety and Documentation" still apply (one physical line per paragraph, fenced ts blocks must compile); the points below are docs-specific.
Cross-reference with machine-checkable links, never free prose
When one doc refers to another doc, an RFC, a package README, or any file in the repo, link it with a relative Markdown link to the actual path — [capability seams](rfc/implemented/2026-06-13-capability-seams.md), [architecture.md](architecture.md). Do NOT refer to it by bare prose or by a number ("see ADR 0009", "per RFC 005"): a number is not checkable, goes stale the moment a file is renamed, and forces the reader to go hunting. A relative link is verified mechanically — pnpm run verify-md-links (part of doc-sync, see the cross-link lint RFC) fails CI and the pre-push hook if any relative target does not exist, so a rename that orphans a link is caught before review rather than rotting silently.
This is why the RFC tree carries no stable numbers: files are named yyyy-mm-dd-topic-title.md and referred to by link, so they survive moves between proposed//implemented//rejected/ without a dangling reference. When you move or rename a doc, the gate tells you every inbound link you still need to fix.
The gate checks file existence, not #anchor validity — a link to a real file with a wrong heading fragment still passes. Prefer linking the file (and a heading when it helps the reader), but don't rely on the gate to catch a stale anchor.
RFCs
Design decisions and proposals live in rfc/ — one kind of doc, grouped by lifecycle into proposed//implemented//rejected/. See rfc/README.md for the naming scheme and when to write one.