7 Architecture Decision Management

7.1 ADR as an engineering object

In Quarto-Needs, an ADR is not a loose file maintained beside requirements. The canonical object is architecture-decision, with lifecycle, attributes, relations, and validation in the same graph used by the rest of engineering.

This preserves an important distinction:

a requirement expresses a need or obligation on the system;
an architecture decision records a choice made in response to drivers;
a component/interface materializes the architecture;
a test/evidence confirms behavior or conformance.

Therefore, a decision does not directly satisfy or implement a requirement. It addresses it.

7.2 Decision relations

Relation	Recommended direction	Meaning
`addresses`	ADR → driver	requirement, need, or risk that motivated the decision
`applies-to`	ADR → architecture element	components/interfaces affected by the decision
`confirmed-by`	ADR → confirmation	test or evidence that confirms the decision
`supersedes`	new ADR → previous ADR	replacement lineage

The inverse forms addressed-by, confirms, and superseded-by belong to the same semantic families.

7.3 Complete example

::: {.need #ADR-007 type="architecture-decision" status="accepted"}
date: 2026-08-28
revisit-after: 2027-08-28
decision-makers: Architecture Team
addresses: NFR-003;RISK-002
applies-to: COMP-004;IF-003
confirmed-by: TC-010;TC-015
tags: audit;privacy

## Separate the audit trail from transactional processing

### Context and Problem Statement
...

### Decision Drivers
...

### Considered Options
...

### Decision Outcome
...

### Consequences
...

### Confirmation
...
:::

Fields used by queries and rules stay structured. Context, alternatives, outcome, and consequences remain in Markdown. The narrative structure is compatible with ADR practices such as MADR without coupling the core to a single textual presentation.

revisit-after is optional. Use it for decisions whose validity should be reconsidered after a known date — for example, temporary technology constraints, transitional architectures, or decisions tied to an external standard. It is not a replacement for superseded: a review may conclude that the existing decision remains valid.

7.4 Selecting and filtering ADRs

Architecture decisions can be rendered as a focused catalog with adr-table, or counted with adr-count. Filters can be combined by lifecycle status, tags, decision makers, and ISO date ranges; date-sort controls chronological ordering.

{{< adr-table status="accepted" tags="security;audit" date-from="2026-01-01" date-sort="desc" >}}

Accepted decisions: {{< adr-count status="accepted" >}}

Supported selectors are status, tags, decision-makers, date-from, date-to, and query. The default columns are id, title, status, date, decision-makers, and tags.

Named queries are also materialized as reusable graph projections. If the project declares a query called accepted-decisions, the same Python-evaluated selection can be explored without restating the filter in Lua:

{{< need-graph query="accepted-decisions" >}}

view="accepted-decisions" is an equivalent, presentation-oriented spelling. Query evaluation still belongs exclusively to the Python core.

7.5 Lifecycle

The recommended lifecycle is:

proposed ──► accepted ──► deprecated
    │            │
    └──► rejected└──► superseded

A superseded decision must retain explicit lineage. The replacement points to the previous decision with supersedes, allowing history to be reconstructed without retroactively editing old decisions.

7.6 DEC rules

The implementation includes:

Code	Check
`DEC001`	an accepted decision must have at least one driver (`addresses`)
`DEC002`	an accepted decision must declare architectural scope (`applies-to`)
`DEC003`	an accepted decision must declare confirmation (`confirmed-by`)
`DEC004`	a decision marked `superseded` needs consistent lineage
`DEC005`	the decision-supersession graph must be acyclic
`DEC006`	an accepted decision with `revisit-after` is reported when its review date is overdue or invalid

Required metadata such as date and decision makers remains covered by required-attributes policy. The rules are configurable through the same mechanism used by REQxxx rules. Date-sensitive findings use the same reproducible reference-date mechanism as evidence expiry (SOURCE_DATE_EPOCH when provided).

7.7 Impact

Impact direction is declared in the relation catalog. A change to a requirement can therefore propagate to the decision that addresses it; the decision can propagate to architecture elements and confirmations.

NFR-014 changed
   ↓
ADR-007
   ├──► COMP-004
   └──► TC-010 ──► EVD-010

This chain is the main benefit of integrating Requirements Engineering and Architecture Decision Management: rationale stops being isolated prose and becomes part of change analysis.