policy-nexus/workplans/POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md

id	type	title	domain	repo	status	owner	topic_slug	created	updated	depends_on_workplans
POLICY-NEXUS-WP-0003	workplan	Review ADRs for conflict, keep what governs, publish the rest properly	infotech	policy-nexus	active	the-custodian	policy-nexus	2026-08-18	2026-08-18	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

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

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

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

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

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

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/<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.

T07 — Point the architecture documents at what remains

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.