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

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

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