Architecture Decision Records

August 22, 2026 · View on GitHub

Records of key design decisions for this project.

Index

ADRTitleStatusDate
0001Core/Adapter Separationaccepted2026-03-10
0002Paper-Faithful CCAI Implementationaccepted2026-03-12
0003Config Directory Designaccepted2026-03-12
0004Three-Layer Memory Architecture [AKC: Extract/Curate/Promote]accepted2026-03-17
0005SessionContext Refactoringaccepted2026-03-14
0006Docker Network Isolationsuperseded-by 00702026-03-14
0007Security Boundary Modelaccepted2026-03-12
0008Two-Stage Distill Pipeline [AKC: Extract]accepted2026-03-22
0009KnowledgeStore Importance Score [AKC: Extract/Quality Gate]accepted2026-03-24
0010Research Data Syncaccepted2026-03-25
0011Deprecating Direct Knowledge Injection in Favor of Skills [AKC: Curate]accepted2026-03-26
0012Human Approval Gate for Behavior-Modifying Commands [AKC: Curate/Promote]accepted2026-03-26
0013Shelving Coding Agent Skills (-ca Series) [AKC: Curate/Promote]accepted2026-03-28
0014Retiring system-spec.md [AKC: Maintain]accepted2026-04-01
0015One External Adapter Per Agentaccepted2026-04-08
0016Insight as Narrow Generator, Stocktake as Broad Consolidator [AKC: Extract/Curate]partially-superseded-by ADR-00972026-04-11
0017Yogācāra Eight-Consciousness Model as Architectural Frameaccepted2026-04-11
0018Per-Caller num_predict + Embedding-Only Stocktakeaccepted2026-04-15
0019Discrete Categories → Embedding + Views [AKC: Promote]accepted2026-04-15
0020Pivot Snapshots for Replayability [AKC: Curate]accepted2026-04-16
0021Pattern Schema Extension — Provenance / Bitemporal / Forgetting / Feedbackpartially-superseded-by 0028, 0029, 00512026-04-16
0022Memory Evolution + Hybrid Retrieval (BM25)withdrawn-by 00342026-04-16
0023Skill-as-Memory Loop — Router, Usage Log, Reflective Writesuperseded-by 00362026-04-16
0024Identity Block Separation — Frontmatter-Addressed Persona Blockssuperseded-by 00302026-04-16
0025Identity History Log Wiring + migrate-identity CLIsuperseded-by 00302026-04-16
0026Retire Discrete Categories (Phase-3 Completion of ADR-0019)partially-superseded-by 00602026-04-16
0027Noise as Seed — From Binary Gate to Salience-Based Forgettingsuperseded-by 00602026-04-16
0028Retire Pattern-Level Forgetting and Feedback — Memory Dynamics Belong to the Skill Layeraccepted — partially-supersedes 00212026-04-18
0029Retire Dormant Provenance Elements — user_input / external_post / sanitizedaccepted — partially-supersedes 00212026-04-18
0030Withdraw Identity Block Separation and History Wiring — Single Responsibilityaccepted — supersedes 0024 and 00252026-04-18
0031Classification as Query — Substrate Principle for Self-Improving Memoryaccepted2026-04-27
0032Stance — Contemplative Agent as a Runtime Agentwithdrawn — tension with contemplative axioms (ADR-0002)2026-04-27
0033Note — Borrowing AAP's Four-Quadrant Lens as a Usage-Description Aidaccepted (note)2026-05-01
0034Withdraw Memory Evolution and BM25 Hybrid Retrieval — Cost Without Benefitaccepted — supersedes 00222026-05-05
0035Sunset ADR-0019 Migration Surface and Consolidate Artifact Extractionaccepted2026-05-05
0036Sunset Skill-as-Memory Loop — Retire Router, Usage Log, and Reflectaccepted — supersedes 00232026-05-05
0037Memory Subsystem Converges to Yogācāra Frame; Paper-Borrowed Mechanisms Retiredaccepted2026-05-05
0038Re-introduce Moments of Recognition into the Distill Observation Target [AKC: Extract]accepted2026-05-13
0039Continuous Novelty Score with Rate-Deficit Lagrangian for Self-Post Gateaccepted2026-05-19
0040Separate Code-Level Findings from Weekly Self-Reflection Reportaccepted2026-05-19
0041Repair the Engagement Gradient Asymmetry in the Self-Post Promptaccepted2026-05-19
0042Explicit Truncation Contract for wrap_untrusted_contentaccepted2026-05-20
0043Per-Post Seeding for Self-Post Generationaccepted2026-05-21
0044Remove topic_keywords End-to-Endaccepted2026-05-23
0045Record Pre-Action internal_note at the Episode Layeraccepted2026-05-25
0046Stocktake Duplicate Detection — LLM Grouping over Embedding Clusteringpartially-superseded-by ADR-00972026-05-30
0047Higher Sampling Temperature for Outward Comment Generationaccepted2026-05-30
0048Trigger-Altitude for Skill Lifecyclepartially-superseded-by ADR-00972026-06-02
0049Meditation Adapter — Beautiful Loop Fidelity Audit and Deferral of Faithful Re-Implementationaccepted2026-06-03
0050Epistemic Taxonomy and Approval Lineage — Observability Without Steeringpartially-superseded-by 0051, 00822026-06-05
0051Retire Trust Weighting — Pure Cosine Retrieval and Bitemporal-Only Livenessaccepted — partially-supersedes 0021, 00502026-06-05
0052Retire Session Insight Generation — Identity Is the Approved Continuity Channelaccepted2026-06-05
0053Importance as Encoding-Time Significance — Three Judgment Points and Re-observation Promotionpartially-superseded-by 00562026-06-06
0054Externalize LLM Instruction Text to config/prompts/ with Hardcoded Fallback for the Injection Boundaryaccepted2026-06-09
0055Counterparty Identity by Author Name; Unified Activity/Report Schemaaccepted2026-06-15
0056Retire the Distill-Time Importance LLM Rating — Extraction Weight Is Pure Time Decayaccepted — partially-supersedes 00532026-06-17
0057Distill Identity From the Self-Reflection Corpus Alone — Drop the Prior-Identity Seed and Redundant Axiom Injection [AKC: Promote]accepted2026-06-20
0058Value-Layer Injection Belongs to Action Time, Not Distillation [AKC: Extract/Curate/Promote]accepted2026-06-20
0059Remove the Dead Reply-History Mechanismaccepted2026-06-22
0060Per-Episode Grounded Distill — Replace Batch Extract + Noise Gate with One Grounded LLM Call per Engagement Episodeaccepted — supersedes 0027; partially-supersedes 00262026-06-23
0061Action-Time Untrusted Input Caps at Platform Field Limits; Internal Note Reads the Full Bodyaccepted2026-06-23
0062Create-Time Content-Verification Handshake with Hybrid LLM/Code Solver; Gate Recording on Visibilityaccepted2026-06-26
0063Scope the NoveltyGate Comparison to Verified (Visible) Postsaccepted2026-06-26
0064Route Generation Through a Local mlx_lm.server on Apple Siliconsuperseded-by 00702026-06-27
0065Wire mlx_lm.server as an On-Demand launchd Job and Enforce a Served-Model-ID Contract on LLM Telemetrypartially-superseded-by 0067/00702026-06-27
0066Backend-Aware Context-Budget Guard via an LLMBackend.context_window Contractaccepted2026-06-27
0067Keep Ollama as the Production Generation Backend — mlx_lm.server Unfit for Unattended Continuous Use on 16 GB Apple Siliconaccepted — partially-supersedes 00652026-06-28
0068Per-Call think Flag and Reasoning-Trace Capture to the Episode Logaccepted2026-06-28
0069Adopt gemma4:e4b as the Production Generation Model and Run the Value-Layer Pipelines think-ONaccepted2026-06-28
0070Retire the MLX Backend to a Sibling Repo and Remove Docker from Mainaccepted — supersedes 0006, 0064; partially-supersedes 00652026-06-28
0071Read-Only Pattern-Composition Instruments (View Supply / Diversity / Grounding)accepted2026-07-03
0072Echo-Chamber Interventions — Register Instruction, Corpus-Grown Seed, Extraction-Failure Guardaccepted2026-07-03
0073Prune the Five Orphaned View Seedsaccepted2026-07-03
0074Weekly Staged Insight — Theme Detection, Pending Guard, Marker-on-Stage, LLM Novelty Gate, Exact Fast Clusteringaccepted2026-07-09
0075Observability by Default — Replayable Audit Logs Ship With the Featureaccepted2026-07-09
0076Skill-Selection Shadow Instrument — Pass-1 LLM Applicability Observed, Not Enforcedaccepted2026-07-10
0077Chaos-TDD Fault Injection — Seeded Fault Schedules as Test-First Specification (Pilot: distill)accepted2026-07-13
0078OTel Connection via Vocabulary Mapping and Offline Export — Not Runtime Adoptionaccepted2026-07-16
0079Module Reorganization — Package Splits, Permanent Facades, and Documented Size-Cap Exceptionsaccepted2026-07-18
0080North Star — Per-Layer End-State Definition, Not a Capability Targetaccepted2026-07-20
0081Skill-Selection Two-Pass Injection Enforcementaccepted2026-07-24
0082Retire the observed Epistemic Key — Delete the Dead Field, Not the Warning About Itaccepted — partially-supersedes 00502026-07-25
0083Episode Logs Enter the Weekly Prompt as Hashes Onlyaccepted2026-07-25
0084Post-Distill Durability Gate — Judge the Produced Patterns, Not the Episodeaccepted2026-07-26
0085Unattended Weekly Fix Chain with a Single Saturday Gateaccepted2026-07-29
0086Submolt Scope — Instrument the Question Before Handing Over the Answeraccepted2026-08-01
0087An Optional count_tokens Capability for the Context-Budget Guardaccepted — extends 00662026-08-01
0088A Shipped Conformance Kit for the LLMBackend Contractaccepted2026-08-02
0089An LLM Behavioral Eval Layer on DeepEvalaccepted2026-08-06
0090Run an IPD Two-Arm Bench Before Adopting a Constitution Amendmentaccepted2026-08-09
0091Value-Layer Cadence in the Weekly Chainaccepted2026-08-10
0092Shadow Constitution Instrument — Patterns-Only Synthesis, Observe-Onlyaccepted2026-08-11
0093Repo-Plane Deterministic Intakes — Docs Consistency and Ledger Condition Watchpartially-superseded-by 00952026-08-14
0094Agent-First Task Ledger — Store / Journal / Projectionsuperseded-by 00952026-08-15
0095Retire the Task-Ledger Machinery — Keep the Store and the Claims, Drop Everything That Parsedaccepted — supersedes 0094; partially-supersedes 00932026-08-16
0096Promotion-Worth Abstain at Insight Time — Judge the Produced Skill, List the Surprisepartially-superseded-by ADR-00972026-08-17
0097Consolidator Dissolution and a Skill-Store Exit — Subtraction, then Exit, then Vocabularyaccepted — partially-supersedes ADR-0016, ADR-0046, ADR-0048, ADR-00962026-08-22

