<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/development/how-to/auditing-special-case-workarounds/">
  <id>https://docs.spec-kitty.ai/development/how-to/auditing-special-case-workarounds/</id>
  <title>Auditing special-case workarounds</title>
  <updated>2026-10-31T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/development/how-to/auditing-special-case-workarounds/"/>
  <summary>How to find, classify and remove the branches that tolerate a wrong input, a private seam or a test double instead of fixing the cause, with the dispositions from issue #6745.</summary>
  <content type="html">&lt;span id=&quot;auditing-special-case-workarounds&quot;&gt;&lt;/span&gt;
&lt;p&gt;&lt;strong&gt;Audience&lt;/strong&gt;: maintainers and implementers who are about to add a branch that
makes a wrong input, a missing seam or a test double “just work”.&lt;/p&gt;
&lt;p&gt;A special-case workaround is a branch that tolerates something the code should
have fixed or refused. It buys a green test and costs a second authority: the
tolerated case behaves differently from the canonical path, the two drift, and
the next change has to keep both working. Issue
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6745&quot;&gt;#6745&lt;/a&gt; is the standing
ticket for finding them; this page is the method it uses and the ledger it
produced, so the next audit starts from a table instead of a keyword grep.&lt;/p&gt;
&lt;h2 id=&quot;is-it-a-workaround-ask-the-input-question-first&quot;&gt;Is it a workaround? Ask the input question first&lt;/h2&gt;
&lt;p&gt;Before adding a branch, ask: &lt;strong&gt;is the input wrong, or is the code wrong?&lt;/strong&gt;&lt;/p&gt;



































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;If…&lt;/th&gt;&lt;th&gt;Then the answer is&lt;/th&gt;&lt;th&gt;Not&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;the value cannot legitimately occur&lt;/td&gt;&lt;td&gt;refuse it where it enters, with a structured error&lt;/td&gt;&lt;td&gt;a warning plus “keep as given”&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;the caller cannot reach a private helper&lt;/td&gt;&lt;td&gt;publish the seam&lt;/td&gt;&lt;td&gt;a duplicated copy of the helper&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;only a test double needs the tolerance&lt;/td&gt;&lt;td&gt;fix the double&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;getattr(..., default)&lt;/code&gt; in production&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;the cause was fixed in a later mission&lt;/td&gt;&lt;td&gt;delete the compensation&lt;/td&gt;&lt;td&gt;keep it “just in case”&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;two modules must agree on one decision&lt;/td&gt;&lt;td&gt;call the one authority&lt;/td&gt;&lt;td&gt;a hand-synced second copy&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;A tolerance that survives this table needs a comment naming the cause it
tolerates &lt;strong&gt;and&lt;/strong&gt; the issue that removes it.&lt;/p&gt;
&lt;h2 id=&quot;the-method&quot;&gt;The method&lt;/h2&gt;
&lt;p&gt;Six greppable heuristics, then classification. Time-box one pass per subsystem
you are already touching (roughly twenty minutes each); this is a sweep, not a
line-by-line review.&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Names and comments&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;compensat&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tolerat&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;workaround&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;fallback&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;legacy&lt;/code&gt;, “for now”, “best-effort”, “kept as written”, “defensive”,
“belt and braces”, “does not depend on a private”.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Broad &lt;code dir=&quot;auto&quot;&gt;except&lt;/code&gt; that yields an empty value or a default&lt;/strong&gt; instead of
surfacing (in this repo: &lt;code dir=&quot;auto&quot;&gt;except Exception  # noqa: BLE001&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A second construction&lt;/strong&gt; of an object another module already builds — a copy
kept alive because the original builder is private.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Production code shaped by a test double&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;getattr(..., default)&lt;/code&gt;,
duck-typed &lt;code dir=&quot;auto&quot;&gt;len&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;in&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;try/except TypeError&lt;/code&gt; around a read.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Shrink-only allowlists and baselines&lt;/strong&gt; still carrying entries whose cause is
gone (see &lt;a href=&quot;/adr/4.x/2026-09-30-1-allowlist-ratchets-are-priced-debt/&quot;&gt;ADR 2026-09-30-1&lt;/a&gt;).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Docstrings describing “residuals”, “carve-outs” or a validator “elsewhere”&lt;/strong&gt;
that does not exist.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Then classify each finding — exactly one of:&lt;/p&gt;






























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Classification&lt;/th&gt;&lt;th&gt;The fix&lt;/th&gt;&lt;th&gt;The tell&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;genuine constraint&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;keep it, and say in the comment what it protects&lt;/td&gt;&lt;td&gt;removing it breaks a documented contract or a real user’s data&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;workaround for bad data&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;refuse or report the input where it enters&lt;/td&gt;&lt;td&gt;the tolerated value has no legitimate producer&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;workaround for a missing seam&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;add the seam, delete the branch or copy&lt;/td&gt;&lt;td&gt;the comment says the original is private&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;dead compensation&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;delete it&lt;/td&gt;&lt;td&gt;the cause it compensates for was removed in a merged mission&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h2 id=&quot;the-ledger-from-6745-2026-10-31&quot;&gt;The ledger from #6745 (2026-10-31)&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;S&amp;#x3C;n&gt;&lt;/code&gt; ids are stable for follow-ups. Evidence paths are &lt;code dir=&quot;auto&quot;&gt;path:line&lt;/code&gt; at
&lt;code dir=&quot;auto&quot;&gt;origin/main&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;dfe9efb0e8&lt;/code&gt;; the full write-up is the mission’s &lt;code dir=&quot;auto&quot;&gt;research.md&lt;/code&gt;
§4.&lt;/p&gt;







































































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Id&lt;/th&gt;&lt;th&gt;Site&lt;/th&gt;&lt;th&gt;Classification&lt;/th&gt;&lt;th&gt;Disposition&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;S1&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/charter/activation/resolver.py:216-224&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;_gated&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;workaround for bad data&lt;/td&gt;&lt;td&gt;&lt;strong&gt;Left.&lt;/strong&gt; An unknown activation token is logged and kept best-effort, then silently dropped by the filter. Refusing it is reachable from real org-pack content, so it needs an operator decision: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6527&quot;&gt;#6527&lt;/a&gt; (open, claimed).&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;S2&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/charter/activation/org_charter.py:333-341&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;_best_effort_offering_root&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;genuine constraint (weak)&lt;/td&gt;&lt;td&gt;&lt;strong&gt;Left.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;resolve_offering_root()&lt;/code&gt; owns its own fallback chain and returns a &lt;code dir=&quot;auto&quot;&gt;Path&lt;/code&gt;; the wrapper’s swallow is the documented best-effort contract of three writers. Tightening it is a refusal change, tracked with S1.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;S3&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/lanes/worktree_allocator.py:1135-1142&lt;/code&gt;&lt;/td&gt;&lt;td&gt;genuine constraint (stale comment)&lt;/td&gt;&lt;td&gt;&lt;strong&gt;Left.&lt;/strong&gt; Legacy missions without &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt; still exist in user repositories and need the &lt;code dir=&quot;auto&quot;&gt;mission_branch&lt;/code&gt; fallback; only the “WP08 will harden it” comment is stale.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;S4&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/charter/offering/drg/org_pack_config.py:649-651&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;ensure_pack_identity&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;workaround for missing data&lt;/td&gt;&lt;td&gt;&lt;strong&gt;Left.&lt;/strong&gt; The planned pack_id backfill owns it; the docstring at &lt;code dir=&quot;auto&quot;&gt;:196-206&lt;/code&gt; says loading without a &lt;code dir=&quot;auto&quot;&gt;pack_id&lt;/code&gt; raises only once the pack_id-keyed readers land.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;S5&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/lanes/implement_support.py:602&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;reenter_lane_self_heal&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;workaround for a missing seam&lt;/td&gt;&lt;td&gt;&lt;strong&gt;Left here&lt;/strong&gt; (needs an allocator refactor, not a P0-audit PR): &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6898&quot;&gt;#6898&lt;/a&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;S6&lt;/td&gt;&lt;td&gt;327 &lt;code dir=&quot;auto&quot;&gt;except Exception  # noqa: BLE001&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;mixed — &lt;strong&gt;sampled, not reviewed&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;strong&gt;Sampled.&lt;/strong&gt; The nine in &lt;code dir=&quot;auto&quot;&gt;src/charter/activation/context_renderers/&lt;/code&gt; are genuine constraints: doctrine rendering degrades to a diagnostic instead of crashing a prompt build. The rest of the 327 are &lt;strong&gt;unreviewed&lt;/strong&gt; and this audit does not claim them.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;S7&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/mission_loader/command.py:206-235&lt;/code&gt;&lt;/td&gt;&lt;td&gt;workaround for a missing seam&lt;/td&gt;&lt;td&gt;&lt;strong&gt;Removed in this PR.&lt;/strong&gt; The loader kept a byte-identical copy of the runtime’s &lt;code dir=&quot;auto&quot;&gt;DiscoveryContext&lt;/code&gt; builder because it was private (its own docstring said so), and mission &lt;code dir=&quot;auto&quot;&gt;up-org-template-fsm-01M06F9K&lt;/code&gt; then had to wire the org tier into both copies. One public builder now: &lt;code dir=&quot;auto&quot;&gt;runtime.next.runtime_bridge_io.build_discovery_context&lt;/code&gt;; a patch-point test proves &lt;code dir=&quot;auto&quot;&gt;mission run&lt;/code&gt; observes it.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;S8&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/runtime/next/runtime_bridge_composition.py:615-645&lt;/code&gt;&lt;/td&gt;&lt;td&gt;production shaped by a test double&lt;/td&gt;&lt;td&gt;&lt;strong&gt;Removed in this PR.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;getattr(result, &quot;invocation_ids&quot;, ())&lt;/code&gt;, a &lt;code dir=&quot;auto&quot;&gt;len()&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;except TypeError&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;getattr(result, &quot;steps&quot;, ())&lt;/code&gt; existed “so test mocks (MagicMock) and real instances both flow through cleanly”; the executor’s result type always carries both. The read is direct, the tolerance-pinning test became a contract test, and a non-sized value now raises instead of logging &lt;code dir=&quot;auto&quot;&gt;emitted 0 invocation(s)&lt;/code&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;S9&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/ownership/validation.py:150&lt;/code&gt;&lt;/td&gt;&lt;td&gt;workaround for bad data (phantom authority)&lt;/td&gt;&lt;td&gt;&lt;strong&gt;Left.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;continue  # defensive: ignore cycles (validated elsewhere)&lt;/code&gt; names a validator that does not exist; the guard bounds the recursion, so the clean fix is to refuse a cyclic &lt;code dir=&quot;auto&quot;&gt;depends-on&lt;/code&gt; graph where it enters: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6899&quot;&gt;#6899&lt;/a&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;S10&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/autocommit.py:221-245&lt;/code&gt;&lt;/td&gt;&lt;td&gt;not a second authority&lt;/td&gt;&lt;td&gt;&lt;strong&gt;Left.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;should_auto_commit_for_worktree&lt;/code&gt; is a documented twin (D-10) of &lt;code dir=&quot;auto&quot;&gt;should_auto_commit&lt;/code&gt;; both are two-line wrappers over one &lt;code dir=&quot;auto&quot;&gt;get_auto_commit_default&lt;/code&gt; decision. Collapsing them is taste, not debt.&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;The issue’s worked example (the activation “keep the id as given, with a
warning” family, mission &lt;code dir=&quot;auto&quot;&gt;activate-output-and-identity-01M5ZA9X&lt;/code&gt;) is &lt;strong&gt;not&lt;/strong&gt; in
the table because it already landed: PR #6748 made
&lt;code dir=&quot;auto&quot;&gt;IdentityIndex.stored_spelling&lt;/code&gt; the one spelling authority and removed the
hand-rolled variants. Do not re-litigate it.&lt;/p&gt;
&lt;h2 id=&quot;what-this-audit-did-not-cover&quot;&gt;What this audit did not cover&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;The 318 unsampled &lt;code dir=&quot;auto&quot;&gt;BLE001&lt;/code&gt; sites.&lt;/strong&gt; S6 is a sample of one subsystem. A
second pass should take one package per session and record a row per hit.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Refusal changes.&lt;/strong&gt; S1, S2 and S9 all convert a silent tolerance into a
refusal, which is a behaviour change for existing pack and mission content.
They are child issues, not this PR.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The process guard.&lt;/strong&gt; The proposal — a reviewer checklist line, a “workaround”
lens for the adversarial squad, and a naming rule for tolerated paths — is
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6900&quot;&gt;#6900&lt;/a&gt;, filed for the
operator to accept or reject. It is deliberately &lt;strong&gt;not&lt;/strong&gt; in &lt;code dir=&quot;auto&quot;&gt;packs/built-in/&lt;/code&gt;:
that pack ships to every consumer, and this is in-house review practice.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;related&quot;&gt;Related&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Issue: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6745&quot;&gt;#6745&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Child issues: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6527&quot;&gt;#6527&lt;/a&gt;,
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6898&quot;&gt;#6898&lt;/a&gt;,
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6899&quot;&gt;#6899&lt;/a&gt;,
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6900&quot;&gt;#6900&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/development/how-to/review-gates/&quot;&gt;Review gates: pre-PR / pre-review checklist&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/development/reference/quality-and-tech-debt-standing-orders/&quot;&gt;Quality &amp;#x26; Tech-Debt Standing Orders&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
