Architecture Decision Records

ADRs capture decisions worth understanding later: the context, the options considered, and the rationale for the choice. They are numbered, append-only, and never silently rewritten. When reality moves past an ADR, record the change in the ADR rather than letting a stale claim mislead — two paths depending on the size of the change:

• Full reversal (the decision no longer holds) → supersede the old ADR with a new one and set the old status to Superseded.
• Refinement (a claim turned out too blunt, a constraint relaxed, a detail corrected) → add a dated Amendment note at the top of the affected section stating the current understanding, and keep the original decision text in place below it (relegated, not deleted), so the audit trail stays intact. Mark the status Accepted (amended <date>) and note it in the index. ADR 0006 and ADR 0014 are worked examples.

Status legend

• Accepted / Approved — current, in effect.
• Accepted (partial) — design ratified and partly built; the ADR carries an ## Implementation status section (see below).
• Proposed — drafted, not yet ratified.
• Superseded — historical, replaced by a later ADR or by a spike outcome; kept for the audit trail.

Keeping status honest

An ADR's Status is a claim about the codebase, not an aspiration. Before setting or changing it, verify the claim against the implementation — read the code; don't trust the previous status or a feature's "done" framing. The same goes for any present-tense statement inside an ADR ("jitter feeds the setup/hold checker"): it's a verifiable claim, so check it.

• Don't bump Proposed → Accepted just because a design merged. Confirm the decision is actually in effect in the code.
• When a design is ratified but only partly built, use Accepted (partial) and add an ## Implementation status section splitting implemented (with file references) from deferred (with the specific gap). ADR 0012 is the worked example.
• Deferred work gets a home: a plan under docs/plans/ and a tracking issue, cross-linked from the ADR's status section, so the unbuilt half isn't lost.

This extends to user-facing docs and --help text: a sentence telling the reader how the tool behaves is a verifiable claim — check it against the code before writing it.

Index

How the ADRs relate

• 0014 / 0015 document the core simulation pipeline: 0014 explains why the AIG (and-inverter graph) is the simulation IR — its uniform AND-gate structure enables the boomerang reduction tree and eliminates per-cell dispatch in the GPU kernel. 0015 describes the boomerang execution model itself — the 13-level hierarchical reduction tree, the GPU resource limits it imposes (8191 inputs, 8191 outputs, 4095 intermediates, 64 SRAM groups per partition), the hypergraph partitioning that distributes work across GPU blocks, and the packed instruction format (FlattenedScriptV1) consumed by the kernel. Together they document the path from gate-level Verilog to GPU kernel execution that the GEM paper describes.

• 0001 / 0003 / 0005 / 0006 describe the timing oracle stack: OpenSTA as the ground truth (0001), vendored at a pinned revision with its own corpus reused (0005), driving SDF preprocessing out-of-process (0006). The earlier OpenTimer in-process plan (0003) was retired after the spike (../spikes/opentimer-sky130.md).

• 0002 is the data contract those tools talk over — a JSON timing IR consumed by Jacquard, produced by opensta-to-ir.

• 0004 governs how PDK-specific testing happens for NDA-bound contributors without leaking files into the public repo.

• 0007 / 0008 are the forward-looking pair: 0008 (Approved) defines the structured timing output Jacquard owes downstream flows; 0007 (Proposed) sketches the model-fidelity work needed to back those outputs at scale (δ(T), clock-tree skew, wire delay). Scheduling for both lives in ../plans/post-phase-0-roadmap.md.

• 0013 / 0017 cover the cosim runtime: 0013 documents the peripheral model architecture (CPU-side PeripheralModel trait, GPU-side kernel patterns, ring buffers, plural-config convention); 0017 documents the execution model (batch dispatch loop, multi-clock scheduler, edges-vs-cycles semantics).

• 0016 accepts the selective X-propagation design documented in docs/selective-x-propagation.md. The full seven-phase design lives there; the ADR is a thin acceptance record with a summary of key choices.

Adding a new ADR

1. Pick the next number (highest existing + 1).
2. Filename: NNNN-short-kebab-title.md.
3. Start with # ADR NNNN — <title> and a **Status:** line — set it to match the code, not the intent (see Keeping status honest).
4. Standard sections: Context, Decision, Consequences. Add Amendment blocks dated when the decision is revisited; do not rewrite accepted history.
5. Add the row to the table above.