--- 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: active owner: the-custodian topic_slug: policy-nexus created: "2026-08-18" updated: "2026-08-18" depends_on_workplans: - POLICY-NEXUS-WP-0001 - POLICY-NEXUS-WP-0002 --- # POLICY-NEXUS-WP-0003 — ADR review, cleanup, publish ## 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 ``` 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 ``` 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: todo priority: high ``` 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. ### T04 — Relevance filter ```task id: POLICY-NEXUS-WP-0003-T04 status: todo priority: high ``` 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. ### T05 — Cleanup packets ```task id: POLICY-NEXUS-WP-0003-T05 status: todo priority: high ``` 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. ### T06 — Register the ready set ```task id: POLICY-NEXUS-WP-0003-T06 status: progress priority: high ``` - 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. ### T07 — Point the architecture documents at what remains ```task id: POLICY-NEXUS-WP-0003-T07 status: todo priority: medium ``` 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. ## 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.