docs: split DESIGN_SPEC.md into pure design doc vs. current state/roadmap #303
Description
Problem
DESIGN_SPEC.md is a ~3500-line monolith that mixes two concerns:
- Design document — architecture, protocols, data models, how things work, design decisions and rationale. Timeless.
- Current state / roadmap — what's built, what's in progress, what's planned, open questions, backlog. Changes frequently.
These should be separate so the design doc reads as a clean design document without status noise.
Proposal
- Design doc (
docs/design_spec.mdor split intodocs/design/*.mdsub-pages) — pure design content. Architecture, protocols, data models, behavior specifications, design rationale. - Current state / roadmap — status tracking, backlog items, open questions, "what's built vs. coming". Could live as a separate doc page, or just defer to GitHub issues/milestones/project board.
Sections to separate
| Section | Keep in design doc? | Move to? |
|---|---|---|
| §1-15 (Vision through Implementation Notes) | Yes — core design | Stay |
| §16 Research & Prior Art | Yes — design rationale | Stay |
| §17 Open Questions & Risks | Split — design questions stay, status items move | Partial |
| §18 Backlog & Future Vision | No — this is roadmap | Current state doc or GitHub issues |
| "Status: Adopted/Planned" labels throughout | No — implementation status | Remove or move |
Also fix
- Internal TOC anchor links (currently broken in MkDocs due to anchor generation differences)
- Consider splitting into sub-pages by major section for better navigation
- The root
DESIGN_SPEC.mdcould become a pointer to the docs version, or be generated from it
Context
docs/design_spec.mdwas added in PR feat: add PR preview deployments via Cloudflare Pages #302 (copy of root file, rendered in MkDocs theme)- Root
DESIGN_SPEC.mdis referenced by CLAUDE.md, README, and many issues - The design doc is the blueprint — not documentation of what's currently built