Architectural Decision Records (ADR) Index

Last Updated: January 13, 2026 Total ADRs: 55 (000-054) 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: 55 ADRs (000-054)
Accepted: ~50 ADRs
Proposed/Draft: ~5 ADRs (047, 049, 050, 051, 053, 054)
Superseded: 0 ADRs
Deprecated: 0 ADRs

ADR Guidelines

Creating New ADRs

Use next sequential number (next: ADR-055)
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

January 13, 2026: Added ADR-053 (Trust Computation Architecture), ADR-054 (Cross-Session Memory Architecture) - Trust gradient and memory persistence from PDR-002; Updated ADR-052 (Tool-Based MCP Standardization)
January 13, 2026: Added ADR-050 (Conversation-as-Graph Model), ADR-051 (Unified User Session Context) - Multi-party conversation modeling and user context unification
January 9, 2026: Added ADR-049 (Conversational State and Hierarchical Intent) - Multi-turn conversation architecture from FTUX-PORTFOLIO
January 4, 2026: Added ADR-048 (ServiceContainer Lifecycle Management) - Singleton pattern and lifecycle management from ARCH-FIX-SINGLETON
December 3, 2025: Added ADR-047 (Async Event Loop Awareness) - Database connection event loop handling from setup wizard debugging
October 17, 2025: Added ADR-052 (Tool-Based MCP Standardization) - MCP implementation standardization from CORE-MCP-MIGRATION
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
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)
ADR-047: Async Event Loop Awareness - Database connection event loop handling for CLI/HTTP contexts
ADR-048: ServiceContainer Lifecycle Management - Singleton pattern and lazy initialization for service container
ADR-049: Conversational State and Hierarchical Intent - Multi-turn conversation architecture
ADR-050: Conversation-as-Graph Model - Multi-party, multi-agent conversational modeling
ADR-051: Unified User Session Context - Unifying user_id and session_id patterns
ADR-052: Tool-Based MCP Standardization - Standardize on tool-based MCP implementation
ADR-053: Trust Computation Architecture - Trust gradient model implementation from PDR-002
ADR-054: Cross-Session Memory Architecture - Three-layer context persistence model from PDR-002