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

fix(workplans): adopt PNEX workplan identities

Browse source 
Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a058f3-8ba0-7692-a042-9a870fc3d663
This commit is contained in:
tegwick 2026-08-31 21:34:20 +02:00
parent 6515ed9ef8
commit 023badb512
6 changed files with 783 additions and 31 deletions
Download patch file Download diff file Expand all files Collapse all files

14
.custodian-brief.md
View file

@ -2,24 +2,24 @@
# Custodian Brief — policy-nexus # Custodian Brief — policy-nexus
**Domain:** infotech **Domain:** infotech
**Last synced:** 2026-08-25 17:56 UTC **Last synced:** 2026-08-31 18:30 UTC
**State Hub:** http://127.0.0.1:8000 *(adjust if running on a remote machine)* **State Hub:** http://127.0.0.1:8000 *(adjust if running on a remote machine)*
## Active Workstreams ## Active Workstreams
### Publish an arc42 architecture collection from owning repos ### Publish an arc42 architecture collection from owning repos
Progress: 5/7 done | workplan_id: `cf780ff6-ccc1-58e5-aace-665ff9234f5c` Progress: 5/7 done | workplan_id: `06f11eab-d531-57f9-ba80-fc853cebc524`
**Open tasks:** **Open tasks:**
- ► T06 — Register and publish `f4761eb6` - ► T06 — Register and publish `edc2edff`
- · T07 — Smoke the published collection `4a07237f` - · T07 — Smoke the published collection `1a8feb5d`
### Review ADRs for conflict, keep what governs, publish the rest properly ### Review ADRs for conflict, keep what governs, publish the rest properly
Progress: 5/7 done | workplan_id: `d1cfae73-460d-59f7-88c3-b251e563fb05` Progress: 5/7 done | workplan_id: `d80b73a4-db3d-565d-9c51-c3e12c93e610`
**Open tasks:** **Open tasks:**
- ► T06 — Register the ready set `a06165fe` - ► T06 — Register the ready set `1960ca1d`
- ► T07 — Point the architecture documents at what remains `f752e1f3` - ► T07 — Point the architecture documents at what remains `244fcd0a`
--- ---
## MCP Orientation (when available) ## MCP Orientation (when available)

32
WORK-RECORDS.md
View file

