Tianyi Cui
605587e79c
Add a second axis to every RFC — its class (feature, bug-fix,
simplification, architecture, process, testing) — encoded in the path
as docs/rfc/{lifecycle}/{class}/file.md. The folder is the label, so
the closed set is enforced by structure rather than a parsed field.
Two new doc-sync gates back it:
- verify-rfc-classification: every RFC sits in a valid class folder and
the README index lists it under the matching lifecycle→class heading.
- verify-doc-refs: every docs/*.md path cited in a packages|examples TS
comment resolves — closes a drift class verify-md-links can't see, and
catches the four comment refs this reorg moved.
The README gains a Classification section explaining the taxonomy and
per-class index sub-sections. A self-referential process RFC records why
the scheme is path-encoded and gated.
2.1 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/architecture/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 lifecycle folders (proposed//implemented//rejected/) and class folders 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 (proposed//implemented//rejected/) then by class (feature/bug-fix/simplification/architecture/process/testing). See rfc/README.md for the class definitions, the naming scheme, and when to write one.