Architecture Decision Records¶
This project uses Architecture Decision Records (ADRs) to document significant technical decisions.
All ADRs¶
Every ADR in the repository, newest last. Status distinguishes live decisions from superseded ones — a superseded ADR is kept rather than deleted so the reasoning behind a reversal stays readable.
Four numbers appear twice (ADR-042, 051, 052, 053): those decisions have a companion Implementation Spec alongside the ADR itself — the ADR holds the decision, the spec holds the delivery detail.
| ADR | Title | Status |
|---|---|---|
| ADR-001 | AI-Integrated Incident Response System | Draft |
| ADR-007 | Council Scoring Methodology | Proposed |
| ADR-008 | Package Structure - Library with Optional MCP | Accepted |
| ADR-009 | HTTP API and Open Core Boundary | Accepted |
| ADR-010 | Consensus Mechanism - Normalized Score Averaging | Proposed |
| ADR-011 | Cost and Token Accounting | Implemented |
| ADR-012 | MCP Server Reliability and Long-Running Operation Handling | Implemented |
| ADR-013 | Secure API Key Handling | Implemented |
| ADR-014 | Verbosity Penalty in Evaluation Prompts | Superseded |
| ADR-015 | Bias Auditing and Length Correlation Tracking | Implemented |
| ADR-016 | Structured Rubric Scoring | Implemented |
| ADR-017 | Response Order Randomization | Implemented |
| ADR-018 | Cross-Session Bias Aggregation | Accepted |
| ADR-019 | AI-Powered Outlook Email Analysis for ITIL Operations Insights | Proposed |
| ADR-020 | Not Diamond Integration Strategy for LLM Council Ecosystem | Implemented |
| ADR-021 | Quint Code and First Principles Framework (FPF) Integration | Proposed |
| ADR-022 | Tiered Model Selection for Confidence Levels | Implemented |
| ADR-023 | Multi-Router Gateway Support (OpenRouter, Requesty, Direct APIs) | Implemented |
| ADR-024 | Unified Routing Architecture | Proposed |
| ADR-025 | Future Integration Capabilities | Accepted |
| ADR-026 | Dynamic Model Intelligence and Benchmark-Driven Selection | Implemented |
| ADR-027 | Frontier Tier | Accepted |
| ADR-028 | Dynamic Candidate Discovery | Accepted |
| ADR-029 | Model Audition Mechanism | Accepted |
| ADR-030 | Scoring Refinements | Accepted |
| ADR-031 | Configuration Modernization & Cleanup | Accepted |
| ADR-032 | Complete Configuration Migration & config.py Deletion | Accepted |
| ADR-033 | Open Source Community Infrastructure | Draft |
| ADR-034 | Agent Skills Integration for Work Verification | Draft |
| ADR-035 | DevSecOps Implementation for Open Source | Accepted |
| ADR-036 | Output Quality Quantification Framework | — |
| ADR-037 | n8n Workflow Automation Integration | Draft |
| ADR-038 | One-Click Deployment Strategy | — |
| ADR-039 | One-Click Deployment Strategy | Superseded |
| ADR-040 | Verification Timeout Guardrails and Observability | Accepted |
| ADR-041 | Verification Telemetry Wiring | Accepted |
| ADR-042 | Implementation Spec — Verify Evidence Injection | Implementation Spec |
| ADR-042 | Verify Evidence Injection — Pre-computed Analysis as Council Context | Draft |
| ADR-043 | OpenRouter Pareto Router Integration | Superseded |
| ADR-044 | Compute-Optimal Deliberation | Implemented |
| ADR-045 | MCP 2026-07-28 Specification Adoption (Tasks, Server Card, Stateless Transport) | Implemented |
| ADR-046 | Streaming Deliberation | Implemented |
| ADR-047 | Verifier Calibration & Judge Reliability | Implemented |
| ADR-048 | Council Quality Benchmark & Golden-Dataset Regression | Implemented |
| ADR-049 | Prompt Caching Across Gateways | Implemented |
| ADR-050 | PostHog LLM Analytics Emission | Implemented |
| ADR-051 | Implementation Spec — Verify Findings Channel | Draft |
| ADR-051 | Verify Findings Channel & Verdict–Evidence Consistency | Implemented |
| ADR-052 | Implementation Spec — Structured-Findings Rollout & Enablement | Implementation Spec |
| ADR-052 | Structured-Findings Rollout & Enablement | Proposed |
| ADR-053 | Implementation Spec — Delivery Plan, Disclosure, and Child Breakdown | Proposed |
| ADR-053 | Verify File Selection — Decodability, Reviewability, and the Trust Boundary | Implemented |
| ADR-054 | What confidence Means in verify() — and How to Calibrate It |
Accepted |
| ADR-055 | Chairman Resilience — Dynamic Fallback for Stage-3 Synthesis | Proposed |
| ADR-056 | External Spend Telemetry — OTLP Spans for Council Cost | Proposed |
ADR Format¶
Each ADR follows the Michael Nygard format as defined in the template docs/adr/ADR-000-template.md:
- Title: Short descriptive title.
- Status: The lifecycle state of the decision.
- Context: The problem and forces at play.
- Decision: The agreed-upon solution.
- Consequences: The trade-offs and outcomes (positive/negative).
Status Lifecycle¶
The Status field tracks the lifecycle of a decision:
- Draft: Work in progress, not ready for review.
- Proposed: Ready for council review and discussion.
- Accepted: Approved and currently active. This is the implementation status.
- Rejected: Decision was considered but not taken.
- Deprecated: Decision was once active but is no longer valid (e.g., technology shift), without a direct replacement.
- Superseded: Decision has been explicitly replaced by a newer ADR. The header must link to the new ADR.
Creating New ADRs¶
- Copy the template from
docs/adr/ADR-000-template.md. - Number sequentially (e.g.,
ADR-040). - Open a Pull Request for discussion (Status:
Proposed). - Upon approval, merge and update Status to
Accepted.
Deprecating or Superseding¶
When a new decision replaces an old one:
1. Create the new ADR (Status: Accepted).
2. Update the old ADR's header:
- Change Status to Superseded.
- Add Superseded By: [Link to new ADR].
- (Optional) Add a note in the Context section explaining why it was replaced.
See the project GOVERNANCE.md for the detailed decision process.