@ -8,26 +8,26 @@
| Kind | ID | Status | Lane | Source | | Kind | ID | Status | Lane | Source |
| --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- |
| workplan | PNEX-WP-0002 | active | — | workplans/PNEX-WP-0002-arc42-architecture-collection.md |
| workplan | PNEX-WP-0003 | active | — | workplans/PNEX-WP-0003-adr-review-cleanup-publish.md |
| workplan | POLICY-NEXUS-WP-0001 | finished | — | workplans/POLICY-NEXUS-WP-0001-permanent-publication-surface.md | | workplan | POLICY-NEXUS-WP-0001 | finished | — | workplans/POLICY-NEXUS-WP-0001-permanent-publication-surface.md |
| workplan | POLICY-NEXUS-WP-0002 | active | — | workplans/POLICY-NEXUS-WP-0002-arc42-architecture-collection.md | | task | PNEX-WP-0002-T01 | done | — | workplans/PNEX-WP-0002-arc42-architecture-collection.md |
| workplan | POLICY-NEXUS-WP-0003 | active | — | workplans/POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md | | task | PNEX-WP-0002-T02 | done | — | workplans/PNEX-WP-0002-arc42-architecture-collection.md |
| task | PNEX-WP-0002-T03 | done | — | workplans/PNEX-WP-0002-arc42-architecture-collection.md |
| task | PNEX-WP-0002-T04 | done | — | workplans/PNEX-WP-0002-arc42-architecture-collection.md |
| task | PNEX-WP-0002-T05 | done | — | workplans/PNEX-WP-0002-arc42-architecture-collection.md |
| task | PNEX-WP-0002-T06 | progress | — | workplans/PNEX-WP-0002-arc42-architecture-collection.md |
| task | PNEX-WP-0002-T07 | todo | — | workplans/PNEX-WP-0002-arc42-architecture-collection.md |
| task | PNEX-WP-0003-T01 | done | — | workplans/PNEX-WP-0003-adr-review-cleanup-publish.md |
| task | PNEX-WP-0003-T02 | done | — | workplans/PNEX-WP-0003-adr-review-cleanup-publish.md |
| task | PNEX-WP-0003-T03 | done | — | workplans/PNEX-WP-0003-adr-review-cleanup-publish.md |
| task | PNEX-WP-0003-T04 | done | — | workplans/PNEX-WP-0003-adr-review-cleanup-publish.md |
| task | PNEX-WP-0003-T05 | done | — | workplans/PNEX-WP-0003-adr-review-cleanup-publish.md |
| task | PNEX-WP-0003-T06 | progress | — | workplans/PNEX-WP-0003-adr-review-cleanup-publish.md |
| task | PNEX-WP-0003-T07 | progress | — | workplans/PNEX-WP-0003-adr-review-cleanup-publish.md |
| task | POLICY-NEXUS-WP-0001-T01 | done | — | workplans/POLICY-NEXUS-WP-0001-permanent-publication-surface.md | | task | POLICY-NEXUS-WP-0001-T01 | done | — | workplans/POLICY-NEXUS-WP-0001-permanent-publication-surface.md |
| task | POLICY-NEXUS-WP-0001-T02 | done | — | workplans/POLICY-NEXUS-WP-0001-permanent-publication-surface.md | | task | POLICY-NEXUS-WP-0001-T02 | done | — | workplans/POLICY-NEXUS-WP-0001-permanent-publication-surface.md |
| task | POLICY-NEXUS-WP-0001-T03 | done | — | workplans/POLICY-NEXUS-WP-0001-permanent-publication-surface.md | | task | POLICY-NEXUS-WP-0001-T03 | done | — | workplans/POLICY-NEXUS-WP-0001-permanent-publication-surface.md |
| task | POLICY-NEXUS-WP-0001-T04 | done | — | workplans/POLICY-NEXUS-WP-0001-permanent-publication-surface.md | | task | POLICY-NEXUS-WP-0001-T04 | done | — | workplans/POLICY-NEXUS-WP-0001-permanent-publication-surface.md |
| task | POLICY-NEXUS-WP-0001-T05 | done | — | workplans/POLICY-NEXUS-WP-0001-permanent-publication-surface.md | | task | POLICY-NEXUS-WP-0001-T05 | done | — | workplans/POLICY-NEXUS-WP-0001-permanent-publication-surface.md |
| task | POLICY-NEXUS-WP-0001-T06 | done | — | workplans/POLICY-NEXUS-WP-0001-permanent-publication-surface.md | | task | POLICY-NEXUS-WP-0001-T06 | done | — | workplans/POLICY-NEXUS-WP-0001-permanent-publication-surface.md |
| task | POLICY-NEXUS-WP-0002-T01 | done | — | workplans/POLICY-NEXUS-WP-0002-arc42-architecture-collection.md |
| task | POLICY-NEXUS-WP-0002-T02 | done | — | workplans/POLICY-NEXUS-WP-0002-arc42-architecture-collection.md |
| task | POLICY-NEXUS-WP-0002-T03 | done | — | workplans/POLICY-NEXUS-WP-0002-arc42-architecture-collection.md |
| task | POLICY-NEXUS-WP-0002-T04 | done | — | workplans/POLICY-NEXUS-WP-0002-arc42-architecture-collection.md |
| task | POLICY-NEXUS-WP-0002-T05 | done | — | workplans/POLICY-NEXUS-WP-0002-arc42-architecture-collection.md |
| task | POLICY-NEXUS-WP-0002-T06 | progress | — | workplans/POLICY-NEXUS-WP-0002-arc42-architecture-collection.md |
| task | POLICY-NEXUS-WP-0002-T07 | todo | — | workplans/POLICY-NEXUS-WP-0002-arc42-architecture-collection.md |
| task | POLICY-NEXUS-WP-0003-T01 | done | — | workplans/POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md |
| task | POLICY-NEXUS-WP-0003-T02 | done | — | workplans/POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md |
| task | POLICY-NEXUS-WP-0003-T03 | done | — | workplans/POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md |
| task | POLICY-NEXUS-WP-0003-T04 | done | — | workplans/POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md |
| task | POLICY-NEXUS-WP-0003-T05 | done | — | workplans/POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md |
| task | POLICY-NEXUS-WP-0003-T06 | progress | — | workplans/POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md |
| task | POLICY-NEXUS-WP-0003-T07 | progress | — | workplans/POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md |

