coulomb/railiance-platform
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
railiance-platform/docs/adr/ADR-0003-decisions-live-in-the-repo.md
codex e7e4e33bb8 RPF-WP-0018 T01-T06: publish S3 posture, placement policy, quotas, ADR surface 
T01 docs/tenancy-posture.md - vector set per service rather than one repo
vector, with the provider-versus-consumer finding routed to net-kingdom.
T02/T03/T06 docs/placement-policy.md - accepts placement ownership scoped
to rule-here/number-there, records a placement owner per workload, reports
the latency-critical + batch co-residency on platform-pg, marks the
connection-ceiling trigger unmonitored pending railiance-telemetry, and
answers the retention floor/ceiling question.
T04 s3-consumer-interfaces 1.1.0 - quota disclosure per SS10.2. Surfaces
that apps-pg has no backup, no resource limits and no tuned parameters.
T05 docs/adr/ created with a mandatory-frontmatter convention and the
first three ADRs. This repo previously held none.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-17 21:55:11 +02:00

2.9 KiB
Raw Blame History

title status revision owner date last_reviewed review_interval
ADR-0003 — Decisions that bind others live in docs/adr, not only in the State Hub accepted 1.0 railiance-platform 2026-08-17 2026-08-17 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.