coulomb/policy-nexus
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Start the arc42 contract and publish the first ADR set

Browse source 
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.
This commit is contained in:
tegwick 2026-08-18 22:16:02 +02:00
parent 7a24e9107f
commit a8fb62a3bc
34 changed files with 9669 additions and 28 deletions
Download patch file Download diff file Expand all files Collapse all files

42
docs/adr-review/SUMMARY.md Normal file
View file

@ -0,0 +1,42 @@
# ADR review ledger summary
Rows: 125
## Inventory dispositions
- `excluded`: 2
- `metadata-pending`: 105
- `published`: 10
- `unsupported-format`: 8
## Proposed dispositions
- `publish`: 9
- `unreviewed`: 116
## Front-matter `id` collisions
- `ADR-001`: coulomb-loop/docs/adr/ADR-001-workplan-prefix.md, kaizen-agentic/docs/adr/ADR-001-workplan-convention.md, rein-aharness/docs/adr/ADR-001-agent-harness-architecture.md, the-custodian/canon/architecture/adr-001-workplans-as-repo-artefacts.md
- `ADR-002`: coulomb-loop/docs/adr/ADR-002-customer-supplier-boundary.md, kaizen-agentic/docs/adr/ADR-002-project-memory-convention.md, the-custodian/canon/architecture/adr-002-custodian-agent-runtime-design.md
- `ADR-003`: coulomb-loop/docs/adr/ADR-003-cadence-ramp-policy.md, kaizen-agentic/docs/adr/ADR-003-protocols-artifact-convention.md, the-custodian/canon/architecture/adr-003-materialized-derived-state.md
- `ADR-004`: coulomb-loop/docs/adr/ADR-004-repo-rotation-on-diminishing-returns.md, kaizen-agentic/docs/adr/ADR-004-project-metrics-convention.md, the-custodian/canon/architecture/adr-004-connectivity-first-network-posture.md
- `ADR-0001`: coulomb-social/docs/adr/ADR-0001-netkingdom-identity.md, key-cape/docs/adr/ADR-0001-choose-go-for-keycape.md, target-revenue/docs/adr/ADR-0001-stage0-library-stack.md
- `ADR-005`: kaizen-agentic/docs/adr/ADR-005-scheduled-agent-execution.md, the-custodian/canon/architecture/adr-005-cross-repo-workplans-project-repos.md
- `netkingdom-iam-profile`: net-kingdom/canon/standards/iam-profile_v0.2.md, net-kingdom/canon/standards/iam-profile_v0.3.md
## Bare ADR-NNNN collisions
- `ADR-0001`: activity-core/docs/adr/adr-001-event-bridge-architecture.md, coulomb-loop/docs/adr/ADR-001-workplan-prefix.md, coulomb-social/docs/adr/ADR-0001-netkingdom-identity.md, evidence-binder/docs/adr/ADR-0001-reference-ui-surface.md, glas-harness/docs/adr/ADR-001-rein-harness-family.md, kaizen-agentic/docs/adr/ADR-001-workplan-convention.md, key-cape/docs/adr/ADR-0001-choose-go-for-keycape.md, markitect-main/docs/adr/ADR-001-client-side-debug-storage.md, policy-nexus/docs/adr/ADR-0001-addressing-and-permanence.md, railiance-master/docs/adr/ADR-0001-repository-prefix-architecture.md, railiance-platform/docs/adr/ADR-0001-s3-platform-service-boundary.md, rapp-postgres/docs/adr/ADR-0001-consumer-boundary-and-tenant-isolation.md, rein-aharness/docs/adr/ADR-001-agent-harness-architecture.md, target-revenue/docs/adr/ADR-0001-stage0-library-stack.md, the-custodian/canon/architecture/adr-001-workplans-as-repo-artefacts.md
- `ADR-0002`: activity-core/docs/adr/adr-002-definition-format.md, coulomb-loop/docs/adr/ADR-002-customer-supplier-boundary.md, coulomb-social/docs/adr/ADR-0002-space-content-forgejo-markdown.md, glas-harness/docs/adr/ADR-002-credential-brokering-and-composable-reins.md, kaizen-agentic/docs/adr/ADR-002-project-memory-convention.md, markitect-main/docs/adr/ADR-002-robustness-principle-for-production-use.md, railiance-hosts/docs/adr/ADR-002-repo-boundary-hosts-vs-bootstrap.md, railiance-infra/docs/adr/ADR-002-repo-boundary-hosts-vs-bootstrap.md, railiance-master/docs/adr/ADR-0002-rail-kubernetes-wave-1-boundary.md, railiance-platform/docs/adr/ADR-0002-placement-policy-ownership.md, rapp-postgres/docs/adr/ADR-0002-data-retention-and-erasure.md, target-revenue/docs/adr/ADR-0002-hosted-trust-service-stack.md, the-custodian/canon/architecture/adr-002-custodian-agent-runtime-design.md
- `ADR-0003`: activity-core/docs/adr/adr-003-rule-instruction-model.md, coulomb-loop/docs/adr/ADR-003-cadence-ramp-policy.md, coulomb-social/docs/adr/ADR-0003-page-centric-markdown-sor.md, glas-harness/docs/adr/ADR-003-scheduling-and-blueprint-sourcing-stay-rein-local.md, kaizen-agentic/docs/adr/ADR-003-protocols-artifact-convention.md, railiance-hosts/docs/adr/ADR-003-railiance-5repo-stack-architecture.md, railiance-infra/docs/adr/ADR-003-railiance-5repo-stack-architecture.md, railiance-master/docs/adr/ADR-0003-rapp-first-wave-selection.md, railiance-platform/docs/adr/ADR-0003-decisions-live-in-the-repo.md, rapp-postgres/docs/adr/ADR-0003-e3-row-level-security-contract.md, the-custodian/canon/architecture/adr-003-materialized-derived-state.md
- `ADR-0004`: activity-core/docs/adr/adr-004-producer-trust-boundary.md, coulomb-loop/docs/adr/ADR-004-repo-rotation-on-diminishing-returns.md, coulomb-social/docs/adr/ADR-0004-content-plane-thin-git-upgrades.md, glas-harness/docs/adr/ADR-004-composable-reins-stay-deferred.md, kaizen-agentic/docs/adr/ADR-004-project-metrics-convention.md, railiance-hosts/docs/adr/ADR-004-forgejo-in-cluster-actions-runner.md, railiance-infra/docs/adr/ADR-004-forgejo-in-cluster-actions-runner.md, railiance-master/docs/adr/ADR-0004-first-wave-reef-rollout.md, rapp-postgres/docs/adr/ADR-0004-platform-pg-cell-ceiling.md, the-custodian/canon/architecture/adr-004-connectivity-first-network-posture.md
- `ADR-0005`: activity-core/docs/adr/adr-005-ops-runs-vs-dev-work-records.md, kaizen-agentic/docs/adr/ADR-005-scheduled-agent-execution.md, railiance-infra/docs/adr/ADR-005-k3s-api-tunnel-only.md, railiance-master/docs/adr/ADR-0005-derived-rail-composition.md, the-custodian/canon/architecture/adr-005-cross-repo-workplans-project-repos.md
- `ADR-0006`: kaizen-agentic/docs/adr/ADR-006-customer-engagement-convention.md, net-kingdom/docs/adr/ADR-0006-recursive-multi-tenant-identity-authorization.md, railiance-master/docs/adr/ADR-0006-reef-production-admission.md, the-custodian/canon/architecture/adr-006-canon-federation-concept-ownership.md
- `ADR-0007`: kaizen-agentic/docs/adr/ADR-007-forward-deployed-engagement-convention.md, net-kingdom/docs/adr/ADR-0007-security-orchestration-boundary.md, railiance-master/docs/adr/ADR-0007-rapp-declaration-contract.md, the-custodian/canon/architecture/adr-007-workplan-identity-and-repo-worker-topology.md
- `ADR-0008`: net-kingdom/docs/adr/ADR-0008-object-storage-sts-credential-vending.md, railiance-master/docs/adr/ADR-0008-private-by-default-exposure.md, the-custodian/canon/architecture/adr-008-multi-tenancy-model.md
- `ADR-0010`: net-kingdom/docs/adr/ADR-0010-orchestration-vs-dependency-self-coherent-intent.md, the-custodian/canon/architecture/adr-010-hub-authority-and-local-cache-model.md
- `ADR-0011`: net-kingdom/docs/adr/ADR-0011-iam-profile-ownership-and-version-governance.md, the-custodian/canon/architecture/adr-011-federated-namespaces-and-reconciliation-limits.md
## Missing files
None.

