ADR-150: ADR Single Source of Truth Consolidation
Status
ACCEPTED (2026-02-03)
Context
CODITECT had three separate ADR numbering schemes across repositories:
| Repository | Location | ADR Count | Example Conflicts |
|---|---|---|---|
| coditect-core | internal/architecture/adrs/ | 70+ | ADR-001 = Framework Architecture |
| cloud-infra docs-site | docs-site/docs/architecture/adrs/ | 60+ | ADR-001 = Async Task Executor |
| cloud-infra backend | docs/architecture/adrs/ | 20+ | ADR-001 = Floating Licenses |
This caused:
- Number collisions - Same number, different content
- Cross-reference confusion - Which ADR-012 is referenced?
- Maintenance burden - Updating ADRs in multiple places
- Discovery difficulty - Finding the authoritative version
Decision
Single Source of Truth: coditect-core
All ADRs will be numbered and maintained in coditect-core only.
AUTHORITATIVE LOCATION:
coditect-core/internal/architecture/adrs/ADR-{number}-{slug}.md
OTHER REPOSITORIES:
- Reference by number (e.g., "See ADR-053")
- Link to coditect-core ADR
- Do NOT maintain separate numbered ADRs
Migration Strategy
Phase 1: Immediate (Complete)
- Created ADR-009 (Multi-Tenant Architecture)
- Created ADR-012 (Data Isolation Strategy)
- Created ADR-053 (Cloud Context Sync Architecture)
Phase 2: Audit & Map (Next)
- Audit all cloud-infra ADRs
- Identify unique content not in coditect-core
- Assign new numbers from available range
Phase 3: Migrate Unique ADRs
- Copy unique cloud-infra ADRs to coditect-core with new numbers
- Update cross-references
- Add "Migrated from" notes
Phase 4: Deprecate Duplicates
- Mark cloud-infra ADRs as "Superseded by coditect-core ADR-XXX"
- Redirect references
- Eventually archive
Number Allocation
Reserved Ranges:
| Range | Purpose |
|---|---|
| 001-099 | Core Framework ADRs |
| 100-149 | Platform & Infrastructure |
| 150-199 | Governance & Standards |
| 200-299 | Cloud Services (migrated from cloud-infra) |
| 300-399 | Licensing (migrated from backend) |
| 400-499 | LMS (Learning Management System) |
| 500+ | Future expansion |
Available Numbers (001-099): 7, 17-19, 22-31, 33-34, 36-37, 39, 42-43, 46-49, 51-52, 55, 58-59, 61-70, 72-73, 77-81, 83, 85-87, 92-99
Cloud-Infra ADR Mapping
ADRs to Migrate (Unique Content):
| cloud-infra # | Title | New coditect-core # | Status |
|---|---|---|---|
| 022 | Codebase Indexing Expansion | ADR-022 | Migrate |
| 023 | SQLite Scalability Analysis | ADR-023 | Migrate |
| 024 | Multi-Tenant Platform | ADR-009 | Merged |
| 025 | Comprehensive Entry Schema | ADR-025 | Migrate |
| 026 | Intent Classification | ADR-026 | Migrate |
| 027 | Guardrail Engine | ADR-027 | Migrate |
| 042 | Litestream Sync | ADR-042 | Migrate |
| 043 | PowerSync | ADR-043 | Migrate |
| 046 | Continual Learning | ADR-046 | Migrate |
| 047 | Platform Foundation | ADR-047 | Migrate |
| 048 | PILOT Execution | ADR-048 | Migrate |
| 049 | Component Creation | ADR-049 | Migrate |
| 051 | Work Discovery | ADR-051 | Migrate |
| 052 | Intent-Aware Context | ADR-052 | Migrate |
| 055 | Licensed Docker Schema | ADR-055 | Migrate |
| 058 | Machine-Specific Logs | ADR-058 | Migrate |
| 061 | Provisioning Strategies | ADR-061 | Migrate |
| 062 | Statusline Config | ADR-062 | Migrate |
ADRs Already in coditect-core (Duplicates):
| cloud-infra # | coditect-core # | Action |
|---|---|---|
| 002 | ADR-002 | Keep coditect-core |
| 008 | ADR-008 | Keep coditect-core |
| 013 | ADR-013 | Keep coditect-core |
| 014 | ADR-014 | Keep coditect-core |
| 015 | ADR-015 | Keep coditect-core |
| 020 | ADR-020 | Keep coditect-core |
| 021 | ADR-021 | Keep coditect-core |
| 044 | ADR-044 | Keep coditect-core |
| 045 | ADR-045 | Keep coditect-core |
| 050 | ADR-050 | Keep coditect-core |
| 054 | ADR-054 | Keep coditect-core |
| 056 | ADR-056 | Keep coditect-core |
| 057 | ADR-057 | Keep coditect-core |
| 060 | ADR-060 | Keep coditect-core |
Backend ADRs (New Range 300+):
| backend # | Title | New coditect-core # |
|---|---|---|
| 001 | Floating vs Node-locked | ADR-300 |
| 002 | Redis Lua Scripts | ADR-301 |
| 003 | Check-on-Init Pattern | ADR-302 |
| ... | ... | ... |
Cross-Reference Format
In coditect-core:
See [ADR-053](pathname://internal/architecture/adrs/ADR-053-cloud-context-sync.md)
In other repositories:
See [ADR-053](https://github.com/coditect-ai/coditect-core/blob/main/internal/architecture/adrs/ADR-053-cloud-context-sync.md) in coditect-core
Deprecation Notice Template
For ADRs in cloud-infra that are superseded:
---
status: superseded
superseded_by: ADR-053
---
# ⚠️ SUPERSEDED
This ADR has been moved to coditect-core as **ADR-053**.
**Authoritative location:**
[coditect-core/internal/architecture/adrs/ADR-053-cloud-context-sync.md](...)
Do not modify this file. All updates should be made to the coditect-core version.
Consequences
Positive
- Single source of truth - No more confusion about authoritative version
- Consistent numbering - One number, one ADR
- Easier discovery - All ADRs in one place
- Simpler cross-references - Just use the number
- Reduced maintenance - Update in one place
Negative
- Migration effort - Time to consolidate
- Broken links - Temporary during migration
- Historical context - May lose some git history
Mitigations
- Phased migration - Don't do all at once
- Redirect markers - Leave superseded notices
- Git history - Reference original commits
Implementation
Immediate Actions ✅
- ADR-009: Multi-Tenant Architecture (created)
- ADR-012: Data Isolation Strategy (created)
- ADR-053: Cloud Context Sync (created)
- ADR-150: This governance ADR
Next Sprint
- Audit cloud-infra docs-site ADRs
- Identify 20 highest-priority unique ADRs
- Migrate with new numbers
- Add superseded notices
Ongoing
- All new ADRs created in coditect-core only
- Quarterly audit for drift
- Automated broken link detection
Related
- ADR-054: Track Nomenclature (similar governance pattern)
- ADR-116: Track-Based Architecture (SSOT for plans)
Track: F (Documentation) Task: F.12.2.6