Architecture decision records

One decision per file under governance-log/decisions/, MADR-shaped, YAML so it is machine-checkable (ISO 42010 6.10 wants decisions with rationale; here the schema makes rationale mandatory rather than polite):

id: decision-order-api-single-integration
title: The order API stays the only integration between portal and ERP
status: accepted        # proposed | accepted | rejected | deprecated | superseded
date: 2026-07-20
context: >
  The forces: what question was open, and why it had to be answered now.
decision: >
  What was decided, in one falsifiable statement.
rationale: >
  Why this option over the others -- including the risk being accepted.
consequences: >
  What becomes easier, what becomes harder, what must now be done.
options:
  - option: Single order API (chosen)
    pros: One contract, one failure mode.
    cons: Concentration risk.
  - option: Point-to-point integrations
    pros: Independent failure domains.
    cons: Hidden coupling; three contracts to govern.
relatedElements: [service-order-api, app-order-portal]

What makes an ADR worth having

• The decision is falsifiable. "We will be API-first" is a poster; "new data needs extend the order API, they do not add parallel channels" can be violated and therefore governed.
• The rationale names the rejected option and the accepted risk. A rationale that only praises the winner is advertising. The record exists for the person in two years asking "did they consider X?" -- show them X in options.
• relatedElements are real model ids (DEC005 checks). This link is what makes decisions appear in ea-context packs -- an ADR bound to no element governs nothing.
• Status transitions are records, not edits. Superseding means: new decision file, old one gets status: superseded + supersededBy: (checked by DEC003/DEC004). Never rewrite an accepted decision's content -- amend history through new records.
• Superseding is not finished until the elements move. relatedElements left on a superseded record means the model still realises a decision that no longer stands -- CORR001, and it is the reason the successor record exists at all. Carry the elements over to the new record, or drop the ones the new decision no longer covers.

Judgement calls

Record decisions at the level someone will contest later: technology selections, integration topologies, standard adoptions, deliberate rule deviations. Do not ADR routine modelling ("we added an element"). If the "decision" is really a waiver from a standard, that is ea-dispensation; if it is a new norm going forward, it likely needs both an ADR (why) and a SIB entry (what).

Two cases arrive from generated proposals (propose) and both are ADRs before they are anything else:

• A wp-rationalize-* work package whose answer is "keep both". Deliberate redundancy — resilience, data residency, a strangler beside what it replaces — is a decision, and without a record the next reader cannot tell it from drift. The same finding then gets re-litigated every quarter. Name both systems and the reason the duplication is bought on purpose.
• A req-* requirement that overturns or leans on an accepted decision. Write the ADR, then have the requirement reference it. A requirement filed alone leaves its reasoning nowhere.

Validate with easkills validate-gov, report the decision in one sentence plus who should confirm status: accepted if you filed it as proposed.