Igloo MCP

# ADR-0002: Living Reports Design v0.3.0 **Status**: Accepted **Date**: 2025-11-23 **Deciders**: Core team **Technical Story**: Living Reports feature implementation ## Context Need auditable business reports that: - Evolve safely with LLM assistance - Preserve full change history - Work offline-first - Never lose data - Prevent LLM hallucinations Options considered: 1. Database-backed reports 2. Markdown files with git history 3. JSON-backed with audit logs ## Decision Implement three-layer architecture: - **Layer 3 (Presentation)**: Quarto QMD rendered to HTML/PDF - **Layer 2 (Machine Truth)**: outline.json with structured data - **Layer 1 (Immutable Memory)**: audit.jsonl + backups **Key Design Choices**: - UUID-based storage (rename immunity) - File-based locking (portalocker) - Atomic writes (temp + fsync + rename) - LLM produces only structured patches (no free-writing) ## Consequences **Positive**: - Complete audit trail (who, when, what, why) - LLM-safe (validation before apply) - Offline-first (no database dependency) - Revertible (audit log replay) - Cross-platform (tested on Mac/Linux/Windows) **Negative**: - Filesystem locking complexity - No real-time multi-user collaboration - Quarto dependency for rendering **Neutral**: - Reports stored in ~/.igloo_mcp/reports/ (unified storage) ## References - [Technical Design](../living-reports/design-v030.md) - Full implementation details - [User Guide](../../living-reports/user-guide.md) - User-facing documentation