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

id	type	title	domain	repo	status	owner	topic_slug	created	updated	depends_on_workplans
POLICY-NEXUS-WP-0002	workplan	Publish an arc42 architecture collection from owning repos	infotech	policy-nexus	active	the-custodian	policy-nexus	2026-08-18	2026-08-18	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:

/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

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

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

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

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

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

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

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.