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.
83 lines
3.4 KiB
Markdown
83 lines
3.4 KiB
Markdown
# 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.
|