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.
300 lines
12 KiB
Markdown
300 lines
12 KiB
Markdown
---
|
||
id: POLICY-NEXUS-WP-0002
|
||
type: workplan
|
||
title: "Publish an arc42 architecture collection from owning repos"
|
||
domain: infotech
|
||
repo: policy-nexus
|
||
status: active
|
||
owner: the-custodian
|
||
topic_slug: policy-nexus
|
||
created: "2026-08-18"
|
||
updated: "2026-08-18"
|
||
depends_on_workplans:
|
||
- POLICY-NEXUS-WP-0001
|
||
---
|
||
|
||
# POLICY-NEXUS-WP-0002 — arc42 architecture collection
|
||
|
||
## Goal
|
||
|
||
Give the estate a countable set of **arc42 architecture documents** — one
|
||
document per system — authored where the system is owned, checked by the
|
||
markdown tooling we already have, retrievable as an infospace, and published
|
||
at permanent addresses on `policy.coulomb.social`.
|
||
|
||
Done means: a reader can open the estate map and the first-wave system
|
||
documents, see which ADRs belong to each, tell whether a document is current,
|
||
and validate a new architecture page the same way as the existing ones.
|
||
|
||
## Why this workplan exists
|
||
|
||
WP-0001 made the publication surface. The inventory behind it is almost all
|
||
**decisions** (ADRs) and almost no **architecture**. A decision log without a
|
||
system description is a pile of answers with no question. The ADRs that
|
||
WP-0003 will keep need something to be consistent *with*.
|
||
|
||
The tooling is already here. Do not start a new documentation stack.
|
||
|
||
- `markitect-main/examples/templates/TEMPLATE-ARC42.md` is a complete 12-chapter
|
||
arc42 template plus a quality checklist.
|
||
- `markitect validate` already checks a markdown file against a schema.
|
||
- `markitect infospace` already init/check/entities/graph an infospace.
|
||
- `info-tech-canon` owns the *information-space model*, not estate
|
||
architecture (ADR-006).
|
||
- `the-custodian/canon/architecture/` currently holds estate ADRs only.
|
||
|
||
The `arc42-v1` entry in Markitect's schema catalog is still a comment. That
|
||
is a handoff to `markitect-main`, not a reason to invent another format.
|
||
|
||
## The collection (first wave)
|
||
|
||
One markdown document per system, not twelve files per system. Chapter 9 is
|
||
the ADR index for that system; the ADRs themselves stay in `docs/adr/` and
|
||
are published separately.
|
||
|
||
| id | System | Owning repo | Path | Why first |
|
||
| --- | --- | --- | --- | --- |
|
||
| `coulomb-estate-architecture` | Coulomb estate | `the-custodian` | `canon/architecture/coulomb-estate_v0.1.md` | The map. Canons, hubs, rails, publication. Chapter 9 indexes custodian ADR-001–011. |
|
||
| `railiance-architecture` | Railiance | `railiance-master` | `docs/architecture/railiance_v0.1.md` | Runtime substrate. Eight ADRs there already have publication-grade front-matter. |
|
||
| `net-kingdom-architecture` | NetKingdom | `net-kingdom` | `docs/architecture/net-kingdom_v0.1.md` | Identity and tenancy. Tenancy Posture is already published; this is the system around it. |
|
||
| `state-hub-architecture` | State Hub | `state-hub` | `docs/architecture/state-hub_v0.1.md` | Coordination read-model. ADR-001 lives here in spirit. |
|
||
| `policy-nexus-architecture` | Policy Nexus | `policy-nexus` | `docs/architecture/policy-nexus_v0.1.md` | This surface. The only first-wave document this repo may author. |
|
||
|
||
Later systems (Markitect, activity-core, flex-auth, artifact-store) join the
|
||
same way: owning repo writes the document, this repo adds a manifest entry.
|
||
They are out of this workplan.
|
||
|
||
## Tooling split (resolved)
|
||
|
||
Use **both**, with a hard split. "Markdown tooling or infospace" is not a
|
||
choice between two products; they already compose.
|
||
|
||
| Concern | Tool | What it does |
|
||
| --- | --- | --- |
|
||
| Shape and compliance | Markitect `TEMPLATE-ARC42.md` + `arc42-v1` schema | A document is valid arc42 or it is not. `markitect validate` is the gate. |
|
||
| Retrieval of the collection | An infospace index | `infospace.yaml` binds the five documents as entities so an agent can list systems, open a chapter, and follow relations. |
|
||
| Publication | This repo | `publication.json` entries under `architecture/<system>/v0.1/`. |
|
||
|
||
The infospace index lives in `the-custodian/canon/architecture/infospace/`
|
||
because the-custodian owns estate architecture. It **points at** the owning
|
||
repos; it does not copy them. InfoTechCanon is not the host — it owns the
|
||
model (`ITC-INFOSPACE`), not this estate's building-block view.
|
||
|
||
This repo still does not write other repos. Content PRs land in the owning
|
||
repo. This workplan coordinates and then publishes.
|
||
|
||
## Addressing
|
||
|
||
Follow ADR-0001:
|
||
|
||
```text
|
||
/architecture/<system>/v0.1/
|
||
/architecture/<system>/v0.1/revisions/<revision>/
|
||
```
|
||
|
||
`<system>` is the kebab slug from the table (`coulomb-estate`, `railiance`,
|
||
`net-kingdom`, `state-hub`, `policy-nexus`). A new major version is a new
|
||
document id and a new current address; the old current address becomes a
|
||
superseded banner, not a delete.
|
||
|
||
Required publication front-matter is the same contract as for ADRs: `id`,
|
||
`title`, `status`, `owner`, `revision` or `version`, `last_reviewed` or
|
||
`updated`, and `review_interval`.
|
||
|
||
## Non-goals
|
||
|
||
- No CMS, no generated-from-code architecture that diverges from the source
|
||
markdown.
|
||
- No twelve-file-per-system split in this workplan. If a chapter later needs
|
||
its own page, that is a new addressing decision.
|
||
- No attempt to finish every chapter to production depth. A first-wave
|
||
document is useful when chapters 1, 3, 4, 5.1, 9 and 12 are real, and
|
||
every other chapter is either real or explicitly `N/A` with a reason.
|
||
- No rewrite of InfoTechCanon's landscape model into arc42. Landscape
|
||
concepts stay in `info-tech-canon`; these documents describe *our*
|
||
systems.
|
||
|
||
## Tasks
|
||
|
||
### T01 — Collection contract
|
||
|
||
```task
|
||
id: POLICY-NEXUS-WP-0002-T01
|
||
status: done
|
||
priority: high
|
||
```
|
||
|
||
Write the contract this workplan just stated so a source owner can comply
|
||
without reading the builder.
|
||
|
||
- Address shape, id scheme, front-matter fields, review interval default
|
||
(`6m` unless the owner declares otherwise).
|
||
- One document per system; chapter 9 lists ADRs, it does not inline them.
|
||
- Infospace index location and the rule that it references, never copies.
|
||
- What "first-wave complete" means (chapters 1, 3, 4, 5.1, 9, 12 real;
|
||
others real or N/A).
|
||
|
||
**Output:** a short owner-facing note in this repo (publication contract,
|
||
not a second architecture). Fold the addressing into ADR-0001 only if the
|
||
`architecture` kind needs an amendment; otherwise keep it here.
|
||
|
||
**Why first:** WP-0003's relevance and conflict checks need to know what an
|
||
architecture document is.
|
||
|
||
Completed 2026-08-18 in `docs/publication-contract.md`. ADR-0001 now names
|
||
the four kinds (`standards`, `architecture`, `constitution`, `adr`). The
|
||
policy-nexus first-wave stub is at `docs/architecture/policy-nexus_v0.1.md`
|
||
and is not published until the architecture selector and inventory catch up.
|
||
|
||
### T02 — Markitect arc42 schema handoff
|
||
|
||
```task
|
||
id: POLICY-NEXUS-WP-0002-T02
|
||
status: todo
|
||
priority: high
|
||
```
|
||
|
||
Make `markitect validate doc.md --schema arc42-v1` work against
|
||
`TEMPLATE-ARC42.md`.
|
||
|
||
- Promote the commented `arc42-v1` catalog entry in
|
||
`markitect-main/markitect/schemas/schema-catalog.yaml`.
|
||
- Derive the schema from the existing template (12 required chapters;
|
||
checklist chapter 13 recommended).
|
||
- Record the command a source owner runs before asking this repo to
|
||
publish.
|
||
|
||
Implementation lands in `markitect-main`. If that is more than a small PR,
|
||
spawn a Markitect workplan and depend on it. Do not reimplement validation
|
||
here.
|
||
|
||
### T03 — Infospace index
|
||
|
||
```task
|
||
id: POLICY-NEXUS-WP-0002-T03
|
||
status: todo
|
||
priority: high
|
||
```
|
||
|
||
Stand up `the-custodian/canon/architecture/infospace/` with `infospace.yaml`
|
||
that binds the first-wave documents as the topic "Coulomb estate
|
||
architecture", using arc42 as the discipline.
|
||
|
||
- `markitect infospace init` then `check` must pass once at least the
|
||
estate document exists.
|
||
- Entities are systems (and, if cheap, chapters). Relations are
|
||
`described-by` / `decided-in` toward published ADRs, not a second copy
|
||
of ADR text.
|
||
- This repo adds the infospace only as a *source to publish* if the
|
||
custodian owner marks the index itself as governing. The five system
|
||
documents are the publication corpus; the index is navigation.
|
||
|
||
Depends on T01. Can start as soon as the estate document path is fixed,
|
||
even as a stub.
|
||
|
||
### T04 — First document: Coulomb estate
|
||
|
||
```task
|
||
id: POLICY-NEXUS-WP-0002-T04
|
||
status: todo
|
||
priority: high
|
||
```
|
||
|
||
Author `the-custodian/canon/architecture/coulomb-estate_v0.1.md` in
|
||
the-custodian.
|
||
|
||
Chapters 1, 3, 4, 5.1, 9 and 12 must be real. Chapter 9 lists the estate
|
||
ADRs already in `canon/architecture/` with status and a pointer, not a
|
||
paste. Remaining chapters are real or N/A with a reason. Front-matter must
|
||
satisfy T01 so this repo can publish it.
|
||
|
||
This is the document WP-0003 checks other ADRs against when the conflict
|
||
is "this decision does not fit the estate".
|
||
|
||
### T05 — Remaining first-wave stubs in owning repos
|
||
|
||
```task
|
||
id: POLICY-NEXUS-WP-0002-T05
|
||
status: progress
|
||
priority: medium
|
||
```
|
||
|
||
Open the four remaining documents in their owning repos, each valid against
|
||
`arc42-v1` and carrying publication front-matter.
|
||
|
||
A stub that has a real chapter 1 (why the system exists), chapter 3 (scope
|
||
and neighbours), and chapter 9 (ADR index, even if short) is enough to
|
||
publish. Deeper chapters are the owning repo's follow-on, not a gate here.
|
||
|
||
This repo authors only `docs/architecture/policy-nexus_v0.1.md`.
|
||
|
||
2026-08-18: policy-nexus stub exists with real chapters 1, 3 and 9. It is
|
||
not in `publication.json` yet — inventory selectors do not include
|
||
`docs/architecture/` until this file is on `HEAD` and T06 reviews it.
|
||
The other four documents remain owning-repo work.
|
||
|
||
### T06 — Register and publish
|
||
|
||
```task
|
||
id: POLICY-NEXUS-WP-0002-T06
|
||
status: todo
|
||
priority: high
|
||
```
|
||
|
||
- Extend `source-inventory.config.json` selectors so
|
||
`canon/architecture/*.md` and `docs/architecture/*.md` in the first-wave
|
||
repos are inventoried (ADRs stay on their existing selectors).
|
||
- Add explicit `publication.json` entries for every first-wave document
|
||
that meets T01.
|
||
- Add the owning repos to `publication.json` `repositories` as needed.
|
||
- Refresh `source-inventory.json` dispositions.
|
||
- `make check` and `make build` pass; currency is declared.
|
||
|
||
Do not glob the new trees into publication. Inventory is discovered;
|
||
publication stays explicit.
|
||
|
||
### T07 — Smoke the published collection
|
||
|
||
```task
|
||
id: POLICY-NEXUS-WP-0002-T07
|
||
status: todo
|
||
priority: medium
|
||
```
|
||
|
||
After promotion (same paired digest review as WP-0001): the index lists
|
||
every first-wave architecture document; each current URL resolves; each
|
||
revision URL is write-once; a `markitect validate` failure in a source repo
|
||
is visible as a missing or stale publication, not as a silently old page.
|
||
|
||
## Sequencing
|
||
|
||
T01 gates everything. T02 and T04 can proceed in parallel once T01 is
|
||
written. T03 needs T01 and becomes useful once T04 exists. T05 can proceed
|
||
per repo as soon as T02 has a schema to validate against. T06 needs at
|
||
least T04 (estate document) to be worth running; it may publish the others
|
||
as they land. T07 is last.
|
||
|
||
WP-0003 may start its corpus inventory immediately. Its conflict-against-
|
||
architecture pass waits on T04. Linking published ADRs into chapter 9 waits
|
||
on T05/T06.
|
||
|
||
## Risks
|
||
|
||
**This repo authors the estate.** Mitigation: only `policy-nexus`'s own
|
||
arc42 is written here. Everything else is a PR in the owning repo.
|
||
|
||
**The infospace becomes a second copy.** Mitigation: the index stores
|
||
references and slugs, not document bodies.
|
||
|
||
**arc42 becomes a novel.** Mitigation: first-wave complete is six real
|
||
chapters, not twelve essays.
|
||
|
||
**Schema work stalls in markitect.** Mitigation: T04 can be authored
|
||
against the template before `arc42-v1` is registered; T06 will not publish
|
||
a document that cannot be validated once T02 is done.
|
||
|
||
## Residuals
|
||
|
||
- Later-wave systems get their own owning-repo work, then a publication
|
||
entry here. Not a third policy-nexus workplan until there is a batch.
|
||
- WP-0003 owns ADR cleanup and ADR publication.
|