docs: architecture-docs migration Part 2 — ADR → Architecture/Decisions

.github/actionlint.yaml

@@ -22,7 +22,7 @@ self-hosted-runner:
     # it is the report that is spoofed, not the label.
     #
     # So the runner is an APU rather than a discrete card, which makes it a
-    # closer proxy for an AMD laptop. See docs/spikes/amd-laptop-backend.md.
+    # closer proxy for an AMD laptop. See docs/architecture/decisions/spikes/amd-laptop-backend.md.
     - amd
     - rocm
     - gfx1036

.github/workflows/ci.yml

@@ -155,7 +155,11 @@ jobs:
           curl -sSL https://github.com/terrastruct/d2/releases/download/v0.7.1/d2-v0.7.1-linux-amd64.tar.gz \
             | tar -xz -C /tmp
           install /tmp/d2-v0.7.1/bin/d2 ~/.cargo/bin/d2
-          cargo install mdbook-d2 --version 0.3.8 --locked
+          # mdbook-d2 may already sit in the restored ~/.cargo/bin cache; a plain
+          # `cargo install` then fails "binary already exists". Reinstall only when
+          # it's missing or the wrong version, so a warm cache stays a fast no-op.
+          mdbook-d2 --version 2>/dev/null | grep -q '0\.3\.8' \
+            || cargo install mdbook-d2 --version 0.3.8 --locked --force
 
       - name: Build mdbook
         run: mdbook build

.github/workflows/publish-netlist-graph.yml

@@ -1,6 +1,6 @@
 name: Publish netlist-graph
 
-# Publishes the `netlist-graph` Python companion tool to PyPI (ADR 0018).
+# Publishes the `netlist-graph` Python companion tool to PyPI (Decision 0018).
 #
 # - Tagging `netlist-graph-v<X.Y.Z>` builds and publishes to PyPI via
 #   trusted publishing (OIDC — no stored token).

.github/workflows/release.yml

@@ -1,7 +1,7 @@
 name: Release
 
 # Builds prebuilt binaries and attaches them to a GitHub Release.
-# See ADR 0018 and docs/plans/distribution.md.
+# See Decision 0018 and docs/plans/distribution.md.
 #
 # - Tagging `v<X.Y.Z>` builds, smoke-tests, and publishes the release with the
 #   macOS/Metal binary attached (or attaches it to an existing release of that
@@ -86,7 +86,7 @@ jobs:
           # binstall requires every non-optional package bin to be in the
           # archive, so it must ship alongside jacquard (it builds without the
           # metal feature, but one invocation keeps the build cache shared).
-          # `synth` (ADR 0021): embeds YoWASP Yosys so the shipped binary accepts
+          # `synth` (Decision 0021): embeds YoWASP Yosys so the shipped binary accepts
           # behavioral RTL directly (`jacquard sim design.v`). The ~39 MB yosys.wasm
           # is not bundled yet — auto-fetch is Phase 4; until then the on-ramp needs
           # `--yosys-wasm` / an installed `yowasp-yosys`. A pre-synthesized netlist

.github/workflows/user-acceptance.yml

@@ -8,7 +8,7 @@ name: User Acceptance (Metal)
 # The same script gates the release in release.yml. This standalone workflow is
 # for validating the user-install experience on demand (e.g. after touching the
 # Metal kernel, packaging, or the install docs) without cutting a release.
-# ADR 0018 / docs/plans/distribution.md.
+# Decision 0018 / docs/plans/distribution.md.
 
 on:
   workflow_dispatch:
@@ -42,7 +42,7 @@ jobs:
 
       - name: Build jacquard (Metal) + opensta-to-ir
         run: |
-          # synth (ADR 0021): shipped binary accepts behavioral RTL (yosys.wasm
+          # synth (Decision 0021): shipped binary accepts behavioral RTL (yosys.wasm
           # auto-fetch is Phase 4; on-ramp needs --yosys-wasm until then).
           cargo build --release --features metal,synth --bin jacquard
           cargo build --release --manifest-path crates/opensta-to-ir/Cargo.toml --bin opensta-to-ir

