# ADR review protocol

Working protocol for POLICY-NEXUS-WP-0003. The ledger in this directory
is a work artefact. It is not published on `policy.coulomb.social`.

Input is `source-inventory.json` only. Do not rediscover by glob.

Refresh the ledger with:

```sh
python3 tools/adr_review_ledger.py
```

## Authority

- The **owning repo** decides whether an ADR still governs and writes
  the cleanup.
- **the-custodian** decides estate-level canon.
- **This repo** records the review and publishes. It does not edit
  another repo's ADR body.

## Review dispositions

Every inventoried source that is not already `published` gets exactly
one proposed disposition. `unreviewed` means T02 has mapped the file
and T03/T04 have not yet ruled.

| Disposition | Meaning | Publication |
| --- | --- | --- |
| `unreviewed` | Facts recorded; relevance not ruled. | no |
| `publish` | Still governs. Front-matter complete. | `publication.json` entry |
| `superseded` | Replaced. Point at the successor. | only if a public URL exists or the successor needs the pointer live |
| `withdrawn` | No longer governs, no successor. | same as superseded |
| `local` | Useful in its repo, not governing for anyone else. | inventory `excluded` |
| `conflict` | Contradicts another ADR or the estate arc42; owner has not ruled. | no |

## Conflict kinds

1. **Identifier collision** — same publication `id`, or the same bare
   `ADR-NNNN` in two repos. Publication ids must be globally unique.
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.
5. **Architecture miss** — an accepted ADR that the matching first-wave
   arc42 does not mention in chapter 9. Waits on WP-0002-T04/T05.
6. **Duplicate claim** — two documents claiming to be the current
   decision on the same question.

## Ledger row

`ledger.json` holds one object per inventory source.

| Field | Set by | Meaning |
| --- | --- | --- |
| `source_repo`, `source_path` | inventory | Identity |
| `inventory_disposition`, `inventory_reason` | inventory | Current source-inventory state |
| `file_present` | T02 | Source file readable in the sibling checkout |
| `frontmatter` | T02 | Parsed fields used by the builder |
| `missing_fields` | T02 | Publication-contract gaps |
| `bare_adr` | T02 | `ADR-NNNN` extracted from id or filename, if any |
| `id_collisions` | T02 | Other sources sharing the same front-matter `id` |
| `bare_adr_collisions` | T02 | Other sources sharing the same bare `ADR-NNNN` |
| `notes` | T02 | Known specials |
| `proposed_disposition` | T03/T04 | Review ruling; `unreviewed` until then |
| `conflict_kinds` | T03 | List of kind numbers, or empty |
| `successor` | T03/T04 | Target when superseded |
| `review_notes` | T03/T04 | One-sentence contradiction or rationale |

T02 fills facts and leaves `proposed_disposition` as `unreviewed`
except for the first publish set named in WP-0003 (this repo's
ADR-0001 and the eight railiance-master ADRs), which start as
`publish` because they are already relevance-obvious.

## First publish set

- `policy-nexus` `docs/adr/ADR-0001-addressing-and-permanence.md`
- `railiance-master` `docs/adr/ADR-0001` through `ADR-0008`

Known duplicate-claim candidate: custodian
`canon/architecture/adr-008-multi-tenancy-model.md` vs published
Tenancy Posture.