Add an exemption to an architectural gate
Who is this for (1)
- Stakeholder Persona: Maintainer — Written for the Maintainer reader.
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
| Kind | Examples | Entry form | Stale entry |
|---|---|---|---|
| Hand-curated | join allowlist, kernel/doctrine import exemptions, os-detect / lock-ban / clock _exemptions/*.txt | content descriptor | fails the gate |
| Census | destructive-op, mutation-ownership, overwrite-ownership gates | CensusKey(...) | warns only |
| Dead-symbol YAML | test_no_dead_symbols.py via tests/architectural/dead_symbol_allowlist.yaml | (module, name) entry with a category and rationale | fails 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/*.txtfile, write one descriptor per line. - In a Python allowlist, add a
ContentDescriptorentry with a non-empty rationale.
Render the line rather than hand-typing it:
from tests.architectural._content_identity import render_descriptor_lineMatching 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: trueAn 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:
PWHEADLESS=1 .venv/bin/python -m pytest tests/architectural/<gate>.py \ tests/architectural/test_ratchet_positional_anchor_ban.py -qDo not run the full tests/architectural/ suite locally; CI owns it.
See also
- Review gates: pre-PR / pre-review checklist
- Entry-format contract:
kitty-specs/ratchet-baseline-census-gate-remediation-01M3EW3Z/contracts/allowlist-entry-formats.md