From 023badb512445c04fbdc2a4fa6844489acfcd457 Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 31 Aug 2026 21:34:20 +0200 Subject: [PATCH] fix(workplans): adopt PNEX workplan identities Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a058f3-8ba0-7692-a042-9a870fc3d663 --- .custodian-brief.md | 14 +- WORK-RECORDS.md | 32 +- ...X-WP-0002-arc42-architecture-collection.md | 354 +++++++++++++++++ ...PNEX-WP-0003-adr-review-cleanup-publish.md | 369 ++++++++++++++++++ ...-WP-0002-arc42-architecture-collection.md} | 19 +- ...XUS-WP-0003-adr-review-cleanup-publish.md} | 26 +- 6 files changed, 783 insertions(+), 31 deletions(-) create mode 100644 workplans/PNEX-WP-0002-arc42-architecture-collection.md create mode 100644 workplans/PNEX-WP-0003-adr-review-cleanup-publish.md rename workplans/{POLICY-NEXUS-WP-0002-arc42-architecture-collection.md => archived/260831-POLICY-NEXUS-WP-0002-arc42-architecture-collection.md} (95%) rename workplans/{POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md => archived/260831-POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md} (92%) diff --git a/.custodian-brief.md b/.custodian-brief.md index ccb33ee..b148258 100644 --- a/.custodian-brief.md +++ b/.custodian-brief.md @@ -2,24 +2,24 @@ # Custodian Brief — policy-nexus **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)* ## Active Workstreams ### 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:** -- ► T06 — Register and publish `f4761eb6` -- · T07 — Smoke the published collection `4a07237f` +- ► T06 — Register and publish `edc2edff` +- · T07 — Smoke the published collection `1a8feb5d` ### 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:** -- ► T06 — Register the ready set `a06165fe` -- ► T07 — Point the architecture documents at what remains `f752e1f3` +- ► T06 — Register the ready set `1960ca1d` +- ► T07 — Point the architecture documents at what remains `244fcd0a` --- ## MCP Orientation (when available) diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md index e51e348..6f0ac82 100644 --- a/WORK-RECORDS.md +++ b/WORK-RECORDS.md @@ -8,26 +8,26 @@ | 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-0002 | active | — | workplans/POLICY-NEXUS-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-T01 | done | — | workplans/PNEX-WP-0002-arc42-architecture-collection.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-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-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-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 | diff --git a/workplans/PNEX-WP-0002-arc42-architecture-collection.md b/workplans/PNEX-WP-0002-arc42-architecture-collection.md new file mode 100644 index 0000000..5fbb97c --- /dev/null +++ b/workplans/PNEX-WP-0002-arc42-architecture-collection.md @@ -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//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//v0.1/ +/architecture//v0.1/revisions// +``` + +`` 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/_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//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//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. diff --git a/workplans/PNEX-WP-0003-adr-review-cleanup-publish.md b/workplans/PNEX-WP-0003-adr-review-cleanup-publish.md new file mode 100644 index 0000000..f8275a4 --- /dev/null +++ b/workplans/PNEX-WP-0003-adr-review-cleanup-publish.md @@ -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///`). +- 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. diff --git a/workplans/POLICY-NEXUS-WP-0002-arc42-architecture-collection.md b/workplans/archived/260831-POLICY-NEXUS-WP-0002-arc42-architecture-collection.md similarity index 95% rename from workplans/POLICY-NEXUS-WP-0002-arc42-architecture-collection.md rename to workplans/archived/260831-POLICY-NEXUS-WP-0002-arc42-architecture-collection.md index 4ab673b..f39354c 100644 --- a/workplans/POLICY-NEXUS-WP-0002-arc42-architecture-collection.md +++ b/workplans/archived/260831-POLICY-NEXUS-WP-0002-arc42-architecture-collection.md @@ -4,11 +4,12 @@ type: workplan title: "Publish an arc42 architecture collection from owning repos" domain: infotech repo: policy-nexus -status: active +status: finished owner: the-custodian topic_slug: policy-nexus created: "2026-08-18" -updated: "2026-08-18" +updated: "2026-08-31" +finished: "2026-08-31" depends_on_workplans: - POLICY-NEXUS-WP-0001 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 +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 Give the estate a countable set of **arc42 architecture documents** — one @@ -259,7 +264,7 @@ open. ```task id: POLICY-NEXUS-WP-0002-T06 -status: progress +status: cancel priority: high state_hub_task_id: "f4761eb6-ab53-5c02-8b7c-f301d3ca04fa" ``` @@ -283,11 +288,17 @@ publication stays explicit. NetKingdom and State Hub are published at `/architecture//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 ```task id: POLICY-NEXUS-WP-0002-T07 -status: todo +status: cancel priority: medium state_hub_task_id: "4a07237f-715d-595a-9448-ae1e342ca633" ``` diff --git a/workplans/POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md b/workplans/archived/260831-POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md similarity index 92% rename from workplans/POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md rename to workplans/archived/260831-POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md index 866c461..a1ecebc 100644 --- a/workplans/POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md +++ b/workplans/archived/260831-POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md @@ -4,11 +4,12 @@ type: workplan title: "Review ADRs for conflict, keep what governs, publish the rest properly" domain: infotech repo: policy-nexus -status: active +status: finished owner: the-custodian topic_slug: policy-nexus created: "2026-08-18" -updated: "2026-08-18" +updated: "2026-08-31" +finished: "2026-08-31" depends_on_workplans: - POLICY-NEXUS-WP-0001 - 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 +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 Walk the inventoried ADR corpus, find conflicts and inconsistencies, drop @@ -256,7 +261,7 @@ railiance-platform. No foreign ADR bodies were edited. ```task id: POLICY-NEXUS-WP-0003-T06 -status: progress +status: cancel priority: high 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 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 ```task id: POLICY-NEXUS-WP-0003-T07 -status: progress +status: cancel priority: medium 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 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 T01 → T02 → T03 and T04 (T04's kind-5 slice waits on WP-0002-T04).