.github/workflows/validate-install.yml

@@ -2,7 +2,7 @@ name: Validate install (staging)
 
 # Runs the *documented* end-user install commands against an already-published
 # release (or release candidate) and is the promotion gate for the staging
-# flow (ADR 0018, docs/release-process.md § Staging validation).
+# flow (Decision 0018, docs/release-process.md § Staging validation).
 #
 # Cut an RC: `bump_version.py X.Y.Z-rc.N`, commit, tag `vX.Y.Z-rc.N` —
 # release.yml publishes a GitHub *prerelease* with the Metal tarball. Then

CHANGELOG.md

@@ -435,7 +435,7 @@ runners land (ADR 0018).
   any sequential design ran two-state. Undriven primary inputs read X in
   cosim; SRAM writes and preloads clear the per-cell X-mask shadow.
   End-to-end CI guards live in `tests/xprop_cosim/`. See ADR 0016 and
-  `docs/plans/cosim-xprop.md`.
+  `docs/plans/archive/cosim-xprop.md`.
 
 ### Changed
 

CLAUDE.md

@@ -68,7 +68,7 @@ NetlistDB (Verilog) → AIG → StagedAIG → Partitions → FlattenedScript →
 - **`repcut.rs`**: Hypergraph partitioning using mt-kahypar for mapping to GPU blocks
 - **`pe.rs`**: Partition executor - builds BoomerangStage structures (hierarchical 8192→1 reduction) that map to GPU block resources
 - **`flatten.rs`**: Generates FlattenedScriptV1 - the final GPU execution script with packed instructions
-- **`synth.rs`**: Embedded Yosys synthesis engine (ADR 0021) — behavioral RTL on-ramp, behind the `synth` feature
+- **`synth.rs`**: Embedded Yosys synthesis engine (Decision 0021) — behavioral RTL on-ramp, behind the `synth` feature
 
 ### GPU Kernels (`csrc/`)
 
@@ -130,7 +130,7 @@ cargo run -r --features metal --bin jacquard -- sim ... --max-clock-edges 1000
 `sim` on AMD needs no special flags, but note it runs differently there: on a
 device without cooperative-launch support the kernel cannot take a grid-wide
 barrier, so the host drives one launch per (cycle, stage) instead of one launch
-per run. Correct, and slower. See `docs/spikes/amd-laptop-backend.md`.
+per run. Correct, and slower. See `docs/architecture/decisions/spikes/amd-laptop-backend.md`.
 
 ## Benchmarks
 
@@ -214,7 +214,7 @@ transaction records (`WR 0x10 <= 0xCAFEBABE`). Buses are declared via
 `bus_traces` in `sim_config.json`; cosim observes the pins on the GPU and
 runs the protocol FSM on the CPU. **APB3** is supported; AHB-Lite/AHB5
 are planned. See `docs/bus-tracing.md` for the full guide,
-`docs/adr/0013-plural-peripheral-configs.md` for the architecture, and
+`docs/architecture/decisions/0013-plural-peripheral-configs.md` for the architecture, and
 `tests/apb_trace/` for a worked example.
 
 ### Timing Violation Detection
@@ -258,6 +258,13 @@ items before the first numbered release) is in
 schema, timing IR FlatBuffers schema) are governed by their own ADRs
 and bump separately from the binary version.
 
