coulomb/policy-nexus
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
policy-nexus/docs/adr-review/protocol.md
tegwick a8fb62a3bc Start the arc42 contract and publish the first ADR set 
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.
2026-08-18 22:16:02 +02:00

3.4 KiB
Raw Blame History

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:

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.