4742
docs/adr-review/ledger.json Normal file
View file

File diff suppressed because it is too large Load diff

83
docs/adr-review/protocol.md Normal file
View file

@ -0,0 +1,83 @@
# ADR review protocol
Working protocol for POLICY-NEXUS-WP-0003. The ledger in this directory
is a work artefact. It is not published on `policy.coulomb.social`.
Input is `source-inventory.json` only. Do not rediscover by glob.
Refresh the ledger with:
```sh
python3 tools/adr_review_ledger.py
```
## Authority
- The **owning repo** decides whether an ADR still governs and writes
the cleanup.
- **the-custodian** decides estate-level canon.
- **This repo** records the review and publishes. It does not edit
another repo's ADR body.
## Review dispositions
Every inventoried source that is not already `published` gets exactly
one proposed disposition. `unreviewed` means T02 has mapped the file
and T03/T04 have not yet ruled.
| Disposition | Meaning | Publication |
| --- | --- | --- |
| `unreviewed` | Facts recorded; relevance not ruled. | no |
| `publish` | Still governs. Front-matter complete. | `publication.json` entry |
| `superseded` | Replaced. Point at the successor. | only if a public URL exists or the successor needs the pointer live |
| `withdrawn` | No longer governs, no successor. | same as superseded |
| `local` | Useful in its repo, not governing for anyone else. | inventory `excluded` |
| `conflict` | Contradicts another ADR or the estate arc42; owner has not ruled. | no |
## Conflict kinds
1. **Identifier collision** — same publication `id`, or the same bare
`ADR-NNNN` in two repos. Publication ids must be globally unique.
2. **Status lie** — body says superseded/relocated, front-matter still
`accepted` (or the reverse).
3. **Missing successor** — status `superseded` with no target.
4. **Contradicting decisions** — two accepted ADRs that cannot both be
true.
5. **Architecture miss** — an accepted ADR that the matching first-wave
arc42 does not mention in chapter 9. Waits on WP-0002-T04/T05.
6. **Duplicate claim** — two documents claiming to be the current
decision on the same question.
## Ledger row
`ledger.json` holds one object per inventory source.
| Field | Set by | Meaning |
| --- | --- | --- |
| `source_repo`, `source_path` | inventory | Identity |
| `inventory_disposition`, `inventory_reason` | inventory | Current source-inventory state |
| `file_present` | T02 | Source file readable in the sibling checkout |
| `frontmatter` | T02 | Parsed fields used by the builder |
| `missing_fields` | T02 | Publication-contract gaps |
| `bare_adr` | T02 | `ADR-NNNN` extracted from id or filename, if any |
| `id_collisions` | T02 | Other sources sharing the same front-matter `id` |
| `bare_adr_collisions` | T02 | Other sources sharing the same bare `ADR-NNNN` |
| `notes` | T02 | Known specials |
| `proposed_disposition` | T03/T04 | Review ruling; `unreviewed` until then |
| `conflict_kinds` | T03 | List of kind numbers, or empty |
| `successor` | T03/T04 | Target when superseded |
| `review_notes` | T03/T04 | One-sentence contradiction or rationale |
T02 fills facts and leaves `proposed_disposition` as `unreviewed`
except for the first publish set named in WP-0003 (this repo's
ADR-0001 and the eight railiance-master ADRs), which start as
`publish` because they are already relevance-obvious.
## First publish set
- `policy-nexus` `docs/adr/ADR-0001-addressing-and-permanence.md`
- `railiance-master` `docs/adr/ADR-0001` through `ADR-0008`
Known duplicate-claim candidate: custodian
`canon/architecture/adr-008-multi-tenancy-model.md` vs published
Tenancy Posture.

