<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/development/reference/ci-gate-mechanics/">
  <id>https://docs.spec-kitty.ai/development/reference/ci-gate-mechanics/</id>
  <title>CI and Architectural Gate Mechanics</title>
  <updated>2026-11-12T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/development/reference/ci-gate-mechanics/"/>
  <summary>What trips each spec-kitty CI gate — marker gates, the architectural battery, docs-freshness registration, and accept-to-consolidate close-out — with symptom and repro.</summary>
  <content type="html">&lt;span id=&quot;ci-and-architectural-gate-mechanics&quot;&gt;&lt;/span&gt;
&lt;p&gt;Many spec-kitty gates pass a naive local run and only go red ~40 minutes into
CI, because they live in shards a fast local run never selects. This page maps
the durable, repeatable ones: &lt;strong&gt;what trips each gate, the symptom it produces,
and the command that reproduces it locally&lt;/strong&gt; so you can catch it before pushing.&lt;/p&gt;
&lt;p&gt;It is a mechanics reference, not a status page — for the &lt;em&gt;current&lt;/em&gt; red list and
fast-drifting toggles see &lt;a href=&quot;/development/reference/known-friction-points/&quot;&gt;Known Current Friction
Points&lt;/a&gt;; for what a red &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; means see &lt;a href=&quot;/development/reference/red-main-and-release-readiness/&quot;&gt;Red Main and
Release Readiness&lt;/a&gt;.&lt;/p&gt;
&lt;h2 id=&quot;how-ci-is-wired-so-a-local-run-can-mirror-it&quot;&gt;How CI is wired (so a local run can mirror it)&lt;/h2&gt;
&lt;p&gt;CI runs as a lean modular pipeline: a path router (&lt;code dir=&quot;auto&quot;&gt;ci-router.yml&lt;/code&gt;) decides which
module and data shards are affected, per-module test jobs run
(&lt;code dir=&quot;auto&quot;&gt;module-tests.yml&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;ci-modules.yml&lt;/code&gt;), and results aggregate with a coverage
and diff-cover gate (&lt;code dir=&quot;auto&quot;&gt;ci-aggregate.yml&lt;/code&gt;); a nightly full run (&lt;code dir=&quot;auto&quot;&gt;ci-nightly.yml&lt;/code&gt;)
and a fork-safe Sonar scan (&lt;code dir=&quot;auto&quot;&gt;sonar.yml&lt;/code&gt;) sit alongside. The nightly’s &lt;code dir=&quot;auto&quot;&gt;performance&lt;/code&gt;
job runs weekly, on the Sunday run only, or on a manual &lt;code dir=&quot;auto&quot;&gt;workflow_dispatch&lt;/code&gt; (#7704);
its red still opens the deduped &lt;code dir=&quot;auto&quot;&gt;performance&lt;/code&gt; P0, and the next green weekly run closes it. The trap is structural:
&lt;strong&gt;a passing &lt;code dir=&quot;auto&quot;&gt;pytest &amp;#x3C;file&gt;&lt;/code&gt; locally does not mean a gate will be green&lt;/strong&gt;, because
the gate that fails may run in a different shard, under a different marker
selection, or only over paths your diff happened to touch.&lt;/p&gt;
&lt;p&gt;Two habits defuse most of this class:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Reproduce a gate by running its &lt;strong&gt;exact selection&lt;/strong&gt;, not just the test file —
e.g. a marker-scoped shard runs &lt;code dir=&quot;auto&quot;&gt;-m &quot;fast and not windows_ci&quot;&lt;/code&gt;, so a test
missing the &lt;code dir=&quot;auto&quot;&gt;fast&lt;/code&gt; marker is silently deselected there even though it passes
when you name it directly.&lt;/li&gt;
&lt;li&gt;Before declaring a branch green, run the architectural gate files your change
implicates over the &lt;strong&gt;rebased tip&lt;/strong&gt;. Do not sweep the whole
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/&lt;/code&gt; directory in mission work (&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty-open-packs/blob/main/packs/internal/directives/no-full-heavy-suites-in-mission.directive.yaml&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;NO_FULL_HEAVY_SUITES_IN_MISSION&lt;/code&gt;&lt;/a&gt;); CI runs
the whole battery for you: the always-on &lt;code dir=&quot;auto&quot;&gt;architectural-fast&lt;/code&gt; job plus the two
&lt;code dir=&quot;auto&quot;&gt;architectural-heavy&lt;/code&gt; legs on code and CI-config PRs.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Since mission &lt;code dir=&quot;auto&quot;&gt;ci-runtime-stabilisation&lt;/code&gt; (&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5510&quot;&gt;#5510&lt;/a&gt;),
these things about that pipeline are worth knowing before you read a red check:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;The battery has three parts.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;architectural-fast&lt;/code&gt; is always on (docs-only PRs
included). Its roster of deterministic ratchet and census gates is held in
&lt;code dir=&quot;auto&quot;&gt;.github/ci-module-registry.yml&lt;/code&gt; under &lt;code dir=&quot;auto&quot;&gt;special_tiers.architectural.fast_gate&lt;/code&gt;,
with a per-file budget. &lt;code dir=&quot;auto&quot;&gt;architectural-heavy&lt;/code&gt; is one job key with a two-leg
matrix (&lt;code dir=&quot;auto&quot;&gt;--battery-part 1/2&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;2/2&lt;/code&gt;). The three parts are file-disjoint and
together cover the base selection exactly, which
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_battery_partition_proof.py&lt;/code&gt; proves statically.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;CI-config changes select the heavy battery.&lt;/strong&gt; The router path group
&lt;code dir=&quot;auto&quot;&gt;ci_config&lt;/code&gt; (workflows, composite actions, &lt;code dir=&quot;auto&quot;&gt;scripts/ci/**&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;pytest.ini&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;Makefile&lt;/code&gt;, the registry and the shard timings file) gates the
heavy battery and no other job.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;A change to a path a gate reads selects that gate (&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6994&quot;&gt;#6994&lt;/a&gt;).&lt;/strong&gt;
Many heavy gates also read paths outside their code scope. The clock bans, for
example, scan &lt;code dir=&quot;auto&quot;&gt;scripts/**&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;tests/**&lt;/code&gt;. Each such gate declares those paths
once, under &lt;code dir=&quot;auto&quot;&gt;special_tiers.architectural.scan_scopes&lt;/code&gt; in the registry.
&lt;code dir=&quot;auto&quot;&gt;scripts/ci/gate_selection.py&lt;/code&gt; derives the router group &lt;code dir=&quot;auto&quot;&gt;arch_scan_scope&lt;/code&gt; from
them, and &lt;code dir=&quot;auto&quot;&gt;ci-router.yml&lt;/code&gt; must list exactly that union. A diff that matches only
that group runs, in each heavy leg, only the gates whose scope it touches
(&lt;code dir=&quot;auto&quot;&gt;scripts/ci/battery_scope.py&lt;/code&gt; writes the list and the plugin reads it from
&lt;code dir=&quot;auto&quot;&gt;SK_BATTERY_GATES_FILE&lt;/code&gt;). A leg that holds none of them skips its run. A code
diff still runs every gate, and so does a change to a file the battery
imports outside &lt;code dir=&quot;auto&quot;&gt;tests/architectural/&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;tests/conftest.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tests/_support/**&lt;/code&gt;,
helper scripts), which is battery code, not a scan scope. When a new gate reads
outside its code scope, add its row to &lt;code dir=&quot;auto&quot;&gt;scan_scopes&lt;/code&gt;.
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_battery_scan_scope_routing.py&lt;/code&gt; proves the property
for every declared gate and glob.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;A declaration must be complete, and CI checks it (&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/7000&quot;&gt;#7000&lt;/a&gt;).&lt;/strong&gt;
A row is only as good as the read it describes: when a gate starts reading a new
root, a stale row lets routing miss it again. &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_gate_scan_scope_completeness.py&lt;/code&gt;
extracts, statically, every repository-rooted read a gate makes —
&lt;code dir=&quot;auto&quot;&gt;_REPO_ROOT / &quot;…&quot;&lt;/code&gt;, a chain built from it, a &lt;code dir=&quot;auto&quot;&gt;glob&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;rglob&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;iterdir&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;walk&lt;/code&gt;
call, a literal &lt;code dir=&quot;auto&quot;&gt;git ls-files&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;ls-tree -- &amp;#x3C;path&gt;&lt;/code&gt; pathspec, in the gate file
and in every &lt;code dir=&quot;auto&quot;&gt;tests/**&lt;/code&gt; helper it imports (absolute or relative) —
and fails when neither the gate’s &lt;code dir=&quot;auto&quot;&gt;scan_scopes&lt;/code&gt; row nor the battery code scope
(&lt;code dir=&quot;auto&quot;&gt;src/**&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tests/architectural/**&lt;/code&gt; and the router’s own code groups) covers it.
A read whose whole path is computed at runtime (&lt;code dir=&quot;auto&quot;&gt;_REPO_ROOT / rel&lt;/code&gt;) names no
repository path and is recorded rather than guessed at; a partly computed read
is checked at its literal parent. The only exemptions are reads that are not
repository reads at all — a synthetic probe path or an untracked scratch dir —
and each one carries a reason and goes stale-red. Adding a read therefore means
adding a glob, not editing the check. The scan is static, so it has known blind
spots (listed in the &lt;code dir=&quot;auto&quot;&gt;_gate_read_scope&lt;/code&gt; docstring): a gate that takes the root from
a pytest parameter (&lt;code dir=&quot;auto&quot;&gt;repo_root&lt;/code&gt;) or from a &lt;code dir=&quot;auto&quot;&gt;tmp_path&lt;/code&gt;, a pathspec passed through a
variable or through a helper whose call never names the root, and the reads of an
imported &lt;code dir=&quot;auto&quot;&gt;tests/conftest.py&lt;/code&gt; are not seen. It narrows the #6994 defect class; it does
not prove absence.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Corpus tests have one advisory owner.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;packs.yml&lt;/code&gt; runs the &lt;code dir=&quot;auto&quot;&gt;-m corpus&lt;/code&gt;
suite as the advisory job &lt;code dir=&quot;auto&quot;&gt;built-in / -m corpus suite (advisory)&lt;/code&gt;. The corpus
tests that have no other blocking per-PR home run blocking in two router jobs:
&lt;code dir=&quot;auto&quot;&gt;tests (corpus-blocking)&lt;/code&gt; (the modules that read the committed corpus) and
&lt;code dir=&quot;auto&quot;&gt;tests (contract tools)&lt;/code&gt; (the contract tool unit tests). The router jobs &lt;code dir=&quot;auto&quot;&gt;tests (cli)&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;tests (status)&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tests (consolidation)&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;tests (corpus)&lt;/code&gt; no longer exist;
the &lt;code dir=&quot;auto&quot;&gt;cli&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;status&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;consolidation&lt;/code&gt; module rows in &lt;code dir=&quot;auto&quot;&gt;ci-modules.yml&lt;/code&gt; are now
their only homes.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;That advisory lane’s budget is derived, not picked&lt;/strong&gt; (&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/7206&quot;&gt;#7206&lt;/a&gt;).
Over 55 advisory-job runs the job’s p95 was 20.3 min against the retired 20-minute cap —
102 % of it — and four runs were killed at the budget with no failing test, so an unrelated
PR read red. A PR run is mostly fixed cost: the whole &lt;code dir=&quot;auto&quot;&gt;tests/&lt;/code&gt; tree is collected
in every worker (1 624 corpus items come from 103 of 4 429 modules, ~8 min), the
content-addressed wall-clock policy scan has no cache on PR runs by design (~3.5 min), and
execution is ~6.3 min. Both fixed costs are architectural, so the cap is not bought with
coverage: a path shard or matrix would narrow the lane, which
&lt;code dir=&quot;auto&quot;&gt;tests/ci/test_corpus_blocking_home.py&lt;/code&gt; (tree-wide corpus reach, #3008) and
&lt;code dir=&quot;auto&quot;&gt;tests/ci/test_contracts_routing.py&lt;/code&gt; (exactly one pytest invocation) forbid. Instead the job
records its measured maximum and the cap follows the #5378 rule
(&lt;code dir=&quot;auto&quot;&gt;ceil((max-suite + 0:30) × 1.5)&lt;/code&gt; = 31), enforced by &lt;code dir=&quot;auto&quot;&gt;tests/ci/test_nightly_timeout_headroom.py&lt;/code&gt;;
the recorded maximum must stay within 75 % of the cap,
&lt;code dir=&quot;auto&quot;&gt;tests/ci/test_corpus_suite_budget.py&lt;/code&gt; holds that and the expiry behaviour: the suite step has
its own budget below the job cap, so a killed run still reaches a notice saying the run is
INCOMPLETE and advisory rather than reading as a failing test
(&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/4437&quot;&gt;#4437&lt;/a&gt;). Selection semantics — the
marker, the deselects, the &lt;code dir=&quot;auto&quot;&gt;continue-on-error&lt;/code&gt; and the trigger — are unchanged.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;A nightly backstop runs the whole battery.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;ci-nightly.yml&lt;/code&gt; job
&lt;code dir=&quot;auto&quot;&gt;architectural-backstop&lt;/code&gt; executes the full base selection with no partition
plugin, so a green nightly means the battery ran (see the amendment to
&lt;a href=&quot;/adr/3.x/2026-09-26-1-ci-coverage-honesty/&quot;&gt;ADR 2026-09-26-1&lt;/a&gt;).&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;A &lt;code dir=&quot;auto&quot;&gt;ready_for_review&lt;/code&gt; run can skip on prior evidence.&lt;/strong&gt; When the same workflow
already went green for the identical tested key, the selection step is
suppressed and the required gates post success. A re-run always executes. See
&lt;a href=&quot;#skip-if-green-on-ready-for-review&quot;&gt;Skip-if-green on ready-for-review&lt;/a&gt; below
and the amendment to
&lt;a href=&quot;/adr/3.x/2026-09-23-1-auto-merge-required-checks-gate/&quot;&gt;ADR 2026-09-23-1&lt;/a&gt;.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;The merge queue runs the required checks again.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;ci-router.yml&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;ci-modules.yml&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;ci-quality.yml&lt;/code&gt; also trigger on &lt;code dir=&quot;auto&quot;&gt;merge_group&lt;/code&gt;, so the
three required checks report on the queue’s temporary
&lt;code dir=&quot;auto&quot;&gt;gh-readonly-queue/main/...&lt;/code&gt; ref, which holds &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; plus the PRs ahead in
the queue. The changed-files and prose-scan steps diff a queue run against
&lt;code dir=&quot;auto&quot;&gt;github.event.merge_group.base_sha&lt;/code&gt;, so it is path-scoped like the PR run.
Skip-if-green never applies there, the &lt;code dir=&quot;auto&quot;&gt;pr:*&lt;/code&gt; label guards read no labels, CI
Aggregate skips queue runs (diff coverage was judged on the PR), and no
optional workflow joins the queue. &lt;code dir=&quot;auto&quot;&gt;tests/ci/test_merge_queue_wiring.py&lt;/code&gt; pins
this.&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The rest of this page groups gates by the change that trips them.&lt;/p&gt;
&lt;h2 id=&quot;testing-and-marker-gates&quot;&gt;Testing and marker gates&lt;/h2&gt;
&lt;p&gt;These fire when a test file’s markers, or the coverage a test contributes, do
not line up with the shard that is supposed to run it.&lt;/p&gt;
&lt;h3 id=&quot;a-test-with-the-wrong-marker-contributes-zero-ci-coverage&quot;&gt;A test with the wrong marker contributes zero CI coverage&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Trips it:&lt;/strong&gt; a new test carries the wrong (or too few) &lt;code dir=&quot;auto&quot;&gt;pytestmark&lt;/code&gt; markers,
so the shard meant to run it deselects it. Example: a test marked only &lt;code dir=&quot;auto&quot;&gt;unit&lt;/code&gt;
when its shard selects &lt;code dir=&quot;auto&quot;&gt;-m &quot;fast and ...&quot;&lt;/code&gt; never runs in CI.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Symptom:&lt;/strong&gt; the diff-coverage gate (&lt;code dir=&quot;auto&quot;&gt;ci-aggregate.yml&lt;/code&gt;) goes red on a source
file that &lt;em&gt;has&lt;/em&gt; a passing test — because that test never executed in CI. Named
directly (&lt;code dir=&quot;auto&quot;&gt;pytest &amp;#x3C;file&gt; --cov&lt;/code&gt;) it shows full coverage locally, which hides
the problem.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fix / repro:&lt;/strong&gt; give the new test the same speed + domain markers its
siblings use (typically &lt;code dir=&quot;auto&quot;&gt;fast&lt;/code&gt; plus the module’s domain marker). Reproduce the
shard’s real selection locally — run &lt;code dir=&quot;auto&quot;&gt;pytest &amp;#x3C;dir&gt; -m &quot;fast and not windows_ci&quot;&lt;/code&gt; — not just &lt;code dir=&quot;auto&quot;&gt;pytest &amp;#x3C;file&gt;&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;a-file-with-two-markers-can-fall-between-two-shards&quot;&gt;A file with two markers can fall between two shards&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Trips it:&lt;/strong&gt; a test file carries two markers whose CI jobs &lt;em&gt;mutually exclude&lt;/em&gt;
it (e.g. both &lt;code dir=&quot;auto&quot;&gt;distribution&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;e2e&lt;/code&gt;, where the e2e shard runs &lt;code dir=&quot;auto&quot;&gt;-m &quot;not distribution&quot;&lt;/code&gt; and the other shard ignores the e2e directory). The file
reaches no gate at all.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Symptom:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_marker_job_completeness.py&lt;/code&gt; goes red —
each routed marker gained a carrier that no job selects. This runs in an
architectural shard, so it only surfaces on CI.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fix / repro:&lt;/strong&gt; make sure the file is positively selected by at least one job.
The minimal fix is a complementary pytest step in an existing job (e.g. add a
&lt;code dir=&quot;auto&quot;&gt;-m &quot;distribution and e2e and not windows_ci&quot;&lt;/code&gt; pass over the e2e directory);
the completeness gate auto-discovers it. Run
&lt;code dir=&quot;auto&quot;&gt;pytest tests/architectural/test_marker_job_completeness.py&lt;/code&gt; before pushing.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;a-new-test-file-must-declare-a-marker&quot;&gt;A new test file must declare a marker&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Trips it:&lt;/strong&gt; a new &lt;code dir=&quot;auto&quot;&gt;tests/**/test_*.py&lt;/code&gt; file lands without a module-level
&lt;code dir=&quot;auto&quot;&gt;pytestmark&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Symptom:&lt;/strong&gt; an architectural marker-convention gate reds, insisting every test
file declare &lt;em&gt;some&lt;/em&gt; marker. It is distinct from the completeness gate above —
and distinct from the marker-baseline gate below — so one can be green while
another is red.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fix / repro:&lt;/strong&gt; add &lt;code dir=&quot;auto&quot;&gt;pytestmark = [pytest.mark.unit, pytest.mark.fast]&lt;/code&gt; (or
the markers the file’s siblings use) at module scope. When a fold adds or moves
a test file, run the marker-related tests in &lt;code dir=&quot;auto&quot;&gt;tests/architectural/&lt;/code&gt;, not just
one of them.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;moving-a-slow--stress--quarantine-test-can-red-the-marker-baseline&quot;&gt;Moving a slow / stress / quarantine test can red the marker baseline&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Trips it:&lt;/strong&gt; relocating or renaming a test that carries a budget marker
(&lt;code dir=&quot;auto&quot;&gt;slow&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;stress&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;quarantine&lt;/code&gt;). Its node-id changes, so the pinned baseline
set gains a “new” node and loses the old one, and the growth check reads that
as new slow surface.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Symptom:&lt;/strong&gt; the marker-baseline architectural gate reds even though it is the
same test with the same marker.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fix / repro:&lt;/strong&gt; do a documented one-for-one swap in the baseline — remove the
old node-id, add the new one, and add a dated comment noting it is the same
node relocated (no net-new slow surface). This is legitimate; a blanket
baseline “update” that hides a genuinely new slow test is not. This gate is
easy to miss because it is not in the fast shard.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;new-contractsmd-yaml-blocks-need-a-round-trip-skip-marker&quot;&gt;New &lt;code dir=&quot;auto&quot;&gt;contracts/*.md&lt;/code&gt; YAML blocks need a round-trip skip marker&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Trips it:&lt;/strong&gt; the router job &lt;code dir=&quot;auto&quot;&gt;tests (corpus-blocking)&lt;/code&gt; (job key
&lt;code dir=&quot;auto&quot;&gt;tests-corpus-blocking&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;ci-router.yml&lt;/code&gt;) runs
&lt;code dir=&quot;auto&quot;&gt;tests/contract/test_example_round_trip.py&lt;/code&gt;, which walks
&lt;strong&gt;every&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;kitty-specs/*/contracts/*.md&lt;/code&gt; and collects each fenced &lt;code dir=&quot;auto&quot;&gt;```yaml&lt;/code&gt;
block as a contract-example case. A block in a non-legacy file that is neither
executable nor marked as an illustration fails.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Symptom:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;test_contract_example_round_trip[...MISSING_FRONTMATTER]&lt;/code&gt; fails,
reddening &lt;code dir=&quot;auto&quot;&gt;tests (corpus-blocking)&lt;/code&gt;. The Packs advisory corpus job deselects
this file, so a red here is blocking, not advisory. A local run of &lt;code dir=&quot;auto&quot;&gt;tests/ci&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;tests/architectural&lt;/code&gt;
(the obvious blast radius for a CI change) does &lt;strong&gt;not&lt;/strong&gt; cover
&lt;code dir=&quot;auto&quot;&gt;tests/contract/&lt;/code&gt;, so illustrative YAML passes locally and only reds on CI.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Fix / repro:&lt;/strong&gt; tag each YAML block with one of, as its first line inside the
fence:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;# pydantic_model: &amp;#x3C;Model&gt;&lt;/code&gt; — executed against that model, or&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;# round-trip: skip: &amp;#x3C;reason&gt;&lt;/code&gt; — non-executable illustration; the reason is
mandatory (a bare marker still fails).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Run &lt;code dir=&quot;auto&quot;&gt;pytest tests/contract/test_example_round_trip.py&lt;/code&gt; locally before pushing.&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;the-pre-review-gate-can-run-the-full-suite-and-hang&quot;&gt;The pre-review gate can run the full suite and hang&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Trips it:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent action implement WP##&lt;/code&gt; (and &lt;code dir=&quot;auto&quot;&gt;review&lt;/code&gt;, and
&lt;code dir=&quot;auto&quot;&gt;move-task --to for_review&lt;/code&gt;) trigger the auto-scoped pre-review regression gate
(&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/review/pre_review_gate.py&lt;/code&gt;, baseline capture in
&lt;code dir=&quot;auto&quot;&gt;review/baseline.py&lt;/code&gt;). When the auto-scope resolves broadly it runs
effectively the whole suite with no path arguments.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Symptom:&lt;/strong&gt; the CLI hangs with no output for a very long time, blocked waiting
on the pytest child; parallel workers each doing this pin every core.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fix / repro:&lt;/strong&gt; set &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_SKIP_PRE_REVIEW_GATE=1&lt;/code&gt; on the lifecycle
command (this is the canonical opt-out; it no longer reads the retired
sync-disable vocabulary). The claim still succeeds — the WP moves to
&lt;code dir=&quot;auto&quot;&gt;in_progress&lt;/code&gt; and the worktree is created — even if baseline capture times out.
To make the baseline itself cheap, declare a fast &lt;code dir=&quot;auto&quot;&gt;review.test_command&lt;/code&gt; in
&lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt; (a local, uncommitted no-op command is legitimate;
revert it at mission end). If a killed gate leaves a stale run-lock or orphaned
pytest children, remove them before retrying. Rely on targeted per-WP tests
plus CI for breadth, never the full suite in-session.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;the-architectural-gate-battery&quot;&gt;The architectural gate battery&lt;/h2&gt;
&lt;p&gt;Adding new &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; symbols and new test files trips a battery of architectural
gates that each pass in isolation but only surface together in CI’s
architectural jobs: the always-on &lt;code dir=&quot;auto&quot;&gt;architectural-fast&lt;/code&gt; job and the two legs of
&lt;code dir=&quot;auto&quot;&gt;architectural-heavy&lt;/code&gt; (a code-scoped job whose failure reds the router gate).
Pre-run the targeted gate files before pushing. A useful invocation base
for these is &lt;code dir=&quot;auto&quot;&gt;PYTHONPATH=src -o addopts=&quot;&quot;&lt;/code&gt; so collection matches CI.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Dead-symbol gate&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_no_dead_symbols.py&lt;/code&gt;): a new
public symbol in a module’s &lt;code dir=&quot;auto&quot;&gt;__all__&lt;/code&gt; that no other &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; file imports fails.
Fix by trimming &lt;code dir=&quot;auto&quot;&gt;__all__&lt;/code&gt; to genuinely public symbols — test-only helpers stay
importable but out of &lt;code dir=&quot;auto&quot;&gt;__all__&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Dead-module gate&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_no_dead_modules.py&lt;/code&gt;): a new
module with zero non-test &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; importer fails — even a &lt;code dir=&quot;auto&quot;&gt;python -m&lt;/code&gt; entry
point launched by an argv string, because that is not a static import. Fix by
&lt;em&gt;wiring&lt;/em&gt; it: have the launcher reference the module by name
(&lt;code dir=&quot;auto&quot;&gt;from . import _server_main; MODULE = _server_main.__name__&lt;/code&gt;) rather than a
string literal, so it is statically reachable and rename-safe.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Clock call-ban&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_clock_call_ban.py&lt;/code&gt;):
&lt;code dir=&quot;auto&quot;&gt;time.time()&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;.now()&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;.utcnow()&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;.today()&lt;/code&gt; anywhere (including tests)
outside &lt;code dir=&quot;auto&quot;&gt;src/kernel/clock.py&lt;/code&gt; fails. Import from &lt;code dir=&quot;auto&quot;&gt;kernel.clock&lt;/code&gt; instead.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Clock import-ban&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_clock_import_ban.py&lt;/code&gt;, distinct
from the call-ban): a raw &lt;code dir=&quot;auto&quot;&gt;import datetime&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;from datetime import ...&lt;/code&gt;
anywhere outside &lt;code dir=&quot;auto&quot;&gt;src/kernel/clock.py&lt;/code&gt; fails. Import from &lt;code dir=&quot;auto&quot;&gt;kernel.clock&lt;/code&gt;, or
add an exemption line under &lt;code dir=&quot;auto&quot;&gt;tests/architectural/_exemptions/&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Charter facade table&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_charter_facades_reexport_offering.py&lt;/code&gt;):
this self-discovers every &lt;code dir=&quot;auto&quot;&gt;src/charter/*.py&lt;/code&gt;, so a new charter facade that
re-exports a &lt;code dir=&quot;auto&quot;&gt;charter.offering&lt;/code&gt; symbol in its &lt;code dir=&quot;auto&quot;&gt;__all__&lt;/code&gt; must be registered in the
facade table. It runs in an architectural shard, invisible to fast-shard local
runs.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Environment-fragile absolute counts:&lt;/strong&gt; integration jobs run
&lt;code dir=&quot;auto&quot;&gt;uv sync --frozen --all-extras&lt;/code&gt;, which installs and imports more optional
dependencies than a local checkout. An absolute module-count or import-count
assertion (&lt;code dir=&quot;auto&quot;&gt;len(modules) &amp;#x3C;= N&lt;/code&gt;) passes locally and false-reds on CI. Assert a
specific module’s presence or absence, never an absolute count.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;fast-roster-shard-legs-and-the-partition-proof&quot;&gt;Fast roster, shard legs, and the partition proof&lt;/h3&gt;
&lt;p&gt;The battery base selection is &lt;code dir=&quot;auto&quot;&gt;tests/architectural&lt;/code&gt; with the marker expression
&lt;code dir=&quot;auto&quot;&gt;not performance and not stress and not timing&lt;/code&gt;, minus the four files that other
always-on lanes own (&lt;code dir=&quot;auto&quot;&gt;test_no_legacy_terminology.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;test_layer_rules.py&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;test_pyproject_shape.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;test_archive_root_byte_identical.py&lt;/code&gt;). It runs as:&lt;/p&gt;



































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Part&lt;/th&gt;&lt;th&gt;Job (display name)&lt;/th&gt;&lt;th&gt;Selection&lt;/th&gt;&lt;th&gt;When&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;Fast&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;architectural fast gates (ratchet/census, always-on)&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;--battery-part fast&lt;/code&gt;: the registry roster&lt;/td&gt;&lt;td&gt;every PR shape&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Heavy leg 1&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;architectural battery (heavy, code-scoped) 1/2&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;--battery-part 1/2&lt;/code&gt;&lt;/td&gt;&lt;td&gt;code, &lt;code dir=&quot;auto&quot;&gt;ci_config&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;architectural&lt;/code&gt; path changes; for a diff that matches only &lt;code dir=&quot;auto&quot;&gt;arch_scan_scope&lt;/code&gt;, the leg’s gates whose declared scan scope the diff touches. A &lt;strong&gt;prose-only&lt;/strong&gt; diff (#4842) runs the same scoped selection when it touches a declared scan scope, and skips the battery when it declares none (#6999)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Heavy leg 2&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;architectural battery (heavy, code-scoped) 2/2&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;--battery-part 2/2&lt;/code&gt;&lt;/td&gt;&lt;td&gt;same as leg 1&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Backstop&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;Architectural battery backstop (nightly-only, #5510)&lt;/code&gt;&lt;/td&gt;&lt;td&gt;the base, no partition flag&lt;/td&gt;&lt;td&gt;nightly&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Prose-only diffs and the declared scopes (#6999, operator ruling 2026-11-01).&lt;/strong&gt; A
PR whose whole Python diff is comments and/or docstrings is down-routed off the
module matrix and every code shard (&lt;code dir=&quot;auto&quot;&gt;scripts/ci/prose_only.py&lt;/code&gt;, published as
&lt;code dir=&quot;auto&quot;&gt;prose-scan&lt;/code&gt;’s &lt;code dir=&quot;auto&quot;&gt;prose_only&lt;/code&gt; output). The heavy battery is exempted from that
subtraction for a &lt;strong&gt;declared&lt;/strong&gt; scan-scope match: &lt;code dir=&quot;auto&quot;&gt;prose-scan&lt;/code&gt; also publishes
&lt;code dir=&quot;auto&quot;&gt;scan_scope_match&lt;/code&gt; (the &lt;code dir=&quot;auto&quot;&gt;arch_scan_scope&lt;/code&gt; globs, read through
&lt;code dir=&quot;auto&quot;&gt;gate_selection.matches_declared_scan_scope&lt;/code&gt;), the battery &lt;code dir=&quot;auto&quot;&gt;if:&lt;/code&gt; runs when
&lt;code dir=&quot;auto&quot;&gt;prose_only != &apos;true&apos;&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;scan_scope_match == &apos;true&apos;&lt;/code&gt;, and the selection step
passes the verdict on (&lt;code dir=&quot;auto&quot;&gt;battery_scope select --prose-only&lt;/code&gt;) so each leg runs
&lt;strong&gt;only&lt;/strong&gt; the gates whose &lt;code dir=&quot;auto&quot;&gt;scan_scopes&lt;/code&gt; declaration matches. A prose-only diff
that matches no declared scope still skips the battery. The companion output,
rather than a second reference to &lt;code dir=&quot;auto&quot;&gt;needs.changes.outputs.arch_scan_scope&lt;/code&gt;, keeps
the parsed group set honest: deleting the group’s own OR term still reds
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_battery_scan_scope_routing.py&lt;/code&gt;. Declared scopes only:
for a prose-only diff the battery relies on the &lt;code dir=&quot;auto&quot;&gt;scan_scopes&lt;/code&gt; rows being
complete (checked by &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_gate_scan_scope_completeness.py&lt;/code&gt;,
#7016), so a gate that reads prose more widely than its declared scope is
skipped for a prose edit outside that scope.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The roster is registry-held.&lt;/strong&gt; Each entry in
&lt;code dir=&quot;auto&quot;&gt;special_tiers.architectural.fast_gate.roster&lt;/code&gt; carries a path, a
&lt;code dir=&quot;auto&quot;&gt;budget_seconds&lt;/code&gt; and a reason. A file earns a roster slot only if it is a
deterministic static gate, so a new slow or CLI-round-trip file belongs in the
heavy legs. The budgets are checked statically against the committed timings by
&lt;code dir=&quot;auto&quot;&gt;tests/ci/test_battery_roster_budgets.py&lt;/code&gt;, never against wall-clock time.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Adding or moving a battery test file&lt;/strong&gt; needs no workflow edit: the plugin
&lt;code dir=&quot;auto&quot;&gt;scripts/ci/battery_partition_plugin.py&lt;/code&gt; assigns each file to exactly one part
from the per-file timings in &lt;code dir=&quot;auto&quot;&gt;.github/ci-shard-timings.json&lt;/code&gt;. A file with no
timing gets the median weight, and a timing-set mismatch prints a &lt;code dir=&quot;auto&quot;&gt;::warning::&lt;/code&gt;
rather than silently using uniform weights.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A partition-proof red&lt;/strong&gt; means a file is in two parts or in none. The proof
(&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_battery_partition_proof.py&lt;/code&gt;) evaluates the three
literal &lt;code dir=&quot;auto&quot;&gt;--battery-part&lt;/code&gt; commands, so fix the roster or the timings, not the
proof.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Worker count&lt;/strong&gt; is a literal &lt;code dir=&quot;auto&quot;&gt;-n 4&lt;/code&gt; in every CI battery command; see
&lt;a href=&quot;/development/testing/testing-parallel/#ci-worker-policy-and-the-nightly-architectural-backstop&quot;&gt;CI worker policy&lt;/a&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;skip-if-green-on-ready-for-review&quot;&gt;Skip-if-green on ready-for-review&lt;/h3&gt;
&lt;p&gt;When a draft PR is marked ready for review, the head SHA has usually already been
tested. The selection jobs (router &lt;code dir=&quot;auto&quot;&gt;changes&lt;/code&gt;, CI Modules &lt;code dir=&quot;auto&quot;&gt;generate-matrix&lt;/code&gt;, Packs
&lt;code dir=&quot;auto&quot;&gt;changes&lt;/code&gt;) therefore run &lt;code dir=&quot;auto&quot;&gt;scripts/ci/green_match.py decide&lt;/code&gt; first. It suppresses
the path-filter step, and so every path-gated job, only when all of these hold:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;the event is a &lt;code dir=&quot;auto&quot;&gt;pull_request&lt;/code&gt; with the action &lt;code dir=&quot;auto&quot;&gt;ready_for_review&lt;/code&gt;, on the first
attempt of the run;&lt;/li&gt;
&lt;li&gt;a completed, successful run of the same workflow exists for the same head SHA;&lt;/li&gt;
&lt;li&gt;that run carries a non-expired marker artifact &lt;code dir=&quot;auto&quot;&gt;ci-tested-key-pr&amp;#x3C;N&gt;-base-&amp;#x3C;sha&gt;&lt;/code&gt;
for the identical tested key &lt;code dir=&quot;auto&quot;&gt;(workflow file, PR, head SHA, first parent of the merge commit the run tested)&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The required contexts &lt;code dir=&quot;auto&quot;&gt;router gate&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;CI Modules gate&lt;/code&gt; still post success. On a
skip run the always-on lanes and &lt;code dir=&quot;auto&quot;&gt;prose-scan&lt;/code&gt; still run, and &lt;code dir=&quot;auto&quot;&gt;tests (docs)&lt;/code&gt; still
runs on a prose-only PR.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Symptom of a surprise skip:&lt;/strong&gt; a &lt;code dir=&quot;auto&quot;&gt;ready_for_review&lt;/code&gt; run finished with every path-gated
shard skipped, and the step summary names a matched run.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Escape hatch:&lt;/strong&gt; re-run the workflow. Attempt 2 always executes.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Never suppressed:&lt;/strong&gt; push, &lt;code dir=&quot;auto&quot;&gt;workflow_dispatch&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;workflow_call&lt;/code&gt;, schedule, any
other &lt;code dir=&quot;auto&quot;&gt;pull_request&lt;/code&gt; action, a failed, cancelled or in-progress prior run, a
moved base, and any lookup error (the helper runs normally and warns).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;CI Aggregate&lt;/strong&gt; re-points to the matched CI Modules run after re-verifying it,
and fails with “re-run CI Modules to execute” if it cannot. Re-run CI Modules,
not Aggregate.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;moving-or-renaming-a-symbol-that-is-dead-symbol-allowlisted&quot;&gt;Moving or renaming a symbol that is dead-symbol allowlisted&lt;/h3&gt;
&lt;p&gt;The dead-symbol allowlist lives in &lt;code dir=&quot;auto&quot;&gt;tests/architectural/dead_symbol_allowlist.yaml&lt;/code&gt;
and is keyed by &lt;code dir=&quot;auto&quot;&gt;(module, name)&lt;/code&gt;: &lt;code dir=&quot;auto&quot;&gt;module&lt;/code&gt; is the module whose &lt;code dir=&quot;auto&quot;&gt;__all__&lt;/code&gt; declares
the name. No body hash is stored
(&lt;a href=&quot;/adr/4.x/2026-10-01-1-dead-symbol-allowlist-module-name-identity/&quot;&gt;ADR 2026-10-01-1&lt;/a&gt;).&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Editing the body&lt;/strong&gt; of an allowlisted symbol costs nothing: no allowlist edit.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Renaming or moving&lt;/strong&gt; one makes the gate report the old entry &lt;code dir=&quot;auto&quot;&gt;GONE&lt;/code&gt; (for a
move, with a “probably moved to &lt;code dir=&quot;auto&quot;&gt;X&lt;/code&gt;” hint) and the new location as an
offender. Update &lt;code dir=&quot;auto&quot;&gt;module:&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;name:&lt;/code&gt; of that entry in the YAML file.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Adding an entry&lt;/strong&gt; needs a declared &lt;code dir=&quot;auto&quot;&gt;category_*&lt;/code&gt;, a rationale (its own or
inherited from the category — see
&lt;a href=&quot;/development/how-to/add-architectural-gate-exemption/#declaring-a-new-category&quot;&gt;declaring a new category&lt;/a&gt;),
an &lt;code dir=&quot;auto&quot;&gt;issue&lt;/code&gt; where the category sets &lt;code dir=&quot;auto&quot;&gt;requires_issue: true&lt;/code&gt;, and a raised
&lt;code dir=&quot;auto&quot;&gt;test_no_dead_symbols&lt;/code&gt; leaf in &lt;code dir=&quot;auto&quot;&gt;tests/architectural/_baselines.yaml&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;allowlist_entries&lt;/code&gt;, or &lt;code dir=&quot;auto&quot;&gt;widened_grandfathered_470&lt;/code&gt; for the widened section).
Both leaves are shrink-only caps. Try wiring the symbol, dropping it from
&lt;code dir=&quot;auto&quot;&gt;__all__&lt;/code&gt; or deleting it first.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Never weaken the gate to get past it.&lt;/p&gt;
&lt;h3 id=&quot;the-ruff-format-exclude-ratchet-has-a-twin&quot;&gt;The &lt;code dir=&quot;auto&quot;&gt;ruff format&lt;/code&gt; exclude ratchet has a twin&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;[tool.ruff.format].exclude&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt; is a large, shrink-only
formatter-debt allowlist (that is why a whole-repo &lt;code dir=&quot;auto&quot;&gt;ruff format --check .&lt;/code&gt; passes
on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; — excluded files are skipped). Two distinct architectural tests guard
it, and checking only one misses failures:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_ruff_format_enforcement.py&lt;/code&gt; — asserts
&lt;code dir=&quot;auto&quot;&gt;ruff format --check .&lt;/code&gt; exits 0 and every exclude entry names a live file.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_ruff_format_exclude_ratchet.py&lt;/code&gt; — asserts every
exclude entry &lt;strong&gt;still genuinely reformats&lt;/strong&gt;, and that the entry count stays
under a shrink-only ceiling.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Two changes trip the ratchet, and both are caught only at the integration/merge
gate, not by a per-WP subset run:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;You run &lt;code dir=&quot;auto&quot;&gt;ruff format&lt;/code&gt; on an excluded file (making it clean) → its entry no
longer reformats → red.&lt;/li&gt;
&lt;li&gt;You delete an excluded file’s source → its entry names a missing file → red.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Fix both by &lt;strong&gt;removing&lt;/strong&gt; the now-dead entries (this only shrinks the list, so no
ceiling bump is needed). Remove entries only for files your branch actually
formats or deletes.&lt;/p&gt;
&lt;h3 id=&quot;a-scanner-that-swallows-a-parse-failure-reds-the-parse-fail-closed-gate&quot;&gt;A scanner that swallows a parse failure reds the parse fail-closed gate&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_scanner_parse_fail_closed.py&lt;/code&gt; scans every module under
&lt;code dir=&quot;auto&quot;&gt;tests/&lt;/code&gt; for a construct that can swallow a failure to parse source: an
&lt;code dir=&quot;auto&quot;&gt;except&lt;/code&gt; catching &lt;code dir=&quot;auto&quot;&gt;SyntaxError&lt;/code&gt; (or a subclass) that does not always re-raise,
a bare, &lt;code dir=&quot;auto&quot;&gt;Exception&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;BaseException&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;AssertionError&lt;/code&gt; or aliased handler around
a parse call, &lt;code dir=&quot;auto&quot;&gt;contextlib.suppress(...)&lt;/code&gt; around one, or &lt;code dir=&quot;auto&quot;&gt;finally: return&lt;/code&gt;. A
scanner that skips a file it cannot parse drops it from its census, so the gate
it feeds passes over code it never read.&lt;/p&gt;
&lt;p&gt;It trips on harmless-looking code too — for example
&lt;code dir=&quot;auto&quot;&gt;try: parse_file(p) except AssertionError: continue&lt;/code&gt;. Repro:
&lt;code dir=&quot;auto&quot;&gt;pytest tests/architectural/test_scanner_parse_fail_closed.py&lt;/code&gt;. Fix it by
reading and parsing through &lt;code dir=&quot;auto&quot;&gt;tests/architectural/_ast_scan.py&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;read_and_parse&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;parse_file&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;parse_source&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;read_source&lt;/code&gt;, which fail
closed naming the file). Only when the input is &lt;em&gt;deliberately&lt;/em&gt; allowed to be
unparseable, add a rationale row to its &lt;code dir=&quot;auto&quot;&gt;_ALLOWED_SWALLOWS&lt;/code&gt; ledger; the ledger
is checked for exact equality, so remove the row when the handler goes.&lt;/p&gt;
&lt;h3 id=&quot;router-path-filters-are-the-tail-of-a-guarded-ssot-chain&quot;&gt;Router path filters are the tail of a guarded SSOT chain&lt;/h3&gt;
&lt;p&gt;The &lt;code dir=&quot;auto&quot;&gt;ci-router.yml&lt;/code&gt; path-filter globs are not a free-standing authority — they
are the verbatim tail of a three-link single-source-of-truth chain:
&lt;code dir=&quot;auto&quot;&gt;tests/release/ci_retirement_scrub.json&lt;/code&gt; (the SSOT) → &lt;code dir=&quot;auto&quot;&gt;.github/ci-module-registry.yml&lt;/code&gt;
→ &lt;code dir=&quot;auto&quot;&gt;ci-router.yml&lt;/code&gt; filters. Each link is pinned by an architectural transcription
guard (&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_module_shard_registry.py&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_ci_router_transcription_guards.py&lt;/code&gt;).&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Trips it:&lt;/strong&gt; adding a glob to a router filter group alone.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Symptom:&lt;/strong&gt; the router-transcription guard reds; cascading the glob to satisfy
it then reds the registry-verbatim guard unless the registry roots change too —
and the registry roots drive the per-module test matrix, so this is a real
CI-matrix change, not a config tweak.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fix:&lt;/strong&gt; to change what a module &lt;em&gt;owns&lt;/em&gt; for routing, edit the scrub SSOT and
cascade verbatim through all three links. To route test directories to modules
&lt;em&gt;without&lt;/em&gt; touching the chain, derive the mapping from the registry inventory in
the gate-selection logic (&lt;code dir=&quot;auto&quot;&gt;scripts/ci/gate_selection.py&lt;/code&gt;) rather than
hand-authoring a second map.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;an-extra-narrow-lane-for-an-out-of-matrix-test&quot;&gt;An extra narrow lane for an out-of-matrix test&lt;/h3&gt;
&lt;p&gt;Not every test tree gets a module row. When a single out-of-matrix test file must run per
PR on a specific diff — the precedent is &lt;code dir=&quot;auto&quot;&gt;mission_state&lt;/code&gt; (#5864) and the runtime-home
path-literal guard (#6879) — add a &lt;strong&gt;non-src&lt;/strong&gt; router group plus one job, not a registry row:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;declare the group’s globs in &lt;code dir=&quot;auto&quot;&gt;tests/release/ci_retirement_scrub.json&lt;/code&gt;
&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;non_src_router_groups&lt;/code&gt;&lt;/strong&gt; and transcribe them verbatim into the filter block, &lt;code dir=&quot;auto&quot;&gt;changes.outputs&lt;/code&gt;
and the job’s &lt;code dir=&quot;auto&quot;&gt;if:&lt;/code&gt;, plus a row in
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_no_duplicate_suite_execution.AUTHORIZED_PER_CHANGE_SUITE_JOBS&lt;/code&gt; and the
&lt;code dir=&quot;auto&quot;&gt;router-gate&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;needs:&lt;/code&gt; list;&lt;/li&gt;
&lt;li&gt;spell the globs &lt;code dir=&quot;auto&quot;&gt;**/&lt;/code&gt;-prefixed (e.g. &lt;code dir=&quot;auto&quot;&gt;**/specify_cli/status/**&lt;/code&gt;). A &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt;-spelled glob makes the
group &lt;em&gt;src-backed&lt;/em&gt;, and every src-backed group must also be a module-registry row
(&lt;code dir=&quot;auto&quot;&gt;test_gate_selection_authority.py&lt;/code&gt;), so the lane becomes a CI-matrix change;&lt;/li&gt;
&lt;li&gt;keep it &lt;strong&gt;out&lt;/strong&gt; of the FR-004 &lt;code dir=&quot;auto&quot;&gt;unmatched&lt;/code&gt; union and &lt;code dir=&quot;auto&quot;&gt;architectural-heavy&lt;/code&gt;’s &lt;code dir=&quot;auto&quot;&gt;if:&lt;/code&gt; — both are
derived from the src-backed group set and the transcription guards red if they diverge;&lt;/li&gt;
&lt;li&gt;do not name a directory that no src-backed group owns (e.g. &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/paths/**&lt;/code&gt;). Such a
directory trips the fail-closed catch-all and already runs &lt;em&gt;every&lt;/em&gt; job, this lane included;
naming it turns that sensor off and narrows the run to your lane.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Trips it:&lt;/strong&gt; adding the globs to the filter block only, or to a src-backed group without a
module row. &lt;strong&gt;Symptom:&lt;/strong&gt; the transcription guard in
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_ci_router_transcription_guards.py&lt;/code&gt;, or
&lt;code dir=&quot;auto&quot;&gt;test_select_modules_full_mode_selects_all_registry_modules&lt;/code&gt;, or the duplicate-suite ledger.&lt;/p&gt;
&lt;h2 id=&quot;stored-test-universe-collection&quot;&gt;Stored test-universe collection&lt;/h2&gt;
&lt;p&gt;Several architectural gates need the full list of collected tests with their
markers (the “test universe”). One real &lt;code dir=&quot;auto&quot;&gt;pytest --collect-only&lt;/code&gt; of the tree takes
tens of seconds, and before this change the first test that needed the list
collected it inside its own setup while four xdist workers competed for the same
CPUs. The list is now collected once per job, in a step before pytest, and stored on
disk; the tests read the stored copy.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;What it does and does not do.&lt;/strong&gt; A first run of a checkout still collects once
in each job that consumes the list: the architectural battery leg whose files hold a
collecting test (today both legs hold one — &lt;code dir=&quot;auto&quot;&gt;test_fast_tier_marker_completeness.py&lt;/code&gt;
in 1/2 and &lt;code dir=&quot;auto&quot;&gt;test_same_tier_uniqueness.py&lt;/code&gt; in 2/2 — but a leg only collects when a
&lt;em&gt;selected&lt;/em&gt; gate holds one, see below), and the &lt;code dir=&quot;auto&quot;&gt;ci&lt;/code&gt; module shard. The change moves that
collection out of test setup and out of worker contention. A re-run of the same
checkout restores the stored list from the CI cache instead of collecting. On one
developer machine a collection took 62.5 s and reading the stored copy 0.33 s. On CI
the pre-test step took 89 to 233 s on a first run and 0.3 to 0.6 s when restored from
the Actions cache; the three runs are in
&lt;code dir=&quot;auto&quot;&gt;kitty-specs/shared-collection-and-shard-recapture-01M42V58/evidence/ci-measurements.md&lt;/code&gt;.&lt;/p&gt;
&lt;h3 id=&quot;where-it-lives-and-what-it-is-keyed-on&quot;&gt;Where it lives and what it is keyed on&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;The code is &lt;code dir=&quot;auto&quot;&gt;tests/architectural/_universe_store.py&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;collect_universe()&lt;/code&gt; in
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/_gate_coverage.py&lt;/code&gt; calls it; its signature and return value are
unchanged.&lt;/li&gt;
&lt;li&gt;The store is &lt;code dir=&quot;auto&quot;&gt;.pytest_cache/universe-store/&lt;/code&gt;, which git ignores. It holds one
record file, &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;key&gt;.json&lt;/code&gt;, plus a lock file. Writing a record deletes every other
record file.&lt;/li&gt;
&lt;li&gt;The key is a digest of the committed tree (not the commit), the interpreter,
the platform, every installed distribution with its version, and the environment
variables named &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_*&lt;/code&gt; plus &lt;code dir=&quot;auto&quot;&gt;PYTEST_ADDOPTS&lt;/code&gt;. The variables the test
session sets for itself are listed in &lt;code dir=&quot;auto&quot;&gt;ENV_EXCLUDED_NAMES&lt;/code&gt; and left out, so a
pre-test step and a test compute the same key. The key also overlays the
operator env file (&lt;code dir=&quot;auto&quot;&gt;.kitty.env&lt;/code&gt;) through the product’s own loader. A machine whose
home-level &lt;code dir=&quot;auto&quot;&gt;.kitty.env&lt;/code&gt; sets &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_*&lt;/code&gt; variables may therefore see local reuse
not happen, because pytest isolates &lt;code dir=&quot;auto&quot;&gt;HOME&lt;/code&gt;; CI is unaffected.&lt;/li&gt;
&lt;li&gt;A record is stored only when the checkout is still the one the key was computed
for after the collection: if a commit, a branch switch or an edit happened
meanwhile, the caller still gets the universe it collected, the report line says
&lt;code dir=&quot;auto&quot;&gt;not stored: the checkout changed during the collection&lt;/code&gt;, and the pre-test step
fails on that line.&lt;/li&gt;
&lt;li&gt;A record is read only when its schema, key, record count and origin (commit and
tree) all match and it holds at least 1,000 records (a corruption guard, not a
ratchet). Anything else is treated as absent and replaced after a fresh
collection.&lt;/li&gt;
&lt;li&gt;For one key, one collection runs at a time on a machine. Other callers wait on
the lock and then read the stored copy.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;when-the-store-is-bypassed&quot;&gt;When the store is bypassed&lt;/h3&gt;
&lt;p&gt;The store is not read or written, and the caller collects for itself, when:&lt;/p&gt;





























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Reason in the report&lt;/th&gt;&lt;th&gt;Condition&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;dirty-checkout&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;git status --porcelain&lt;/code&gt; is not empty. Untracked files count, because an untracked test file changes what is collected.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;root-override&lt;/code&gt;&lt;/td&gt;&lt;td&gt;the caller passed a &lt;code dir=&quot;auto&quot;&gt;repo_root&lt;/code&gt; (a patched root).&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;unsupported-platform&lt;/code&gt;&lt;/td&gt;&lt;td&gt;the platform is not Linux or macOS. The same reason, with a &lt;code dir=&quot;auto&quot;&gt;detail&lt;/code&gt;, is reported when the store directory or its lock cannot be used.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;git-unavailable&lt;/code&gt;&lt;/td&gt;&lt;td&gt;git cannot describe the checkout.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;env-file-unreadable&lt;/code&gt;&lt;/td&gt;&lt;td&gt;an operator &lt;code dir=&quot;auto&quot;&gt;.kitty.env&lt;/code&gt; exists but cannot be read, so the environment variables of the key are unknown.&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h3 id=&quot;the-per-test-budget-on-a-collecting-gate&quot;&gt;The per-test budget on a collecting gate&lt;/h3&gt;
&lt;p&gt;A bypass is not free: the caller now pays the whole collection inside its own test setup. One
&lt;code dir=&quot;auto&quot;&gt;pytest --collect-only&lt;/code&gt; of the tree costs 89 to 233 s on a first CI run (the measurements above),
247.7 s on the machine that filed #7052, and 90 to 422 s on a shared development VM depending on
load; the post-test &lt;code dir=&quot;auto&quot;&gt;check&lt;/code&gt; step cannot see that cost, because it only reads the report lines.&lt;/p&gt;
&lt;p&gt;The suite’s per-test timeout is a 240 s runaway-hang backstop (&lt;code dir=&quot;auto&quot;&gt;pytest.ini&lt;/code&gt;, #3143), which is at
or below a legitimate collection. A gate whose fixture setup may collect therefore carries its
own &lt;code dir=&quot;auto&quot;&gt;@pytest.mark.timeout(...)&lt;/code&gt; budget, derived from the collector’s own ceiling
(&lt;code dir=&quot;auto&quot;&gt;tests/architectural/_gate_coverage.COLLECT_TIMEOUT_S&lt;/code&gt;, 900 s) plus an allowance for the work
that runs beside the collection. pytest-timeout installs its timer over setup as well as the
call (&lt;code dir=&quot;auto&quot;&gt;timeout_func_only&lt;/code&gt; is unset), so the marker also bounds the module-scoped fixture setup
that triggers the collection.&lt;/p&gt;
&lt;p&gt;The rule is the one &lt;code dir=&quot;auto&quot;&gt;pytest.ini&lt;/code&gt; states: a legitimate slow test gets a per-test marker, the
global default is not raised. The budget must never be below &lt;code dir=&quot;auto&quot;&gt;COLLECT_TIMEOUT_S&lt;/code&gt; — a smaller one
reports a real collection as a hang, which is exactly #7052: on the architectural battery leg the
whole-repo collection was killed at 240 s and 16 tests in
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_same_tier_uniqueness.py&lt;/code&gt; errored at once while &lt;code dir=&quot;auto&quot;&gt;check&lt;/code&gt; still printed
“Reuse held” (an interrupted request writes no report line).&lt;/p&gt;
&lt;p&gt;Two invariants keep the two numbers together, both in that test module: every test whose fixture
closure reaches &lt;code dir=&quot;auto&quot;&gt;universe&lt;/code&gt; must carry a budget of at least &lt;code dir=&quot;auto&quot;&gt;COLLECT_TIMEOUT_S&lt;/code&gt;, and
&lt;code dir=&quot;auto&quot;&gt;_gate_coverage.py&lt;/code&gt; may not pass a bare numeric timeout to a collection subprocess. A test that
never collects keeps the 240 s default.&lt;/p&gt;
&lt;p&gt;Giving the tests room does not make a broken reuse green. On CI a bypass inside the pytest step
is still a red at the &lt;code dir=&quot;auto&quot;&gt;check&lt;/code&gt; step (&lt;code dir=&quot;auto&quot;&gt;Reuse broken: … collected&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;… bypassed (dirty-checkout)&lt;/code&gt;),
with the reason and the dirty paths in the job summary; the budget only stops that red from
arriving as a timeout storm that names no cause.&lt;/p&gt;
&lt;h3 id=&quot;the-report-line&quot;&gt;The report line&lt;/h3&gt;
&lt;p&gt;When &lt;code dir=&quot;auto&quot;&gt;SK_GATE_REUSE_REPORT&lt;/code&gt; names a file, each call of &lt;code dir=&quot;auto&quot;&gt;collect_universe()&lt;/code&gt; appends
one JSON line to it: &lt;code dir=&quot;auto&quot;&gt;outcome&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;reused&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;collected&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;bypassed&lt;/code&gt;), &lt;code dir=&quot;auto&quot;&gt;reason&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;no-record&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;invalid-record&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;origin-mismatch&lt;/code&gt; or a bypass reason from the table),
&lt;code dir=&quot;auto&quot;&gt;key&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;caller&lt;/code&gt; (the pre-step is &lt;code dir=&quot;auto&quot;&gt;prestep&lt;/code&gt;, a test is its file path), &lt;code dir=&quot;auto&quot;&gt;seconds&lt;/code&gt;, and
when present &lt;code dir=&quot;auto&quot;&gt;detail&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;dirty_paths&lt;/code&gt;. A &lt;code dir=&quot;auto&quot;&gt;detail&lt;/code&gt; starting with &lt;code dir=&quot;auto&quot;&gt;not stored&lt;/code&gt; on a
&lt;code dir=&quot;auto&quot;&gt;collected&lt;/code&gt; line means the fresh collection could not be written back.&lt;/p&gt;
&lt;h3 id=&quot;the-pre-test-step-and-the-post-test-check&quot;&gt;The pre-test step and the post-test check&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;python -m scripts.ci.collect_universe_prestep &amp;#x3C;command&gt;&lt;/code&gt; runs from the repository
root checkout:&lt;/p&gt;



































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Command&lt;/th&gt;&lt;th&gt;What it does&lt;/th&gt;&lt;th&gt;Exit status&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;key [--with-commit]&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Prints the collection key. With &lt;code dir=&quot;auto&quot;&gt;--with-commit&lt;/code&gt; it prints &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;key&gt;-&amp;#x3C;commit&gt;&lt;/code&gt;, which is the CI cache key.&lt;/td&gt;&lt;td&gt;0; 2 when the checkout is dirty or git cannot describe it&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;collect&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Calls &lt;code dir=&quot;auto&quot;&gt;collect_universe()&lt;/code&gt; once and prints the report line.&lt;/td&gt;&lt;td&gt;0 only when the line is &lt;code dir=&quot;auto&quot;&gt;reused&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;collected&lt;/code&gt; with the record stored, or an unsupported-platform bypass without a &lt;code dir=&quot;auto&quot;&gt;detail&lt;/code&gt;; 1 for anything else, including a record that could not be stored&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;check&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Reads the report file and writes a table to the job summary.&lt;/td&gt;&lt;td&gt;1 when the pre-test line is not acceptable, when a later request in the job collected or was bypassed (other than &lt;code dir=&quot;auto&quot;&gt;root-override&lt;/code&gt;) after the pre-test step stored or reused a record, or when a report line is malformed; 0 otherwise&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;consumers --battery-part &amp;#x3C;part&gt; [--gates-file &amp;#x3C;path&gt;]&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Prints &lt;code dir=&quot;auto&quot;&gt;true&lt;/code&gt; when the battery partition holds a test file that calls &lt;code dir=&quot;auto&quot;&gt;collect_universe()&lt;/code&gt; (found by scanning &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_*.py&lt;/code&gt;), &lt;code dir=&quot;auto&quot;&gt;false&lt;/code&gt; otherwise. &lt;code dir=&quot;auto&quot;&gt;--gates-file&lt;/code&gt; (default &lt;code dir=&quot;auto&quot;&gt;$SK_BATTERY_GATES_FILE&lt;/code&gt;, the variable the battery plug-in reads) intersects the question with the gates the diff selected for this leg (&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/7001&quot;&gt;#7001&lt;/a&gt;), so a scope-only leg whose selected gates hold no consumer skips the pre-step instead of collecting a universe it never reads; no file means the whole partition.&lt;/td&gt;&lt;td&gt;0 with an answer; 1 and no answer for an unknown part, an unreadable gates file, or any other failure&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;compare&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Collects once with the store bypassed and diffs the result against the stored record.&lt;/td&gt;&lt;td&gt;1 on any difference or when no usable record exists&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;collect&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;check&lt;/code&gt; fail when the pre-test step could not store a collection.
Only an unsupported platform is a legitimate fallback: the job then collects for
itself, &lt;code dir=&quot;auto&quot;&gt;check&lt;/code&gt; prints a fallback note and exits 0.&lt;/p&gt;
&lt;h3 id=&quot;where-it-runs&quot;&gt;Where it runs&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;ci-router.yml&lt;/code&gt;, job &lt;code dir=&quot;auto&quot;&gt;architectural-heavy&lt;/code&gt;&lt;/strong&gt; (a leg runs these steps only when its
partition holds a collecting test; the battery partition moves with the timings, so
each leg first runs &lt;code dir=&quot;auto&quot;&gt;consumers --battery-part &amp;#x3C;leg&gt;&lt;/code&gt; in a step with id &lt;code dir=&quot;auto&quot;&gt;select&lt;/code&gt;, and
a failed answer fails the job). Steps in order: compute the key, restore the store,
&lt;code dir=&quot;auto&quot;&gt;collect&lt;/code&gt;, save the store, run the battery (the pytest command line is unchanged),
&lt;code dir=&quot;auto&quot;&gt;check&lt;/code&gt; with &lt;code dir=&quot;auto&quot;&gt;if: always()&lt;/code&gt;.
The decision is intersected with the leg’s own selected-gates file (&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/7001&quot;&gt;#7001&lt;/a&gt;):
&lt;code dir=&quot;auto&quot;&gt;consumers&lt;/code&gt; is asked with &lt;code dir=&quot;auto&quot;&gt;--gates-file&lt;/code&gt; bound to the same
&lt;code dir=&quot;auto&quot;&gt;steps.scope.outputs.gates_file&lt;/code&gt; the battery step reads as &lt;code dir=&quot;auto&quot;&gt;SK_BATTERY_GATES_FILE&lt;/code&gt;.
A scoped leg (#6994) runs a handful of gates, so it needs the universe only when one
of &lt;em&gt;those&lt;/em&gt; gates collects it; when none does, every universe step is skipped. A
whole-leg run passes an empty path and keeps the whole-partition answer.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;module-tests.yml&lt;/code&gt;, job &lt;code dir=&quot;auto&quot;&gt;test&lt;/code&gt;.&lt;/strong&gt; The same steps, but only in per-PR mode and
only on the shard whose selected test list contains
&lt;code dir=&quot;auto&quot;&gt;tests/ci/test_corpus_blocking_home.py::test_every_corpus_test_has_a_blocking_per_pr_home&lt;/code&gt;,
the test that takes the &lt;code dir=&quot;auto&quot;&gt;live_universe&lt;/code&gt; fixture. The &lt;code dir=&quot;auto&quot;&gt;ci&lt;/code&gt; module runs as one shard
(&lt;code dir=&quot;auto&quot;&gt;shard_count: 1&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;.github/ci-module-registry.yml&lt;/code&gt;), so that shard holds the test.
&lt;code dir=&quot;auto&quot;&gt;tests/ci/test_ci_workflow_prestep_shape.py&lt;/code&gt; pins that the test still exists.
Full-mode warm-up may rewrite &lt;code dir=&quot;auto&quot;&gt;uv.lock&lt;/code&gt; and leave the checkout dirty, so it
skips the step.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The cache key is &lt;code dir=&quot;auto&quot;&gt;universe-&amp;#x3C;key&gt;-&amp;#x3C;commit&gt;&lt;/code&gt;.&lt;/strong&gt; It includes the commit because a
stored record is valid for one commit only and a CI cache key never changes once
saved; a key without the commit could keep a record that a later commit rejects,
and the save step is skipped after a restore hit. Only an exact key restores
(there are no &lt;code dir=&quot;auto&quot;&gt;restore-keys&lt;/code&gt;), and the save runs before pytest, so a leg that goes
red on a test can still be re-run warm.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The shard list lives in the runner’s temp directory&lt;/strong&gt;, not in the checkout. An
untracked file there would make the checkout dirty for the rest of the job.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;None of the collect, check or compare steps sets &lt;code dir=&quot;auto&quot;&gt;continue-on-error&lt;/code&gt;.&lt;/strong&gt; The
shape test pins that, because it would turn the check into a summary.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;nightly-equivalence-job&quot;&gt;Nightly equivalence job&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;ci-nightly.yml&lt;/code&gt; job &lt;code dir=&quot;auto&quot;&gt;universe-equivalence&lt;/code&gt; runs &lt;code dir=&quot;auto&quot;&gt;collect&lt;/code&gt; and then &lt;code dir=&quot;auto&quot;&gt;compare&lt;/code&gt; in
one job. It shows that collection is deterministic and that a stored record
round-trips to the same list as a fresh collection. It does not show that a record
restored from the CI cache on another runner equals a fresh one. It is part of
&lt;code dir=&quot;auto&quot;&gt;nightly-summary&lt;/code&gt;.&lt;/p&gt;
&lt;h3 id=&quot;run-it-locally&quot;&gt;Run it locally&lt;/h3&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# The key of a clean checkout, and the CI cache key (commit appended)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;python&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-m&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;scripts.ci.collect_universe_prestep&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;key&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;python&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-m&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;scripts.ci.collect_universe_prestep&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;key&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--with-commit&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Collect once and store it, then run a gate against the stored copy&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;export&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;SK_GATE_REUSE_REPORT&lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;/&lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;tmp&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;/&lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;universe-reuse&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;.&lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;jsonl&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;python&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-m&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;scripts.ci.collect_universe_prestep&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;collect&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;PYTHONPATH&lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;src&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;python&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-m&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;pytest&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;tests/architectural/test_fast_tier_marker_completeness.py&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-q&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;python&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-m&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;scripts.ci.collect_universe_prestep&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;check&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Prove the stored copy equals a fresh collection&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;python&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-m&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;scripts.ci.collect_universe_prestep&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;compare&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Ask a leg about its own selected gates instead of its whole partition (#7001)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;printf&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&apos;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;%s\n&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&apos;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;tests/architectural/test_dead_builtin_doc_paths.py&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;/tmp/gates.txt&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;python&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-m&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;scripts.ci.collect_universe_prestep&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;consumers&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--battery-part&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;1/2&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--gates-file&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;/tmp/gates.txt&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# -&gt; false (that gate never collects the universe), so every universe step is skipped&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;printf&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&apos;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;%s\n&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&apos;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;tests/architectural/test_fast_tier_marker_completeness.py&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;/tmp/gates.txt&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;python&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-m&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;scripts.ci.collect_universe_prestep&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;consumers&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--battery-part&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;1/2&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--gates-file&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;/tmp/gates.txt&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# -&gt; true (this one does)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h3 id=&quot;what-a-scope-only-leg-skips&quot;&gt;What a scope-only leg skips&lt;/h3&gt;
&lt;p&gt;A pull request that touches only a path a few gates declare as their scan scope runs
only those gates (#6994). Until #7001 its legs still asked their question of the whole
battery partition, whose only two collecting tests live one per leg, so &lt;strong&gt;both&lt;/strong&gt; legs
answered “collect” for a diff that selected three or four unrelated gates. The
intersection removes that:&lt;/p&gt;



































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Diff&lt;/th&gt;&lt;th&gt;Selected gates (1/2 · 2/2)&lt;/th&gt;&lt;th&gt;A collecting one among them?&lt;/th&gt;&lt;th&gt;Universe steps&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;docs-only (&lt;code dir=&quot;auto&quot;&gt;docs/**&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;3 · 3&lt;/td&gt;&lt;td&gt;no&lt;/td&gt;&lt;td&gt;all five skipped&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;docs/adr-only (&lt;code dir=&quot;auto&quot;&gt;docs/adr/**&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;3 · 4&lt;/td&gt;&lt;td&gt;no&lt;/td&gt;&lt;td&gt;all five skipped&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;tests-only (&lt;code dir=&quot;auto&quot;&gt;tests/**&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;19 · 23&lt;/td&gt;&lt;td&gt;yes (both legs)&lt;/td&gt;&lt;td&gt;unchanged&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;a &lt;code dir=&quot;auto&quot;&gt;src/**&lt;/code&gt; change&lt;/td&gt;&lt;td&gt;—&lt;/td&gt;&lt;td&gt;full leg (&lt;code dir=&quot;auto&quot;&gt;mode=full&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;unchanged&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;Measured on the development host (a shared machine with heavy concurrent load, so the
absolute numbers are pessimistic): a cold collection took &lt;strong&gt;396.7 s&lt;/strong&gt; and a warm reuse
0.55 s, while the decision itself — partition, AST scan and the one file read — costs
about &lt;strong&gt;1.5 s&lt;/strong&gt;. The published CI range for a first collection is 89–233 s, so the
ordering holds on CI even though this host is slower. A cold collection is the common
case for a new commit: the cache key is &lt;code dir=&quot;auto&quot;&gt;universe-&amp;#x3C;key&gt;-&amp;#x3C;commit&gt;&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;Further cheap wins, noted but &lt;strong&gt;not&lt;/strong&gt; taken here:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;A re-run of the same commit restores the store from the Actions cache instead of
collecting, because the key does not include the partition. On a first run the two
legs still collect in parallel: each job populates the cache only when it finishes,
so the second leg cannot see the first one’s record in time. Making the two legs
share one collection would need a job-level split, not a cache change.&lt;/li&gt;
&lt;li&gt;A scoped leg still pays checkout and &lt;code dir=&quot;auto&quot;&gt;uv sync --frozen --all-extras&lt;/code&gt; (about 1–2
minutes) for a handful of gates; narrowing that sync is a separate change.&lt;/li&gt;
&lt;li&gt;The decision could reuse the partition it already computed for the plug-in instead of
recomputing it, saving well under a second.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;A dirty checkout (including an untracked file) is bypassed on purpose; commit or
stash first to see a &lt;code dir=&quot;auto&quot;&gt;reused&lt;/code&gt; line. To force a fresh collection, run
&lt;code dir=&quot;auto&quot;&gt;rm -rf .pytest_cache/universe-store&lt;/code&gt;; there is no bypass environment variable, and
&lt;code dir=&quot;auto&quot;&gt;pytest --cache-clear&lt;/code&gt; does not remove that directory.&lt;/p&gt;
&lt;h2 id=&quot;scheduled-shard-timings-recapture&quot;&gt;Scheduled shard-timings recapture&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;.github/ci-shard-timings.json&lt;/code&gt; records, for each registry module, the exact node
ids its shard collects and how long each took (&lt;code dir=&quot;auto&quot;&gt;module_test_node_durations&lt;/code&gt;, the
identity-keyed authority &lt;code dir=&quot;auto&quot;&gt;scripts/ci/shard_select.py&lt;/code&gt; weights a shard by), their
ordered projection (&lt;code dir=&quot;auto&quot;&gt;module_test_durations&lt;/code&gt;), the count and the summed seconds. The
entry drifts whenever a test is added, removed, renamed or replaced. The workflow
&lt;code dir=&quot;auto&quot;&gt;ci-shard-recapture.yml&lt;/code&gt; (schedule 04:41 UTC daily, plus &lt;code dir=&quot;auto&quot;&gt;workflow_dispatch&lt;/code&gt;, and
only on the primary branch (&lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;)) refreshes the drifted entries for &lt;strong&gt;every&lt;/strong&gt;
registry module and proposes the change as a pull request. The code is
&lt;code dir=&quot;auto&quot;&gt;scripts/ci/recapture_shard_timings.py&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;The job &lt;code dir=&quot;auto&quot;&gt;recapture-shard-timings&lt;/code&gt; runs the script in three steps:&lt;/p&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Phase&lt;/th&gt;&lt;th&gt;Holds the token&lt;/th&gt;&lt;th&gt;What it does&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;detect&lt;/code&gt;&lt;/td&gt;&lt;td&gt;yes&lt;/td&gt;&lt;td&gt;Asks &lt;code dir=&quot;auto&quot;&gt;gh&lt;/code&gt; whether a recapture pull request is open on the proposal branch.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;capture&lt;/code&gt;&lt;/td&gt;&lt;td&gt;no&lt;/td&gt;&lt;td&gt;Finds drifted modules, captures them, and writes the result (&lt;code dir=&quot;auto&quot;&gt;drifted&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;captured&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;failed&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;deferred&lt;/code&gt;) as a step output and a job-summary table.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;publish&lt;/code&gt;&lt;/td&gt;&lt;td&gt;yes&lt;/td&gt;&lt;td&gt;Pushes the refreshed file and opens or refreshes the pull request.&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;The &lt;code dir=&quot;auto&quot;&gt;capture&lt;/code&gt; phase runs test code for a long time, so it refuses to run when
&lt;code dir=&quot;auto&quot;&gt;CHARTER_SHARD_RECAPTURE_TOKEN&lt;/code&gt; is in its environment and starts every subprocess
without any token variable.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Finding drift.&lt;/strong&gt; A collection-only pass (&lt;code dir=&quot;auto&quot;&gt;pytest --collect-only&lt;/code&gt;, over the same
directories and marker expression the producer uses) lists each module’s &lt;strong&gt;node
ids&lt;/strong&gt; for every module whose committed provenance is valid. A module is drifted
when its provenance record is missing or not valid, when its collected id set
differs from the committed &lt;code dir=&quot;auto&quot;&gt;module_test_node_durations&lt;/code&gt; (a rename at an unchanged
count included — a count-only check sees nothing), when the entry is still the
retired positional shape with no node ids (a recapture is what migrates it), or
when its committed tables disagree with each other. A reordered but identical id
set is not drift: the weights are keyed by id.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Capturing.&lt;/strong&gt; Each drifted module is captured by
&lt;code dir=&quot;auto&quot;&gt;python -m scripts.ci.capture_shard_timings --module &amp;#x3C;m&gt; --write&lt;/code&gt; in its own
subprocess, longest-untouched first.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Time budget.&lt;/strong&gt; The workflow passes &lt;code dir=&quot;auto&quot;&gt;--budget-seconds 4200&lt;/code&gt;, counted from the start
of the &lt;code dir=&quot;auto&quot;&gt;capture&lt;/code&gt; phase, so the count-only passes are inside it. No count pass and no
capture starts once the budget is spent; the modules left over are reported as
&lt;code dir=&quot;auto&quot;&gt;deferred&lt;/code&gt;, never as clean, and the next run recomputes drift (no state is kept).
A count pass is capped at 300 s per module, a capture at 2,100 s, and the job at
130 minutes (70 minutes to start work, up to 35 for the last capture and 25 for setup, battery refresh and publication).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;The valid-capture rule.&lt;/strong&gt; A capture is kept when its provenance record carries
the run id the script passed in, the pytest exit status was 0 or 1, at least one
test was measured, and the committed slice is structurally complete — exact, unique
node ids, finite non-negative durations, and every derived table (ordered
projection, count, summed seconds, &lt;code dir=&quot;auto&quot;&gt;unique_tests_measured&lt;/code&gt;) agreeing with the
keyed table. Anything else (a crash, a collection error, a timeout, an unreadable
file, an entry whose ids and durations do not line up) puts the committed file back
byte for byte and reports the module as &lt;code dir=&quot;auto&quot;&gt;failed&lt;/code&gt;; the other modules still run. A
capture whose pytest exit status was 1 must include a failed runtest report; it keeps its complete durations but is reported
as &lt;em&gt;captured with failing tests&lt;/em&gt;, never as a clean capture. An exit of 1 without a failed test report is rejected as possibly incomplete. A count pass that fails
or times out also reports its module as &lt;code dir=&quot;auto&quot;&gt;failed&lt;/code&gt;. The script exits 1 when any
module failed.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Proposal.&lt;/strong&gt; The branch is &lt;code dir=&quot;auto&quot;&gt;ci/recapture-shard-timings&lt;/code&gt;, and GitHub allows one open
pull request per head branch.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;With no open pull request, &lt;code dir=&quot;auto&quot;&gt;publish&lt;/code&gt; force-pushes the branch and opens one.&lt;/li&gt;
&lt;li&gt;With an open pull request, &lt;code dir=&quot;auto&quot;&gt;capture&lt;/code&gt; starts from the proposal’s timings for the
modules it already refreshed, so each run continues the work, and &lt;code dir=&quot;auto&quot;&gt;publish&lt;/code&gt; adds
a follow-up commit with a plain push. It never forces.&lt;/li&gt;
&lt;li&gt;A push the token is not allowed to make (HTTP 403) fails the step with a message
naming the secret. That is a token problem code cannot fix; see #5624.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;The red window.&lt;/strong&gt; Per pull request, the module-tests select step reports a drifted
count as a warning, and the live collection in this gate is skipped (#7288). The job &lt;code dir=&quot;auto&quot;&gt;strict-shard-timings-check&lt;/code&gt; in the same
workflow runs &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_module_length_agreement.py&lt;/code&gt; with
&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_STRICT_SHARD_TIMINGS=1&lt;/code&gt; and has no &lt;code dir=&quot;auto&quot;&gt;needs&lt;/code&gt; edge to the recapture job. So
from the first scheduled run that sees a drift until the proposal merges, the strict
check is red on each scheduled run. That window is accepted: the red is the alarm
and the proposal is the fix.&lt;/p&gt;
&lt;p&gt;To run it by hand, &lt;code dir=&quot;auto&quot;&gt;capture&lt;/code&gt; without &lt;code dir=&quot;auto&quot;&gt;--write&lt;/code&gt; only reports drift:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;python&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-m&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;scripts.ci.recapture_shard_timings&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;capture&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--module&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;charter&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h2 id=&quot;docs-freshness-and-registration-gates&quot;&gt;Docs-freshness and registration gates&lt;/h2&gt;
&lt;p&gt;Adding or moving a &lt;code dir=&quot;auto&quot;&gt;docs/**&lt;/code&gt; page trips several documentation gates that draw
from separate committed catalogs; fixing one leaves the others red.&lt;/p&gt;
&lt;p&gt;The prose of those pages is linted by a separate, always-on job: see
&lt;a href=&quot;#docs-lint&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs-lint&lt;/code&gt;&lt;/a&gt;.&lt;/p&gt;
&lt;h3 id=&quot;a-new-docs-page-needs-triple-registration-plus-a-description-band&quot;&gt;A new docs page needs triple registration plus a description band&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Trips it:&lt;/strong&gt; a new &lt;code dir=&quot;auto&quot;&gt;docs/**/*.md&lt;/code&gt; page that is not registered everywhere.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Symptom:&lt;/strong&gt; the docs build and docs-freshness checks red with a mix of
&lt;code dir=&quot;auto&quot;&gt;DOCS-INDEX-DRIFT&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;INVENTORY-INCOMPLETE&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;INVENTORY-LOCKFILE-DRIFT&lt;/code&gt; /
&lt;code dir=&quot;auto&quot;&gt;LEAK-MISSING-INVENTORY&lt;/code&gt;, and a description-length failure. The “committed
index” in a drift error is the machine-generated &lt;em&gt;retrieval&lt;/em&gt; index, not the
curated &lt;code dir=&quot;auto&quot;&gt;index.md&lt;/code&gt;, which is why updating only &lt;code dir=&quot;auto&quot;&gt;index.md&lt;/code&gt; is not enough.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Fix / repro:&lt;/strong&gt; register the page in its curated index and satisfy the
frontmatter band; leave the generated surfaces alone:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Curated section index&lt;/strong&gt; — hand-add the page to its section’s &lt;code dir=&quot;auto&quot;&gt;index.md&lt;/code&gt;
(satisfies the index-completeness rule).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Page inventory, retrieval index, ADR era table rows&lt;/strong&gt; — do &lt;strong&gt;not&lt;/strong&gt;
regenerate &lt;code dir=&quot;auto&quot;&gt;docs/development/page-inventory.yaml&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;docs/development/docs-retrieval-index.yaml&lt;/code&gt; or the era table rows in the
PR. They are regenerated on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; after merge by the &lt;code dir=&quot;auto&quot;&gt;ci/regen-docs-index&lt;/code&gt;
bot pull request (&lt;code dir=&quot;auto&quot;&gt;docs-index-regen.yml&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;scripts/ci/regen_docs_index.py&lt;/code&gt;),
and the &lt;code dir=&quot;auto&quot;&gt;docs-lint&lt;/code&gt; guard (&lt;code dir=&quot;auto&quot;&gt;scripts/ci/check_generated_docs_untouched.py&lt;/code&gt;)
refuses a PR that edits them. Until the bot PR merges, &lt;code dir=&quot;auto&quot;&gt;INVENTORY-INCOMPLETE&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;LEAK-MISSING-INVENTORY&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;INVENTORY-LOCKFILE-DRIFT&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;DOCS-INDEX-DRIFT&lt;/code&gt;
report the new page as &lt;strong&gt;warnings&lt;/strong&gt;, and &lt;code dir=&quot;auto&quot;&gt;spec-kitty docs query&lt;/code&gt; does not
find it yet. The per-PR content check is
&lt;code dir=&quot;auto&quot;&gt;tests/docs/test_docs_index_regenerates_cleanly.py&lt;/code&gt;: the generators must
run cleanly over the tree you merge.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Frontmatter &lt;code dir=&quot;auto&quot;&gt;description&lt;/code&gt;&lt;/strong&gt; — a hard &lt;strong&gt;50–180 character&lt;/strong&gt; band on every
published page, enforced by &lt;code dir=&quot;auto&quot;&gt;tests/docs/test_docs_seo.py&lt;/code&gt; (over 180 also fails
the docsite build’s frontmatter gate).&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Verify with &lt;code dir=&quot;auto&quot;&gt;PYTHONPATH=. python scripts/docs/check_docs_freshness.py --ci&lt;/code&gt;
(expect &lt;code dir=&quot;auto&quot;&gt;errors=0&lt;/code&gt;; staleness and external-URL link-health &lt;em&gt;warnings&lt;/em&gt; are fine).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;ADRs&lt;/strong&gt; need only the ADR file: the bot adds the era index-table row
(&lt;code dir=&quot;auto&quot;&gt;freshen_adr_inventory --all&lt;/code&gt;). An ADR’s frontmatter needs &lt;code dir=&quot;auto&quot;&gt;title:&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;date:&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;updated:&lt;/code&gt;, and a 50–180 character &lt;code dir=&quot;auto&quot;&gt;description&lt;/code&gt;.&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;docs-lint&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs-lint&lt;/code&gt;&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Trips it:&lt;/strong&gt; a typo or British spelling in docs prose, or a changelog
&lt;code dir=&quot;auto&quot;&gt;[Unreleased]&lt;/code&gt; entry that breaks the house style. Any PR can trip it, because
the job has no path filter.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Job:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;docs-lint&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;.github/workflows/ci-router.yml&lt;/code&gt; (display name “docs
lint (spelling + changelog style, always-on)”). It is listed in the
&lt;code dir=&quot;auto&quot;&gt;router-gate&lt;/code&gt; job’s &lt;code dir=&quot;auto&quot;&gt;needs&lt;/code&gt;, so a red &lt;code dir=&quot;auto&quot;&gt;docs-lint&lt;/code&gt; blocks the merge. It is
&lt;strong&gt;blocking&lt;/strong&gt;: neither command’s exit code is masked.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Why always-on:&lt;/strong&gt; its inputs span &lt;code dir=&quot;auto&quot;&gt;docs/**&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;README.md&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;packs/built-in/**/*.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt; (the &lt;code dir=&quot;auto&quot;&gt;[tool.codespell]&lt;/code&gt; table and
the pinned &lt;code dir=&quot;auto&quot;&gt;codespell&lt;/code&gt;) and &lt;code dir=&quot;auto&quot;&gt;uv.lock&lt;/code&gt;. No single router path group covers all
of them, so a path filter would let some edits skip the check.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;What it runs:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;uv sync --frozen&lt;/code&gt;, then
&lt;code dir=&quot;auto&quot;&gt;python -m scripts.docs.check_spelling&lt;/code&gt; (typo, US-spelling and Unreleased
passes) and &lt;code dir=&quot;auto&quot;&gt;python -m scripts.docs.check_changelog_style&lt;/code&gt;. It runs &lt;strong&gt;no
pytest&lt;/strong&gt;. The planted-violation and live-tree tests for the two scripts
(&lt;code dir=&quot;auto&quot;&gt;tests/docs/test_check_spelling.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tests/docs/test_changelog_style.py&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;tests/docs/test_docs_spelling_live.py&lt;/code&gt;) run in the &lt;code dir=&quot;auto&quot;&gt;tests-docs&lt;/code&gt; job.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Exit codes:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;0&lt;/code&gt; clean; &lt;code dir=&quot;auto&quot;&gt;1&lt;/code&gt; findings; &lt;code dir=&quot;auto&quot;&gt;2&lt;/code&gt; the check could not run or could
not prove it looked at anything: a usage error, &lt;code dir=&quot;auto&quot;&gt;codespell&lt;/code&gt; missing, no
&lt;code dir=&quot;auto&quot;&gt;[tool.codespell]&lt;/code&gt; table in &lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt;, an unreadable changelog (both
scripts), a &lt;code dir=&quot;auto&quot;&gt;typo&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;us&lt;/code&gt; pass that scanned 0 files, or an &lt;code dir=&quot;auto&quot;&gt;unreleased&lt;/code&gt;
scratch file that a &lt;code dir=&quot;auto&quot;&gt;[tool.codespell]&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;skip&lt;/code&gt; glob would drop. A changelog with
no &lt;code dir=&quot;auto&quot;&gt;[Unreleased]&lt;/code&gt; section is &lt;code dir=&quot;auto&quot;&gt;0&lt;/code&gt; (nothing to check). The changelog guard also
exits &lt;code dir=&quot;auto&quot;&gt;0&lt;/code&gt; on warnings alone.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Scope:&lt;/strong&gt; Markdown only. &lt;code dir=&quot;auto&quot;&gt;docs/archive/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;docs/reports/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;docs/plans/&lt;/code&gt; and
the generated CLI reference (&lt;code dir=&quot;auto&quot;&gt;docs/api/cli-commands.md&lt;/code&gt;) are skipped through
the &lt;code dir=&quot;auto&quot;&gt;[tool.codespell]&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;skip&lt;/code&gt; list, so a finding never comes from them. A
relative &lt;code dir=&quot;auto&quot;&gt;--changelog&lt;/code&gt; resolves against the repository root in both scripts
(against &lt;code dir=&quot;auto&quot;&gt;--repo-root&lt;/code&gt; for the spelling check), not the current directory.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Symptom:&lt;/strong&gt; the job log lists one finding per line as
&lt;code dir=&quot;auto&quot;&gt;path:line: [rule] ... — fix&lt;/code&gt;, ending in a summary line. It is not one of the
docs-freshness or registration errors above. The guard’s rules include
&lt;code dir=&quot;auto&quot;&gt;bullet-marker&lt;/code&gt; (a column-0 &lt;code dir=&quot;auto&quot;&gt;* &lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;+ &lt;/code&gt; bullet), &lt;code dir=&quot;auto&quot;&gt;conflict-marker&lt;/code&gt; (a leftover
&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;&amp;#x3C;&amp;#x3C;&amp;#x3C;&amp;#x3C;&amp;#x3C;&amp;#x3C;&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;|||||||&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&lt;/code&gt; line) and banned-token checks on
prose between a &lt;code dir=&quot;auto&quot;&gt;###&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;####&lt;/code&gt; heading and its first bullet; the how-to lists
every rule and the false-positive shapes (&lt;code dir=&quot;auto&quot;&gt;WP-D-1&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;SC-2086&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;DEFAULT-branch&lt;/code&gt;) to put in backticks.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fix / repro:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;make docs-lint&lt;/code&gt; from the repository root reproduces the job
(it runs the same two commands). The how-to has the steps: &lt;a href=&quot;/development/how-to/review-gates/#changelog-update-and-style&quot;&gt;run the checks,
allow a word, exempt a quoted literal, and read a
failure&lt;/a&gt;. Never run bare
&lt;code dir=&quot;auto&quot;&gt;codespell&lt;/code&gt;, which scans the whole repository.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Owning files:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;scripts/docs/check_spelling.py&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;scripts/docs/check_changelog_style.py&lt;/code&gt;, and the &lt;code dir=&quot;auto&quot;&gt;[tool.codespell]&lt;/code&gt; table
(&lt;code dir=&quot;auto&quot;&gt;skip&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;ignore-words-list&lt;/code&gt;) plus the exact &lt;code dir=&quot;auto&quot;&gt;codespell==2.4.3&lt;/code&gt; pin in
&lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt;. The pin is exact on purpose: a new &lt;code dir=&quot;auto&quot;&gt;codespell&lt;/code&gt; release
changes its dictionary, so bump it deliberately, together with the docs it
newly flags.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;touching-any-docs-path-can-surface-a-pre-existing-docs-test-flake&quot;&gt;Touching any docs path can surface a pre-existing docs-test flake&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Trips it:&lt;/strong&gt; touching any &lt;code dir=&quot;auto&quot;&gt;docs/**&lt;/code&gt; path flips the docs-test path filter,
which can run a &lt;code dir=&quot;auto&quot;&gt;tests/docs/&lt;/code&gt; test that never ran on your branch before.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Symptom:&lt;/strong&gt; a docs test you did not write reds — often a fragile
single-cold-measurement performance assertion on a contended runner. Do not
misattribute it to your diff.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fix / repro:&lt;/strong&gt; classify it as pre-existing (reproduce on the merge base),
then fix perf flakes at the root with warm-run discipline (discard the cold
pass, assert the fastest of several warm runs); never retry-to-green.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;where-the-docs-site-deploys-from&quot;&gt;Where the docs site deploys from&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;docs.spec-kitty.ai&lt;/code&gt; is deployed by &lt;code dir=&quot;auto&quot;&gt;.github/workflows/docs-pages.yml&lt;/code&gt; from
this repository’s &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;. The workflow runs on pushes to &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; that touch an
input of the doc-kitty build (&lt;code dir=&quot;auto&quot;&gt;docs/**&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;site/**&lt;/code&gt;, the &lt;code dir=&quot;auto&quot;&gt;scripts/docs&lt;/code&gt; modules
the build runs, and the two workflow files) or on manual dispatch. It first
probes whether GitHub Pages is configured and skips cleanly if not. The &lt;code dir=&quot;auto&quot;&gt;build&lt;/code&gt;
job then calls &lt;code dir=&quot;auto&quot;&gt;.github/workflows/docs-site-build.yml&lt;/code&gt;, so &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; deploys only
a site built by the definition the required &lt;code dir=&quot;auto&quot;&gt;docs-site&lt;/code&gt; pull-request gate runs.
The &lt;code dir=&quot;auto&quot;&gt;deploy&lt;/code&gt; job runs only for &lt;code dir=&quot;auto&quot;&gt;spec-kitty/spec-kitty&lt;/code&gt; on
&lt;code dir=&quot;auto&quot;&gt;refs/heads/main&lt;/code&gt;; a &lt;code dir=&quot;auto&quot;&gt;workflow_dispatch&lt;/code&gt; on another branch builds but does not
deploy. After each deploy, the &lt;code dir=&quot;auto&quot;&gt;smoketest&lt;/code&gt; job runs
&lt;code dir=&quot;auto&quot;&gt;scripts/docs/site_live_probe.py&lt;/code&gt; against &lt;code dir=&quot;auto&quot;&gt;https://docs.spec-kitty.ai&lt;/code&gt;, and a
mismatch turns the run red. The legacy generator the cutover replaced is retired
(#6943): rolling back to it means reverting that pull request and the cutover
(#7558), so rolling forward is preferred.&lt;/p&gt;
&lt;h3 id=&quot;the-docsites-python-steps-need-pythonpath&quot;&gt;The docsite’s Python steps need &lt;code dir=&quot;auto&quot;&gt;PYTHONPATH&lt;/code&gt;&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Trips it:&lt;/strong&gt; the shared docsite build and the deploy’s &lt;code dir=&quot;auto&quot;&gt;smoketest&lt;/code&gt; run
Python modules under &lt;code dir=&quot;auto&quot;&gt;scripts/docs/&lt;/code&gt; with the runner’s &lt;code dir=&quot;auto&quot;&gt;python3&lt;/code&gt;, without
installing the package. Several of them import &lt;code dir=&quot;auto&quot;&gt;from kernel.clock import ...&lt;/code&gt;
or other &lt;code dir=&quot;auto&quot;&gt;scripts.docs.*&lt;/code&gt; modules, so a step with no &lt;code dir=&quot;auto&quot;&gt;PYTHONPATH&lt;/code&gt; raises
&lt;code dir=&quot;auto&quot;&gt;ModuleNotFoundError: No module named &apos;kernel&apos;&lt;/code&gt; (or &lt;code dir=&quot;auto&quot;&gt;&apos;scripts&apos;&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Symptom:&lt;/strong&gt; a docsite build step or the smoketest fails at import. A failed
build skips the deploy, so merged &lt;code dir=&quot;auto&quot;&gt;docs/&lt;/code&gt; changes never go live.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fix / repro:&lt;/strong&gt; give each such step &lt;code dir=&quot;auto&quot;&gt;PYTHONPATH: .:src&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;..:../src&lt;/code&gt; for
steps that run in &lt;code dir=&quot;auto&quot;&gt;site/&lt;/code&gt;). The shared build runs on every pull request that
touches the docsite, through the &lt;code dir=&quot;auto&quot;&gt;docs-site&lt;/code&gt; gate. &lt;code dir=&quot;auto&quot;&gt;docs-pages.yml&lt;/code&gt; itself has
no &lt;code dir=&quot;auto&quot;&gt;pull_request&lt;/code&gt; trigger, so a change to it is exercised only by its
job-graph tests (&lt;code dir=&quot;auto&quot;&gt;tests/release/test_release_ci_ownership.py&lt;/code&gt;) before merge.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;accept-to-consolidate-gates&quot;&gt;Accept-to-consolidate gates&lt;/h2&gt;
&lt;p&gt;The &lt;code dir=&quot;auto&quot;&gt;accept&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;consolidate&lt;/code&gt; close-out has several gates that block silently until fed
exactly what they expect.&lt;/p&gt;
&lt;h3 id=&quot;the-issue-matrix-verdict-gate-blocks-wp-approval&quot;&gt;The issue-matrix verdict gate blocks WP approval&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Trips it:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;move-task &amp;#x3C;WP&gt; --to approved&lt;/code&gt; when a gating &lt;code dir=&quot;auto&quot;&gt;#NNN&lt;/code&gt; reference in
the mission’s artifacts has no verdict row in &lt;code dir=&quot;auto&quot;&gt;issue-matrix.json&lt;/code&gt;. Not every
reference gates: context-only and PR/commit references are recorded but do
not block.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Symptom:&lt;/strong&gt; the approval is blocked, and the error lists the missing rows.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fix:&lt;/strong&gt; seed the matrix up front with &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent issue-verdict&lt;/code&gt;. The
verdict values, which references gate, and the evidence-token rule for
&lt;code dir=&quot;auto&quot;&gt;deferred-with-followup&lt;/code&gt; are documented once, in the
&lt;a href=&quot;/development/reference/issue-matrix-verdicts/&quot;&gt;Issue-Matrix Verdict Reference&lt;/a&gt;. The per-WP
reviewer should &lt;strong&gt;refuse to fabricate&lt;/strong&gt; verdicts for unfixed issues; the
orchestrator fills them honestly and flips &lt;code dir=&quot;auto&quot;&gt;in-mission&lt;/code&gt; rows to a terminal
verdict at accept.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;the-other-close-out-gates&quot;&gt;The other close-out gates&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Lane branches reject any &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt; change&lt;/strong&gt; (“kitty-specs/ changes are
not allowed on lane branches”). Before moving a task to &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt; or
&lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt;, restore the planning artifacts from the planning branch and commit.
The review-claim step can re-dirty them, so re-clean between claim and approve.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Record &lt;code dir=&quot;auto&quot;&gt;acceptance-matrix.json&lt;/code&gt; verdicts with &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent acceptance-verdict&lt;/code&gt;; do not hand-edit the file.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent acceptance-verdict --mission &amp;#x3C;m&gt; --criterion FR-001 --result pass --evidence &amp;#x3C;ref&gt;&lt;/code&gt; writes the criterion through the matrix seam, commits it, and
recomputes &lt;code dir=&quot;auto&quot;&gt;overall_verdict&lt;/code&gt;. Its negative-invariant mode (&lt;code dir=&quot;auto&quot;&gt;--negative-invariant &amp;#x3C;id&gt; --description ... --verification-method grep_absence|route_check|custom_command --verification-command ...&lt;/code&gt;) registers an invariant through the same seam and
runs it at once (&lt;code dir=&quot;auto&quot;&gt;--no-execute&lt;/code&gt; registers only). &lt;code dir=&quot;auto&quot;&gt;accept&lt;/code&gt; also fails on a
dirty tree, so commit or clean the dossier state first.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty consolidate&lt;/code&gt; refuses a dirty coordination worktree&lt;/strong&gt; — commit the
status files and clear ignored &lt;code dir=&quot;auto&quot;&gt;.kittify/&lt;/code&gt; state in the coordination worktree,
then &lt;code dir=&quot;auto&quot;&gt;--resume&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The graph-manifest check verifies the pack manifest, not just the graph
files.&lt;/strong&gt; Regenerating the reference graph alone leaves the manifest stale; run
the full &lt;code dir=&quot;auto&quot;&gt;spec-kitty charter pack regenerate-graph&lt;/code&gt;, which regenerates both.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The post-merge stale-assertion analyzer&lt;/strong&gt; flags test string-literals tied to
removed code even when the test still passes. Confirm the test is green, then
refresh the docstring or literal.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;contracts-gates&quot;&gt;Contracts gates&lt;/h2&gt;
&lt;p&gt;The &lt;code dir=&quot;auto&quot;&gt;mission-status&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;mission-write&lt;/code&gt; contracts, their tools and the Mission Status API service
live in &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;contracts/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;service/&lt;/code&gt;; ADR
&lt;a href=&quot;/adr/4.x/2026-10-29-1-the-events-domain-and-its-java-services-live-in-spec-kitty-events/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;2026-10-29-1&lt;/code&gt;&lt;/a&gt;),
which builds, checks and releases them on its &lt;code dir=&quot;auto&quot;&gt;service-v*&lt;/code&gt; line. Core keeps only the five handoff
fixtures &lt;code dir=&quot;auto&quot;&gt;contracts/fixtures/fixture_0*.json&lt;/code&gt; and pins one release in
&lt;code dir=&quot;auto&quot;&gt;pins/read-service.source.yaml&lt;/code&gt; (#6915). The contract tests in core read the pinned
&lt;code dir=&quot;auto&quot;&gt;contract-bundles&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;contract-tools&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;conformance-fixtures&lt;/code&gt; extras, which &lt;code dir=&quot;auto&quot;&gt;make sync-services&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;make dev-setup&lt;/code&gt; fetches the extras only) and the &lt;code dir=&quot;auto&quot;&gt;.github/actions/sync-services&lt;/code&gt; action fetch and
digest-verify; &lt;code dir=&quot;auto&quot;&gt;tests/pinned_service_assets.py&lt;/code&gt; fails closed when they are missing.&lt;/p&gt;
&lt;h3 id=&quot;what-runs-where&quot;&gt;What runs where&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;tests (contract tools)&lt;/code&gt;&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;tests-contract-tools&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;ci-router.yml&lt;/code&gt;, a required check
through &lt;code dir=&quot;auto&quot;&gt;router-gate&lt;/code&gt;): &lt;code dir=&quot;auto&quot;&gt;pytest -m &quot;corpus and not windows_ci&quot; tests/contract&lt;/code&gt; minus three
&lt;code dir=&quot;auto&quot;&gt;--ignore&lt;/code&gt; modules, after the sync-services action. It runs when the &lt;code dir=&quot;auto&quot;&gt;corpus&lt;/code&gt; filter group
matches (&lt;code dir=&quot;auto&quot;&gt;contracts/fixtures/**&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;pins/**&lt;/code&gt;) or the &lt;code dir=&quot;auto&quot;&gt;contract_tools&lt;/code&gt; group matches
(&lt;code dir=&quot;auto&quot;&gt;tests/contract/**&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;pins/**&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;scripts/sync_services.py&lt;/code&gt;, the sync-services action,
&lt;code dir=&quot;auto&quot;&gt;tests/pinned_service_assets.py&lt;/code&gt;, the lock and pytest configuration, &lt;code dir=&quot;auto&quot;&gt;tests/conftest.py&lt;/code&gt; and the
&lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; modules the mission-status reference reader imports, spelled &lt;code dir=&quot;auto&quot;&gt;**/&amp;#x3C;module path&gt;&lt;/code&gt; so the
group stays non-src). Unmarked &lt;code dir=&quot;auto&quot;&gt;tests/contract&lt;/code&gt; modules run in the module matrix.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The reality check and its payload helper&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;tests/contract/test_mission_status_reality.py&lt;/code&gt;
and &lt;code dir=&quot;auto&quot;&gt;tests/contract/test_mission_status_payloads.py&lt;/code&gt;) read the committed corpus and run in
&lt;code dir=&quot;auto&quot;&gt;tests (corpus-blocking)&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;tests-corpus-blocking&lt;/code&gt;), together with the example round trip,
&lt;code dir=&quot;auto&quot;&gt;tests/integration/test_mission_review_contract_gate.py&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/migration/test_corpus_wp_snapshot_parity.py&lt;/code&gt; and one performance class.
The modules of both router jobs are deselected from the Packs advisory corpus run, so each runs
once. &lt;code dir=&quot;auto&quot;&gt;tests/ci/test_contracts_routing.py&lt;/code&gt; fails when a corpus-marked &lt;code dir=&quot;auto&quot;&gt;tests/contract&lt;/code&gt; module is
run by neither router job, or by both, and when Packs deselects a module that does not exist.
&lt;strong&gt;The reality check reads the repository’s primary worktree&lt;/strong&gt;, not the checkout that imports it
(&lt;code dir=&quot;auto&quot;&gt;oracles.primary_worktree_root&lt;/code&gt;; #6966). The Mission resolver answers a coord-less or
un-backfilled Mission’s read directory with the primary worktree, so a check rooted at the
checkout would enumerate one &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt; tree and read Missions out of another whenever the
checkout is a linked worktree — the drift read then refuses the whole report with
&lt;code dir=&quot;auto&quot;&gt;500 drift_scan_unreadable&lt;/code&gt; and the Project read reports an &lt;code dir=&quot;auto&quot;&gt;outside root&lt;/code&gt; fallback the oracle
never derives. From a &lt;code dir=&quot;auto&quot;&gt;git worktree&lt;/code&gt; the check therefore judges the primary worktree’s corpus, so a
corpus change made in a linked worktree — committed or not — is not seen there; it is covered by the
corpus-blocking CI job on the PR (whose checkout is the primary worktree) and after the change lands.
From the primary checkout (CI, a plain clone) the root, the corpus and the pass counts are exactly
as before. When git cannot name the primary worktree (no git, not a repository, an empty or failed
listing) the checkout root is used and the linked-worktree mixing can return — the module must still
collect there.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The nightly corpus compare&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;mission-status-corpus&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;ci-nightly.yml&lt;/code&gt;) starts the pinned
native read-service binary and compares it with the Python reference over the whole corpus, with
no exemption list (&lt;code dir=&quot;auto&quot;&gt;scripts/ci/mission_status_corpus_compare.py&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Pins.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;tests/ci/test_service_pins_gate.py&lt;/code&gt; checks every committed pin; &lt;code dir=&quot;auto&quot;&gt;release.yml&lt;/code&gt;
fetches and checks the service pins before it builds (&lt;code dir=&quot;auto&quot;&gt;scripts/sync_services.py --service all --check&lt;/code&gt;) and asserts the wheel carries the pins and no service binary.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Absence.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_events_cutover_absent.py&lt;/code&gt; (on the always-on
&lt;code dir=&quot;auto&quot;&gt;architectural-fast&lt;/code&gt; roster) fails if &lt;code dir=&quot;auto&quot;&gt;services/&lt;/code&gt;, the removed &lt;code dir=&quot;auto&quot;&gt;contracts/&lt;/code&gt; modules or the
retired &lt;code dir=&quot;auto&quot;&gt;contracts.yml&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;contracts-release.yml&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;mission-status-api.yml&lt;/code&gt; workflows come
back, or if a CI, build or script file names them.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;a-reader-or-test-only-change-selects-no-corpus-job&quot;&gt;A reader or test-only change selects no corpus job&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Trips it:&lt;/strong&gt; a pull request that edits a status reader the reality check imports
(anything under &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/status/**&lt;/code&gt;), the reality check’s own test files or
fixture, or a Mission’s &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt;. The router’s &lt;code dir=&quot;auto&quot;&gt;corpus&lt;/code&gt;
group matches &lt;code dir=&quot;auto&quot;&gt;contracts/fixtures/**&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;pins/**&lt;/code&gt; but none of those, so &lt;code dir=&quot;auto&quot;&gt;tests (corpus-blocking)&lt;/code&gt;, the job
that runs the reality check, is not selected. An edit under &lt;code dir=&quot;auto&quot;&gt;tests/contract/**&lt;/code&gt;
selects &lt;code dir=&quot;auto&quot;&gt;tests (contract tools)&lt;/code&gt; through the &lt;code dir=&quot;auto&quot;&gt;contract_tools&lt;/code&gt; group, which does not
run the reality check. The Packs run on a push to &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; does not help: &lt;code dir=&quot;auto&quot;&gt;packs.yml&lt;/code&gt;
passes &lt;code dir=&quot;auto&quot;&gt;--deselect&lt;/code&gt; for every &lt;code dir=&quot;auto&quot;&gt;tests/contract&lt;/code&gt; module that runs in a router job, so
the &lt;code dir=&quot;auto&quot;&gt;built-in-corpus-suite&lt;/code&gt; never runs them.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Symptom:&lt;/strong&gt; a green pull request. The drift is first seen by the nightly run
(&lt;code dir=&quot;auto&quot;&gt;ci-nightly.yml&lt;/code&gt;, job &lt;code dir=&quot;auto&quot;&gt;interpreter-matrix-shard-4&lt;/code&gt;, which runs &lt;code dir=&quot;auto&quot;&gt;tests/contract&lt;/code&gt;,
scheduled daily at 03:17 UTC), up to a day later. This is an accepted risk, tracked
in issue #5623: status-reader drift is caught by the nightly run, not on the
pull request. It was seen on a real pull request, which needed a manual router run.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fix / repro:&lt;/strong&gt; run the check before pushing:
&lt;code dir=&quot;auto&quot;&gt;PWHEADLESS=1 .venv/bin/python -m pytest -q tests/contract/test_mission_status_reality.py&lt;/code&gt;,
and dispatch the router in full mode on the branch:
&lt;code dir=&quot;auto&quot;&gt;gh workflow run ci-router.yml -f mode=full --ref &amp;#x3C;branch&gt;&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;mission-status-api-workflow&quot;&gt;Mission Status API workflow&lt;/h3&gt;
&lt;p&gt;Retired with core’s copy of the service (#6915): the Mission Status API’s build, native legs,
lock-interop job and release run in &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;.github/workflows/service.yml&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;service-release.yml&lt;/code&gt;). Core runs the nightly corpus compare against the pinned binary (above).&lt;/p&gt;
&lt;h3 id=&quot;what-only-a-merge-can-confirm&quot;&gt;What only a merge can confirm&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;The fleet-verdict job is triggered by &lt;code dir=&quot;auto&quot;&gt;workflow_run&lt;/code&gt;, and GitHub runs the copy of
such a workflow that is on the default branch. A change to the workflows it lists
cannot be tested from a pull request; confirm it on the first run after the merge.&lt;/li&gt;
&lt;li&gt;The Packs &lt;code dir=&quot;auto&quot;&gt;built-in-corpus-suite&lt;/code&gt; does &lt;strong&gt;not&lt;/strong&gt; run the reality check or the other
contract tests on a push to &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;: it deselects them, because the router job
&lt;code dir=&quot;auto&quot;&gt;tests (corpus-blocking)&lt;/code&gt; owns the reality check and the router job
&lt;code dir=&quot;auto&quot;&gt;tests (contract tools)&lt;/code&gt; owns the rest. The runs after the merge that execute
them are the router on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; (each job runs only for a change that selects it) and
the nightly shard 4.&lt;/li&gt;
&lt;li&gt;A release tag is a maintainer act and is never pushed from a pull request.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;see-also&quot;&gt;See also&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/development/reference/known-friction-points/&quot;&gt;Known Current Friction Points&lt;/a&gt; — the fast-drifting,
time-stamped list of what is red &lt;em&gt;today&lt;/em&gt;.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/development/reference/red-main-and-release-readiness/&quot;&gt;Red Main and Release Readiness&lt;/a&gt; — what a red
&lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; means and why CI is the release authority.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/development/testing/testing-parallel/&quot;&gt;Parallel testing&lt;/a&gt; — why the make targets are
shaped the way they are.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/development/how-to/pr-landing/&quot;&gt;Landing contributor PRs&lt;/a&gt; — the maintainer landing
runbook and red-classification step.

&lt;/li&gt;
&lt;/ul&gt;
</content>
</entry>
