How to Propose, Accept, Supersede, or Deprecate an ADR

How to Propose, Accept, Supersede, or Deprecate an ADR

Manage an Architectural Decision Record’s lifecycle in mif-rs, from first draft through to acceptance or eventual supersession.

Prerequisites

• A change with real, considered alternatives — not a task or a requirement (see ADR-0001).
• Familiarity with the Structured MADR format this repository uses (via the mif-docs:adr skill), not plain MADR.

Propose a new ADR

1. Create a new file in docs/adr/ named NNNN-title-with-dashes.md, using the next sequential number.
2. Author it with the mif-docs:adr skill so it carries the required Structured MADR sections and MIF frontmatter.
3. Set status: proposed in the frontmatter.
4. Open a pull request.

Accept an ADR

1. After discussion and approval on the pull request, change status to accepted.
2. Merge the pull request.

Supersede an ADR

1. Create a new ADR (per “Propose a new ADR” above) that documents the replacement decision.
2. In the old ADR’s frontmatter, set status: superseded and add a relationships entry of type superseded-by pointing at the new ADR.
3. Set the new ADR’s status to accepted once approved.

Deprecate an ADR

1. If a decision is no longer relevant but has no direct replacement, set status: deprecated in its frontmatter.
2. Add a note in the ADR’s ## Audit section explaining why.

An accepted ADR’s outcome is never edited in place — a changed decision gets a new, superseding ADR instead.

ADR Index

• ADR-0001 — Use Architectural Decision Records
• ADR-0002 — Documentation Directory Structure
• ADR-0003 — Virtual Cargo Workspace, Not a Root Package
• ADR-0004 — Library Crates Never Depend on the Binary Crates
• ADR-0005 — Per-Crate thiserror Error Enums, No Shared Top-Level Error Type
• ADR-0006 — Vendor the Canonical JSON Schema at Compile Time, Not Fetch at Validate Time
• ADR-0007 — Generic Frontmatter Pass-Through, Not a Curated Field List
• ADR-0008 — Hand-Written Core Types, Not Schema-to-Rust Codegen
• ADR-0009 — Pedantic, Nursery, and Cargo Clippy Lint Groups, Workspace-Wide
• ADR-0010 — Release Profile: panic = "abort", strip, and Thin LTO
• ADR-0011 — Ban openssl and atty; Use rustls and std::io::IsTerminal
• ADR-0012 — cargo-chef Multi-Stage Docker Build for Dependency-Layer Caching
• ADR-0013 — Chainguard glibc-dynamic as the Container Runtime Base, Superseding distroless/cc-debian12
• ADR-0014 — GHCR Package Visibility: Manual, Not Automated
• ADR-0015 — Local Embeddings and a SQLite Brute-Force Vector Store
• ADR-0016 — Lefthook Git Hooks: Fast Pre-Commit, Full CI-Parity Pre-Push
• ADR-0017 — RFC 9457 Error-Type URIs Hosted on This Repository’s Own GitHub Pages Site
• ADR-0018 — Publish rustdoc Alongside the Starlight Site in One Pages Deployment
• ADR-0019 — Ship the Research-Harness Ontology Engine as mif-rh Crates Inside the mif-rs Workspace
• ADR-0020 — mif-rh-mcp Speaks stdio-Only MCP Transport