architecture-decisions

# Architecture Decisions ## Fail-Fast Rule If an architecture decision is irreversible and affects 3+ modules, **stop and write an ADR first**. Never implement a cross-cutting change without documenting the trade-offs. Never assume a "quick fix" to a structural problem won't have cascading effects. ## The 10x Scale Rule Every architecture decision must pass this test: > "Does this scale to 10x the current number of integrations / users / events > without a rewrite?" If the answer is no, the architecture is wrong — even if it works today. For a system with N upstream integrations across M pool workers, plan for 10·N: - Pool workers may need to grow roughly linearly (resource allocation) - IPC throughput grows linearly with the number of entities - Memory footprint grows linearly — watch for per-entity overhead - New integration quirks multiply combinatorially ## ADR Template **Where ADRs live in this framework:** `.claude/adr/<ADR-NNN-slug>.md` — see `.claude/adr/README.md` for naming, lifecycle, and the existing records (`ADR-001` runtime state directory, `ADR-002` Python hooks package layout, `ADR-003` branch protection replaces skill signing). The existing ADRs are concrete examples to follow. Every significant architecture decision gets recorded: ```markdown # ADR-{NNN}: {Title} ## Status: PROPOSED | ACCEPTED | REJECTED | SUPERSEDED ## Context What problem are we solving? Why now? ## Decision Drivers - Driver 1 (e.g., latency budget) - Driver 2 (e.g., memory c...