<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/4.x/2026-09-30-1-allowlist-ratchets-are-priced-debt/">
  <id>https://docs.spec-kitty.ai/adr/4.x/2026-09-30-1-allowlist-ratchets-are-priced-debt/</id>
  <title>ADR: allowlist ratchets are priced debt</title>
  <updated>2026-09-30T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/4.x/2026-09-30-1-allowlist-ratchets-are-priced-debt/"/>
  <summary>Accepted: an allowlist ratchet costs CI money on every run and keeps a known defect alive, so it is owned, time-boxed and drained; a defect-class gate closes with no allowlist.</summary>
  <content type="html">&lt;span id=&quot;adr-allowlist-ratchets-are-priced-debt&quot;&gt;&lt;/span&gt;
&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-09-30&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Stijn Dejongh (owner), ruling of 2026-09-30.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt; Mission &lt;code dir=&quot;auto&quot;&gt;git-paths-are-data-01M3SSXR&lt;/code&gt;
(&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5392&quot;&gt;#5392&lt;/a&gt;,
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5400&quot;&gt;#5400&lt;/a&gt;).&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;DIRECTIVE_043&lt;/code&gt; tells us to close a recurring defect class with a structural gate. In
practice the gate usually ships with a shrink-only allowlist: the current offenders are
frozen in a list or a count in &lt;code dir=&quot;auto&quot;&gt;tests/architectural/_baselines.yaml&lt;/code&gt;, and the gate only
stops the list from growing. Charter standing order 5 named that allowlist as part of the
fix.&lt;/p&gt;
&lt;p&gt;That shape has two costs we were not counting:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;It costs money on every CI run.&lt;/strong&gt; Every allowlisted entry is scanned again on every
pull request, every push and every nightly run. The cost does not stop when the mission
that added the ratchet closes.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;It keeps a known defect alive.&lt;/strong&gt; An allowlisted site is a site we already know is
wrong. Allowlists outlive their missions: nobody owns the burn-down, and the entries stay.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The 2026-09-14 census ruling
(&lt;a href=&quot;/adr/3.x/2026-09-14-1-census-floor-ratchet-adjudication/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;2026-09-14-1-census-floor-ratchet-adjudication.md&lt;/code&gt;&lt;/a&gt;)
already showed the maintenance side of this: an estimated 40 of the last 70
baseline-maintenance commits went to four census ratchets whose measured catch record was
at or near zero. That ADR judged four
specific gates. This one sets the rule for all of them.&lt;/p&gt;
&lt;p&gt;The owner’s ruling, 2026-09-30:&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;“Regarding those ratchets: we should start considering them very expensive debt. As
they cost us money on every single CI run. Make note of this, and ensure it is stored in
our ADRs / charter as part of the git issue remediation mission.”&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;The recurring CI cost of a ratchet, paid on every run for as long as it exists.&lt;/li&gt;
&lt;li&gt;A ratchet keeps known defects in the codebase; a gate should end the class, not freeze it.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;DIRECTIVE_043&lt;/code&gt; still applies: a gate must be non-vacuous, with a concrete floor and a
self-mutation test.&lt;/li&gt;
&lt;li&gt;Single canonical authority: one baseline file, one rule for when an entry may exist.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Keep shrink-only ratchets as the standard way to close a defect class.&lt;/li&gt;
&lt;li&gt;Ban allowlists entirely.&lt;/li&gt;
&lt;li&gt;Treat every allowlist as priced debt: owned, time-boxed, and drained, with an
empty-allowlist invariant as the default closing state.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option:&lt;/strong&gt; 3, because it removes the recurring cost without blocking the rare case
where a class cannot be drained in one mission.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;A shrink-only allowlist ratchet is &lt;strong&gt;debt with a price&lt;/strong&gt;. Every entry is re-scanned on
every CI run and keeps a known defect alive.&lt;/li&gt;
&lt;li&gt;The &lt;strong&gt;default closing state&lt;/strong&gt; of a defect-class gate is an &lt;strong&gt;empty-allowlist
invariant&lt;/strong&gt;: the gate forbids the pattern everywhere except the canonical owner.&lt;/li&gt;
&lt;li&gt;A &lt;strong&gt;new gate&lt;/strong&gt; is added only when it can start empty, or in the same mission that
drains it to empty.&lt;/li&gt;
&lt;li&gt;A &lt;strong&gt;transient allowlist&lt;/strong&gt; needs a tracker issue, a named owner and an exit date, and is
recorded in &lt;code dir=&quot;auto&quot;&gt;tests/architectural/_baselines.yaml&lt;/code&gt;. A gate with no allowlist needs no
baseline entry.&lt;/li&gt;
&lt;li&gt;Existing ratchets are drained as campsite work when a mission touches their surface.
A ratchet with no owner or exit date is a finding, not a baseline to re-pin.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;This relates to, and does not supersede, the 2026-09-14 census ruling. Its per-gate
verdicts stand.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;First application.&lt;/strong&gt; Mission &lt;code dir=&quot;auto&quot;&gt;git-paths-are-data-01M3SSXR&lt;/code&gt; closes the git path-listing
class with &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_git_path_listing_owner.py&lt;/code&gt;, which ships with an empty
allowlist. The hand-built git runners that do not list paths could not be drained in the
same mission, so they became follow-up issue
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5475&quot;&gt;#5475&lt;/a&gt;, whose gate is added only
once it can start empty. They were not added as allowlist entries.&lt;/p&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;CI stops paying, run after run, for defects we have already decided to remove.&lt;/li&gt;
&lt;li&gt;Each defect-class gate has a clear finish line: an empty allowlist.&lt;/li&gt;
&lt;li&gt;Every remaining allowlist has someone who answers for it and a date to meet.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Closing a class takes more work up front: the offenders are migrated in the same
mission instead of frozen.&lt;/li&gt;
&lt;li&gt;A class too large for one mission waits for its gate until the drain is planned, so it
has only review cover in the meantime.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;DIRECTIVE_043&lt;/code&gt; and the &lt;code dir=&quot;auto&quot;&gt;architectural-gate-non-vacuity&lt;/code&gt; tactic are unchanged in
substance. The built-in &lt;code dir=&quot;auto&quot;&gt;frozen-baseline-shrink-only-ratchet&lt;/code&gt; tactic gains a generic
cost caveat; the CI-cost rationale lives in the internal pack
(&lt;code dir=&quot;auto&quot;&gt;spec-kitty-ratchet-cost&lt;/code&gt; tactic), not in consumer doctrine.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Charter standing order 5 and Burn-down Policy (a) state the rule.&lt;/li&gt;
&lt;li&gt;The next gate that lands does so with an empty allowlist, or with a drain mission.&lt;/li&gt;
&lt;li&gt;The count of non-zero entries in &lt;code dir=&quot;auto&quot;&gt;tests/architectural/_baselines.yaml&lt;/code&gt; goes down over
the 4.x line, and none is added without an issue, an owner and an exit date.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;1-keep-shrink-only-ratchets&quot;&gt;1. Keep shrink-only ratchets&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; cheapest way to land a gate; no migration needed.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt; the cost recurs on every run with no end; entries outlive their missions; the
defect class stays open.&lt;/p&gt;
&lt;h3 id=&quot;2-ban-allowlists-entirely&quot;&gt;2. Ban allowlists entirely&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; no ratchet cost ever.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt; a class too large for one mission could never get a gate until fully drained,
and a necessary short-lived exception would have to be forced through anyway.&lt;/p&gt;
&lt;h3 id=&quot;3-priced-debt-empty-by-default-chosen&quot;&gt;3. Priced debt, empty by default (chosen)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; removes the recurring cost in the normal case; keeps an escape hatch that is
visible, owned and dated.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt; more up-front work per gate; needs review to hold the owner and exit date.&lt;/p&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Owner ruling: Stijn Dejongh, 2026-09-30 (quoted above).&lt;/li&gt;
&lt;li&gt;Related ADR: &lt;a href=&quot;/adr/3.x/2026-09-14-1-census-floor-ratchet-adjudication/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;2026-09-14-1-census-floor-ratchet-adjudication.md&lt;/code&gt;&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;Mission: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/git-paths-are-data-01M3SSXR/&lt;/code&gt; (FR-009 to FR-012), issues
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5392&quot;&gt;#5392&lt;/a&gt; and
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5400&quot;&gt;#5400&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;Follow-up: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5475&quot;&gt;#5475&lt;/a&gt;, route the
remaining hand-built git runners and &lt;code dir=&quot;auto&quot;&gt;worktree list&lt;/code&gt; parsing through &lt;code dir=&quot;auto&quot;&gt;kernel.git&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Doctrine: &lt;code dir=&quot;auto&quot;&gt;.kittify/charter/charter.md&lt;/code&gt; (standing order 5, Burn-down Policy),
&lt;code dir=&quot;auto&quot;&gt;packs/built-in/tactics/frozen-baseline-shrink-only-ratchet.tactic.yaml&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;packs/internal/tactics/spec-kitty-ratchet-cost.tactic.yaml&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
