[ryanbr]

AGENTS.md described the gate-trigger gap as entirely open. Half of it is shut as of #2582, so that
paragraph was stale in the direction that matters most: it told the next reader to expect a trap that
has since been partly removed, without saying which half still remains.

docs/CONTRIBUTING.md said nothing about the ledger at all. Checked before writing: zero mentions of
parity_twin_map, refresh-derived, parity_ratchet, parity_ledger or disposition in 701
lines. A contributor's first contact with the ratchet was therefore a red check with no prose
anywhere explaining what it wanted.

AGENTS.md

Past-tenses the old description and records three things: that the repository-acceptance suite, the
one test in that workflow about PRODUCT source rather than about the scanner, now runs on the
unfiltered tools-python leg; that the scanner's own unit tests stay path-filtered deliberately; and
what the remedy explicitly was not, since naming product paths in the filter only moves the trap,
which is the #1691 lesson already written into that same guard test.

docs/CONTRIBUTING.md

A new ### The parity ledger (one-sided declarations) under cross-platform discipline, since the
ledger is the mechanical enforcement of exactly that discipline. Every fact in it was read out of
Tools/parity_ledger.py and Tools/parity_ratchet.py rather than written from memory:

• the exact scanned roots, as a table
• --refresh-derived, plus --repair-stale-base for the case where a stale base is not the
  contributor's to absorb, with --migrate-authority marked as a maintainer call and why
• the three disposition types with their exact key sets, plus the allowed_kinds limit, so people
  learn early that a shared-parity regression or a pair removal cannot be waived at all
• the two scope gaps, named rather than left to be discovered: Strand/ and StrandiOS/ sit outside
  Swift scope while com/noop/data/** is inside Kotlin scope (Parity ledger scope is asymmetric: Strand/ is out of scope, so Kotlin twins there can never pair #2567), and out_of_scope_twin is
  Kotlin-only with a twin_path regex that cannot match any path under StrandiOS/
• what CI does not promise here, including the daily schedule and the advice to rebase before
  drawing any conclusion from a green run

Also a TOC entry, and a step 5 in "Add a new metric", which is where contributors most often walk
into this: step 1 lands in a scanned root, and MetricCatalog.swift living in Strand/ against a
Kotlin catalog twin in com/noop/data/** is precisely the asymmetry case.

Verification

• doc_comment_lint.py, validate_examples.py, check_source_references.py: all pass
• ACCEPTANCE=1 python3 -m unittest tests.test_parity_governance_acceptance: 50 tests, OK, exit 0
• branch sits on current origin/main (4a827f908)

Docs only. No product or tooling source is touched.