ADR Types

ADRs in this project fall into two categories with different editability rules:

Problem-solving ADRs (emergent) Record reactive design decisions triggered by a concrete issue. Most ADRs in this index are of this type. They can be superseded by later ADRs that offer a better solution for the same problem.

Examples: ADR-0005 (SessionContext refactoring), ADR-0008 (two-stage distill pipeline), ADR-0009 (importance score), ADR-0016 (insight narrow / stocktake broad).

Worldview ADRs (axiomatic) Record the mental models and philosophical frames that the project operates under from the start. These are not reactive — they are the prerequisite under which problem-solving ADRs are even formulated. Changing a worldview ADR is not the same as fixing a bug; it is altering the project's identity and requires a different kind of judgment.

Examples: ADR-0002 (paper-faithful CCAI), ADR-0007 (security boundary model), ADR-0017 (Yogācāra eight-consciousness frame).

Rule of thumb: If the ADR could have been written differently under a different project with the same problem, it is problem-solving. If the ADR describes a frame under which the project's problems become legible at all, it is worldview. Worldview ADRs are downstream-of-nothing; problem-solving ADRs are downstream of a worldview (even if unnamed).

Template

When adding a new ADR, follow this format:

# ADR-NNNN: Title

## Status
accepted / proposed / withdrawn / superseded-by ADR-NNNN

