70 lines
2.5 KiB
Markdown
70 lines
2.5 KiB
Markdown
|
---
|
||
|
|
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.
|