# Rule: ADR conventions

## Structure

- Location: `docs/adr/NNNN-short-title.md`
- One architecturally significant decision per ADR
- Split independent decisions into separate ADRs

## Lifecycle

| Rule | Detail |
|------|--------|
| Immutable in substance | Accepted/Amended/Rejected: no semantic in-place edits |
| Append-only log | Meaning changes → new ADR, not silent rewrite |
| Chronology | Keep numeric order; use INDEX for grouping |
| Status | Proposed → Accepted / Amended / Rejected → Superseded / Deprecated |
| Amendment | Core decision still holds → new ADR with `## Amends` (ADR-0021) |
| Supersession | Core decision no longer valid → new ADR with `## Supersedes` |

## Editing and evolution

Operational rules for in-place maintenance, **amend**, and **supersede**:
**`rules/08-adr-editing-evolution.md`** (mandatory for AI and humans).
Amendment semantics: [ADR-0021](../docs/adr/0021-amending-accepted-adrs.md).

## ADR-0000

| Repository | ADR-0000 records |
|------------|------------------|
| **`a2c-workflow`** | Foundational workflow-repo decision (canonical definition) — not self-adoption |
| **Downstream A2C projects** | Adoption of A2C version X.Y and how workflow assets are consumed |
| **Superbuild consumer** (not A2C-governed) | Adoption of **superbuild-workflow** at `tools/ai-rules/` — see [superbuild-workflow `docs/adr-conventions.md`](https://gitlab.com/libesys/ai-workflows/superbuild-workflow/-/blob/develop/docs/adr-conventions.md) |

## Index

Update `docs/adr/INDEX.md` when adding, amending, or superseding ADRs — in the same commit as the ADR.

## Template

Use `templates/adr/adr-template.md`.

## External web sources

New ADRs and docs under `docs/` **must** cite new external URLs with `[web:NNN]` tags and entries in [../web-source-mapping.md](../web-source-mapping.md). See [ADR-0011](0011-web-source-tags-with-central-mapping.md) and [../../rules/15-web-source-tags.md](../../rules/15-web-source-tags.md). Existing Accepted ADRs may keep inline URLs (soft adoption).