feat(ci): declare sibling visibility, and un-dark seven cross-repo checks

[Polichinel]

Adds ADR-016. Partially mitigates C-81; resolves the CI residual on C-46 and C-57.

The failure this fixes had already happened

A few tests here verify claims this repo makes about other repos — chiefly that the coordinate-registry edition we pinned is still the one that exists. They need the sibling on disk, so they skipped in CI and ran only on a laptop.

Which siblings CI could fetch was decided in a comment, and the comment said views-appwrite was private. It went public on 2026-08-08 (views-appwrite@9d80b75, a deliberate recorded act) and the comment did not — so seven checks stayed dark for two days for no reason, including both registry-drift detectors, which had fired twice in one day the week before.

The first draft of ADR-016 proposed issuing a credential to reach those seven. It was written one day after the fact justifying it stopped being true. That is not a footnote to this change; it is the argument for it.

The fix: a declaration that carries its own date

Sibling(env=..., public=..., public_checked=..., ci_checkout=..., note=...)

public is a fact about the world. ci_checkout is our decision. Conflating them into one sentence of prose is exactly what went wrong.

frozen=True, kw_only=True deliberately: two adjacent booleans are a one-token slip between "public, not checked out" and the combination rule G3 forbids, and a plain dict would let a missing ci_checkout read as None — silently exempting that sibling from every rule, which is the failure mode this repo has registered more than any other.

ref: main is not a detail

Without it actions/checkout takes the sibling's own default branch — which for views-appwrite is development. Two checks read the working tree while a third demands reachability from main. Latent today (both branches carry the same edition); contradictory the first time a bump lands on development first. Retrofitted to the existing crafdapi step too, and made a rule rather than a habit.

The guards

tests/test_ci_sibling_coverage.py — eight rules, each a pure function of (workflow, siblings), so each runs against a synthetic broken world as well as the real file. A rule demonstrable only by editing CI is one nobody ever watches fail.

	rule	why
G1	declared checkouts exist, and the env var on the pytest step matches the checkout path	env on the Lint step passes a naive check and the tests see nothing
G2	every checkout maps to a declaration, across all workflow files	a sibling smuggled into codeql.yml is not invisible
G3	private ⇒ must have a token; public ⇒ must not	see below
G4	every non-checked-out sibling explains why, naming a record	a deferral needs an owner (ADR-014 §4)
G5	no sibling checkout carries continue-on-error	see below
G6	paths under _siblings/	it is what ruff excludes; a sibling elsewhere once produced 745 lint findings
G7	ref: main	above
G8	public_checked parses, and is not in the future

G3 and G5 look like fussiness and are not. No test here touches the network — that is a hard convention. public is verified by CI doing the tokenless checkout: the default GITHUB_TOKEN is scoped to this repo, so fetching a repo declared public fails if it is actually private. One token: added to dodge a rate limit, or one continue-on-error: added while debugging, and that verification silently stops existing.

A meta-test refuses a rule added to _RULES with no mutant proving it bites — and it is itself mutation-proven.

Found en route: an empty variable was a silent skip

broken_sibling_overrides filtered on if value, so VIEWS_APPWRITE="" read as unset — which is exactly what a YAML interpolation resolving to nothing produces. Seven checks would skip on a green build, in the one place it matters. Path("").exists() is True, so dropping the truthiness test alone makes it worse; the .strip() is load-bearing.

One test changes character rather than merely un-skipping

test_no_coordinate_value_is_copied_into_this_repo — the scan refusing registry values in this public repo's markdown — now runs on every PR rather than only on a maintainer's machine. README.md carried four such values once already. Its own comment said the opposite and has been corrected.

What is deferred, and what is overridden

Deferred: the credential for views-faoapi, the one genuinely private sibling. It buys one test — admittedly the one whose failure produces no error anywhere — and a better answer is pending: asking FAO to consent to making that repo public. An audit of its full history found no credentials and no partner staff emails; it is already MIT. ADR-016 §8 carries the trigger for falling back to the credential.

Overridden, and disposed of in the same change (ADR-014 §5): C-46 recommended "do not add sibling checkouts to the per-PR workflow". Its stated objection was coupling to another repo's default branch — which ref: main addresses. The residual cost is real and stated rather than glossed: a merge to a sibling's main can turn this repo red and block merges until someone re-pins. That is the drift detector working, and the trade is deliberate.

Also

pyyaml declared and re-locked in the same commit — it already arrived transitively, which is precisely how this repo lost pytest, and a stale lock makes poetry install refuse and takes the whole suite with it. The lock diff is two lines.

Deciders swept across ADRs 000–015: the PRIO MD&D Team no longer exists, and a decider field naming a body nobody can ask is worse than useless.

Verification

ruff check .                                 # clean
poetry check --lock                          # fresh
pytest -q                                    # 404 passed, 40 xfailed
VIEWS_APPWRITE=/nonexistent pytest -q        # FAILS, does not skip
VIEWS_APPWRITE="" pytest -q                  # FAILS — the hole above

Expected CI skips after this lands: 9 (8 views-datafactory, which no credential can fix — its tests need raw data absent from its git repo — plus 1 views-faoapi). I will read the real number off the CI run and correct the record if it differs, rather than deriving it.

🤖 Generated with Claude Code