ADR conventions

A2C uses Architecture Decision Records (ADRs) as first-class governing artifacts.

ADR properties

Property	Rule
Immutable in substance	Accepted/Rejected ADRs are not rewritten for semantic changes
Append-only log	New decisions → new ADRs; history stays inspectable
Supersession	Meaning changes → new ADR; old ADR marked Superseded
Chronology	ADRs remain in numeric order — do not reorder for grouping
Navigation	Grouped views use INDEX.md, not filename reshuffling
Focus	One architecturally significant decision per ADR

If a change involves multiple independent decisions, split into multiple ADRs.

File naming

docs/adr/NNNN-short-title.md

• NNNN — zero-padded sequence (0000, 0001, …)
• short-title — lowercase kebab-case summary

ADR-0000 convention

ADR-0000 meaning depends on repository role:

In a2c-workflow (this repository)

ADR-0000 records a foundational decision about the workflow repository itself — for example, establishing a2c-workflow as the canonical A2C definition repository.

It must not be written as self-adoption (adopt A2C workflow vX.Y) as if this repo were a downstream consumer.

Example commit: adr(workflow): Establish a2c-workflow as the canonical A2C repository

In downstream A2C-based projects

Every consumer project starts with ADR-0000 recording:

• the decision to adopt A2C as the governing workflow
• the specific A2C version adopted (from a2c-workflow VERSION or tag)
• how workflow assets are mounted or copied

Example commit: adr(workflow): Adopt A2C workflow vX.Y.Z

In superbuild consumer workspaces

Repositories that adopt superbuild-workflow at tools/ai-rules/ (legacy superbuild migration / CMake policy) use the same ADR file format and lifecycle as A2C-governed projects, but are not A2C-governed workflows. Each Git repo keeps its own docs/adr/ sequence.

Role	ADR-0000 records
Superbuild workspace root	Adoption of superbuild-workflow revision at tools/ai-rules/
Product repo under src/ (if A2C-governed)	Adoption of A2C workflow vX.Y.Z

Superbuild-specific guidance: superbuild-workflow docs/adr-conventions.md.

Consumer tool state and method asset paths (including legacy .a2c/ vs .tools/esys/a2c/) are defined by ADR-0024 (supersedes ADR-0013). How a2c discovers workspace root W is ADR-0025. Workspace method install and member enumeration (esysrepo / repo) is ADR-0027 (Proposed). IDE adapter materialization (Cursor / Copilot) is ADR-0028.

Status lifecycle

Status	Meaning
Proposed	Under discussion — may be edited freely until Accepted/Rejected
Accepted	Governing contract — immutable in substance (see below)
Amended	Still governing as a base; read with Accepted amendments under ## Amended by
Rejected	Decision not adopted — immutable in substance
Superseded	Replaced by a later ADR — body frozen; update Status and links only
Deprecated	No longer recommended — document replacement

Amendment vs supersession: ADR-0021.

ADR editing and evolution

The ADR log is a historical record of decisions, not a living document that gets silently rewritten. These rules are cornerstone-level: humans and AI must follow them exactly.

Machine-usable rule: pathname:///a2c-assets/rules/08-adr-editing-evolution.md.

A. Immutability principle

Once an ADR is Accepted, Amended, or Rejected, it is immutable in substance. The decision, context, rationale, and consequences must not be changed in place to reflect new intent.

• Proposed ADRs may be edited until accepted or rejected.
• Do not "update" an Accepted ADR to match new reality — record a new ADR (amend if the core decision still holds; supersede if it does not).

B. Allowed in-place edits (non-semantic maintenance)

The following are allowed on Accepted, Amended, Rejected, or Superseded ADRs when they do not alter decision, context, rationale, or consequences:

• Fixing typos, spelling, or grammar
• Fixing broken URLs or incorrect links (wrong path or protocol)
• Fixing incorrect file references when intent is clearly unchanged (e.g. docs/foo.md → docs/foo/overview.md)
• Adjusting Markdown formatting (headings, lists, code fences) without meaning change
• Clarifying non-normative wording where decision, context, and consequences remain exactly the same

