---
title: "ADR convention for railiance-platform"
status: accepted
revision: "1.0"
owner: railiance-platform
date: "2026-08-17"
last_reviewed: "2026-08-17"
review_interval: 12m
---

# ADRs in this repo

Work record: `RPF-WP-0018` T05.

Until 2026-08-17 this repo held **no ADRs**. Its decisions lived either as
prose in `docs/` without status or ownership, or in the State Hub via
`record_decision()`. Both are wrong homes, for the same reason: the hub is a
read model and prose is not addressable as a decision. `policy-nexus`
publishes canon and ADRs only, so a repo with no ADRs publishes nothing —
regardless of how much governing content it holds. See `ADR-0003`.

## What gets an ADR here

A decision gets an ADR when it **binds someone other than the person who made
it** — another repo, a future maintainer, or a consumer of an S3 interface.

| Content | Home | Published |
| --- | --- | --- |
| A decision binding others | `docs/adr/` | yes |
| A procedure someone follows | `docs/*.md` runbook | no |
| Live interface values | `docs/s3-consumer-interfaces.md` | no |
| Work sequencing | `workplans/` | no |

Runbooks stay prose deliberately. A site that publishes everything publishes
nothing in particular, and `POLICY-NEXUS-WP-0001` T03 already draws that line.

## Frontmatter is mandatory

Every ADR carries the YAML block below. The fields are not decoration: they
are exactly what `POLICY-NEXUS-WP-0001` T02 and T05 consume to render a page
and to mark it stale.

```yaml
---
title: "ADR-NNNN — short imperative statement of the decision"
status: proposed | accepted | superseded | withdrawn
revision: "1.0"
owner: railiance-platform
date: "YYYY-MM-DD"          # when decided
last_reviewed: "YYYY-MM-DD"
review_interval: 6m | 12m   # after which the page shows as stale
supersedes: ADR-NNNN        # optional
superseded_by: ADR-NNNN     # optional
---
```

`last_reviewed` and `review_interval` are the two fields the rest of the estate
mostly lacks — of 69 ADRs across 19 repos on 2026-08-17, 2 carried any notion
of a review date. A publication surface cannot compute staleness without them
and must not invent them, so they are required here.

Numbering is `ADR-NNNN`, four digits, never reused. A superseded ADR keeps its
number and its file; it gains `superseded_by` and its status changes. Nothing
is deleted — the published URL must keep resolving.

## Sections

Context · Decision · Consequences · Alternatives considered. Keep the decision
statement to one paragraph a reader can quote.