Architectural Decision Records (ADR) Index

Last Updated: November 30, 2025 Total ADRs: 47 Status: Active

Overview

This index provides a complete catalog of all Architectural Decision Records (ADRs) in the Piper Morgan system. ADRs document important architectural decisions, their context, rationale, and consequences.

ADR Catalog

Foundation & Core Platform

ADR-000: Meta-Platform - Core platform architecture foundation
ADR-045: Object Model - “Entities Experience Moments in Places” - Foundational grammar for Piper’s consciousness (“Entities experience Moments in Places”)
ADR-046: Micro-Format Agent Architecture - Typed input decomposition and specialized agent routing for coordination

Integration & Communication

ADR-001: MCP Integration - Model Control Protocol integration
ADR-002: Claude Code Integration - Claude Code agent integration
ADR-013: MCP + Spatial Intelligence Integration Pattern - Spatial intelligence integration

Service Enhancement & Features

ADR-003: Intent Classifier Enhancement - Intent classification improvements
ADR-004: Action Humanizer Integration - Human-readable action formatting
ADR-014: Attribution First - Attribution-based architecture
ADR-015: Wild Claim - Wild claim handling approach
ADR-016: Ambiguity Driven - Ambiguity-driven design decisions

Data & Repository Management

ADR-005: Eliminate Dual Repository Implementations - Repository pattern standardization
ADR-006: Standardize Async Session Management - Session management patterns
ADR-025: Unified Session Management Architecture - Comprehensive session management
ADR-041: Domain Primitives - Item and List Refactoring - Polymorphic inheritance with Item/List as universal primitives

Infrastructure & Operations

ADR-007: Staging Environment Architecture - Staging environment design
ADR-008: MCP Connection Pooling Production - Connection pooling strategy
ADR-009: Health Monitoring System - System health monitoring
ADR-010: Configuration Patterns - Configuration management
ADR-012: Protocol Ready JWT Authentication - Authentication architecture
ADR-027: Configuration Architecture: User vs. System Separation - Configuration architecture (may partly supersede ADR-010?)
ADR-040: Local Database Per Environment - CODE ≠ DATA architecture (git-managed code, PostgreSQL per environment data)

Testing & Quality Assurance

ADR-011: Test Infrastructure Hanging Fixes - Test infrastructure reliability
ADR-023: Test Infrastructure Activation - Test activation patterns

Spatial Intelligence & Advanced Features

ADR-013: MCP + Spatial Intelligence Integration Pattern - Spatial intelligence integration
ADR-017: Spatial MCP - Spatial MCP implementation
ADR-018: Server Functionality - Server capability architecture
ADR-019: Orchestration Commitment - Orchestration strategy
ADR-020: Protocol Investment - Protocol investment decisions
ADR-021: Multi Federation - Multi-federation architecture
ADR-038: Spatial Intelligence Architecture Patterns - Two validated spatial patterns (Granular Adapter, Embedded Intelligence)

Core Patterns & Workflows

ADR-043: Application-Layer Stored Procedures - Multi-step workflow composition at application layer instead of database layer

Experimentation & Innovation

ADR-022: Autonomy Experimentation - Autonomous system experiments
ADR-024: Persistent Context Architecture - Context persistence design

External Integrations

ADR-026: Notion Client Migration - Migration to official Notion client library

Methodological Architecture

[ADR-028: Three-Tier Verification Pyramid(adr-028-verification-pyramid.md)\
Foundational framework for all agent coordination, requiring systematic evidence at each level before proceeding

ADR Status Summary

Total: 47 ADRs
Accepted: 47 ADRs (all current ADRs are accepted/implemented)
Superseded: 0 ADRs
Deprecated: 0 ADRs

ADR Guidelines

Creating New ADRs

Use next sequential number (next: ADR-046)
Follow naming convention: adr-XXX-descriptive-title.md
Include required sections: Status, Date, Context, Decision, Consequences
Update this index when adding new ADRs

ADR Lifecycle

Proposed: Initial draft, under review
Accepted: Decision approved and implemented
Superseded: Replaced by newer ADR
Deprecated: No longer applicable

Recent Changes

November 30, 2025: Added ADR-046 (Micro-Format Agent Architecture) - Typed input decomposition and specialized agent routing for coordination; emerges from Ted Nadeau’s advisor mailbox insights - Total now 47 ADRs (000-046)
November 29, 2025: Added ADR-045 (Object Model - “Entities Experience Moments in Places”) - Foundational conceptual grammar establishing how Piper perceives the world through Entities, Places, Moments, and Situations - Total was 46 ADRs (000-045)
November 24, 2025: Added ADR-044 (Lightweight RBAC vs Traditional) - Security architecture decision for role-based access control
November 22, 2025: Added ADR-043 (Application-Layer Stored Procedures) - Documents Piper’s stored procedure pattern at application layer (orchestration, workflows, intent handlers) - Total was 43 ADRs (000-043)
November 4, 2025: Added ADR-041 (Domain Primitives - Item and List Refactoring) - Polymorphic inheritance with Item/List as universal primitives - Total was 42 ADRs (000-041)
November 4, 2025: Added ADR-040 (Local Database Per Environment) - CODE ≠ DATA architecture for Sprint A8 P0 blockers
October 13, 2025: Updated index with ADR-037, ADR-038, ADR-039 (PROOF-8 audit) - Total was 42 ADRs
October 7, 2025: Added ADR-039 (Canonical Handler Fast-Path Pattern) - Dual-path intent architecture from GREAT-4
October 2-4, 2025: Updated ADR-034 (Plugin Architecture) with implementation verification (GREAT-3)
September 30, 2025: Added ADR-038 (Spatial Intelligence Architecture Patterns) - Three validated spatial patterns from GREAT-2
September 22, 2025: Added ADR-037 (Test-Driven Locking Strategy) and ADR-036 (QueryRouter Resurrection) from GREAT-1

Architecture Overview
Domain Models Index
Pattern Catalog
Technical Specifications
ADR-029: Domain Service Mediation Architecture - Complete domain service mediation for external system access
ADR-030: Configuration Service Centralization - Centralized configuration management through PortConfigurationService
ADR-031: MVP Redefinition - Core vs Feature MVP distinction for strategic development
ADR-032: Intent Classification Universal Entry - Intent classification as universal conversation entry point
ADR-033: Multi-Agent Deployment - Multi-agent coordination scripts deployment strategy
ADR-034: Plugin Architecture - Extensible plugin architecture for PM tool integration
ADR-035: Inchworm Protocol - Sequential execution methodology
ADR-036: QueryRouter Resurrection Strategy - Complete and reenable QueryRouter
ADR-037: Test-Driven Locking Strategy - Lock critical infrastructure with tests
ADR-038: Spatial Intelligence Architecture Patterns - Three validated spatial patterns (Granular, Embedded, Delegated MCP)
ADR-039: Canonical Handler Fast-Path Pattern - Dual-path architecture for intent classification
ADR-040: Local Database Per Environment - CODE ≠ DATA architecture (git-managed code, PostgreSQL per environment data)
ADR-043: Application-Layer Stored Procedures - Application-layer workflow composition pattern through OrchestrationEngine, WorkflowFactory, and IntentService (supports ADR-019)