Skip to content

Add an exemption to an architectural gate

Who is this for (1)

Audience: maintainers and agents whose change trips a tests/architectural/ gate on a site that is genuinely allowed (a sanctioned os.path.join, a guarded reset --hard, a known OS-detection branch).

Every exemption identifies its site by content, never by line number. A line-pinned entry goes red on any unrelated edit above it and, once stale, can silently bless a new violation on its old line. The positional-anchor ban (tests/architectural/test_ratchet_positional_anchor_ban.py) rejects line-pinned entries anywhere under tests/architectural/, and its own exemption set is pinned empty.

1. Identify which kind of allowlist the gate uses

KindExamplesEntry formStale entry
Hand-curatedjoin allowlist, kernel/doctrine import exemptions, os-detect / lock-ban / clock _exemptions/*.txtcontent descriptorfails the gate
Censusdestructive-op, mutation-ownership, overwrite-ownership gatesCensusKey(...)warns only
Dead-symbol YAMLtest_no_dead_symbols.py via tests/architectural/dead_symbol_allowlist.yaml(module, name) entry with a category and rationalefails the gate

2a. Hand-curated gate: add a content descriptor

The descriptor form is <repo-relative path>::<qualname>::<token_substring>[::<occurrence>]. qualname is the enclosing scope and token_substring is a distinctive fragment of the statement’s normalised tokens. Add occurrence (0-based) only when the same qualname and token appear more than once in the file.

  • In an _exemptions/*.txt file, write one descriptor per line.
  • In a Python allowlist, add a ContentDescriptor entry with a non-empty rationale.

Render the line rather than hand-typing it:

from tests.architectural._content_identity import render_descriptor_line

Matching goes only through tests/architectural/_content_identity.py (resolve_allowlist + partition_findings). One entry suppresses at most one finding.

2b. Census gate: add a CensusKey

The gate’s failure message prints the unexpected site as rel::qualname::op#ordinal (line N) tokens=.... The line is a locator only. Add a literal to the gate’s _ALLOWLIST:

CensusKey(rel="src/...", qualname="...", token_line="...", op="...", op_ordinal=0): (
"why this destructive operation is safe here"
),

op_ordinal counts identical (qualname, token_line, op) sites in source order. A second identical operation in the same function therefore becomes a new, unexpected site and fails the gate. If the gate is registered in tests/architectural/_baselines.yaml (for example the mutation-ownership gate’s destructive_op_allowlist), raise that ceiling in the same change and justify it in review. Baselines are shrink-only by default.

2c. Dead-symbol gate: add a YAML entry

First try to wire the symbol, drop it from __all__, or delete it. If an exemption is genuinely warranted, append an entry under entries: in tests/architectural/dead_symbol_allowlist.yaml:

- module: specify_cli.example.module # the module whose __all__ declares the name
name: ExampleSymbol
category: category_c_example # must be declared under categories:
rationale: why this public symbol has no src/ caller yet # optional -- see below
issue: '#1234' # required where the category sets requires_issue: true

An entry’s rationale: is optional: if omitted, the gate falls back to its category’s rationale (loader rule L6 — the effective rationale is never empty, but an entry does not have to restate its category’s reason). Give an entry its own rationale: only when this specific symbol needs a reason beyond the category’s.

The loader (tests/architectural/_dead_symbol_allowlist.py) refuses unknown keys (never add line: or body_hash:), a present-but-empty rationale, an undeclared category, a duplicate (module, name), and a declared category with no entries. In the same change, raise the test_no_dead_symbols: allowlist_entries leaf in tests/architectural/_baselines.yaml by one and justify it in review. The widened widened_grandfathered_470 section has its own leaf.

Declaring a new category

A new category_* is declared under categories:, with its own required rationale and requires_issue policy:

categories:
category_x_example:
rationale: a one-line reason every entry in this category shares
requires_issue: false # true forces every entry (and the widened section) to carry issue:

Rule L9 refuses a category with no entries (no tombstones): declare the category and its first entry in the same change, and delete the category once its last entry is removed.

A body edit to an allowlisted symbol needs no allowlist edit. A move or rename is reported as a GONE entry plus a new offender; update the entry’s module: or name:. See CI and Architectural Gate Mechanics and the identity ADR.

3. Verify

Run the gate you touched and the positional-anchor ban:

Terminal window
PWHEADLESS=1 .venv/bin/python -m pytest tests/architectural/<gate>.py \
tests/architectural/test_ratchet_positional_anchor_ban.py -q

Do not run the full tests/architectural/ suite locally; CI owns it.

See also