<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/3.x/2026-05-28-1-ci-dependency-resolution-and-test-surface-consistency/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-05-28-1-ci-dependency-resolution-and-test-surface-consistency/</id>
  <title>ADR 2026-05-28-1: CI Dependency Resolution and Test Surface Consistency</title>
  <updated>2026-05-28T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/3.x/2026-05-28-1-ci-dependency-resolution-and-test-surface-consistency/"/>
  <summary>CI installs from the frozen lockfile so the pipeline environment matches local development, closing four failure modes that were invisible outside CI.</summary>
  <content type="html">&lt;p&gt;for &lt;code dir=&quot;auto&quot;&gt;feat/pre-doctrine-stabilization-remediation&lt;/code&gt; (GitHub Actions run 26558837157).
Root causes identified via full CI run retrospective.&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;During a full CI pipeline run (run 26558837157) on the
&lt;code dir=&quot;auto&quot;&gt;feat/pre-doctrine-stabilization-remediation&lt;/code&gt; branch, 27 tests failed across four
distinct failure modes. All failures were silent in local development but visible in CI.
The root cause in every case was the same structural gap: the test environment in CI was
not equivalent to the local development environment, and the test surface did not enforce
the production contracts it claimed to verify.&lt;/p&gt;
&lt;h3 id=&quot;discovery-process&quot;&gt;Discovery Process&lt;/h3&gt;
&lt;p&gt;The failures were traced through the following chain:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Observation:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;integration-tests-agent&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;fast-tests-agent&lt;/code&gt; jobs showed 23
tests failing with empty output — “No JSON envelope found in output.”&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Hypothesis:&lt;/strong&gt; Reproduced locally using typer 0.26.2 (installed in an isolated venv).
The local &lt;code dir=&quot;auto&quot;&gt;uv.lock&lt;/code&gt; pins typer to 0.24.2; CI installs via &lt;code dir=&quot;auto&quot;&gt;pip install -e .[test]&lt;/code&gt;
against the loose &lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt; bound &lt;code dir=&quot;auto&quot;&gt;typer&gt;=0.24.1&lt;/code&gt;, resolving to 0.26.2.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Root cause:&lt;/strong&gt; Typer 0.26 vendors click internally as &lt;code dir=&quot;auto&quot;&gt;typer._click&lt;/code&gt;. Exceptions
raised by typer internals (&lt;code dir=&quot;auto&quot;&gt;UsageError&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;Abort&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;Exit&lt;/code&gt;) now come from that vendored
module and are unrelated to the standalone &lt;code dir=&quot;auto&quot;&gt;click&lt;/code&gt; package’s exception hierarchy.
&lt;code dir=&quot;auto&quot;&gt;_JSONErrorGroup&lt;/code&gt;’s &lt;code dir=&quot;auto&quot;&gt;except click.UsageError&lt;/code&gt; clause silently missed every exception
raised by typer 0.26+.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Secondary failures:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;pytest.raises(click.exceptions.Exit)&lt;/code&gt; in four test files
matched the wrong class for the same reason. &lt;code dir=&quot;auto&quot;&gt;test_quickstart_end_to_end.py&lt;/code&gt; used a
hand-rolled SHA-256 hash instead of the canonical &lt;code dir=&quot;auto&quot;&gt;charter.hasher.hash_content()&lt;/code&gt;,
diverging silently. E2e tests failed because &lt;code dir=&quot;auto&quot;&gt;.kittify/charter/metadata.yaml&lt;/code&gt; is
gitignored and absent in CI clones, but the e2e conftest did not synthesize it.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;why-these-were-invisible-locally&quot;&gt;Why These Were Invisible Locally&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Local development uses &lt;code dir=&quot;auto&quot;&gt;uv sync --locked&lt;/code&gt;, which installs exactly what &lt;code dir=&quot;auto&quot;&gt;uv.lock&lt;/code&gt;
specifies (typer 0.24.2).&lt;/li&gt;
&lt;li&gt;CI used &lt;code dir=&quot;auto&quot;&gt;pip install -e .[test]&lt;/code&gt;, which resolves &lt;code dir=&quot;auto&quot;&gt;typer&gt;=0.24.1&lt;/code&gt; to the latest
available version at install time — currently 0.26.2.&lt;/li&gt;
&lt;li&gt;No CI matrix exercised more than one typer version.&lt;/li&gt;
&lt;li&gt;No lint rule prevented direct &lt;code dir=&quot;auto&quot;&gt;click.exceptions.*&lt;/code&gt; imports in test files.&lt;/li&gt;
&lt;li&gt;No shared fixture synthesized CI-absent runtime state files.&lt;/li&gt;
&lt;li&gt;No lint rule required tests to import production helpers rather than re-implement them.&lt;/li&gt;
&lt;/ul&gt;
&lt;hr&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Local development and CI must run against the same resolved dependency graph.&lt;/li&gt;
&lt;li&gt;The version drift that exposed these failures was not user error — it was a structural
gap in how the project manages its environment contract.&lt;/li&gt;
&lt;li&gt;Linting and fixture discipline should enforce correct patterns before review, not
after a CI failure.&lt;/li&gt;
&lt;li&gt;Tests that re-implement production algorithms test their own copy, not the system under
test. Any deviation between the two silently breaks the test’s validity as a contract
check.&lt;/li&gt;
&lt;li&gt;E2e test infrastructure must be self-contained; it must not inherit implicit
preconditions from the developer’s machine state or gitignored runtime files.&lt;/li&gt;
&lt;/ul&gt;
&lt;hr&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;h3 id=&quot;gap-1-ci-vs-local-dependency-resolver-mismatch&quot;&gt;Gap 1: CI vs. local dependency resolver mismatch&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Option A (chosen):&lt;/strong&gt; Run CI via &lt;code dir=&quot;auto&quot;&gt;uv sync --frozen&lt;/code&gt;, making the lockfile the single
contract for both local and CI environments.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option B:&lt;/strong&gt; Add upper-bound pins in &lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt; for sensitive transitive deps.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option C:&lt;/strong&gt; Keep &lt;code dir=&quot;auto&quot;&gt;pip install&lt;/code&gt;, add a scheduled “latest-deps” shadow CI job.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;gap-2-no-version-compatibility-test-for-the-typerclick-interface&quot;&gt;Gap 2: No version-compatibility test for the typer/click interface&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Option A (chosen):&lt;/strong&gt; Add a targeted smoke test that exercises &lt;code dir=&quot;auto&quot;&gt;_JSONErrorGroup&lt;/code&gt;’s
JSON envelope output end-to-end, parameterized by importing &lt;code dir=&quot;auto&quot;&gt;typer.Exit&lt;/code&gt; through the
stable public surface.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option B:&lt;/strong&gt; Add a full CI matrix axis &lt;code dir=&quot;auto&quot;&gt;typer: [pinned, latest]&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option C:&lt;/strong&gt; No test; rely on lockfile pinning from Gap 1.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;gap-3-test-helpers-re-implement-production-algorithms&quot;&gt;Gap 3: Test helpers re-implement production algorithms&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Option A (chosen):&lt;/strong&gt; Ruff &lt;code dir=&quot;auto&quot;&gt;noqa&lt;/code&gt; allowlist ban — add a custom or per-file linter
rule that flags inline re-implementations of known production helpers (detected by
pattern, e.g., &lt;code dir=&quot;auto&quot;&gt;hashlib.sha256&lt;/code&gt; inside &lt;code dir=&quot;auto&quot;&gt;tests/&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option B:&lt;/strong&gt; Code review checklist only (no automated enforcement).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option C:&lt;/strong&gt; Extract a shared test-utilities module and require all tests to import
from it.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;gap-4-e2e-fixtures-depend-on-gitignored-runtime-state&quot;&gt;Gap 4: E2e fixtures depend on gitignored runtime state&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Option A (chosen):&lt;/strong&gt; E2e conftest synthesizes all required runtime state files
explicitly after &lt;code dir=&quot;auto&quot;&gt;copytree&lt;/code&gt;, using the production helpers to produce valid content.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option B:&lt;/strong&gt; Disable preflight globally for test contexts (ad-hoc, per-conftest).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option C:&lt;/strong&gt; Commit a minimal &lt;code dir=&quot;auto&quot;&gt;metadata.yaml&lt;/code&gt; fixture file for tests only.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;gap-5-direct-clickexceptions-imports-in-test-files&quot;&gt;Gap 5: Direct &lt;code dir=&quot;auto&quot;&gt;click.exceptions.*&lt;/code&gt; imports in test files&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Option A (chosen):&lt;/strong&gt; Ruff banned-import rule covering &lt;code dir=&quot;auto&quot;&gt;click.exceptions&lt;/code&gt; in the
&lt;code dir=&quot;auto&quot;&gt;tests/&lt;/code&gt; tree. Any test that needs to assert on CLI exit/error types must import
through &lt;code dir=&quot;auto&quot;&gt;typer&lt;/code&gt;’s public surface.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option B:&lt;/strong&gt; Code review checklist only.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option C:&lt;/strong&gt; Test-only compatibility shim (mirrors the production shim).&lt;/li&gt;
&lt;/ul&gt;
&lt;hr&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;All five options A are accepted.&lt;/strong&gt; They are the minimal set of changes that directly
address the structural root cause in each gap with automated enforcement rather than
convention.&lt;/p&gt;
&lt;h3 id=&quot;decision&quot;&gt;Decision&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;CI runs &lt;code dir=&quot;auto&quot;&gt;uv sync --frozen&lt;/code&gt;.&lt;/strong&gt; Every test job in &lt;code dir=&quot;auto&quot;&gt;ci-quality.yml&lt;/code&gt; replaces its
&lt;code dir=&quot;auto&quot;&gt;pip install -e .[test]&lt;/code&gt; block with &lt;code dir=&quot;auto&quot;&gt;astral-sh/setup-uv&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;uv sync --frozen&lt;/code&gt;.
The lockfile is the environment contract for both local and CI.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;A typer-surface smoke test is added.&lt;/strong&gt; A single parameterized test in the
&lt;code dir=&quot;auto&quot;&gt;fast-tests-agent&lt;/code&gt; group verifies that invoking the CLI without a subcommand (the
&lt;code dir=&quot;auto&quot;&gt;_JSONErrorGroup&lt;/code&gt; trigger path) returns a JSON envelope with &lt;code dir=&quot;auto&quot;&gt;&quot;ok&quot;: false&lt;/code&gt;, using
&lt;code dir=&quot;auto&quot;&gt;typer.Exit&lt;/code&gt; (not &lt;code dir=&quot;auto&quot;&gt;click.exceptions.Exit&lt;/code&gt;) as the expected exit-code exception class.
This test is the canary for the specific regression mode we observed.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;hashlib.sha256&lt;/code&gt; usage inside &lt;code dir=&quot;auto&quot;&gt;tests/&lt;/code&gt; is banned by ruff.&lt;/strong&gt; Tests that need to
compute a production-format hash must import and call the canonical helper. The rule
prevents future test helpers from diverging silently from the algorithm they are
supposed to exercise.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;E2e conftest is self-contained.&lt;/strong&gt; The conftest synthesizes &lt;code dir=&quot;auto&quot;&gt;metadata.yaml&lt;/code&gt; using
the production &lt;code dir=&quot;auto&quot;&gt;charter.hasher.hash_content()&lt;/code&gt; helper immediately after &lt;code dir=&quot;auto&quot;&gt;copytree&lt;/code&gt;,
rather than disabling preflight. This closes the “fixture inherits machine state”
gap; any future preflight precondition must also be synthesized in the fixture.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;click.exceptions&lt;/code&gt; is a banned import in &lt;code dir=&quot;auto&quot;&gt;tests/&lt;/code&gt;.&lt;/strong&gt; Ruff &lt;code dir=&quot;auto&quot;&gt;banned-api&lt;/code&gt; rule covers
&lt;code dir=&quot;auto&quot;&gt;click.exceptions.Exit&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;click.exceptions.UsageError&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;click.exceptions.Abort&lt;/code&gt;.
The allowed public surface for assertion is &lt;code dir=&quot;auto&quot;&gt;typer.Exit&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;typer.BadParameter&lt;/code&gt;, etc.&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&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;Local and CI environments are now described by the same lockfile contract. Any
dependency upgrade is visible, deliberate, and reviewed in a PR via &lt;code dir=&quot;auto&quot;&gt;uv.lock&lt;/code&gt; diff.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;_JSONErrorGroup&lt;/code&gt; regression mode now has a test that would have caught it at the
time it was introduced (i.e., at the first &lt;code dir=&quot;auto&quot;&gt;uv.lock&lt;/code&gt; update that bumped typer).&lt;/li&gt;
&lt;li&gt;Lint rules enforce both bans (re-implemented algorithms, direct click imports) without
requiring human attention in review.&lt;/li&gt;
&lt;li&gt;The e2e fixture is reproducible across any fresh clone, eliminating a class of
“works on my machine” CI failures.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;CI install time increases slightly (uv resolves and installs from lockfile rather than
just latest-compatible). Measured impact is expected to be under 5 seconds per job
given uv’s speed.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;uv.lock&lt;/code&gt; must be kept current; PRs that add or change dependencies must also update
the lockfile. &lt;code dir=&quot;auto&quot;&gt;uv lock --check&lt;/code&gt; already enforces this (NFR-005 gate, job
&lt;code dir=&quot;auto&quot;&gt;uv-lock-check&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;hashlib.sha256&lt;/code&gt; ban in &lt;code dir=&quot;auto&quot;&gt;tests/&lt;/code&gt; may produce false positives for tests that
legitimately compute a raw SHA-256 (e.g., testing a hashing utility’s output, PKCE
challenges, body/file-integrity checksums). Those tests must carry an inline
&lt;code dir=&quot;auto&quot;&gt;# noqa: TID251 — &amp;#x3C;justification&gt;&lt;/code&gt; suppression (the configured rule is &lt;code dir=&quot;auto&quot;&gt;TID251&lt;/code&gt;,
flake8-tidy-imports banned-api — there is no &lt;code dir=&quot;auto&quot;&gt;SC001&lt;/code&gt; rule). The ban is enforced
per-call across the whole &lt;code dir=&quot;auto&quot;&gt;tests/&lt;/code&gt; tree by the dedicated
&lt;code dir=&quot;auto&quot;&gt;[ENFORCED] banned-API lint gate (TID251)&lt;/code&gt; step in &lt;code dir=&quot;auto&quot;&gt;ci-quality.yml&lt;/code&gt;; there are no
whole-directory exemptions that could silently disarm it.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;The typer version-compatibility smoke test does not replace the full envelope contract
test suite; it is additive. Existing tests continue to run unchanged.&lt;/li&gt;
&lt;li&gt;No production code changes are required by this ADR; all changes are in CI
configuration, test infrastructure, and lint configuration.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;This ADR is considered fully implemented when:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;All &lt;code dir=&quot;auto&quot;&gt;pip install -e .[test]&lt;/code&gt; blocks in &lt;code dir=&quot;auto&quot;&gt;ci-quality.yml&lt;/code&gt; are replaced with
&lt;code dir=&quot;auto&quot;&gt;uv sync --frozen&lt;/code&gt; and CI continues to pass.&lt;/li&gt;
&lt;li&gt;A failing test exists in &lt;code dir=&quot;auto&quot;&gt;fast-tests-agent&lt;/code&gt; that would have caught the
&lt;code dir=&quot;auto&quot;&gt;_JSONErrorGroup&lt;/code&gt; / typer 0.26 regression.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;ruff check tests/&lt;/code&gt; flags any new introduction of &lt;code dir=&quot;auto&quot;&gt;hashlib.sha256&lt;/code&gt; or
&lt;code dir=&quot;auto&quot;&gt;click.exceptions.*&lt;/code&gt; in the test tree.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/e2e/conftest.py&lt;/code&gt; synthesizes &lt;code dir=&quot;auto&quot;&gt;metadata.yaml&lt;/code&gt; using the production helper and
does not rely on &lt;code dir=&quot;auto&quot;&gt;preflight.enabled: false&lt;/code&gt; as the solution.&lt;/li&gt;
&lt;li&gt;The full CI pipeline passes on a clean clone with no gitignored files present.&lt;/li&gt;
&lt;/ol&gt;
&lt;hr&gt;
&lt;h2 id=&quot;assessment-does-this-remediate-the-problem&quot;&gt;Assessment: Does This Remediate the Problem?&lt;/h2&gt;
&lt;p&gt;The five changes directly address the five structural gaps identified in the retrospective.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Gap 1 (resolver mismatch):&lt;/strong&gt; Switching to &lt;code dir=&quot;auto&quot;&gt;uv sync --frozen&lt;/code&gt; eliminates the
divergence entirely. There is no longer a path where CI resolves a different version of
any dependency than local development. Future version upgrades are explicit lockfile
changes that go through PR review.&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Implementation note (second-pass fix, CI run 26565789745):&lt;/strong&gt; The initial
implementation of &lt;code dir=&quot;auto&quot;&gt;uv sync --frozen&lt;/code&gt; omitted the &lt;code dir=&quot;auto&quot;&gt;--all-extras&lt;/code&gt; flag. Since pytest,
pytest-cov, ruff, and mypy live in &lt;code dir=&quot;auto&quot;&gt;[project.optional-dependencies.test]&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;[project.optional-dependencies.lint]&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;uv sync --frozen&lt;/code&gt; without &lt;code dir=&quot;auto&quot;&gt;--all-extras&lt;/code&gt;
produced a venv that was missing pytest entirely, causing every test job to fail with
&lt;code dir=&quot;auto&quot;&gt;No module named pytest&lt;/code&gt;. All 37 non-infrastructure &lt;code dir=&quot;auto&quot;&gt;uv sync --frozen&lt;/code&gt; invocations in
&lt;code dir=&quot;auto&quot;&gt;ci-quality.yml&lt;/code&gt; were corrected to &lt;code dir=&quot;auto&quot;&gt;uv sync --frozen --all-extras&lt;/code&gt;. The three exempt
infrastructure jobs (&lt;code dir=&quot;auto&quot;&gt;uv-lock-check&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;build-wheel&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;clean-install-verification&lt;/code&gt;) had
no &lt;code dir=&quot;auto&quot;&gt;uv sync&lt;/code&gt; calls and were unaffected.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;&lt;strong&gt;Gap 2 (no version-compatibility test):&lt;/strong&gt; The smoke test is narrow by design — it
covers the exact trigger path (&lt;code dir=&quot;auto&quot;&gt;_JSONErrorGroup&lt;/code&gt; with no subcommand) that silently broke
in production. A broader matrix test would provide more coverage but is out of scope for
this ADR; the single test is the canary that was missing.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Gap 3 (re-implemented algorithms):&lt;/strong&gt; The ruff ban is permanent and automated.
Copy-pasted algorithm implementations will be caught on the next &lt;code dir=&quot;auto&quot;&gt;ruff check&lt;/code&gt; run before
they are committed. The rule does not fix existing divergence in other tests; that
requires a separate audit.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Gap 4 (gitignored state in e2e):&lt;/strong&gt; The conftest change makes the fixture
self-describing. This is a point fix for &lt;code dir=&quot;auto&quot;&gt;metadata.yaml&lt;/code&gt;; it does not generalize to
every possible gitignored file that might be needed in future. The design principle
established here — conftest synthesizes all required state — is the convention for
future e2e fixtures.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Gap 5 (direct click imports):&lt;/strong&gt; The ruff rule catches the symptom (direct use of
&lt;code dir=&quot;auto&quot;&gt;click.exceptions.*&lt;/code&gt; in tests) but does not prevent future production code from using
the wrong exception class. The production-side fix (the &lt;code dir=&quot;auto&quot;&gt;_CLICK_USAGE_ERRORS&lt;/code&gt; shim in
&lt;code dir=&quot;auto&quot;&gt;_JSONErrorGroup&lt;/code&gt;) is already in place. Together, both layers are required: the
production shim handles version drift in runtime behavior; the lint rule prevents tests
from silently depending on the wrong class for assertions.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;GitHub Actions run 26558837157 — full CI run that surfaced all four failure modes.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/orchestrator_api/commands.py&lt;/code&gt; — &lt;code dir=&quot;auto&quot;&gt;_JSONErrorGroup&lt;/code&gt; and the
&lt;code dir=&quot;auto&quot;&gt;_CLICK_USAGE_ERRORS&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;_CLICK_ABORTS&lt;/code&gt; compatibility shim.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/e2e/conftest.py&lt;/code&gt; — e2e fixture and the &lt;code dir=&quot;auto&quot;&gt;preflight.enabled: false&lt;/code&gt; workaround
being replaced by this ADR.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/integration/test_quickstart_end_to_end.py&lt;/code&gt; — charter hash fix.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;architecture/adrs/2026-02-21-1-consistent-code-style-enforcement-via-git-hooks.md&lt;/code&gt;
— related ADR on automated style enforcement.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;[tool.ruff]&lt;/code&gt; section — location of banned-api rules.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
