policy-nexus/docs/publication-contract.md

# 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 PNEX-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` |
| `findings` | A finding explicitly marked public by `risk-nexus` | `findings/RISK-F-NNNN-<slug>.md` |
| `methods` | A public risk judgement instrument | `docs/method/<name>.md` |

Risk findings and methods are published only after `risk-nexus` has made the
disclosure decision and an explicit `publication.json` entry names the file.
Embargoed or restricted findings fail that admission test. Workplans, evidence,
runbooks, review ledgers, rulings, 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 | adopted | fixed | 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 six 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/
/findings/flex-auth-unauthenticated-check/v1/
/methods/risk-severity/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:

```sh
markitect validate docs/architecture/<system>_v0.1.md \
  --schema /path/to/markitect-main/markitect/schemas/arc42-schema-v1.0.md
```

Catalog id: `arc42-v1`.

## 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.

```sh
markitect infospace check --config \
  the-custodian/canon/architecture/infospace/infospace.yaml
```

## 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` |