architectural-proposals

## Context Proposals create alignment before code is written. Cheaper to change a doc than refactor code. Use this pattern when: - Architecture shifts invalidate existing assumptions - Product direction changes require new foundation - Multiple waves/milestones will be affected by a decision - External dependencies (Copilot CLI, SDK APIs) change ## Patterns ### Proposal Structure (docs/proposals/) **Required sections:** 1. **Problem Statement** — Why current state is broken (specific, measurable evidence) 2. **Proposed Architecture** — Solution with technical specifics (not hand-waving) 3. **What Changes** — Impact on existing work (waves, milestones, modules) 4. **What Stays the Same** — Preserve existing functionality (no regression) 5. **Key Decisions Needed** — Explicit choices with recommendations 6. **Risks and Mitigations** — Likelihood + impact + mitigation strategy 7. **Scope** — What's in v1, what's deferred (timeline clarity) **Optional sections:** - Implementation Plan (high-level milestones) - Success Criteria (measurable outcomes) - Open Questions (unresolved items) - Appendix (prior art, alternatives considered) ### Tone Ceiling Enforcement **Always:** - Cite specific evidence (user reports, performance data, failure modes) - Justify recommendations with technical rationale - Acknowledge trade-offs (no perfect solutions) - Be specific about APIs, libraries, file paths **Never:** - Hype ("revolutionary", "game-changing") - Hand-waving ("we'll figure it o...