Date: September 30, 2025 (Updated: October 1, 2025) Status: Accepted · AMENDED 2026-07-30 (Amendment A, Arch) — decision stands; verification claims corrected. Read Amendment A at the foot of this file before citing any operational claim. Context: CORE-GREAT-2C Verification Work (GitHub Issue #194), CORE-GREAT-2D Discovery (GitHub Issue #195) Supersedes: None Superseded by: None
The decision below stands and is validated. Its verification claims are corrected. In one line:
this ADR was right about the pattern and wrong about which connector proved it — notion_spatial,
cited here as the Embedded-Intelligence proof, has zero importers, while Notion’s spatial capability is
live by another route. Do not cite §§106–112, 134, 144 or 204 as current fact.
Spatial deletions remain HELD pending PM’s call; spatial intelligence is protected representation.
Update 2026-08-29: PM ruled 2026-08-15/16 (spatial committed-theory review closed) and the
cold-island disposal is now EXECUTED — notion_spatial and its cold peers are deleted from the
live tree, retained as prior art via commit-hash references in the 2026-08-29 spatial-disposal
entry of docs/internal/architecture/decisions/decisions.log. The live spatial layer
(github_spatial, place_service, place_detector, home_state_service, spatial_intent_classifier,
the spatial_adapter base class, the slack socket-path pair) stays — rescope, not abandonment.
(Two interim CXO notices stood here from 2026-07-29 as placeholders pending the amendment. Amendment A supersedes them and folds in their substance, so they are collapsed to this pointer rather than left to rot — they had already gone stale twice, describing three layers where the measured map has four. Removing the duplicate copy is the fix; m-46: don’t keep a measurable fact in two places, and when one is superseded, delete it rather than leaving a reader to discover which is current. — CXO, 2026-07-30)
Piper Morgan will support three distinct spatial intelligence patterns optimized for different integration domains:
All patterns are considered first-class architectural approaches, and new integrations should choose the pattern most appropriate for their domain.
During CORE-GREAT-2C verification work (Phases 1-2, September 30, 2025), we discovered that Slack and Notion integrations implement fundamentally different but equally valid spatial architecture approaches.
During CORE-GREAT-2D investigation (Phase 0, October 1, 2025), we discovered Calendar implements a third distinct pattern using Model Context Protocol (MCP) delegation.
services/integrations/slack/spatial_*.pyrouter.get_spatial_adapter() → SlackSpatialAdapterBaseSpatialAdapterservices/intelligence/spatial/notion_spatial.pyNotionSpatialIntelligence class using router internallyservices/integrations/calendar/ (router) and services/mcp/consumer/ (adapter)router.method() delegates to MCP adapterBaseSpatialAdapterForce all integrations to use the same architectural approach.
Advantages:
Disadvantages:
Allow domain-optimized architectures based on integration characteristics.
Advantages:
Disadvantages:
Decision: CHOSEN - Benefits outweigh costs. October 2025 update: Calendar’s Delegated MCP Pattern confirms this approach scales well for protocol-based integrations.
Combine both patterns in single implementation (e.g., granular components with embedded access).
Advantages:
Disadvantages:
Key Insight: Domain-specific optimization outweighs standardization for standardization’s sake.
Different integration domains have fundamentally different spatial requirements:
Reactive Coordination (Slack):
Analytical Intelligence (Notion):
Production Validation:
Architectural Quality:
Developer Experience:
New spatial integrations must choose pattern based on:
Domain Complexity:
Requirement Stability:
Performance Criticality:
Testing Requirements:
Team Structure:
Domain Nature:
Integration Architecture (NEW - Oct 2025):
When to Use:
Structure:
services/integrations/{integration}/
spatial_types.py # Domain types and primitives
spatial_adapter.py # Main adapter (inherits BaseSpatialAdapter)
spatial_agent.py # Navigation and awareness
spatial_intent_classifier.py # Intent classification
spatial_mapper.py # Domain-specific mapping
spatial_memory.py # Memory storage/retrieval
tests/
test_spatial_*.py # Component-level tests
Access Pattern:
router = IntegrationRouter()
adapter = router.get_spatial_adapter()
result = await adapter.map_to_position(context)
When to Use:
Structure:
services/intelligence/spatial/{integration}_spatial.py
# Single comprehensive class
# 8-dimensional analysis methods
# Built-in analytics tracking
# Internal router usage
Access Pattern:
spatial = IntegrationSpatialIntelligence()
await spatial.connect()
analysis = await spatial.get_comprehensive_spatial_analysis(item_id)
When to Use:
Structure:
services/integrations/{integration}/
{integration}_integration_router.py # Minimal router (delegation only)
services/mcp/consumer/
{integration}_adapter.py # MCP adapter (inherits BaseSpatialAdapter)
# Spatial intelligence implementation
# MCP protocol compliance
# Custom spatial context extraction
Access Pattern:
router = IntegrationRouter()
# Router methods delegate to MCP adapter
events = await router.get_todays_events()
# Spatial methods also available
context = router.get_context(external_id)
Key Characteristics:
BaseSpatialAdapterExample: Calendar integration
services/integrations/calendar/calendar_integration_router.py (397 lines)services/mcp/consumer/google_calendar_adapter.py (499 lines)All spatial patterns must:
Router Integration:
8-Dimensional Spatial Metaphor:
Backward Compatibility:
Async Patterns:
Observability:
For Multiple Patterns:
For Documentation Overhead:
docs/architecture/spatial-intelligence-patterns.md)For Training:
For Consistency:
Slack (Granular Adapter Pattern):
Notion (Embedded Intelligence Pattern):
New spatial integrations must:
Pattern selection should be reviewed during:
services/integrations/slack/spatial_*.py (11 files)services/intelligence/spatial/notion_spatial.py (1 file)services/integrations/spatial_adapter.pydev/2025/09/30/2025-09-30-1025-prog-code-log.md| Date | Version | Author | Changes |
|---|---|---|---|
| 2025-09-30 | 1.0 | Claude Code | Initial ADR creation based on GREAT-2C verification |
Approved by: CORE-GREAT-2C Verification Work (Phases 1-4) Implementation Status: Complete and Operational Production Status: Both patterns deployed and validated
Next Review: After next spatial integration implementation Related ADRs: None (first spatial architecture ADR) Supersedes: None Superseded by: None (active)
See ADR-034: Plugin Architecture Implementation for the plugin system that now manages all spatial intelligence integrations. The three spatial patterns documented in this ADR are now implemented as plugins following the Wrapper/Adapter pattern, providing:
config/PIPER.user.mdPluginRegistryPiperPlugin interfaceAll spatial intelligence patterns remain valid architectural choices, now enhanced with plugin capabilities.
This ADR documents the discovery and validation of two production spatial patterns during GREAT-2C verification work (September 30, 2025).
Status of the amendment: ACCEPTED as a correction to this ADR’s verification claims. The decision is NOT reversed.
Authored by: Chief Architect · Sources: ../spatial-intelligence-layer-map-and-costed-options.md (the measured map), ../spatial-intelligence-experience-thesis.md (CXO, the experience argument).
Supersedes: the two ⚠️ notices at the head of this file, which were placeholders pending this amendment. Their substance is folded in here.
ADR-038 replaced ADR-013’s maximalism (“ALL external tool integrations MUST use the unified MCP + Spatial Intelligence pattern”) with domain-appropriate pluralism. That call was right and the evidence has strengthened, not weakened. Every connector a user can actually connect today has a live spatial path, and they arrive by different patterns — which is precisely what this ADR predicted:
| Advertised connector | Live spatial path | Pattern |
|---|---|---|
| Slack | integrations/slack/spatial_adapter (3 importers) |
Granular Adapter |
| Notion | mcp/consumer/notion_adapter → notion_integration_router |
(see A2 — not the pattern this ADR cited) |
| Calendar | mcp/consumer/google_calendar_adapter → calendar_integration_router |
Delegated MCP |
| GitHub | integrations/spatial/github_spatial + mcp/consumer/github_adapter |
full 8-dimensional, live |
No part of this ADR’s decision requires amendment. What requires amendment is how it evidenced the decision.
The Verification Results section (and the “Production-proven / Proven operational” lines at §§112, 134, 144, 204) asserted per-connector operational status. Measured 2026-07-30:
| ADR-038 claim | Current state | Verdict |
|---|---|---|
| “Slack spatial: 11 files, 100% operational” | slack/spatial_adapter live — 3 importers |
✅ holds |
| “Calendar spatial: 2 files, 100% operational, MCP protocol integration” | google_calendar_adapter live via calendar_integration_router |
✅ holds |
| “Notion spatial: 1 file, 100% operational, 8-dimensional analysis working” | intelligence/spatial/notion_spatial has ZERO importers and ~12 undefined methods (~75% abandoned) |
❌ CONTRADICTED |
But Notion’s spatial capability is live — via mcp/consumer/notion_adapter, which produces SpatialContext/SpatialPosition. Notion users are not missing place-modeling. What is dead is the specific file this ADR cited as proof.
Do not cite §§106–112, 134, 144 or 204 as current fact. They were true when written; one is now false, and all four are frozen snapshots of a moving system.
ADR-038 was right about the pattern and wrong about which connector proved it.
The notion_spatial citation didn’t go stale because the pattern failed. It went stale because CORE-MCP-MIGRATION #198 moved the implementation — replacing per-connector direct-API spatial modules with MCP consumer adapters built on the same spatial contract (BaseSpatialAdapter / SpatialContext, services/integrations/spatial_adapter.py) — while this ADR kept pointing at the superseded predecessor.
The error class: citing an IMPLEMENTATION as evidence for a PATTERN that outlives it. An implementation is a point-in-time fact with a short half-life; a pattern is a decision. Binding the second to the first means a successful migration makes the ADR look falsified — and that is exactly what happened here. An agent reading §107 against the cold notion_spatial file would conclude the pattern failed. It succeeded so thoroughly that the code it was demonstrated on became redundant.
Forward rule for this corpus: an ADR may cite implementations as illustration, never as proof of continuing validity. Where an ADR needs to make a live/cold claim, it must point at a command that re-derives it rather than freezing a table. (This amendment follows that rule — see A4.)
This amendment deliberately does not restate the live/cold inventory. It lives in ../spatial-intelligence-layer-map-and-costed-options.md, and every claim there is re-derivable:
python3 scripts/reachability-map.py services/integrations/spatial services/intelligence/spatial services/mcp/consumer
If any table in this corpus disagrees with that command, the command is right. (CXO’s formulation, 2026-07-30: “prose can’t be re-run; the tool can” — adopted here as a corpus convention, not just a note.)
⚠️ A string match on a module name is not an import edge. Both CXO and I independently mistook config_service.py:222’s feature-flag string "notion_spatial_mapping" for a notion_spatial importer, within a day of each other. Use the tool.
The committed-theory review has not concluded. Open: PPM’s roadmap-dependency slice; Lead’s cost estimate for an L4 (ambient-presence) monitoring loop; and PM’s call on the 10-module cold island, which should be described as “superseded implementation strategy, retained as prior art” rather than dead code — it holds the only worked examples of place-modeling for four connectors.
Spatial deletions remain HELD. Spatial intelligence is protected representation under PM’s standing rule, and nothing here authorizes removal.