Skip to content

Architecture Decision Records (ADRs) — Production Design

Each file in this directory captures one architectural decision: the context that motivated it, the alternatives considered, what we decided, what tradeoffs we accepted, what becomes harder later, and how reversible the choice is.

The format is lightweight Nygard-style (per Michael Nygard's original 2011 essay) with extensions for tradeoffs and reversibility. Every ADR has:

Section What it captures
Status Proposed · Accepted · Provisional Accepted · Deferred · Superseded
Context The situation, forces, and constraints that triggered the decision
Options considered The alternatives evaluated, briefly
Decision What we chose, stated unambiguously
Tradeoffs What we gain and what we give up — both columns
Consequences What becomes easier, what becomes harder, what's now constrained downstream
Reversibility How costly it is to undo this decision later, and what would need to change
Evidence / sources The references this decision is grounded in

Conventions

  • Filenames are NNNN-kebab-case-title.md with zero-padded four-digit numbers. Numbers are assigned at write-time and never reused, even if an ADR is superseded.
  • Numbers are sequential and immutable. A superseded ADR keeps its number; the new ADR gets the next number and links back.
  • Status transitions are append-only. When you supersede an ADR, edit both the old and new ADRs to cross-link, but don't delete history.
  • Provisional Accepted is for accepted direction with named future evidence still outstanding. Every provisional ADR MUST include a **Review trigger:** line naming the evidence, phase, or date that will either promote it to Accepted, keep it provisional with new evidence, or retire it.
  • Supersession is reciprocal. The old ADR says **Status:** Superseded by ADR-NNNN; the successor says **Supersedes:** ADR-MMMM. One-way links are incomplete history, not valid lifecycle metadata.
  • Each ADR is self-contained. A reader should be able to understand the decision from the ADR alone, without reading the main design.md.

Index — Accepted decisions

# Title Tags
0001 Layered Hybrid orchestration — three layers, not one framework orchestration · architecture
0002 LangGraph as runtime, SHERPA as discipline — composition over alternatives orchestration · runtime
0003 Temporal as the durable workflow substrate platform · durability
0004 Python as the harness language across POC and service language · ecosystem
0005 No LLM in the gather pipeline — determinism end-to-end gather · determinism
0006 Continuous deterministic gather — event-triggered, always-fresh gather · runtime
0007 Probe contract preserved unchanged from POC to service contract · stability
0008 Trust score uses objective signals only — no LLM self-confidence trust · safety
0009 Humans always merge — no autonomous merge to production safety · governance
0010 Seven-stage pipeline shape (Discovery → Learning) pipeline · structure
0011 Recipe-first → RAG → LLM-fallback planning order planning · cost
0012 microVM sandbox isolation for trust gates trust · sandbox
0013 Pre-rendered Redis hot views for agent context latency · ergonomics
0014 Three-retry default per gate transition policy · escalation
0024 Cost is observable end-to-end as a first-class commitment cost · observability
0025 Per-workflow cost cap as a hard guard cost · safety
0026 ROI KPI model — what we measure and how roi · metrics
0027 Cost attribution model — mapping costs to workflows, repos, and task classes cost · attribution
0028 Task class introduction order — vulnerability remediation before migration task-class · sequencing
0029 Task-Class Context Manifests — context selection as data context · task-class · skills
0030 Graph-aware context queries — dep graph + tree-sitter + SCIP power TCCMs context · graph-analysis · scip
0031 Plugin architecture — granular (task × language × build-tool) units of work architecture · plugins · extension-by-addition
0032 Language search adapters — bridging generic queries to language-specific indexers adapters · code-search · scip · plugins
0033 Domain modeling discipline — newtype + smart constructor + sum type + illegal-states-unrepresentable typing · correctness · discipline
0034 Event sourcing as canonical primitive for agent runs event-sourcing · audit · replay · observability
0035 Operator portal — read-only-first, event-log-projected, GitHub-OAuth, with visibility/authority separated ui · observability · audit · ops · phase-13.5
0036 Plugin/task enablement — dual-source policy (operator Postgres + repo codegenie.yaml), OR resolution, fail-closed, stage-aware policy · kill-switch · config-as-code · audit · phase-13.5
0037 Layered analysis funnel — SCIP for gather, type-checkers for verification, LSP reserved for interactive loops gather · verification · scip · type-checker · lsp · cost · phase-boundaries
0038 Vulnerability provenance attribution — vuln.provenance as a query-time join over gather-time SBOMs vuln · provenance · sbom · routing · query-primitive · adapter · gather · assessment · phase-7 · phase-10
0039 Extension by addition allows bounded additive core primitives architecture · extension-by-addition · contracts · phase-7
0040 Data lifecycle, retention, and classification data · governance · retention
0041 Model and prompt release qualification llm · release · reproducibility · capability · content-addressed-digest
0042 Multi-plugin coordination for Both workflows orchestration · coordination · planning

Index — Deferred decisions

These are committed to the architecture as questions; the decision itself awaits evidence. Each ADR documents the default behavior until the decision is made and what evidence would resolve it.

# Title Tags
0015 Trust-score threshold calibration trust · calibration
0016 Checkpointer backend (Postgres vs Redis) platform · storage
0017 Knowledge-graph backend (Qdrant / pgvector / Neo4j) platform · storage
0018 Hierarchical Planner: pure routing vs LLM-driven orchestration · cost
0019 Sandbox stack (Firecracker / gVisor / nested QEMU) platform · sandbox
0020 Leaf Agents SDK choice (Anthropic / OpenAI / both) llm · vendor
0021 Policy engine: build vs adopt RuleZ platform · safety
0022 Per-subgraph topology — when to extract shared structure orchestration · refactor
0023 MCP server topology (single global vs per-stage) platform · authorization

How to add a new ADR

  1. Pick the next sequential number (look at the highest existing).
  2. Choose a short kebab-case title that names the decision (not the conclusion).
  3. Create NNNN-title.md using the template below.
  4. Add an entry to the index above (Accepted or Deferred).
  5. Reference the ADR from the relevant section of ../design.md.
  6. If this ADR supersedes a previous one, edit both to cross-link and mark the old one Superseded by ADR-NNNN.

Template

# ADR-NNNN: <Decision title>

**Status:** Proposed | Accepted | Provisional Accepted | Deferred | Superseded by ADR-XXXX
**Date:** YYYY-MM-DD
**Tags:** tag · tag · tag
**Related:** ADR-NNNN, ADR-NNNN
**Review trigger:** Required only when status is `Provisional Accepted`
**Supersedes:** Required only when this ADR replaces an older ADR

## Context

What situation triggered this decision? What are the forces in play? Cite specific sections of design.md or other docs where this decision surfaces.

## Options considered

- **Option A** — one-paragraph summary
- **Option B** — one-paragraph summary
- **Option C** — one-paragraph summary

## Decision

What we chose, stated unambiguously in one or two sentences.

## Tradeoffs

| Gain | Cost |
|---|---|
| ... | ... |

## Consequences

- What becomes easier downstream.
- What becomes harder or constrained.
- What new invariants must be preserved.

## Reversibility

How costly is undoing this decision later? What would need to change in the rest of the system? Low / Medium / High with justification.

## Evidence / sources

- Citations to design.md sections, other ADRs, research docs, published papers, or external references.