## Date
YYYY-MM-DD

## Context
What was the problem

## Decision
What was decided

## Alternatives Considered
Rejected options and why

## Consequences
What resulted from this decision

## References
- `ADR-NNNN` (`NNNN-slug.md`) — short note on the relationship (supersedes / refines / depends-on / precedent)
- External sources (papers, prior art, evidence)

Status line conventions

The Status field follows established phrasing so that the index, ADR bodies, and graph.jsonld stay in sync. Use one of:

  • accepted — currently in effect
  • accepted — supersedes ADR-NNNN — replaces an earlier ADR (the index also lists the replaced ADR with superseded-by ADR-NNNN)
  • accepted — partially-supersedes ADR-NNNN[, ADR-NNNN] — replaces only specific sections of an earlier ADR (the index also lists the older ADR with partially-superseded-by ADR-NNNN; name the scope in the ADR body)
  • accepted (note) — observational / narrow ADR that does not commit the project to a long-lived rule
  • accepted (amended YYYY-MM-DD) — body amended; see the Amendment section in the ADR
  • partially-superseded-by ADR-NNNN[, ADR-NNNN] — only specific sections were replaced; surviving sections remain in effect
  • superseded-by ADR-NNNN — fully replaced; preserve the original body
  • withdrawn by ADR-NNNN — retracted because a later ADR judged this approach incorrect
  • withdrawn (YYYY-MM-DD) — retracted in-place, typically same-day or by the same author; the body preserves the withdrawal reason