14
docs/adr/ADR-0001-addressing-and-permanence.md
View file

@ -1,3 +1,13 @@
---
id: policy-nexus-adr-0001
title: "Policy addressing and permanence"
status: accepted
owner: the-custodian
revision: "accepted-1"
last_reviewed: "2026-08-18"
review_interval: 6m
---
# ADR-0001 — policy addressing and permanence
- Status: accepted
@ -13,6 +23,10 @@ A document has one stable current address and immutable revision addresses:
/<kind>/<document>/<version>/revisions/<revision>/
```
`<kind>` is one of `standards`, `architecture`, `constitution`, or `adr`.
`<document>` is a kebab-case slug that is unique on the site. The owner-facing
rules live in `docs/publication-contract.md`.
The publication manifest records both. Existing public paths become permanent
redirect aliases; the first is `/tenancy-posture.html`. No URL is derived from
a checkout path, branch name, build number or hosting implementation.

161
docs/architecture/policy-nexus_v0.1.md Normal file
View file

@ -0,0 +1,161 @@
---
id: policy-nexus-architecture
title: "Policy Nexus architecture"
status: proposed
owner: the-custodian
revision: "draft-1"
version: "0.1"
last_reviewed: "2026-08-18"
review_interval: 6m
---
# Policy Nexus — Software Architecture Documentation (arc42)
## About this document
This document follows the **arc42** template for the publication surface
at `policy.coulomb.social`. It is the first-wave architecture document
this repository is allowed to author. Other first-wave systems are
written in their owning repos.
---
## 1. Introduction and Goals
Policy Nexus exists so estate canon and architecture decisions have a
permanent, current, addressable public home. Before this system,
governing documents were served from disposable artifact URLs.
### 1.1 Requirements Overview
- Publish canon (`standards`, `architecture`, `constitution`) and
per-repo ADRs from the repositories that own them.
- Keep one stable current URL and one immutable revision URL per
document (ADR-0001).
- Fail closed when a source disappears or an immutable revision would
change.
- Show status, owner, revision, and review currency on every page.
### 1.2 Quality Goals
1. Permanence of published addresses.
2. Honesty about staleness.
3. Source-of-truth stays upstream — this system never writes back.
4. Builds are deterministic and stdlib-only.
### 1.3 Stakeholders
| Role | Concern |
| --- | --- |
| the-custodian | What counts as canon; ratification. |
| Source-repo owners | Their document is published accurately. |
| railiance-platform / rapp-policy-nexus | Substrate, Helm, promotion. |
| Readers inside and outside the estate | A URL that still resolves. |
---
## 2. Architecture Constraints
N/A for this stub — first-wave complete will record stdlib-only
rendering, single-node rail availability, and the no-CMS rule.
---
## 3. System Scope and Context
**In:** addressing, rendering, currency, the public static site.
**Out:** ratification, legal advice, regulatory intake (`risk-nexus`),
editing surfaces, search.
### 3.1 Business Context
Source owners publish governing documents. This system makes those
documents findable and durable. It does not decide what is current
canon.
### 3.2 Technical Context
- Inputs: `publication.json`, sibling or fetched git checkouts,
`source-inventory.json`.
- Outputs: static HTML, `publication-manifest.json`, an OCI image.
- Neighbours: owning source repos, Forgejo Actions, `rapp-policy-nexus`,
`railiance-apps`, the reef Traefik/cert-manager substrate.
---
## 4. Solution Strategy
N/A for this stub — pull-on-schedule ingestion, explicit manifest
entries, stdlib renderer. To be written as first-wave complete.
---
## 5. Building Block View
### 5.1 Level 1 – System/Top-Level
N/A for this stub — builder, inventory auditor, currency checker,
OCI artifact, Helm package in `rapp-policy-nexus`.
### 5.2 Level 2 – Key Components
N/A for this stub.
### 5.3 Level 3 – Internal Structure (as needed)
N/A for this stub.
---
## 6. Runtime View
N/A — the published site is static files. Daily source-pull and
promotion are operational scenarios for a later revision.
---
## 7. Deployment View
N/A for this stub — see WP-0001-T04. Single-node restart recovery, not
a high-availability SLA.
---
## 8. Cross-Cutting Concepts
N/A for this stub.
---
## 9. Architecture Decisions
| Id | Status | Decision | Source |
| --- | --- | --- | --- |
| `policy-nexus-adr-0001` | accepted | Stable current address + immutable revision address; no deletion | `docs/adr/ADR-0001-addressing-and-permanence.md` |
Later `publish` ADRs from WP-0003 land here. `local` and unresolved
`conflict` rows do not.
---
## 10. Quality Requirements
N/A for this stub — currency failure is already a build/CI failure.
---
## 11. Risks and Technical Debt
N/A for this stub. Known residual: Markitect `arc42-v1` schema is not
registered yet (WP-0002-T02).
---
## 12. Glossary
| Term | Meaning |
| --- | --- |
| Current address | The stable URL for the document as it now stands. |
| Revision address | Write-once URL for one source digest. |
| Publication entry | One object in `publication.json`. Discovery is not publication. |
| First-wave complete | Chapters 1, 3, 4, 5.1, 9 and 12 are real; others real or N/A. |

130
docs/publication-contract.md Normal file
View file

@ -0,0 +1,130 @@
# 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` |