Decisions

Every architectural decision, what was measured to reach it, and what would make us revisit it.

Each of these looks arbitrary until you know why. Changing one is fine; doing it without reading the reason is not.

Every record follows the same shape: the context with the numbers that produced it, the options weighed, the decision, and — the part that matters most — what would make us reverse it.

	Decision	The measurement behind it
001	TypeScript on Node	An empty Node process costs 40 ms of a 200 ms budget
002	JSON, one object per file	JSON parses 10k events in 6 ms; YAML takes 496 ms
003	No runtime dependencies in the core	`zod` costs 23.6 ms to import — 15% of the budget for a seven-field object
004	`cac` for arguments, esbuild for the bundle	`cac` imports in 3.3 ms against 17.1 ms for `commander`
005	Synchronous I/O, mandatory snapshot	Async reading measured 42 ms slower; the snapshot is 23× faster
006	Keep `cac`, load the TUI lazily	blessed costs 28 ms; the fast path must never pay for it
007	The repository is the product	80% of tracked files had nothing to do with kadence
008	The site lives in its own repository	A landing page cannot pass the ADR-007 test
009	The agent contract: both entry files, coded errors, a published schema	Claude Code loads `CLAUDE.md` and does not read `AGENTS.md`
010	Decisions are events; documents are linked, not stored	A grep buries the answering document among 10–35 candidates — 1.3 MB against 39 KB

The canonical records are in the product repository under docs/decisions/. The first eight were written in Ukrainian and the pages here are translations; from ADR-009 the records are written in English and these are copies. If the two ever disagree, the repository wins.