Skip to content

Architecture Decisions

This section records the significant architectural decisions made for Assurance Forge as Architecture Decision Records (ADRs).

An ADR captures a single decision: the context that forced it, the choice that was made, and the consequences accepted as a result. It documents why the codebase looks the way it does — the reasoning that the source code and the current-state architecture docs cannot express on their own.

We use the lightweight Michael Nygard format: Title, Status, Context, Decision, Consequences.

Lifecycle

An ADR moves through these statuses:

Status Meaning
Proposed Under discussion; not yet agreed.
Accepted Agreed and in effect.
Superseded Replaced by a later ADR. Note it as Superseded by ADR-NNNN.
Deprecated No longer relevant, but kept for the historical record.

ADRs are append-only. Once an ADR is Accepted, do not rewrite it. To change a decision, write a new ADR that supersedes it and update the old ADR's status to point at the replacement. This keeps the decision history intact.

Adding an ADR

  1. Copy adr-template.md.
  2. Name it with the next number and a kebab-case title, e.g. 0006-use-x-for-y.md.
  3. Fill in Context, Decision, and Consequences. Set the status (usually Proposed while in review, Accepted once merged).
  4. Add it to the table below and to the Architecture → Decisions (ADRs) nav in mkdocs.yml.

Records

ADR Title Status
0001 Record architecture decisions Accepted
0002 Layered architecture with build-time gates Accepted
0003 SACM XML as the source of truth Accepted
0004 MkDocs Material documentation site Accepted
0005 Provider-agnostic AI with explicit user consent Accepted (clarified in part by 0013)
0006 SACM 2.3 as an independent reusable library Accepted
0007 Explicit consent for sharing assurance cases over MCP Accepted (superseded in part by 0009, 0014)
0008 One owner for the open project Accepted (superseded in part by 0009, 0010, 0014)
0009 One integrated working draft per argument file Accepted (superseded in part by 0016)
0010 Draft provenance, persistence, and human-controlled promotion Accepted (superseded in part by 0016)
0011 Panels own their view types Accepted
0012 A claim carries one Description Accepted
0013 Review methods are independent of inference providers Accepted
0014 Projectless MCP discovery with explicit runtime case binding Accepted
0015 Versioned AI provider profiles and fail-closed selection Accepted
0016 The working draft is a SACM document, not a list of operations Accepted