The relationship phrases (supersedes, superseded-by, withdrawn by, partially-supersedes, partially-superseded-by) are mirrored as typed edges (supersedes, supersededBy, withdrawnBy, partiallySupersedes, partiallySupersededBy) in graph.jsonld so LLMs can traverse the supersede / withdrawal chain without parsing prose. A node's edges must match its own Status prose — a bare accepted node carries no supersede-family edge — and tests/test_adr_status_consistency.py enforces that alongside head agreement across all five faces. The mirror is per-node, with one cross-node rule: partial supersessions must carry both halves, because the two are one claim stated from each end rather than a vocabulary choice. Six of them recorded only the backward half until 2026-08-15 (T-ADR-PARTIAL-RECIPROCITY); test_partial_supersede_edges_are_reciprocal now fails on a half added without its counterpart. Whether a withdrawal should also read as a supersession stays a judgment call and is not asserted.

Which half states which scope. A partial supersession has two scopes — what was retired, and what still stands — and they belong on different faces. The forward half (on the newer ADR) names only what it retired. The surviving scope lives on the backward half (on the superseded ADR), because that is the only face that can stay correct as later partial supersessions land: ADR-0021's residue today is what survived ADR-0028, ADR-0029 and ADR-0051, so replicating it onto any one of them would have each claim a state that was not true on its own date. No test can check this — it is a semantic agreement between two prose faces — so it is a convention, written here because the 2026-08-15 review caught all four new forward halves stating it wrongly before the convention existed. Prose inside a body describing a scoped supersession uses supersedes X in part, the form the Status parser also accepts; a bare superseded on a scoped subject reads as a full retirement.

Guidelines

  • Numbers are sequential (0001–), in chronological order
  • Changes to existing ADRs are made via a new ADR that supersedes the original (never overwrite)
  • When an ADR supersedes or withdraws another, update the older ADR's Status to point at the new one (one-line edit; do not rewrite the body)
  • Only record decisions affecting architecture, data models, or security — minor decisions need not be recorded
  • When adding a new ADR, also add a node (and any supersede / withdrawal edges) to graph.jsonld so the LLM-facing knowledge graph stays current
  • Use /sync-context to check consistency between the ADR index and files