tegwick
a8fb62a3bc
Add the owner-facing publication contract, a regenerable ADR review ledger, and publication entries for this repo's ADR-0001 plus the eight ready railiance-master ADRs.
130 lines
4.9 KiB
Markdown
130 lines
4.9 KiB
Markdown
# Publication contract for source owners
|
|
|
|
How a governing document gets a permanent address on
|
|
`https://policy.coulomb.social`. This note is the owner-facing contract
|
|
from POLICY-NEXUS-WP-0002-T01. It is not itself a published policy
|
|
document.
|
|
|
|
`policy-nexus` publishes. It does not author your document and it does
|
|
not write back.
|
|
|
|
## What can be published
|
|
|
|
| Kind | What it is | Typical source path |
|
|
| --- | --- | --- |
|
|
| `standards` | Governing standard | `canon/standards/<name>_vN.md` |
|
|
| `architecture` | One arc42 document per system | `docs/architecture/<system>_v0.1.md` or `canon/architecture/<system>_v0.1.md` |
|
|
| `constitution` | Estate constitution | `canon/constitution/` |
|
|
| `adr` | Architecture decision record | `docs/adr/<file>.md` |
|
|
|
|
Workplans, evidence, runbooks, review ledgers, and general docs are out.
|
|
|
|
An ADR is published only after an explicit `publication.json` entry.
|
|
Architecture documents follow the same rule. Discovery
|
|
(`source-inventory.config.json`) is not publication.
|
|
|
|
## Front-matter the builder requires
|
|
|
|
```yaml
|
|
---
|
|
id: <globally-unique-id>
|
|
title: "Human title"
|
|
status: proposed | accepted | superseded | withdrawn
|
|
owner: <owning-repo-or-canon-owner>
|
|
revision: "accepted-1"
|
|
last_reviewed: "YYYY-MM-DD"
|
|
review_interval: 6m
|
|
---
|
|
```
|
|
|
|
| Field | Rule |
|
|
| --- | --- |
|
|
| `id` | Must equal the `publication.json` `id`. Globally unique. Repo-prefix ADRs (`RMASTER-ADR-0001`, `policy-nexus-adr-0001`). Bare `ADR-001` will collide. |
|
|
| `title` | Shown on the page and the site index. |
|
|
| `status` | Honesty with the body. If the prose says relocated, the status is `superseded`. |
|
|
| `owner` | Who answers for the content. |
|
|
| `revision` or `version` | Becomes the immutable revision slug. |
|
|
| `last_reviewed` or `updated` | ISO date. Currency starts here. |
|
|
| `review_interval` | `Nd`, `Nm`, or `Ny`. Default `6m` if you do not declare one; the publication entry may also set it. |
|
|
|
|
A document missing any of those fields fails the build. Do not ask this
|
|
repo to invent them.
|
|
|
|
## Addresses
|
|
|
|
From ADR-0001:
|
|
|
|
```text
|
|
/<kind>/<document>/<version>/
|
|
/<kind>/<document>/<version>/revisions/<revision>/
|
|
```
|
|
|
|
- `<kind>` is one of the four kinds above.
|
|
- `<document>` is a kebab-case slug, unique on the site. If two systems
|
|
would share a short name, prefix with the system slug
|
|
(`railiance-repository-prefix`, not `repository-prefix`).
|
|
- `<version>` is the document series (`v0.1`, `v1`). A new major version
|
|
is a new current address; the old one stays and is marked superseded.
|
|
- `<revision>` is the front-matter `revision` (for example `draft-8`,
|
|
`accepted-1`). That URL is write-once.
|
|
|
|
Examples:
|
|
|
|
```text
|
|
/standards/tenancy-posture/v0.1/
|
|
/architecture/policy-nexus/v0.1/
|
|
/adr/addressing-and-permanence/v1/
|
|
/adr/railiance-repository-prefix/v1/
|
|
```
|
|
|
|
No URL is derived from a checkout path, branch, or build number.
|
|
|
|
## Architecture documents (arc42)
|
|
|
|
One markdown file per system, following
|
|
`markitect-main/examples/templates/TEMPLATE-ARC42.md`.
|
|
|
|
- Chapter 9 **lists** that system's ADRs (id, status, pointer). It does
|
|
not paste them.
|
|
- First-wave complete means chapters **1, 3, 4, 5.1, 9 and 12** are
|
|
real. Every other chapter is real or explicitly `N/A` with a reason.
|
|
- A stub that can be published early has real chapters **1, 3 and 9**
|
|
plus this front-matter.
|
|
|
|
Validate once Markitect registers `arc42-v1`:
|
|
|
|
```sh
|
|
markitect validate docs/architecture/<system>_v0.1.md --schema arc42-v1
|
|
```
|
|
|
|
Until that schema exists, author against the template. This repo will
|
|
not publish an architecture document that cannot be validated after the
|
|
schema lands.
|
|
|
|
## Infospace index
|
|
|
|
The collection index lives at
|
|
`the-custodian/canon/architecture/infospace/`. It **references** the
|
|
owning-repo documents. It does not copy them. InfoTechCanon owns the
|
|
information-space model, not this estate's building-block view.
|
|
|
|
## How to request publication
|
|
|
|
1. Put the front-matter on the source document in the owning repo.
|
|
2. For an architecture document, meet the stub or first-wave bar above.
|
|
3. Open a PR against `policy-nexus` that adds one `publication.json`
|
|
entry (and a `repositories` path if the repo is new here).
|
|
4. `make check` and `make build` must pass.
|
|
|
|
Do not glob a tree into `publication.json`. Inventory records every
|
|
matching source; publication stays one explicit entry per document.
|
|
|
|
## First-wave architecture collection
|
|
|
|
| Publication id | System slug | Owning repo | Source path |
|
|
| --- | --- | --- | --- |
|
|
| `coulomb-estate-architecture` | `coulomb-estate` | `the-custodian` | `canon/architecture/coulomb-estate_v0.1.md` |
|
|
| `railiance-architecture` | `railiance` | `railiance-master` | `docs/architecture/railiance_v0.1.md` |
|
|
| `net-kingdom-architecture` | `net-kingdom` | `net-kingdom` | `docs/architecture/net-kingdom_v0.1.md` |
|
|
| `state-hub-architecture` | `state-hub` | `state-hub` | `docs/architecture/state-hub_v0.1.md` |
|
|
| `policy-nexus-architecture` | `policy-nexus` | `policy-nexus` | `docs/architecture/policy-nexus_v0.1.md` |
|