---
id: RPLAT-ADR-0003
title: "ADR-0003 — Decisions that bind others live in docs/adr, not only in the State Hub"
status: accepted
revision: "1.0"
owner: railiance-platform
date: "2026-08-17"
last_reviewed: "2026-08-17"
review_interval: 12m
---

# ADR-0003 — Decisions that bind others live in `docs/adr`, not only in the State Hub

## Context

This repo recorded decisions with the State Hub's `record_decision()` and wrote
governing content as prose in `docs/` — 24 files on 2026-08-17, none carrying a
status, owner, revision or review date. It held no ADRs at all.

Two things made that a defect rather than a style.

**The hub is a read model.** The estate's standing rule is that local files are
the source of truth and the hub reflects them. A decision that exists only as a
hub record inverts that for the one class of content where it matters most.

**`policy-nexus` publishes canon and ADRs only**, globbing `docs/adr/*.md` from
each repo. A repo with no ADRs is invisible to the estate's publication surface
no matter how much governing content it holds. This repo owns S3 boundary
rules, the credential-lane model and the consumption-mode gate — all binding on
other repos, all unpublishable.

The gap was structural, not an oversight: nothing in the session protocol ever
told anyone to write an ADR here.

## Decision

**A decision that binds anyone outside this repo is recorded as an ADR in
`docs/adr/`, with the frontmatter in `docs/adr/README.md`, before or alongside
any hub record.** The hub record points at the ADR; it does not replace it.

Runbooks and procedures stay as prose in `docs/` and stay unpublished. The test
is not importance — several runbooks are critical — but whether the document
*decides* something for someone else.

## Consequences

- `docs/adr/` exists, with a convention, a template and this repo's first three
  ADRs.
- Existing prose is not converted wholesale. Content is promoted when it is
  next touched, or when a consumer needs to cite it.
- `last_reviewed` and `review_interval` are mandatory here, which is stricter
  than the estate norm — of 69 ADRs across 19 repos on 2026-08-17, 21 had YAML
  frontmatter and 2 had any notion of a review date. `POLICY-NEXUS-WP-0001` T05
  cannot compute staleness without those fields and must not invent them, since
  inventing them would make the publication a second source of truth, which is
  that workplan's own top risk. Routed as `RPF-WP-0018` finding F5.
- Session protocol guidance should follow, so the next agent writes an ADR
  without being told. Not done in this ADR.

## Alternatives considered

**Keep decisions in the hub and have `policy-nexus` read it.** Rejected on
both sides: it would make a read model authoritative, and it would give the
publication surface a source that no repo can diff or review.

**Add frontmatter to all 24 existing `docs/` files.** Rejected. Most are
runbooks that should not be published, and stamping them with a status would
assert a decision that was never made.