policy-nexus/workplans/PNEX-WP-0002-arc42-architecture-collection.md

---
id: PNEX-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-31"
depends_on_workplans:
  - POLICY-NEXUS-WP-0001
state_hub_workstream_id: "06f11eab-d531-57f9-ba80-fc853cebc524"
---

# PNEX-WP-0002 — arc42 architecture collection

Renamed from `POLICY-NEXUS-WP-0002` on 2026-08-31. `PNEX-WP-` is the
repository-derived prefix adopted for active Policy Nexus work under
CUST-ADR-007; the deterministic workplan and task UUIDs were re-derived from
the new identifiers.

## 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: PNEX-WP-0002-T01
status: done
priority: high
state_hub_task_id: "43798974-65c1-56eb-95ff-fff5a968a8f2"
```

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: PNEX-WP-0002-T02
status: done
priority: high
state_hub_task_id: "137ca0cb-e5fe-5f27-b795-c27191bd97a9"
```

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.

Completed 2026-08-19. `markitect/schemas/arc42-schema-v1.0.md` and catalog
id `arc42-v1`. All five first-wave documents and the template validate.

### T03 — Infospace index

```task
id: PNEX-WP-0002-T03
status: done
priority: high
state_hub_task_id: "093c7d88-5f1d-5f1e-a1a0-f9cc7f2131bb"
```

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.

Completed 2026-08-19. Pointer infospace at
`the-custodian/canon/architecture/infospace/` — five system entities,
arc42 discipline, no copied document bodies. `markitect infospace check`
runs.

### T04 — First document: Coulomb estate

```task
id: PNEX-WP-0002-T04
status: done
priority: high
state_hub_task_id: "df471356-3629-526c-a358-7c5bd3c0b38f"
```

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

Completed 2026-08-18 in
`the-custodian/canon/architecture/coulomb-estate_v0.1.md`. Chapters 1, 3,
4, 5.1, 9 and 12 are real. Chapter 9 lists the estate ADRs and excludes
unresolved WP-0003 conflicts.

### T05 — Remaining first-wave stubs in owning repos

```task
id: PNEX-WP-0002-T05
status: done
priority: medium
state_hub_task_id: "079bd63c-c3b8-5c2c-bc87-bbc3a4315d79"
```

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
published at `/architecture/policy-nexus/v0.1/`.

Completed 2026-08-18. Stubs now exist in `railiance-master`,
`net-kingdom`, and `state-hub` (`docs/architecture/<system>_v0.1.md`)
with real chapters 1, 3 and 9. Estate map was T04. First wave is
open.

### T06 — Register and publish

```task
id: PNEX-WP-0002-T06
status: progress
priority: high
state_hub_task_id: "edc2edff-d954-5d08-8a8d-e7977abbc201"
```

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

2026-08-18: `docs/architecture/*.md` is a policy-nexus selector.
`policy-nexus-architecture` is published at
`/architecture/policy-nexus/v0.1/`. Estate map is published at
`/architecture/coulomb-estate/v0.1/`. First-wave stubs for Railiance,
NetKingdom and State Hub are published at
`/architecture/<system>/v0.1/`.

2026-08-31: the five-document registry and 162-source inventory are current,
and a clean-output build publishes all 60 registered documents. The retained
build history correctly refuses the next build because Railiance and State Hub
changed their `draft-2` architecture bodies without advancing the immutable
revision. The currency gate also reports CUST-ADR-001 overdue since 2026-08-28.
Owner handoffs are in `docs/adr-review/packets/`.

2026-08-31: owner corrections landed in `the-custodian@d3c6f13`,
`railiance-master@5ffd7d1`, `state-hub@da30ce6`,
`activity-core@b72fdb5`, and `net-kingdom@d4e57e6`. The retained-history build,
currency gate, and release verifier now pass for all 60 documents. Production
promotion remains before this task can close.

### T07 — Smoke the published collection

```task
id: PNEX-WP-0002-T07
status: todo
priority: medium
state_hub_task_id: "1a8feb5d-d6fb-5f3f-a780-30304776230a"
```

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.

2026-08-31 smoke: `https://policy.coulomb.social/` returns 200, but all five
first-wave `/architecture/<system>/v0.1/` URLs return 404. T07 remains open
until the source-owner revision fixes unblock a release and the paired-digest
promotion is performed.

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