354
workplans/PNEX-WP-0002-arc42-architecture-collection.md Normal file
View file

@ -0,0 +1,354 @@
---
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.

369
workplans/PNEX-WP-0003-adr-review-cleanup-publish.md Normal file
View file

@ -0,0 +1,369 @@
---
id: PNEX-WP-0003
type: workplan
title: "Review ADRs for conflict, keep what governs, publish the rest properly"
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
- PNEX-WP-0002
state_hub_workstream_id: "d80b73a4-db3d-565d-9c51-c3e12c93e610"
---
# PNEX-WP-0003 — ADR review, cleanup, publish
Renamed from `POLICY-NEXUS-WP-0003` 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
Walk the inventoried ADR corpus, find conflicts and inconsistencies, drop
what no longer governs, and give every remaining ADR the metadata and
address it needs to be published on `policy.coulomb.social`.
Done means: every inventoried ADR has a reviewed disposition; the ones
that still govern have publication-grade front-matter in their owning
repo, a `publication.json` entry here, a current URL, an immutable
revision URL, and a pointer from the matching first-wave arc42 chapter 9.
## Why this workplan exists
WP-0001 inventoried 124 sources and published one. Of the rest, **113
ADRs and canon files sit at `metadata-pending`**. A first pass over that
inventory (2026-08-18) found:
| State | Count |
| --- | --- |
| Already published | 1 (Tenancy Posture) |
| Publication-ready front-matter, not yet registered | 8 (all `railiance-master`) |
| YAML front-matter but missing owner / revision / review | ~56 |
| No front-matter | 49 |
| Directory indexes, excluded | 2 |
| Non-Markdown, unsupported | 8 |
This repo's own ADR-0001 is in the "no front-matter" pile. Ids collide
across repos (`ADR-001` means different decisions in coulomb-loop,
flex-auth, activity-core, the-custodian). Some estate ADRs are already
marked superseded in place (custodian ADR-008 → Tenancy Posture) while
siblings still read as current.
Publishing that pile as-is would freeze the conflicts. Cleaning without a
protocol would invent authority this repo does not have.
## Authority
Unchanged from WP-0001.
- **Owning repo** decides whether an ADR still governs, and writes the
cleanup (front-matter, successor links, status).
- **the-custodian** decides what counts as estate-level canon.
- **This repo** reviews, records the review, and publishes. It does not
edit another repo's ADR body.
A "cleanup packet" is a per-repo note this workplan produces. The owning
repo applies it.
## Review protocol
Every inventoried ADR (and every in-scope canon file that is not already
`published`) gets exactly one of:
| Disposition | Meaning | Publication |
| --- | --- | --- |
| `publish` | Still governs. Front-matter complete. Register it. | `publication.json` entry |
| `superseded` | Replaced. Keep the source, point at the successor, publish *as superseded* so the old URL never 404s once it has been public. Unpublished superseded ADRs stay in the inventory as `excluded` with that reason until someone needs the historical URL. | only if a public URL already exists or the successor needs the pointer live |
| `withdrawn` | No longer governs, no successor. Same retention rule as ADR-0001. | same as superseded |
| `local` | Useful in its repo, not governing for anyone else. Out of this site. | inventory `excluded` |
| `conflict` | Contradicts another ADR or the estate arc42, and the owner has not ruled. Stays `metadata-pending` with the conflict recorded. Not published. | no |
Conflict kinds this pass must look for:
1. **Identifier collision** — same `id` or same `ADR-NNNN` in two repos.
Publication ids must be globally unique (repo-prefixed, as
`RMASTER-ADR-0001` already is).
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 (example class: "hub is source of truth" vs custodian ADR-001).
5. **Architecture miss** — an accepted ADR that the matching first-wave
arc42 does not mention in chapter 9, or that chapter 9 lists with the
wrong status. This check waits on WP-0002-T04 (estate) and T05 (other
systems).
6. **Duplicate claim** — two documents claiming to be the current
decision on the same question (custodian ADR-008 vs Tenancy Posture is
the known case; treat it as the template).
Evidence for each review is a row in a review ledger this repo owns
(`docs/adr-review/` or equivalent). The ledger is a work artefact, not a
published policy document.
## First publish set (already ready or nearly so)
Do these as soon as T01 exists; do not wait for the full corpus pass.
1. **policy-nexus ADR-0001** — add front-matter here, then register it.
This repo eating its own contract is the rehearsal for everyone else.
2. **railiance-master ADR-0001–0008** — already have `id`, `title`,
`status`, `owner`, `revision`, `last_reviewed`, `review_interval`.
Register them once T01's id/address scheme is applied.
Everything else waits on the review row.
## Non-goals
- No silent rewrite of other repos.
- No State Hub `/decisions` registration. That API is for open work
choices; these files are architecture records.
- No requirement that every remaining ADR become an essay. Cleanup is
metadata, status honesty, and successor links. Content rewrites stay
with the owner.
- No publication of `local` ADRs "for completeness".
## Tasks
### T01 — Review protocol and ledger
```task
id: PNEX-WP-0003-T01
status: done
priority: high
state_hub_task_id: "00168c5f-1ca5-52fb-b066-78aecb6c722b"
```
Write the protocol above into a working ledger format: one row per
inventory source, with proposed disposition, conflict kind (if any),
successor, required front-matter gaps, and owning repo.
Use `source-inventory.json` as the input set. Do not rediscover by glob.
**Output:** `docs/adr-review/` (ledger + protocol). Not published.
Completed 2026-08-18. Protocol, regenerable `ledger.json`, and
`tools/adr_review_ledger.py` are in place.
### T02 — Corpus map
```task
id: PNEX-WP-0003-T02
status: done
priority: high
state_hub_task_id: "8796d8ed-8bd0-5c52-90e5-dde1a556b07d"
```
Fill the ledger from the files as they are, without yet ruling
relevance.
- Group by owning repo.
- Record existing front-matter vs the publication contract from
WP-0002-T01 / ADR-0001.
- Flag identifier collisions and missing files.
- Note already-known specials: this repo's ADR-0001; the eight
railiance-master ADRs; custodian ADR-008 relocated to Tenancy Posture.
Depends on T01. Does not depend on WP-0002.
Completed 2026-08-18. `docs/adr-review/ledger.json` records front-matter,
gaps, identifier collisions, and the known ADR-008 / Tenancy Posture
special. First-publish-set rows start as `publish`; everything else is
`unreviewed`.
### T03 — Conflict and inconsistency pass
```task
id: PNEX-WP-0003-T03
status: done
priority: high
state_hub_task_id: "e5e55aaa-ad0d-5407-9818-7c9146c4837c"
```
Apply conflict kinds 1–4 (and 6) to the corpus map. Kind 5 waits on
WP-0002-T04.
For each hit: record both sides, the contradiction in one sentence, and
who must rule (owning repo, or the-custodian if the clash is
estate-level). Do not resolve a custodian-level clash in this repo.
**Acceptance:** every `conflict` row is readable by the owning-repo
agent that will have to act on it.
Completed 2026-08-18. `docs/adr-review/conflicts.md` and `rulings.json`.
Kind 1 is automatic on a shared front-matter id and is a prefix packet.
Live unpublished conflicts: hosts/infra ADR-003, hosts/infra ADR-004,
coulomb-social ADR-0002. No kind-4 contradiction found. Kind 5 waits
on chapter 9 (now present on the estate stub; re-check in T04).
### T04 — Relevance filter
```task
id: PNEX-WP-0003-T04
status: done
priority: high
state_hub_task_id: "88c38acb-e28a-5b7f-8887-a6029daa254c"
```
Propose `publish` / `superseded` / `withdrawn` / `local` for every
non-conflict row.
A `publish` ADR is one that still constrains at least one other repo, or
that the matching first-wave arc42 needs in chapter 9. A `local` ADR is
one whose audience is the producing repo only (implementation notes,
tooling preferences with no cross-repo effect).
the-custodian reviews the estate-level proposals before this repo
publishes them. Per-repo proposals go out in T05 packets.
Kind-5 (architecture miss) runs here once WP-0002-T04 exists, and again
when T05 of that workplan lands a system document.
2026-08-18: first relevance slice is in `rulings.json`. Superseded:
custodian ADR-008, both IAM Profile predecessors, both ADR-002 host/infra
copies. Publish (after prefix/metadata packets): estate ADRs 001–007 and
010–011, activity-core 001–005, railiance-platform 0001–0003, IAM
Profile v0.3. Remainder still `unreviewed`. Kind 5 against the estate
chapter 9: the listed estate ADRs match; no miss on that document.
Completed 2026-08-19. Remaining rows are classified: fleet-binding
records `publish`, product-local notes `local`, templates and draft
companions `local`. Unsupported formats stay inventoried, not published.
### T05 — Cleanup packets
```task
id: PNEX-WP-0003-T05
status: done
priority: high
state_hub_task_id: "ec4bc4e6-e4b7-52b2-b829-c17ac3200cd2"
```
For each owning repo with remaining work, write a packet: required
front-matter, status/successor fixes, identifier prefix if the current
`id` would collide on the site, and the list of ADRs this repo is
prepared to publish once those land.
Deliver the packet as a message or a PR *checklist* in the owning repo,
not as an edit of the ADR bodies. This repo applies the packet only for
`policy-nexus` itself.
Completed 2026-08-18. Checklists in `docs/adr-review/packets/` and
inbox messages from `policy-nexus` to the-custodian, net-kingdom,
railiance-hosts, railiance-infra, coulomb-social, activity-core, and
railiance-platform. No foreign ADR bodies were edited.
### T06 — Register the ready set
```task
id: PNEX-WP-0003-T06
status: progress
priority: high
state_hub_task_id: "1960ca1d-0f9b-5c7d-83b5-91373b6516b0"
```
- Add publication front-matter to `docs/adr/ADR-0001-addressing-and-permanence.md`
and a `publication.json` entry under
`adr/addressing-and-permanence/v1/`.
- Register the eight railiance-master ADRs (and any others that become
ready during T05) with globally unique ids and ADR-0001 addresses
(`/adr/<document>/<version>/`).
- Add missing `publication.json` `repositories` entries.
- Refresh inventory dispositions.
- `make check` and `make build` pass.
Further registrations happen as packets return, still under this task
until the ledger has no `publish` row left unpublished.
2026-08-18: first publish set is in `publication.json` — this repo's
ADR-0001 (with publication front-matter) and railiance-master
ADR-0001–0008. Inventory dispositions match. Remaining `publish` rows
wait on later packets.
2026-08-19: activity-core ACT-ADR-001–005 (metadata applied in the
owning repo) and ops-warden ADR-0001–0005 (harvest request; already
publication-ready) are registered.
2026-08-31: registered 22 newly ready records: NetKingdom ADR-0006–0008
and 0010–0015, RINFRA-ADR-0005, ACT-ADR-006/007, Ops Warden ADR-0007–0010,
RMASTER-ADR-0009, CUST-ADR-012, and four current NetKingdom security
standards. The corpus now has 60 explicit publications. Seven unpublished
superseded records remain excluded history. Thirty-five `publish` rulings
still await owner metadata, and 13 already-published sources need owner-side
revision bumps before the retained immutable build can advance. CUST-ADR-001
also needs its overdue owner review before the currency gate can pass.
2026-08-31: all 13 immutable-revision corrections and the CUST-ADR-001 review
landed in their owner repositories. The retained-history build, currency gate,
and release verifier pass for the 60-document batch. The remaining 35
metadata-dependent publish rulings and five owner conflicts are handed off as
`CUST-IN-0016`; they do not keep this bounded batch open.
### T07 — Point the architecture documents at what remains
```task
id: PNEX-WP-0003-T07
status: done
priority: medium
state_hub_task_id: "244fcd0a-7193-5845-86f8-31596011faa9"
```
Once WP-0002 has first-wave arc42 documents, chapter 9 of each must list
every `publish` ADR for that system and must not list `local` or
unresolved `conflict` rows as current.
This is a PR in the owning repo of the arc42 document, same as T05.
Depends on WP-0002-T04/T05 and on this workplan's T04.
2026-08-19: first-wave chapter 9 lists CUST-ADR-001–011, published
Railiance/NetKingdom/activity-core/ops-warden/platform ADRs, and keeps
hosts/infra conflicts out. Stubs bumped to draft-2.
2026-08-31: chapter-9 owner handoffs now cover CUST-ADR-012, the explicit
NetKingdom ADR list/current security standards, and current State Hub status.
Railiance already lists RMASTER-ADR-0009. These edits remain owner-repo work;
Policy Nexus does not rewrite the four foreign architecture sources.
Completed 2026-08-31. The owner changes landed in
`the-custodian@d3c6f13`, `state-hub@da30ce6`, and
`net-kingdom@d4e57e6`; Railiance already contained RMASTER-ADR-0009. All five
first-wave chapter-9 indexes now match the registered publication set.
## Sequencing
T01 → T02 → T03 and T04 (T04's kind-5 slice waits on WP-0002-T04).
T06's first two bullets (this repo's ADR-0001, railiance-master) can
run as soon as T01 has the address/id rule — they are already
relevance-obvious.
T05 follows T04. T07 is last.
Do not block the first publish set on finishing the 113-row pass.
## Risks
**The review becomes a rewrite of the estate.** Mitigation: dispositions
and metadata, not new architecture. New architecture is WP-0002.
**Conflicts linger unpublished and unread.** Mitigation: `conflict` rows
are a first-class ledger state and a cleanup-packet item, not a silent
`metadata-pending`.
**Identifier prefixes paint over history.** Mitigation: the source
filename does not have to change; only the publication `id` and URL
slug must be unique. Record the original filename in the ledger.
**This repo publishes a local ADR because the filter is timid.**
Mitigation: T04's default for "no cross-repo effect" is `local`, not
`publish`.
## Residuals
- Unresolved `conflict` rows after owner silence become an intake on
the-custodian, not a third policy-nexus workplan, unless a new batch
of publications is ready.
- Later-wave architecture documents (WP-0002 residual) pick up new ADR
indexes under the same protocol.