Use commit type docs(adr): or fix(adr): for maintenance — not adr(...) (reserved for new decisions).

Example (allowed): ADR-0000 references ../../VERSION with a broken path; fix the link to point at the repository VERSION file without changing what the ADR decided.

Example (forbidden): Rewording ## Decision because the project now uses a different workflow version — that requires a new superseding ADR.

C. Changes that require a new ADR (amend or supersede)

If any of the following would change, do not edit the Accepted ADR in place — create a new ADR:

• The decision itself (even slightly)
• Scope of what the decision applies to
• Context or rationale in a way that changes interpretation
• Which specs, workflow versions, or governing documents the decision depends on (when that changes the basis)
• Obligations, constraints, or consequences (broader or narrower)
• Reinterpreting the ADR instead of recording a new decision

Intent	Path
Core decision still holds; additive or clarifying only	Amend (§ D)
Core decision no longer valid	Supersede (§ E)

D. Amending pattern

When the core decision still holds but needs an additive extension or clarification:

1. New ADR — Decision contains only the delta; lists base under ## Amends.
2. Base ADR — keep original body (except B maintenance); set Status: Amended; set ## Amended by: ADR-NNNN.
3. INDEX.md — update in the same adr(...) commit as the new ADR.
4. Effective contract — Amended base plus Accepted amendments in the chain.

E. Superseding pattern

When decision meaning changes such that the old core is no longer valid:

1. New ADR — states the new decision; lists superseded ADR(s) under ## Supersedes; explains why the old decision is insufficient.
2. Old ADR — keep original body (except B maintenance); set Status: Superseded; set Superseded by: ADR-NNNN.
3. INDEX.md — update in the same adr(...) commit as the new ADR.
4. Active contract — the latest Accepted ADR in the chain.

One amending or superseding decision per new ADR file; one adr(...) commit per new ADR.

F. Versioning examples

Downstream A2C project

Step	Action
Initial	ADR-0000: Adopt A2C workflow v0.1.0 — Accepted
Upgrade	ADR-0005: Adopt A2C workflow v0.2.0 — supersedes ADR-0000
Old ADR	ADR-0000 → Status Superseded; Superseded by ADR-0005

a2c-workflow repository (this repo)

• ADR-0000 records a foundational workflow-repo decision (e.g. establish a2c-workflow as the canonical A2C repository).
• It does not say "this project uses A2C vX.Y" — that pattern is for consumer repos only.
• Releasing VERSION 0.2.0 does not require editing ADR-0000; only a foundational decision change requires a new superseding ADR.

G. AI behavior

AI tools (including Cursor) must:

• Treat Accepted/Amended/Rejected ADRs as immutable in substance
• Apply only B maintenance edits when the request clearly matches B
• If a request would change meaning (C): propose an amending or superseding ADR (choose via § C) or ask for confirmation — never silently rewrite Decision, Context, or Consequences
• Preserve amend and supersession chains; never delete or renumber ADRs to tidy history

See also pathname:///a2c-assets/rules/05-ai-behavior.md and pathname:///a2c-assets/prompts/phases/adr-create-update.md.

Index maintenance

Update INDEX.md in the same commit as a new, amending, or superseded ADR.

The index provides grouped navigation without breaking chronological file order.

ADR commits

ADRs use a dedicated conventional commit type:

adr(<category>): <short summary>

Categories: workflow, build, layout, docs, security, etc.

One ADR per commit. No bundling with implementation or unrelated documentation.

Full rules: pathname:///a2c-assets/rules/03-adr-commits.md.

External web sources

New ADRs and docs under docs/ must cite new external URLs with [web:NNN] tags registered in ../web-source-mapping.md. Process: ADR-0011, pathname:///a2c-assets/rules/15-web-source-tags.md. Accepted ADRs may keep legacy inline URLs (soft adoption). Validate with python scripts/check_web_source_tags.py.

Template

Use pathname:///a2c-assets/templates/adr/adr-template.md.

Related

• INDEX.md
• ../workflow/principles.md