--- id: POLICY-NEXUS-WP-0003 type: workplan title: "Review ADRs for conflict, keep what governs, publish the rest properly" domain: infotech repo: policy-nexus status: finished owner: the-custodian topic_slug: policy-nexus created: "2026-08-18" updated: "2026-08-31" finished: "2026-08-31" depends_on_workplans: - POLICY-NEXUS-WP-0001 - POLICY-NEXUS-WP-0002 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 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: POLICY-NEXUS-WP-0003-T01 status: done priority: high state_hub_task_id: "1a8070da-ff5b-59c0-98b6-bda7b27a0d15" ``` 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: POLICY-NEXUS-WP-0003-T02 status: done priority: high state_hub_task_id: "25ba4084-17c5-5748-862c-405b25f43211" ``` 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: POLICY-NEXUS-WP-0003-T03 status: done priority: high state_hub_task_id: "10f298cc-7ee2-57dc-b0ba-89d948024518" ``` 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: POLICY-NEXUS-WP-0003-T04 status: done priority: high state_hub_task_id: "dc5709cc-1c82-5fca-8fdb-84008cf1b250" ``` 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: POLICY-NEXUS-WP-0003-T05 status: done priority: high state_hub_task_id: "f7bf5d39-61b4-54f2-b007-bc73693b53b0" ``` 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: POLICY-NEXUS-WP-0003-T06 status: cancel priority: high state_hub_task_id: "a06165fe-dabd-58bb-a67a-50e97122a0cc" ``` - 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. ### T07 — Point the architecture documents at what remains ```task id: POLICY-NEXUS-WP-0003-T07 status: cancel priority: medium state_hub_task_id: "f752e1f3-881e-5c3e-bcd3-071283f7d40b" ``` 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. ## 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.