19
workplans/POLICY-NEXUS-WP-0002-arc42-architecture-collection.md → workplans/archived/260831-POLICY-NEXUS-WP-0002-arc42-architecture-collection.md
View file

@ -4,11 +4,12 @@ type: workplan
title: "Publish an arc42 architecture collection from owning repos" title: "Publish an arc42 architecture collection from owning repos"
domain: infotech domain: infotech
repo: policy-nexus repo: policy-nexus
status: active status: finished
owner: the-custodian owner: the-custodian
topic_slug: policy-nexus topic_slug: policy-nexus
created: "2026-08-18" created: "2026-08-18"
updated: "2026-08-18" updated: "2026-08-31"
finished: "2026-08-31"
depends_on_workplans: depends_on_workplans:
- POLICY-NEXUS-WP-0001 - POLICY-NEXUS-WP-0001
state_hub_workstream_id: "cf780ff6-ccc1-58e5-aace-665ff9234f5c" state_hub_workstream_id: "cf780ff6-ccc1-58e5-aace-665ff9234f5c"
@ -16,6 +17,10 @@ state_hub_workstream_id: "cf780ff6-ccc1-58e5-aace-665ff9234f5c"
# POLICY-NEXUS-WP-0002 — arc42 architecture collection # POLICY-NEXUS-WP-0002 — arc42 architecture collection
This identity was retired on 2026-08-31 and continues as `PNEX-WP-0002`.
Completed tasks retain their history here; T06 and T07 were cancelled under
this identifier and continue under the conformant successor.
## Goal ## Goal
Give the estate a countable set of **arc42 architecture documents** — one Give the estate a countable set of **arc42 architecture documents** — one
@ -259,7 +264,7 @@ open.
```task ```task
id: POLICY-NEXUS-WP-0002-T06 id: POLICY-NEXUS-WP-0002-T06
status: progress status: cancel
priority: high priority: high
state_hub_task_id: "f4761eb6-ab53-5c02-8b7c-f301d3ca04fa" state_hub_task_id: "f4761eb6-ab53-5c02-8b7c-f301d3ca04fa"
``` ```
@ -283,11 +288,17 @@ publication stays explicit.
NetKingdom and State Hub are published at NetKingdom and State Hub are published at
`/architecture/<system>/v0.1/`. `/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. Owner handoffs are in `docs/adr-review/packets/`.
### T07 — Smoke the published collection ### T07 — Smoke the published collection
```task ```task
id: POLICY-NEXUS-WP-0002-T07 id: POLICY-NEXUS-WP-0002-T07
status: todo status: cancel
priority: medium priority: medium
state_hub_task_id: "4a07237f-715d-595a-9448-ae1e342ca633" state_hub_task_id: "4a07237f-715d-595a-9448-ae1e342ca633"
``` ```

26
workplans/POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md → workplans/archived/260831-POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md
View file

@ -4,11 +4,12 @@ type: workplan
title: "Review ADRs for conflict, keep what governs, publish the rest properly" title: "Review ADRs for conflict, keep what governs, publish the rest properly"
domain: infotech domain: infotech
repo: policy-nexus repo: policy-nexus
status: active status: finished
owner: the-custodian owner: the-custodian
topic_slug: policy-nexus topic_slug: policy-nexus
created: "2026-08-18" created: "2026-08-18"
updated: "2026-08-18" updated: "2026-08-31"
finished: "2026-08-31"
depends_on_workplans: depends_on_workplans:
- POLICY-NEXUS-WP-0001 - POLICY-NEXUS-WP-0001
- POLICY-NEXUS-WP-0002 - POLICY-NEXUS-WP-0002
@ -17,6 +18,10 @@ state_hub_workstream_id: "d1cfae73-460d-59f7-88c3-b251e563fb05"
# POLICY-NEXUS-WP-0003 — ADR review, cleanup, publish # POLICY-NEXUS-WP-0003 — ADR review, cleanup, publish
This identity was retired on 2026-08-31 and continues as `PNEX-WP-0003`.
Completed tasks retain their history here; T06 and T07 were cancelled under
this identifier and continue under the conformant successor.
## Goal ## Goal
Walk the inventoried ADR corpus, find conflicts and inconsistencies, drop Walk the inventoried ADR corpus, find conflicts and inconsistencies, drop
@ -256,7 +261,7 @@ railiance-platform. No foreign ADR bodies were edited.
```task ```task
id: POLICY-NEXUS-WP-0003-T06 id: POLICY-NEXUS-WP-0003-T06
status: progress status: cancel
priority: high priority: high
state_hub_task_id: "a06165fe-dabd-58bb-a67a-50e97122a0cc" state_hub_task_id: "a06165fe-dabd-58bb-a67a-50e97122a0cc"
``` ```
@ -283,11 +288,19 @@ wait on later packets.
owning repo) and ops-warden ADR-0001–0005 (harvest request; already owning repo) and ops-warden ADR-0001–0005 (harvest request; already
publication-ready) are registered. publication-ready) are registered.
2026-08-31: registered 22 newly ready records: NetKingdom ADR-0006–0008
and 0010–0015, RINFRA-ADR-0005, ACT-ADR-006/007, Ops Warden ADR-0007–0010,
RMASTER-ADR-0009, CUST-ADR-012, and four current NetKingdom security
standards. The corpus now has 60 explicit publications. Seven unpublished
superseded records remain excluded history. Thirty-five `publish` rulings
still await owner metadata, and 13 already-published sources need owner-side
revision bumps before the retained immutable build can advance.
### T07 — Point the architecture documents at what remains ### T07 — Point the architecture documents at what remains
```task ```task
id: POLICY-NEXUS-WP-0003-T07 id: POLICY-NEXUS-WP-0003-T07
status: progress status: cancel
priority: medium priority: medium
state_hub_task_id: "f752e1f3-881e-5c3e-bcd3-071283f7d40b" state_hub_task_id: "f752e1f3-881e-5c3e-bcd3-071283f7d40b"
``` ```
@ -303,6 +316,11 @@ Depends on WP-0002-T04/T05 and on this workplan's T04.
Railiance/NetKingdom/activity-core/ops-warden/platform ADRs, and keeps Railiance/NetKingdom/activity-core/ops-warden/platform ADRs, and keeps
hosts/infra conflicts out. Stubs bumped to draft-2. hosts/infra conflicts out. Stubs bumped to draft-2.
2026-08-31: chapter-9 owner handoffs now cover CUST-ADR-012, the explicit
NetKingdom ADR list/current security standards, and current State Hub status.
Railiance already lists RMASTER-ADR-0009. These edits remain owner-repo work;
Policy Nexus does not rewrite the four foreign architecture sources.
## Sequencing ## Sequencing
T01 → T02 → T03 and T04 (T04's kind-5 slice waits on WP-0002-T04). T01 → T02 → T03 and T04 (T04's kind-5 slice waits on WP-0002-T04).