+## Writing docs
+
+Prose for the docs, decision records, and plans follows the house style in
+`docs/prose-style.md`: direct voice, no AI-marker words, no mid-sentence
+interjections, and present-tense claims that track the code. Read it before writing
+or reframing a doc.
+
 ## Handoffs
 
 This project treats handoffs as ephemeral working memory, not historical record. When you write one, follow `docs/handoff-discipline.md` — markdown at `docs/handoffs/<topic>-handoff.md` (sibling to `docs/plans/`, deliberately separate so the persistent plan docs aren't mixed with in-flight working memory). At resolution, fold the content into ADRs / design docs / plan docs, then delete the handoff file. Keep **one handoff per active thread of work** (not one globally); resolved ones are removed, not archived. If the live handoff count outruns ~2× the people actively working, treat that as a WIP signal to resolve/consolidate threads, not to open more. The `git log -- docs/handoffs/` history is the audit trail.

book.toml

@@ -7,7 +7,7 @@ src = "docs"
 # Renders ```d2 fenced blocks to inline SVG at build time by shelling out to the
 # `d2` binary (must be on PATH in the docs CI job). Chosen over mermaid for
 # noticeably better auto-layout on 2-D architecture diagrams; see
-# docs/spikes/architecture-doc-redesign.md.
+# docs/architecture/decisions/spikes/architecture-doc-redesign.md.
 path = "d2"
 layout = "elk"
 

crates/cell-decomp/Cargo.toml

@@ -2,7 +2,7 @@
 name = "cell-decomp"
 version = "0.3.0"
 edition = "2021"
-description = "PDK-neutral behavioral Verilog parsing and AIG decomposition primitives shared by jacquard core and the Liberty->IR converter. See docs/adr/0019-cell-model-ir.md."
+description = "PDK-neutral behavioral Verilog parsing and AIG decomposition primitives shared by jacquard core and the Liberty->IR converter. See docs/architecture/decisions/0019-cell-model-ir.md."
 license = "Apache-2.0"
 repository = "https://github.com/gpu-eda/Jacquard"
 publish = false

crates/cell-model-ir/Cargo.toml

@@ -2,7 +2,7 @@
 name = "cell-model-ir"
 version = "0.3.0"
 edition = "2021"
-description = "Jacquard cell-model IR: a generated, JSON-first, per-cell-type library descriptor (pin directions, combinational AIG, sequential/classification, timing). See docs/adr/0019-cell-model-ir.md."
+description = "Jacquard cell-model IR: a generated, JSON-first, per-cell-type library descriptor (pin directions, combinational AIG, sequential/classification, timing). See docs/architecture/decisions/0019-cell-model-ir.md."
 license = "Apache-2.0"
 repository = "https://github.com/gpu-eda/Jacquard"
 publish = false

crates/cell-model-ir/src/bin/cell-model-ir-diff.rs

@@ -1,7 +1,7 @@
 //! `cell-model-ir-diff` — structural diff between two cell-model-IR documents.
 //!
 //! Used by CI to validate that descriptor regeneration is deterministic
-//! (ADR 0019 D7): a freshly generated descriptor must structurally equal the
+//! (Decision 0019 D7): a freshly generated descriptor must structurally equal the
 //! previous one. Also useful for debugging differences between descriptors
 //! produced by different converter versions.
 

crates/cell-model-ir/src/diff.rs

@@ -1,6 +1,6 @@
 //! Structural diff between two cell-model-IR descriptors.
 //!
-//! This is the [ADR 0019 D7](../../../docs/adr/0019-cell-model-ir.md) provenance
+//! This is the [Decision 0019 D7](../../../docs/architecture/decisions/0019-cell-model-ir.md) provenance
 //! check in tool form: descriptors are regenerated in CI rather than committed,
 //! so the gate is that regeneration is **deterministic** — a freshly generated
 //! descriptor must structurally equal the previous one. It also helps debug

crates/cell-model-ir/src/lib.rs

@@ -1,6 +1,6 @@
 //! Cell-model IR — a generated, JSON-first, per-cell-type library descriptor.
 //!
-//! Realises [ADR 0019](../../../docs/adr/0019-cell-model-ir.md). One
+//! Realises [Decision 0019](../../../docs/architecture/decisions/0019-cell-model-ir.md). One
 //! descriptor carries *everything per-cell-type about a library*; Jacquard
 //! core consumes it as its only source of cell semantics, so the per-PDK Rust
 //! classifiers, the `build.rs` pin-table generation, the runtime
@@ -18,7 +18,7 @@
 //! - **L4 — timing characterization** ([`CellTiming`], decision D5):
 //!   per-cell-type combinational / clock→Q delays and setup/hold constraints,
 //!   plus SRAM/macro timing, **keyed by corner** ([`Corner`] / [`TimingValue`])
-//!   exactly as the timing IR (ADR 0002, `crates/timing-ir`) does — corner is
+//!   exactly as the timing IR (Decision 0002, `crates/timing-ir`) does — corner is
 //!   the outer key, `min`/`typ`/`max` is the orthogonal within-corner derate.
 //!
 //! The schema is explicitly versioned ([`SCHEMA_MAJOR`] / [`SCHEMA_MINOR`]).
@@ -42,7 +42,7 @@
 //!
 //! Cells are keyed by their **full netlist cell-type name** (e.g.
 //! `gf180mcu_fd_sc_mcu9t5v0__nand2_1`) and pins by their **netlistdb pin-name
-//! string** (`A1`, `Y`, `ZN`). This is the same join the timing IR (ADR 0002)
+//! string** (`A1`, `Y`, `ZN`). This is the same join the timing IR (Decision 0002)
 //! uses, so the two IRs co-reference a design purely through the netlist with
 //! no shared-schema join to maintain.
 //!
@@ -60,7 +60,7 @@
 //! A [`Ref`] names any node plus an inversion bit. Each AND node is the
 //! conjunction of two refs to *earlier* nodes; each output pin maps to a ref.
 //! This is the same and-inverter shape Jacquard's design AIG uses
-//! ([ADR 0014](../../../docs/adr/0014-aig-as-simulation-ir.md)), so splicing is
+//! ([Decision 0014](../../../docs/architecture/decisions/0014-aig-as-simulation-ir.md)), so splicing is
 //! a direct node-id remap at load.
 
 use std::collections::HashMap;
@@ -95,7 +95,7 @@ pub struct CellModelIr {
     /// descriptor names a corner by its index into this list. Empty for a
     /// descriptor that carries no L4 timing (e.g. a logic-only C1 descriptor);
     /// the single-corner common flow has exactly one entry. Mirrors the timing
-    /// IR's `corners` (ADR 0002).
+    /// IR's `corners` (Decision 0002).
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub corners: Vec<Corner>,
     /// Name of the corner selected when the user passes no `--corner` (D5).
@@ -293,7 +293,7 @@ impl CombLogic {
     /// Evaluate every output pin for a given assignment of input pin -> bool.
     ///
     /// Pure 2-state evaluation over the AIG; used by round-trip tests and by
-    /// the converter's Liberty-vs-`.v` cross-check (ADR 0019 D6). Returns a
+    /// the converter's Liberty-vs-`.v` cross-check (Decision 0019 D6). Returns a
     /// map from output pin name to value. Returns `Err` if an input pin named
     /// in [`Self::inputs`] is missing from `input_values`.
     pub fn eval(
@@ -570,7 +570,7 @@ pub struct SeqOutput {
 // L4 — timing characterization, corner-keyed (decision D5)
 // ---------------------------------------------------------------------------
 
-/// A PVT corner. Mirrors the timing IR's `Corner` (ADR 0002): every
+/// A PVT corner. Mirrors the timing IR's `Corner` (Decision 0002): every
 /// [`TimingValue`] names one of these by its index into
 /// [`CellModelIr::corners`].
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]

crates/liberty-parse/Cargo.toml

@@ -2,7 +2,7 @@
 name = "liberty-parse"
 version = "0.3.0"
 edition = "2021"
-description = "Generic Liberty (.lib) tokenizer + group/attribute parser. The single Liberty front-end in Jacquard: jacquard's TimingLibrary and the (future) Liberty->cell-model-ir converter both consume this. See docs/adr/0019-cell-model-ir.md (D6)."
+description = "Generic Liberty (.lib) tokenizer + group/attribute parser. The single Liberty front-end in Jacquard: jacquard's TimingLibrary and the (future) Liberty->cell-model-ir converter both consume this. See docs/architecture/decisions/0019-cell-model-ir.md (D6)."
 license = "Apache-2.0"
 repository = "https://github.com/gpu-eda/Jacquard"
 publish = false

crates/liberty-parse/src/json.rs

@@ -6,7 +6,7 @@
 //! SKY130 (`vendor/sky130_fd_sc_hd/`) ships its Liberty exclusively as
 //! `.lib.json` (6848 per-cell-per-corner cell files + a small per-corner
 //! library header), never as `.lib` text. To give SKY130 a generated
-//! cell-model-IR descriptor (ADR 0019), the converter needs a `LibertyGroup`
+//! cell-model-IR descriptor (Decision 0019), the converter needs a `LibertyGroup`
 //! tree — this module decodes the JSON encoding into exactly that tree so the
 //! `liberty-to-cellir` converter consumes it unchanged.
 //!

crates/liberty-parse/src/lib.rs

@@ -7,7 +7,7 @@
 //! consumers walk to extract whatever they need — jacquard core's
 //! `TimingLibrary` (L4 timing characterization) and the future
 //! Liberty -> cell-model-IR converter (L1-L3) both build on this crate.
-//! See `docs/adr/0019-cell-model-ir.md` decision D6.
+//! See `docs/architecture/decisions/0019-cell-model-ir.md` decision D6.
 //!
 //! Liberty's concrete syntax has exactly two statement forms:
 //!

crates/liberty-to-cellir/Cargo.toml

@@ -2,7 +2,7 @@
 name = "liberty-to-cellir"
 version = "0.3.0"
 edition = "2021"
-description = "Build/CI-time tool that generates a cell-model-IR descriptor from a Liberty library (ADR 0019, D6). Lives outside the root cargo package; `cargo test` from the repo root does NOT run its tests — use `cargo test --manifest-path crates/liberty-to-cellir/Cargo.toml`. Not depended on by jacquard core."
+description = "Build/CI-time tool that generates a cell-model-IR descriptor from a Liberty library (Decision 0019, D6). Lives outside the root cargo package; `cargo test` from the repo root does NOT run its tests — use `cargo test --manifest-path crates/liberty-to-cellir/Cargo.toml`. Not depended on by jacquard core."
 license = "Apache-2.0"
 repository = "https://github.com/gpu-eda/Jacquard"
 publish = false
@@ -12,7 +12,7 @@ path = "src/lib.rs"
 
 # The CLI is gated behind the (default-on) `cli` feature so build-time
 # consumers — notably Jacquard's `build.rs`, which links this crate as a
-# library to generate bundled descriptors (ADR 0019 D7) — can depend on it
+# library to generate bundled descriptors (Decision 0019 D7) — can depend on it
 # with `default-features = false` and skip the `clap` build cost.
 [[bin]]
 name = "liberty-to-cellir"

crates/liberty-to-cellir/src/crosscheck.rs

@@ -5,7 +5,7 @@
 //! For a combinational cell that has BOTH a Liberty-derived [`CombLogic`]
 //! AND a discoverable `functional.v` model, evaluate both over every input
 //! assignment and surface any disagreement. This is the eval-based check
-//! ADR 0019 D6 calls for — it reuses `cell_decomp`'s `.v` evaluator as the
+//! Decision 0019 D6 calls for — it reuses `cell_decomp`'s `.v` evaluator as the
 //! oracle rather than rebuilding an AIG from the `.v`.
 //!
 //! Wide cells (input count above [`MAX_EXHAUSTIVE_INPUTS`]) are skipped from
@@ -236,7 +236,7 @@ pub fn check_cell(cell: &CellModel, index: &ModelIndex) -> CellCheck {
     }
 }
 
-/// Outcome of the L4 **arc-set agreement** check for one cell (ADR 0019 D6):
+/// Outcome of the L4 **arc-set agreement** check for one cell (Decision 0019 D6):
 /// does the Liberty-derived delay-arc set match the `.v` `specify` delay-path
 /// set?
 #[derive(Debug, Clone, PartialEq, Eq)]

crates/liberty-to-cellir/src/function.rs

@@ -2,7 +2,7 @@
 
 //! Liberty `function` expression -> [`cell_model_ir::CombLogic`] (single output).
 //!
-//! This is the crux of the converter (ADR 0019 D3/D6): it turns a Liberty
+//! This is the crux of the converter (Decision 0019 D3/D6): it turns a Liberty
 //! boolean function string into a pre-built and-inverter graph that the
 //! runtime splices into the design AIG with no further decomposition.
 //!

crates/liberty-to-cellir/src/lib.rs

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 //! `liberty-to-cellir`: generate a cell-model-IR descriptor from a Liberty
-//! library (ADR 0019 D6 — the converter crate).
+//! library (Decision 0019 D6 — the converter crate).
 //!
 //! Build/CI-time tool, mirroring `opensta-to-ir`. Not depended on by
 //! jacquard core. Three modules:

crates/liberty-to-cellir/src/load.rs

@@ -2,7 +2,7 @@
 
 //! Liberty library loading — shared by the `liberty-to-cellir` CLI and by
 //! callers that drive the converter as a library (e.g. Jacquard's `build.rs`
-//! build-time descriptor generation, ADR 0019 D7).
+//! build-time descriptor generation, Decision 0019 D7).
 //!
 //! ## Split-library handling
 //!
@@ -14,7 +14,7 @@
 //!
 //! File discovery is deterministic (`files.sort()` before merge) so the
 //! resulting [`cell_model_ir::CellModelIr`] — and its serialized JSON — is
-//! byte-identical across repeated runs (ADR 0019 D7 determinism requirement).
+//! byte-identical across repeated runs (Decision 0019 D7 determinism requirement).
 
 use std::path::{Path, PathBuf};
 

crates/liberty-to-cellir/src/main.rs

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 
-//! `liberty-to-cellir` CLI (ADR 0019 D6).
+//! `liberty-to-cellir` CLI (Decision 0019 D6).
 //!
 //! ```text
 //! liberty-to-cellir <input.lib> [-o out.json] [--functional-v <dir>] [--prefix <p>]...
@@ -32,7 +32,7 @@ use liberty_to_cellir::sequential::SeqNote;
 #[derive(ClapParser, Debug)]
 #[command(
     name = "liberty-to-cellir",
-    about = "Generate a cell-model-IR descriptor from a Liberty library (ADR 0019 D6)."
+    about = "Generate a cell-model-IR descriptor from a Liberty library (Decision 0019 D6)."
 )]
 struct Cli {
     /// Input Liberty library (.lib). If it carries no `cell` groups, per-cell

crates/liberty-to-cellir/src/sequential.rs

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 
-//! L3 — sequential pin-roles + classification (ADR 0019 D4).
+//! L3 — sequential pin-roles + classification (Decision 0019 D4).
 //!
 //! Reads a cell's Liberty `ff` / `latch` group (and the `clock_gate_*` pin
 //! attributes) and projects it onto [`cell_model_ir::Sequential`] plus a

crates/liberty-to-cellir/src/specify.rs

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 //! Verilog `specify` block parsing for the D6 L4 **arc-set agreement** check
-//! (ADR 0019 D6).
+//! (Decision 0019 D6).
 //!
 //! A standard-cell `.v` `specify` block carries timing *arc topology* — which
 //! delay paths exist — but only zero/placeholder values (an SDF