tegwick
a8fb62a3bc
Add the owner-facing publication contract, a regenerable ADR review ledger, and publication entries for this repo's ADR-0001 plus the eight ready railiance-master ADRs.
301 lines
11 KiB
Markdown
301 lines
11 KiB
Markdown
---
|
||
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.
|