107 lines
5.5 KiB
Markdown
107 lines
5.5 KiB
Markdown
# INTENT — policy-nexus
|
|
|
|
## Why this repo exists
|
|
|
|
`policy-nexus` is the permanent home for the estate's **policy surface**: the
|
|
place where policy is published and kept current. It serves
|
|
`policy.coulomb.social`, and is **owned by `the-custodian`**.
|
|
|
|
It does one thing. Gathering policy from the outside world was originally
|
|
scoped here and moved to `risk-nexus` on 2026-08-17 — judging what an external
|
|
rule demands of the estate is risk work, not publishing work.
|
|
|
|
Before this repo existed, published policy lived in a bad place.
|
|
|
|
**Published policy was temporary.** Documents that other people needed to read
|
|
were pushed to disposable artifact pages — private URLs, no index, no history,
|
|
no guarantee the link resolves next month. A document that governs how six
|
|
repos behave cannot be delivered as a link that might expire. The estate has
|
|
already been bitten by the adjacent failure: a canon draft routed for
|
|
ratification on 2026-08-10 sat unratified in neither canon directory because
|
|
nothing tracked that it was in flight.
|
|
|
|
This repo exists so that policy has a permanent address and a known freshness.
|
|
|
|
## What it owns
|
|
|
|
- **`policy.coulomb.social`** — the public publication surface: its
|
|
infrastructure, deployment, availability and rollback.
|
|
- **Publication of estate policy**, scoped to **canon and architecture decision
|
|
records**. Rendering governing documents from their source repos into a
|
|
durable, addressable, indexed site. The source of truth stays in the owning
|
|
repo; this repo owns the *publication*, not the content.
|
|
|
|
The corpus in scope today is bounded and countable: two canon trees
|
|
(`the-custodian/canon`, `net-kingdom/canon`) and roughly 68 ADRs across 18
|
|
repositories. Workplans, evidence, runbooks and general documentation are
|
|
**out of scope** — this is a policy site, not a documentation site. That line
|
|
is deliberate: a site that publishes everything publishes nothing in
|
|
particular, and the value here is that a reader knows what governs and what
|
|
merely describes.
|
|
- **Stable addressing.** A published document keeps its URL. Superseded
|
|
versions remain reachable and are marked superseded rather than removed.
|
|
- **Currency.** Every published document carries its status, revision, and when
|
|
it was last reviewed. A stale document is visibly stale rather than silently
|
|
wrong.
|
|
- **Publication for `risk-nexus`.** Regulatory records and publishable findings
|
|
arrive as another source in the manifest. This repo renders and hosts them;
|
|
it does not decide what they mean or when they may be seen.
|
|
- **The relevance loop.** Detecting when a published or gathered document has
|
|
gone out of date, and surfacing that rather than waiting for someone to
|
|
notice.
|
|
|
|
## What it does not own
|
|
|
|
- **The content of estate policy.** Canon lives in its owning canon repo;
|
|
per-repo ADRs live in their repos. This repo publishes what those own and
|
|
must never become a second place where policy is edited. The local-files-are-
|
|
source-of-truth rule applies with full force: if the site and the source
|
|
disagree, the source is right and the publication is a defect.
|
|
- **Ratification.** Whether a draft becomes canon is a canon-process decision.
|
|
This repo can show that a draft is in flight and how long it has been; it
|
|
cannot advance it.
|
|
- **Legal advice.** Gathered external policy is recorded with its source and
|
|
date. Interpreting what it requires of the estate is the owning repo's
|
|
decision, informed by the record, and the record must not read as a ruling.
|
|
- **Identity, authorization, storage, secrets.** Consumed from the platform
|
|
packages, never reimplemented.
|
|
- **Being a CMS.** No editing surface, no drafting in a browser. Documents
|
|
arrive from repositories.
|
|
|
|
## Permanence is the point
|
|
|
|
The word doing the work in this repo's purpose is *permanent*. It sets
|
|
requirements that a temporary page does not have:
|
|
|
|
- **A URL that resolves in five years.** Addressing is a design decision made
|
|
once and then honoured, not a consequence of whatever generated the page.
|
|
- **History that survives.** A superseded policy is part of the record. Anyone
|
|
asking "what did this say when we made that decision" must be able to find
|
|
out.
|
|
- **Availability that is somebody's job.** If policy governs behaviour, policy
|
|
being unreachable is an incident, not an inconvenience.
|
|
- **Generated, never authored.** Every page is derived from a source document
|
|
in a repository. Nothing is hand-written into the site, because hand-written
|
|
content diverges from its source — a failure this estate has already had
|
|
once, between an ADR and its published page, and fixed by generating the page
|
|
from the markdown.
|
|
|
|
## Relationship to the rest of the estate
|
|
|
|
`policy-nexus` is downstream of every repo that owns policy and upstream of
|
|
nobody. It reads; it does not write back. That direction is deliberate: a
|
|
publication surface with write authority becomes a second source of truth, and
|
|
the estate has a standing rule against exactly that.
|
|
|
|
The first content it must carry is already waiting: NetKingdom's *Tenancy
|
|
Posture* standard, now reviewed by all six affected repos and still served from
|
|
a disposable artifact URL. The renderer that produces that page from canon
|
|
markdown lives here as `tools/render.py`.
|
|
|
|
## What good looks like
|
|
|
|
A person outside the estate can find the policy that governs a decision, see
|
|
when it was last reviewed, read the version that was current at any past date,
|
|
and tell at a glance whether it is ratified or in flight. A person inside the
|
|
estate never asks "where is the current version of that" and never has to be
|
|
told "the link expired".
|