Architecture Decision Records¶
Status field convention¶
A documentation-lifecycle review (2026-07) found that a single "Status" word
per ADR routinely conflated three independent facts — whether the decision
was accepted, whether it's implemented, and whether that implementation
claim has been verified against the current code — which is exactly how
several ADRs went stale silently (e.g. ADR-022 said "implemented" when only
one of its four backends had shipped). Introducing a separate structured
frontmatter schema (decision_status/implementation_status/
verification_status fields, as some ADR tooling does) was considered and
deferred: every ADR here uses a single plain-prose **Status:** line, and
retrofitting 40+ files with fabricated metadata (owners, PR numbers, "last
verified" dates for documents nobody actually re-audited line-by-line) would
trade one inaccuracy for another. Instead, the convention going forward
is to keep encoding the same three facts in that one line, explicitly:
**Status:** <decision: Proposed | Accepted | Superseded by ADR-NNN | Deprecated>
— <implementation: implemented | partially implemented (name what's missing)
| not implemented>. <optional amendment note: what's stale, what superseded
it, where the current behavior is documented instead>
The **Verified:** receipt (opt-in)¶
A 2026-08 status review found the residual half of the same problem, which no amount of status prose solves: ADR-049's Status said its shadow evaluator "is not called from any pipeline stage" and that nothing was wired into the CLI or reports, and five merged PRs later that was simply false. The status line was internally consistent, agreed with the index row, and was wrong — because the code moved and nobody re-read it. Comparing two documents cannot catch that; only re-reading the code can.
So a second, optional metadata line records when someone last did:
placed directly after the Status paragraph. It means "a maintainer checked this ADR's Status claims against the tree at that commit" — nothing more.
Name a commit on the default branch, not the branch you're writing the
receipt on. A branch commit stops existing once the PR squash-merges, and
because the ai-readiness job checks out full history, an unresolvable sha
is an error rather than a tolerated skip — so a receipt anchored to a PR
commit passes on that PR and then fails on main permanently. Since a PR
that adds a receipt normally doesn't change the code being attested, the
right sha is the main commit the branch is based on. adr-status-sync
enforces this. It
is opt-in precisely so it stays truthful: an ADR without one has simply never
been checked, which is the honest state of most of the files below and is not
an error. Adding one you didn't actually perform is worse than having none.
Name a module in full if you want it watched — abicheck/foo.py, not
_foo.py after a sibling. Family shorthand is deliberately not guessed at:
the gate would have to infer whether the family is replaced or appended, and
a wrong inference either watches an unrelated file or silently watches
nothing. A full path is exact, auditable from the Status line alone, and
keeps working after the file is renamed or deleted (which is when a claim is
most likely to have gone stale).
What it buys is a tripwire rather than a promise. adr-status-sync
(implemented in scripts/adr_status_sync.py, registered as a check by
scripts/check_ai_readiness.py) reads the first-party module paths the Status
paragraph names and warns when commits after the recorded sha have touched
any of them — i.e. when the code a claim describes has moved out from under
it. That's a WARN, not an ERROR: a changed module doesn't prove the claim went
stale, it proves nobody has re-read it since. Move the line forward when you
re-check, or correct the claim.
The same check ERRORs on a flat contradiction between an ADR's own Status and its row in the table below — one side claiming nothing is implemented while the other claims something is (which is exactly how ADR-056's row went stale). It deliberately does not require the two to paraphrase each other: the index cell is an abridgement of a paragraph that often runs a dozen lines, and an earlier prototype that compared them more strictly flagged 15 of 56 ADRs, nearly all false positives.
Good examples already in this table: ADR-022 ("partially implemented" +
naming exactly which backend shipped), ADR-037 (distinguishes "the contract
is implemented" from "enforcement is advisory until 1.0"), ADR-025 ("Proposed,
but substantially implemented/generalized elsewhere" + pointers to the ADRs
that absorbed it). When you touch an ADR and confirm a claim against current
code, update its **Status:** line rather than leaving the reader to infer
freshness from the file's git history. scripts/check_usecase_docs_sync.py
and the adr-index-nav-sync AI-readiness check keep the registry and nav
mechanically honest; the status line itself is still maintainer-verified
prose, not generated — treat a status claim you haven't personally checked
against the code as unverified, regardless of how confident it reads.
| # | Title | Status |
|---|---|---|
| 001 | Technology Stack — Python + pyelftools + castxml | Accepted — implemented, substantially amended |
| 002 | Multi-binary / release compare UX and architecture | Accepted — implemented |
| 003 | Data Source Architecture — checks, instruments, and binary types (+ exploratory binary fingerprint extension) | Accepted — implemented; conceptually extended by the L0–L5 model (ADR-028–031, 041) |
| 004 | Report Filtering, Deduplication, and Leaf-Change Mode | Accepted — implemented |
| 005 | Application Compatibility Checking | Accepted — implemented |
| 006 | Package-Level Comparison | Accepted — implemented |
| 007 | BTF and CTF Debug Format Support | Accepted — implemented |
| 008 | Full-Stack Dependency Validation | Accepted — implemented |
| 009 | Verdict System and Exit Code Contract | Accepted — implemented |
| 010 | Policy Profile System | Accepted — implemented |
| 011 | ABI Change Classification Taxonomy | Accepted — implemented |
| 012 | ABICC Drop-In Compatibility Layer | Accepted — implemented |
| 013 | Suppression System Design | Accepted — implemented |
| 014 | Output Format Strategy | Accepted — implemented |
| 015 | Snapshot Serialization and Schema Versioning | Accepted — implemented |
| 016 | Three-Tier Visibility Model | Accepted — implemented; extended by ADR-024's two-axis surface model |
| 017 | GitHub Action Design | Accepted — implemented |
| 018 | Cross-Platform Binary Format Support | Accepted — implemented |
| 019 | Testing Strategy and Parity Validation | Accepted — implemented |
| 020a | Build-Context Aware Header Extraction | Accepted — implemented |
| 020b | SYCL and Heterogeneous Computing Stack Support | Accepted — implemented |
| 021a | Debug Artifact Resolution Subsystem | Accepted — implemented |
| 021b | MCP Security Model | Deprecated — Retired: MCP interface removed |
| 022 | Baseline Registry and Snapshot Distribution | Accepted — not implemented; the filesystem backend and baseline command group that once shipped were deleted by ADR-043 D4, which also records recreating a registry as a non-goal |
| 023 | Bundle-Aware Multi-Binary ABI Analysis | Accepted — implemented |
| 024 | Public ABI Surface Resolution and False-Positive Traceability | Accepted — implemented |
| 025 | PR-Diff-Aware ABI Evaluation (Source Diff as Trigger and Localizer) | Proposed; D1–D3 absorbed by ADR-033/035, D4 still future work |
| 026 | Source-Only Changes and the Evidence-Tier Boundary | Accepted — substantially superseded by ADR-028/030/035/038 (its "no embedded Clang" conclusion was reversed) |
| 027 | API Surface Intelligence — Structure Metrics, Idiom Detection, Cross-Library Reasoning, Pattern-Aware Verdicts | Accepted — Phases 0-5 implemented; --pattern-verdicts default-on flip deferred pending release-cycle FP-rate/parity validation |
| 028 | Optional Source and Build Evidence Pack Architecture | Accepted — implemented |
| 029 | Build Graph and Toolchain Context Capture | Accepted — implemented |
| 030 | Source ABI Replay and Linked Source Surface | Accepted — implemented |
| 031 | Source and Implementation Graph Augmentation | Accepted — implemented |
| 032 | Evidence Extractor Plugin Interface and Security Model | Accepted — implemented |
| 033 | CI Rollout, Performance, Caching, and Validation Strategy | Accepted — implemented |
| 034 | Managed-Runtime and Non-C ABI Frontends | Proposed |
| 035 | PR-Tier Source Intelligence and Cross-Source Validation | Accepted — implemented (G19, D1–D10) |
| 036 | Report view-model and canonical report severity | Accepted — core implemented (Increments 1-2); Increment 3 (routing html_report.py/pr_comment.py through ReportModel) remains optional cleanup |
| 037 | CLI Interface Contract, Configuration Balance, and Extension Policy | Accepted — implemented (G22) |
| 038 | Working With Sources — Full-Scan and Two Build-Injection Flows | Accepted — implemented |
| 039 | Build-Context Reconciliation of Context-Free Header-Parse Artifacts | Accepted — implemented |
| 040 | compare Surface Reduction — Side-Aware Flags, Config Demotion, Run Profiles |
Accepted — phased implementation substantially complete (Phase A + Phase B landed, Phase C Lever-1 landed except the ast-frontend carve-out, Phase D landed as a constraint-aware subset) |
| 041 | Compiler-Facts Semantic Impact Graph — Roadmap and P0 Slice | Accepted — P0 slices 1-4, the header-only-graph addendum, and P1 items 1-5 implemented; remainder is roadmap, not a shipping commitment |
| 042 | Formal separation of CompatibilityDecision and GateDecision | Accepted — implemented for JSON/SARIF/compare-release gate summaries and html_report.py's CI Gate card; mcp_server.py/junit_report.py still compute an exit code inline in places |
| 043 | Pre-1.0 CLI Surface Reset — Root Command Collapse, Depth Ladder Narrowing, and Dry-Run Unification | Accepted — implemented |
| 044 | Reachability-Aware Suppression and the Effective Public ABI | Accepted — P0, P1, and P2 all implemented (see ADR for exact scope) |
| 045 | Identity-Based Old/New Entity Matching | Accepted — implemented for RecordType and EnumType |
| 046 | Source Graph Identity v2 — USR-Based Entity Resolution and Evidence-Preserving Merge | Accepted — D1-D6 all implemented, each to the documented scope (D4 is a deliberately scoped subset of the originally sketched full rewrite; see ADR for exactly what's covered per decision) |
| 047 | GitHub Actions Integration Model — Project Lifecycle Over Aggregate-Centric Design | Accepted — substantially implemented (P0 and the main P1 lifecycle implemented; P2 partially implemented, see ADR); see G30 |
| 048 | Canonical Entity Identity and Graph Reconciliation (G31 Phase B) | Accepted — implemented |
| 049 | Contract Relevance and Compatibility Configuration | Accepted (2026-07-26) — Phases 0-6 implemented (vocabulary, typed config/resolver/packs, finding identity, shadow evaluator in all three contract domains, persisted evidence context + replay, one resolved config per front end, --contract domain selection); Phase 7 partially (coverage exit landed; authoritative decision, default flip, and aggregate folding still open) |
| 050 | Comparability Contract — Profile/Scope Fingerprints and the Multi-TU Manifest | Accepted — implemented (Phase 0 and Phases A-E; D1-D6); see G32 |
| 051 | Documentation Operational Model (Ownership Registry + Docs-Contract Gate) | Accepted — Stages 1-4 implemented; Stage 5 explicitly deferred |
| 052 | Unified Impact Assessment Model (G29 Phase 3, slices 1-9) | Accepted — slices 1-9 implemented |
| 053 | TU → Link-Unit → DSO Source-Evidence Attribution | Accepted — implemented (core algorithm + validator; CLI/Action pipeline wiring deferred, see D5) |
| 054 | CLI Project-Integration Surface Consolidation | Accepted — implemented |
| 055 | Typed Request/Result Completeness and a Schema-Version Registry | Accepted — implemented (D1-D4), including D1's structural half: the CLI and typed API share one input resolution. D4 (MCP dedup) and other MCP-specific claims are historical — the MCP server was later removed |
| 056 | Multi-Artifact / Library-Set scan |
Proposed — partially implemented (Phases 1-4's engine/detector/CLI/Action slice shipped ahead of formal sign-off; MCP half, example catalog, and --dry-run estimator deferred); see G35 |
| 057 | Consumer Graph and the Consumer/Source Impact Join (G29 Phase 4, slice 1) | Accepted — slice 1 implemented (consumer graph, the join, ADR-046 D6's tier-1 selector, the --used-by overlay wiring); the use-case manifest and runtime-trace halves of Phase 4 are not implemented; see G29 |
| 058 | Native Compatibility Agent Skills — User-Task-First Domain Layer | Accepted — not implemented; see G36 |