---
type: "Concept"
title: "CI and Architectural Gate Mechanics"
description: "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."
status: "stable"
generated:
  by: "process:dockitty-export"
  at: "2026-11-12T00:00:00Z"
---

# CI and Architectural Gate Mechanics

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: **what trips each gate, the symptom it produces,
and the command that reproduces it locally** so you can catch it before pushing.

It is a mechanics reference, not a status page — for the *current* red list and
fast-drifting toggles see [Known Current Friction
Points](/development/reference/known-friction-points.md); for what a red `main` means see [Red Main and
Release Readiness](/development/reference/red-main-and-release-readiness.md).

## How CI is wired (so a local run can mirror it)

CI runs as a lean modular pipeline: a path router (`ci-router.yml`) decides which
module and data shards are affected, per-module test jobs run
(`module-tests.yml` / `ci-modules.yml`), and results aggregate with a coverage
and diff-cover gate (`ci-aggregate.yml`); a nightly full run (`ci-nightly.yml`)
and a fork-safe Sonar scan (`sonar.yml`) sit alongside. The nightly's `performance`
job runs weekly, on the Sunday run only, or on a manual `workflow_dispatch` (#7704);
its red still opens the deduped `performance` P0, and the next green weekly run closes it. The trap is structural:
**a passing `pytest <file>` locally does not mean a gate will be green**, 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.

Two habits defuse most of this class:

- Reproduce a gate by running its **exact selection**, not just the test file —
  e.g. a marker-scoped shard runs `-m "fast and not windows_ci"`, so a test
  missing the `fast` marker is silently deselected there even though it passes
  when you name it directly.
- Before declaring a branch green, run the architectural gate files your change
  implicates over the **rebased tip**. Do not sweep the whole
  `tests/architectural/` directory in mission work ([`NO_FULL_HEAVY_SUITES_IN_MISSION`](https://github.com/spec-kitty/spec-kitty-open-packs/blob/main/packs/internal/directives/no-full-heavy-suites-in-mission.directive.yaml)); CI runs
  the whole battery for you: the always-on `architectural-fast` job plus the two
  `architectural-heavy` legs on code and CI-config PRs.

Since mission `ci-runtime-stabilisation` ([#5510](https://github.com/spec-kitty/spec-kitty/issues/5510)),
these things about that pipeline are worth knowing before you read a red check:

- **The battery has three parts.** `architectural-fast` is always on (docs-only PRs
  included). Its roster of deterministic ratchet and census gates is held in
  `.github/ci-module-registry.yml` under `special_tiers.architectural.fast_gate`,
  with a per-file budget. `architectural-heavy` is one job key with a two-leg
  matrix (`--battery-part 1/2` and `2/2`). The three parts are file-disjoint and
  together cover the base selection exactly, which
  `tests/architectural/test_battery_partition_proof.py` proves statically.
- **CI-config changes select the heavy battery.** The router path group
  `ci_config` (workflows, composite actions, `scripts/ci/**`, `pytest.ini`,
  `pyproject.toml`, `Makefile`, the registry and the shard timings file) gates the
  heavy battery and no other job.
- **A change to a path a gate reads selects that gate ([#6994](https://github.com/spec-kitty/spec-kitty/issues/6994)).**
  Many heavy gates also read paths outside their code scope. The clock bans, for
  example, scan `scripts/**` and `tests/**`. Each such gate declares those paths
  once, under `special_tiers.architectural.scan_scopes` in the registry.
  `scripts/ci/gate_selection.py` derives the router group `arch_scan_scope` from
  them, and `ci-router.yml` must list exactly that union. A diff that matches only
  that group runs, in each heavy leg, only the gates whose scope it touches
  (`scripts/ci/battery_scope.py` writes the list and the plugin reads it from
  `SK_BATTERY_GATES_FILE`). 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 `tests/architectural/` (`tests/conftest.py`, `tests/_support/**`,
  helper scripts), which is battery code, not a scan scope. When a new gate reads
  outside its code scope, add its row to `scan_scopes`.
  `tests/architectural/test_battery_scan_scope_routing.py` proves the property
  for every declared gate and glob.
- **A declaration must be complete, and CI checks it ([#7000](https://github.com/spec-kitty/spec-kitty/issues/7000)).**
  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. `tests/architectural/test_gate_scan_scope_completeness.py`
  extracts, statically, every repository-rooted read a gate makes --
  `_REPO_ROOT / "…"`, a chain built from it, a `glob`/`rglob`/`iterdir`/`walk`
  call, a literal `git ls-files` / `ls-tree -- <path>` pathspec, in the gate file
  and in every `tests/**` helper it imports (absolute or relative) --
  and fails when neither the gate's `scan_scopes` row nor the battery code scope
  (`src/**`, `tests/architectural/**` and the router's own code groups) covers it.
  A read whose whole path is computed at runtime (`_REPO_ROOT / rel`) 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 `_gate_read_scope` docstring): a gate that takes the root from
  a pytest parameter (`repo_root`) or from a `tmp_path`, a pathspec passed through a
  variable or through a helper whose call never names the root, and the reads of an
  imported `tests/conftest.py` are not seen. It narrows the #6994 defect class; it does
  not prove absence.
- **Corpus tests have one advisory owner.** `packs.yml` runs the `-m corpus`
  suite as the advisory job `built-in / -m corpus suite (advisory)`. The corpus
  tests that have no other blocking per-PR home run blocking in two router jobs:
  `tests (corpus-blocking)` (the modules that read the committed corpus) and
  `tests (contract tools)` (the contract tool unit tests). The router jobs `tests (cli)`,
  `tests (status)`, `tests (consolidation)` and `tests (corpus)` no longer exist;
  the `cli`, `status` and `consolidation` module rows in `ci-modules.yml` are now
  their only homes.
- **That advisory lane's budget is derived, not picked** ([#7206](https://github.com/spec-kitty/spec-kitty/issues/7206)).
  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 `tests/` 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
  `tests/ci/test_corpus_blocking_home.py` (tree-wide corpus reach, #3008) and
  `tests/ci/test_contracts_routing.py` (exactly one pytest invocation) forbid. Instead the job
  records its measured maximum and the cap follows the #5378 rule
  (`ceil((max-suite + 0:30) × 1.5)` = 31), enforced by `tests/ci/test_nightly_timeout_headroom.py`;
  the recorded maximum must stay within 75 % of the cap,
  `tests/ci/test_corpus_suite_budget.py` 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
  ([#4437](https://github.com/spec-kitty/spec-kitty/issues/4437)). Selection semantics — the
  marker, the deselects, the `continue-on-error` and the trigger — are unchanged.
- **A nightly backstop runs the whole battery.** `ci-nightly.yml` job
  `architectural-backstop` executes the full base selection with no partition
  plugin, so a green nightly means the battery ran (see the amendment to
  [ADR 2026-09-26-1](/adr/3.x/2026-09-26-1-ci-coverage-honesty.md)).
- **A `ready_for_review` run can skip on prior evidence.** 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
  [Skip-if-green on ready-for-review](#skip-if-green-on-ready-for-review) below
  and the amendment to
  [ADR 2026-09-23-1](/adr/3.x/2026-09-23-1-auto-merge-required-checks-gate.md).

- **The merge queue runs the required checks again.** `ci-router.yml`,
  `ci-modules.yml` and `ci-quality.yml` also trigger on `merge_group`, so the
  three required checks report on the queue's temporary
  `gh-readonly-queue/main/...` ref, which holds `main` plus the PRs ahead in
  the queue. The changed-files and prose-scan steps diff a queue run against
  `github.event.merge_group.base_sha`, so it is path-scoped like the PR run.
  Skip-if-green never applies there, the `pr:*` label guards read no labels, CI
  Aggregate skips queue runs (diff coverage was judged on the PR), and no
  optional workflow joins the queue. `tests/ci/test_merge_queue_wiring.py` pins
  this.

The rest of this page groups gates by the change that trips them.

## Testing and marker gates

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.

### A test with the wrong marker contributes zero CI coverage

- **Trips it:** a new test carries the wrong (or too few) `pytestmark` markers,
  so the shard meant to run it deselects it. Example: a test marked only `unit`
  when its shard selects `-m "fast and ..."` never runs in CI.
- **Symptom:** the diff-coverage gate (`ci-aggregate.yml`) goes red on a source
  file that *has* a passing test — because that test never executed in CI. Named
  directly (`pytest <file> --cov`) it shows full coverage locally, which hides
  the problem.
- **Fix / repro:** give the new test the same speed + domain markers its
  siblings use (typically `fast` plus the module's domain marker). Reproduce the
  shard's real selection locally — run `pytest <dir> -m "fast and not
  windows_ci"` — not just `pytest <file>`.

### A file with two markers can fall between two shards

- **Trips it:** a test file carries two markers whose CI jobs *mutually exclude*
  it (e.g. both `distribution` and `e2e`, where the e2e shard runs `-m "not
  distribution"` and the other shard ignores the e2e directory). The file
  reaches no gate at all.
- **Symptom:** `tests/architectural/test_marker_job_completeness.py` goes red —
  each routed marker gained a carrier that no job selects. This runs in an
  architectural shard, so it only surfaces on CI.
- **Fix / repro:** 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
  `-m "distribution and e2e and not windows_ci"` pass over the e2e directory);
  the completeness gate auto-discovers it. Run
  `pytest tests/architectural/test_marker_job_completeness.py` before pushing.

### A new test file must declare a marker

- **Trips it:** a new `tests/**/test_*.py` file lands without a module-level
  `pytestmark`.
- **Symptom:** an architectural marker-convention gate reds, insisting every test
  file declare *some* 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.
- **Fix / repro:** add `pytestmark = [pytest.mark.unit, pytest.mark.fast]` (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 `tests/architectural/`, not just
  one of them.

### Moving a slow / stress / quarantine test can red the marker baseline

- **Trips it:** relocating or renaming a test that carries a budget marker
  (`slow`, `stress`, `quarantine`). 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.
- **Symptom:** the marker-baseline architectural gate reds even though it is the
  same test with the same marker.
- **Fix / repro:** 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.

### New `contracts/*.md` YAML blocks need a round-trip skip marker

- **Trips it:** the router job `tests (corpus-blocking)` (job key
  `tests-corpus-blocking` in `ci-router.yml`) runs
  `tests/contract/test_example_round_trip.py`, which walks
  **every** `kitty-specs/*/contracts/*.md` and collects each fenced ` ```yaml `
  block as a contract-example case. A block in a non-legacy file that is neither
  executable nor marked as an illustration fails.
- **Symptom:** `test_contract_example_round_trip[...MISSING_FRONTMATTER]` fails,
  reddening `tests (corpus-blocking)`. The Packs advisory corpus job deselects
  this file, so a red here is blocking, not advisory. A local run of `tests/ci` + `tests/architectural`
  (the obvious blast radius for a CI change) does **not** cover
  `tests/contract/`, so illustrative YAML passes locally and only reds on CI.
- **Fix / repro:** tag each YAML block with one of, as its first line inside the
  fence:
  - `# pydantic_model: <Model>` — executed against that model, or
  - `# round-trip: skip: <reason>` — non-executable illustration; the reason is
    mandatory (a bare marker still fails).

  Run `pytest tests/contract/test_example_round_trip.py` locally before pushing.

### The pre-review gate can run the full suite and hang

- **Trips it:** `spec-kitty agent action implement WP##` (and `review`, and
  `move-task --to for_review`) trigger the auto-scoped pre-review regression gate
  (`src/specify_cli/review/pre_review_gate.py`, baseline capture in
  `review/baseline.py`). When the auto-scope resolves broadly it runs
  effectively the whole suite with no path arguments.
- **Symptom:** 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.
- **Fix / repro:** set `SPEC_KITTY_SKIP_PRE_REVIEW_GATE=1` 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
  `in_progress` and the worktree is created — even if baseline capture times out.
  To make the baseline itself cheap, declare a fast `review.test_command` in
  `.kittify/config.yaml` (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.

## The architectural gate battery

Adding new `src/` 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 `architectural-fast` job and the two legs of
`architectural-heavy` (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 `PYTHONPATH=src -o addopts=""` so collection matches CI.

- **Dead-symbol gate** (`tests/architectural/test_no_dead_symbols.py`): a new
  public symbol in a module's `__all__` that no other `src/` file imports fails.
  Fix by trimming `__all__` to genuinely public symbols — test-only helpers stay
  importable but out of `__all__`.
- **Dead-module gate** (`tests/architectural/test_no_dead_modules.py`): a new
  module with zero non-test `src/` importer fails — even a `python -m` entry
  point launched by an argv string, because that is not a static import. Fix by
  *wiring* it: have the launcher reference the module by name
  (`from . import _server_main; MODULE = _server_main.__name__`) rather than a
  string literal, so it is statically reachable and rename-safe.
- **Clock call-ban** (`tests/architectural/test_clock_call_ban.py`):
  `time.time()` / `.now()` / `.utcnow()` / `.today()` anywhere (including tests)
  outside `src/kernel/clock.py` fails. Import from `kernel.clock` instead.
- **Clock import-ban** (`tests/architectural/test_clock_import_ban.py`, distinct
  from the call-ban): a raw `import datetime` / `from datetime import ...`
  anywhere outside `src/kernel/clock.py` fails. Import from `kernel.clock`, or
  add an exemption line under `tests/architectural/_exemptions/`.
- **Charter facade table** (`tests/architectural/test_charter_facades_reexport_offering.py`):
  this self-discovers every `src/charter/*.py`, so a new charter facade that
  re-exports a `charter.offering` symbol in its `__all__` must be registered in the
  facade table. It runs in an architectural shard, invisible to fast-shard local
  runs.
- **Environment-fragile absolute counts:** integration jobs run
  `uv sync --frozen --all-extras`, which installs and imports more optional
  dependencies than a local checkout. An absolute module-count or import-count
  assertion (`len(modules) <= N`) passes locally and false-reds on CI. Assert a
  specific module's presence or absence, never an absolute count.

### Fast roster, shard legs, and the partition proof

The battery base selection is `tests/architectural` with the marker expression
`not performance and not stress and not timing`, minus the four files that other
always-on lanes own (`test_no_legacy_terminology.py`, `test_layer_rules.py`,
`test_pyproject_shape.py`, `test_archive_root_byte_identical.py`). It runs as:

| Part | Job (display name) | Selection | When |
| --- | --- | --- | --- |
| Fast | `architectural fast gates (ratchet/census, always-on)` | `--battery-part fast`: the registry roster | every PR shape |
| Heavy leg 1 | `architectural battery (heavy, code-scoped) 1/2` | `--battery-part 1/2` | code, `ci_config` or `architectural` path changes; for a diff that matches only `arch_scan_scope`, the leg's gates whose declared scan scope the diff touches. A **prose-only** diff (#4842) runs the same scoped selection when it touches a declared scan scope, and skips the battery when it declares none (#6999) |
| Heavy leg 2 | `architectural battery (heavy, code-scoped) 2/2` | `--battery-part 2/2` | same as leg 1 |
| Backstop | `Architectural battery backstop (nightly-only, #5510)` | the base, no partition flag | nightly |

- **Prose-only diffs and the declared scopes (#6999, operator ruling 2026-11-01).** A
  PR whose whole Python diff is comments and/or docstrings is down-routed off the
  module matrix and every code shard (`scripts/ci/prose_only.py`, published as
  `prose-scan`'s `prose_only` output). The heavy battery is exempted from that
  subtraction for a **declared** scan-scope match: `prose-scan` also publishes
  `scan_scope_match` (the `arch_scan_scope` globs, read through
  `gate_selection.matches_declared_scan_scope`), the battery `if:` runs when
  `prose_only != 'true'` or `scan_scope_match == 'true'`, and the selection step
  passes the verdict on (`battery_scope select --prose-only`) so each leg runs
  **only** the gates whose `scan_scopes` declaration matches. A prose-only diff
  that matches no declared scope still skips the battery. The companion output,
  rather than a second reference to `needs.changes.outputs.arch_scan_scope`, keeps
  the parsed group set honest: deleting the group's own OR term still reds
  `tests/architectural/test_battery_scan_scope_routing.py`. Declared scopes only:
  for a prose-only diff the battery relies on the `scan_scopes` rows being
  complete (checked by `tests/architectural/test_gate_scan_scope_completeness.py`,
  #7016), so a gate that reads prose more widely than its declared scope is
  skipped for a prose edit outside that scope.
- **The roster is registry-held.** Each entry in
  `special_tiers.architectural.fast_gate.roster` carries a path, a
  `budget_seconds` 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
  `tests/ci/test_battery_roster_budgets.py`, never against wall-clock time.
- **Adding or moving a battery test file** needs no workflow edit: the plugin
  `scripts/ci/battery_partition_plugin.py` assigns each file to exactly one part
  from the per-file timings in `.github/ci-shard-timings.json`. A file with no
  timing gets the median weight, and a timing-set mismatch prints a `::warning::`
  rather than silently using uniform weights.
- **A partition-proof red** means a file is in two parts or in none. The proof
  (`tests/architectural/test_battery_partition_proof.py`) evaluates the three
  literal `--battery-part` commands, so fix the roster or the timings, not the
  proof.
- **Worker count** is a literal `-n 4` in every CI battery command; see
  [CI worker policy](../testing/testing-parallel.md#ci-worker-policy-and-the-nightly-architectural-backstop).

### Skip-if-green on ready-for-review

When a draft PR is marked ready for review, the head SHA has usually already been
tested. The selection jobs (router `changes`, CI Modules `generate-matrix`, Packs
`changes`) therefore run `scripts/ci/green_match.py decide` first. It suppresses
the path-filter step, and so every path-gated job, only when all of these hold:

- the event is a `pull_request` with the action `ready_for_review`, on the first
  attempt of the run;
- a completed, successful run of the same workflow exists for the same head SHA;
- that run carries a non-expired marker artifact `ci-tested-key-pr<N>-base-<sha>`
  for the identical tested key `(workflow file, PR, head SHA, first parent of the
  merge commit the run tested)`.

The required contexts `router gate` and `CI Modules gate` still post success. On a
skip run the always-on lanes and `prose-scan` still run, and `tests (docs)` still
runs on a prose-only PR.

- **Symptom of a surprise skip:** a `ready_for_review` run finished with every path-gated
  shard skipped, and the step summary names a matched run.
- **Escape hatch:** re-run the workflow. Attempt 2 always executes.
- **Never suppressed:** push, `workflow_dispatch`, `workflow_call`, schedule, any
  other `pull_request` action, a failed, cancelled or in-progress prior run, a
  moved base, and any lookup error (the helper runs normally and warns).
- **CI Aggregate** 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.

### Moving or renaming a symbol that is dead-symbol allowlisted

The dead-symbol allowlist lives in `tests/architectural/dead_symbol_allowlist.yaml`
and is keyed by `(module, name)`: `module` is the module whose `__all__` declares
the name. No body hash is stored
([ADR 2026-10-01-1](../../adr/4.x/2026-10-01-1-dead-symbol-allowlist-module-name-identity.md)).

- **Editing the body** of an allowlisted symbol costs nothing: no allowlist edit.
- **Renaming or moving** one makes the gate report the old entry `GONE` (for a
  move, with a "probably moved to `X`" hint) and the new location as an
  offender. Update `module:` or `name:` of that entry in the YAML file.
- **Adding an entry** needs a declared `category_*`, a rationale (its own or
  inherited from the category -- see
  [declaring a new category](../how-to/add-architectural-gate-exemption.md#declaring-a-new-category)),
  an `issue` where the category sets `requires_issue: true`, and a raised
  `test_no_dead_symbols` leaf in `tests/architectural/_baselines.yaml`
  (`allowlist_entries`, or `widened_grandfathered_470` for the widened section).
  Both leaves are shrink-only caps. Try wiring the symbol, dropping it from
  `__all__` or deleting it first.

Never weaken the gate to get past it.

### The `ruff format` exclude ratchet has a twin

`[tool.ruff.format].exclude` in `pyproject.toml` is a large, shrink-only
formatter-debt allowlist (that is why a whole-repo `ruff format --check .` passes
on `main` — excluded files are skipped). Two distinct architectural tests guard
it, and checking only one misses failures:

- `tests/architectural/test_ruff_format_enforcement.py` — asserts
  `ruff format --check .` exits 0 and every exclude entry names a live file.
- `tests/architectural/test_ruff_format_exclude_ratchet.py` — asserts every
  exclude entry **still genuinely reformats**, and that the entry count stays
  under a shrink-only ceiling.

Two changes trip the ratchet, and both are caught only at the integration/merge
gate, not by a per-WP subset run:

1. You run `ruff format` on an excluded file (making it clean) → its entry no
   longer reformats → red.
2. You delete an excluded file's source → its entry names a missing file → red.

Fix both by **removing** 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.

### A scanner that swallows a parse failure reds the parse fail-closed gate

`tests/architectural/test_scanner_parse_fail_closed.py` scans every module under
`tests/` for a construct that can swallow a failure to parse source: an
`except` catching `SyntaxError` (or a subclass) that does not always re-raise,
a bare, `Exception`, `BaseException`, `AssertionError` or aliased handler around
a parse call, `contextlib.suppress(...)` around one, or `finally: return`. 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.

It trips on harmless-looking code too — for example
`try: parse_file(p) except AssertionError: continue`. Repro:
`pytest tests/architectural/test_scanner_parse_fail_closed.py`. Fix it by
reading and parsing through `tests/architectural/_ast_scan.py`
(`read_and_parse` / `parse_file` / `parse_source` / `read_source`, which fail
closed naming the file). Only when the input is *deliberately* allowed to be
unparseable, add a rationale row to its `_ALLOWED_SWALLOWS` ledger; the ledger
is checked for exact equality, so remove the row when the handler goes.

### Router path filters are the tail of a guarded SSOT chain

The `ci-router.yml` path-filter globs are not a free-standing authority — they
are the verbatim tail of a three-link single-source-of-truth chain:
`tests/release/ci_retirement_scrub.json` (the SSOT) → `.github/ci-module-registry.yml`
→ `ci-router.yml` filters. Each link is pinned by an architectural transcription
guard (`tests/architectural/test_module_shard_registry.py`,
`tests/architectural/test_ci_router_transcription_guards.py`).

- **Trips it:** adding a glob to a router filter group alone.
- **Symptom:** 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.
- **Fix:** to change what a module *owns* for routing, edit the scrub SSOT and
  cascade verbatim through all three links. To route test directories to modules
  *without* touching the chain, derive the mapping from the registry inventory in
  the gate-selection logic (`scripts/ci/gate_selection.py`) rather than
  hand-authoring a second map.

### An extra narrow lane for an out-of-matrix test

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 `mission_state` (#5864) and the runtime-home
path-literal guard (#6879) — add a **non-src** router group plus one job, not a registry row:

- declare the group's globs in `tests/release/ci_retirement_scrub.json`
  **`non_src_router_groups`** and transcribe them verbatim into the filter block, `changes.outputs`
  and the job's `if:`, plus a row in
  `tests/architectural/test_no_duplicate_suite_execution.AUTHORIZED_PER_CHANGE_SUITE_JOBS` and the
  `router-gate` `needs:` list;
- spell the globs `**/`-prefixed (e.g. `**/specify_cli/status/**`). A `src/`-spelled glob makes the
  group *src-backed*, and every src-backed group must also be a module-registry row
  (`test_gate_selection_authority.py`), so the lane becomes a CI-matrix change;
- keep it **out** of the FR-004 `unmatched` union and `architectural-heavy`'s `if:` — both are
  derived from the src-backed group set and the transcription guards red if they diverge;
- do not name a directory that no src-backed group owns (e.g. `src/specify_cli/paths/**`). Such a
  directory trips the fail-closed catch-all and already runs *every* job, this lane included;
  naming it turns that sensor off and narrows the run to your lane.

**Trips it:** adding the globs to the filter block only, or to a src-backed group without a
module row. **Symptom:** the transcription guard in
`tests/architectural/test_ci_router_transcription_guards.py`, or
`test_select_modules_full_mode_selects_all_registry_modules`, or the duplicate-suite ledger.

## Stored test-universe collection

Several architectural gates need the full list of collected tests with their
markers (the "test universe"). One real `pytest --collect-only` 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.

**What it does and does not do.** 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 — `test_fast_tier_marker_completeness.py`
in 1/2 and `test_same_tier_uniqueness.py` in 2/2 — but a leg only collects when a
*selected* gate holds one, see below), and the `ci` 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
`kitty-specs/shared-collection-and-shard-recapture-01M42V58/evidence/ci-measurements.md`.

### Where it lives and what it is keyed on

- The code is `tests/architectural/_universe_store.py`. `collect_universe()` in
  `tests/architectural/_gate_coverage.py` calls it; its signature and return value are
  unchanged.
- The store is `.pytest_cache/universe-store/`, which git ignores. It holds one
  record file, `<key>.json`, plus a lock file. Writing a record deletes every other
  record file.
- 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 `SPEC_KITTY_*` plus `PYTEST_ADDOPTS`. The variables the test
  session sets for itself are listed in `ENV_EXCLUDED_NAMES` and left out, so a
  pre-test step and a test compute the same key. The key also overlays the
  operator env file (`.kitty.env`) through the product's own loader. A machine whose
  home-level `.kitty.env` sets `SPEC_KITTY_*` variables may therefore see local reuse
  not happen, because pytest isolates `HOME`; CI is unaffected.
- 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
  `not stored: the checkout changed during the collection`, and the pre-test step
  fails on that line.
- 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.
- For one key, one collection runs at a time on a machine. Other callers wait on
  the lock and then read the stored copy.

### When the store is bypassed

The store is not read or written, and the caller collects for itself, when:

| Reason in the report | Condition |
| --- | --- |
| `dirty-checkout` | `git status --porcelain` is not empty. Untracked files count, because an untracked test file changes what is collected. |
| `root-override` | the caller passed a `repo_root` (a patched root). |
| `unsupported-platform` | the platform is not Linux or macOS. The same reason, with a `detail`, is reported when the store directory or its lock cannot be used. |
| `git-unavailable` | git cannot describe the checkout. |
| `env-file-unreadable` | an operator `.kitty.env` exists but cannot be read, so the environment variables of the key are unknown. |

### The per-test budget on a collecting gate

A bypass is not free: the caller now pays the whole collection inside its own test setup. One
`pytest --collect-only` 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 `check` step cannot see that cost, because it only reads the report lines.

The suite's per-test timeout is a 240 s runaway-hang backstop (`pytest.ini`, #3143), which is at
or below a legitimate collection. A gate whose fixture setup may collect therefore carries its
own `@pytest.mark.timeout(...)` budget, derived from the collector's own ceiling
(`tests/architectural/_gate_coverage.COLLECT_TIMEOUT_S`, 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 (`timeout_func_only` is unset), so the marker also bounds the module-scoped fixture setup
that triggers the collection.

The rule is the one `pytest.ini` states: a legitimate slow test gets a per-test marker, the
global default is not raised. The budget must never be below `COLLECT_TIMEOUT_S` — 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
`tests/architectural/test_same_tier_uniqueness.py` errored at once while `check` still printed
"Reuse held" (an interrupted request writes no report line).

Two invariants keep the two numbers together, both in that test module: every test whose fixture
closure reaches `universe` must carry a budget of at least `COLLECT_TIMEOUT_S`, and
`_gate_coverage.py` may not pass a bare numeric timeout to a collection subprocess. A test that
never collects keeps the 240 s default.

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 `check` step (`Reuse broken: … collected` / `… bypassed (dirty-checkout)`),
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.

### The report line

When `SK_GATE_REUSE_REPORT` names a file, each call of `collect_universe()` appends
one JSON line to it: `outcome` (`reused`, `collected` or `bypassed`), `reason`
(`no-record`, `invalid-record`, `origin-mismatch` or a bypass reason from the table),
`key`, `caller` (the pre-step is `prestep`, a test is its file path), `seconds`, and
when present `detail` and `dirty_paths`. A `detail` starting with `not stored` on a
`collected` line means the fresh collection could not be written back.

### The pre-test step and the post-test check

`python -m scripts.ci.collect_universe_prestep <command>` runs from the repository
root checkout:

| Command | What it does | Exit status |
| --- | --- | --- |
| `key [--with-commit]` | Prints the collection key. With `--with-commit` it prints `<key>-<commit>`, which is the CI cache key. | 0; 2 when the checkout is dirty or git cannot describe it |
| `collect` | Calls `collect_universe()` once and prints the report line. | 0 only when the line is `reused`, `collected` with the record stored, or an unsupported-platform bypass without a `detail`; 1 for anything else, including a record that could not be stored |
| `check` | Reads the report file and writes a table to the job summary. | 1 when the pre-test line is not acceptable, when a later request in the job collected or was bypassed (other than `root-override`) after the pre-test step stored or reused a record, or when a report line is malformed; 0 otherwise |
| `consumers --battery-part <part> [--gates-file <path>]` | Prints `true` when the battery partition holds a test file that calls `collect_universe()` (found by scanning `tests/architectural/test_*.py`), `false` otherwise. `--gates-file` (default `$SK_BATTERY_GATES_FILE`, the variable the battery plug-in reads) intersects the question with the gates the diff selected for this leg ([#7001](https://github.com/spec-kitty/spec-kitty/issues/7001)), 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. | 0 with an answer; 1 and no answer for an unknown part, an unreadable gates file, or any other failure |
| `compare` | Collects once with the store bypassed and diffs the result against the stored record. | 1 on any difference or when no usable record exists |

`collect` and `check` 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, `check` prints a fallback note and exits 0.

### Where it runs

- **`ci-router.yml`, job `architectural-heavy`** (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 `consumers --battery-part <leg>` in a step with id `select`, and
  a failed answer fails the job). Steps in order: compute the key, restore the store,
  `collect`, save the store, run the battery (the pytest command line is unchanged),
  `check` with `if: always()`.
  The decision is intersected with the leg's own selected-gates file ([#7001](https://github.com/spec-kitty/spec-kitty/issues/7001)):
  `consumers` is asked with `--gates-file` bound to the same
  `steps.scope.outputs.gates_file` the battery step reads as `SK_BATTERY_GATES_FILE`.
  A scoped leg (#6994) runs a handful of gates, so it needs the universe only when one
  of *those* 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.
- **`module-tests.yml`, job `test`.** The same steps, but only in per-PR mode and
  only on the shard whose selected test list contains
  `tests/ci/test_corpus_blocking_home.py::test_every_corpus_test_has_a_blocking_per_pr_home`,
  the test that takes the `live_universe` fixture. The `ci` module runs as one shard
  (`shard_count: 1` in `.github/ci-module-registry.yml`), so that shard holds the test.
  `tests/ci/test_ci_workflow_prestep_shape.py` pins that the test still exists.
  Full-mode warm-up may rewrite `uv.lock` and leave the checkout dirty, so it
  skips the step.
- **The cache key is `universe-<key>-<commit>`.** 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 `restore-keys`), and the save runs before pytest, so a leg that goes
  red on a test can still be re-run warm.
- **The shard list lives in the runner's temp directory**, not in the checkout. An
  untracked file there would make the checkout dirty for the rest of the job.
- **None of the collect, check or compare steps sets `continue-on-error`.** The
  shape test pins that, because it would turn the check into a summary.

### Nightly equivalence job

`ci-nightly.yml` job `universe-equivalence` runs `collect` and then `compare` 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
`nightly-summary`.

### Run it locally

```bash
# The key of a clean checkout, and the CI cache key (commit appended)
python -m scripts.ci.collect_universe_prestep key
python -m scripts.ci.collect_universe_prestep key --with-commit

# Collect once and store it, then run a gate against the stored copy
export SK_GATE_REUSE_REPORT=/tmp/universe-reuse.jsonl
python -m scripts.ci.collect_universe_prestep collect
PYTHONPATH=src python -m pytest tests/architectural/test_fast_tier_marker_completeness.py -q
python -m scripts.ci.collect_universe_prestep check

# Prove the stored copy equals a fresh collection
python -m scripts.ci.collect_universe_prestep compare

# Ask a leg about its own selected gates instead of its whole partition (#7001)
printf '%s\n' tests/architectural/test_dead_builtin_doc_paths.py > /tmp/gates.txt
python -m scripts.ci.collect_universe_prestep consumers --battery-part 1/2 --gates-file /tmp/gates.txt
# -> false (that gate never collects the universe), so every universe step is skipped
printf '%s\n' tests/architectural/test_fast_tier_marker_completeness.py > /tmp/gates.txt
python -m scripts.ci.collect_universe_prestep consumers --battery-part 1/2 --gates-file /tmp/gates.txt
# -> true (this one does)
```

### What a scope-only leg skips

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 **both** legs
answered "collect" for a diff that selected three or four unrelated gates. The
intersection removes that:

| Diff | Selected gates (1/2 · 2/2) | A collecting one among them? | Universe steps |
| --- | --- | --- | --- |
| docs-only (`docs/**`) | 3 · 3 | no | all five skipped |
| docs/adr-only (`docs/adr/**`) | 3 · 4 | no | all five skipped |
| tests-only (`tests/**`) | 19 · 23 | yes (both legs) | unchanged |
| a `src/**` change | — | full leg (`mode=full`) | unchanged |

Measured on the development host (a shared machine with heavy concurrent load, so the
absolute numbers are pessimistic): a cold collection took **396.7 s** and a warm reuse
0.55 s, while the decision itself — partition, AST scan and the one file read — costs
about **1.5 s**. 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 `universe-<key>-<commit>`.

Further cheap wins, noted but **not** taken here:

- 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.
- A scoped leg still pays checkout and `uv sync --frozen --all-extras` (about 1–2
  minutes) for a handful of gates; narrowing that sync is a separate change.
- The decision could reuse the partition it already computed for the plug-in instead of
  recomputing it, saving well under a second.

A dirty checkout (including an untracked file) is bypassed on purpose; commit or
stash first to see a `reused` line. To force a fresh collection, run
`rm -rf .pytest_cache/universe-store`; there is no bypass environment variable, and
`pytest --cache-clear` does not remove that directory.

## Scheduled shard-timings recapture

`.github/ci-shard-timings.json` records, for each registry module, the exact node
ids its shard collects and how long each took (`module_test_node_durations`, the
identity-keyed authority `scripts/ci/shard_select.py` weights a shard by), their
ordered projection (`module_test_durations`), the count and the summed seconds. The
entry drifts whenever a test is added, removed, renamed or replaced. The workflow
`ci-shard-recapture.yml` (schedule 04:41 UTC daily, plus `workflow_dispatch`, and
only on the primary branch (`main`)) refreshes the drifted entries for **every**
registry module and proposes the change as a pull request. The code is
`scripts/ci/recapture_shard_timings.py`.

The job `recapture-shard-timings` runs the script in three steps:

| Phase | Holds the token | What it does |
| --- | --- | --- |
| `detect` | yes | Asks `gh` whether a recapture pull request is open on the proposal branch. |
| `capture` | no | Finds drifted modules, captures them, and writes the result (`drifted`, `captured`, `failed`, `deferred`) as a step output and a job-summary table. |
| `publish` | yes | Pushes the refreshed file and opens or refreshes the pull request. |

The `capture` phase runs test code for a long time, so it refuses to run when
`CHARTER_SHARD_RECAPTURE_TOKEN` is in its environment and starts every subprocess
without any token variable.

**Finding drift.** A collection-only pass (`pytest --collect-only`, over the same
directories and marker expression the producer uses) lists each module's **node
ids** 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 `module_test_node_durations` (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.

**Capturing.** Each drifted module is captured by
`python -m scripts.ci.capture_shard_timings --module <m> --write` in its own
subprocess, longest-untouched first.

**Time budget.** The workflow passes `--budget-seconds 4200`, counted from the start
of the `capture` 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
`deferred`, 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).

**The valid-capture rule.** 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, `unique_tests_measured`) 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 `failed`; 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 *captured with failing tests*, 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 `failed`. The script exits 1 when any
module failed.

**Proposal.** The branch is `ci/recapture-shard-timings`, and GitHub allows one open
pull request per head branch.

- With no open pull request, `publish` force-pushes the branch and opens one.
- With an open pull request, `capture` starts from the proposal's timings for the
  modules it already refreshed, so each run continues the work, and `publish` adds
  a follow-up commit with a plain push. It never forces.
- 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.

**The red window.** 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 `strict-shard-timings-check` in the same
workflow runs `tests/architectural/test_module_length_agreement.py` with
`SPEC_KITTY_STRICT_SHARD_TIMINGS=1` and has no `needs` 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.

To run it by hand, `capture` without `--write` only reports drift:

```bash
python -m scripts.ci.recapture_shard_timings capture --module charter
```

## Docs-freshness and registration gates

Adding or moving a `docs/**` page trips several documentation gates that draw
from separate committed catalogs; fixing one leaves the others red.

The prose of those pages is linted by a separate, always-on job: see
[`docs-lint`](#docs-lint).

### A new docs page needs triple registration plus a description band

- **Trips it:** a new `docs/**/*.md` page that is not registered everywhere.
- **Symptom:** the docs build and docs-freshness checks red with a mix of
  `DOCS-INDEX-DRIFT`, `INVENTORY-INCOMPLETE` / `INVENTORY-LOCKFILE-DRIFT` /
  `LEAK-MISSING-INVENTORY`, and a description-length failure. The "committed
  index" in a drift error is the machine-generated *retrieval* index, not the
  curated `index.md`, which is why updating only `index.md` is not enough.
- **Fix / repro:** register the page in its curated index and satisfy the
  frontmatter band; leave the generated surfaces alone:
  1. **Curated section index** — hand-add the page to its section's `index.md`
     (satisfies the index-completeness rule).
  2. **Page inventory, retrieval index, ADR era table rows** — do **not**
     regenerate `docs/development/page-inventory.yaml`,
     `docs/development/docs-retrieval-index.yaml` or the era table rows in the
     PR. They are regenerated on `main` after merge by the `ci/regen-docs-index`
     bot pull request (`docs-index-regen.yml`, `scripts/ci/regen_docs_index.py`),
     and the `docs-lint` guard (`scripts/ci/check_generated_docs_untouched.py`)
     refuses a PR that edits them. Until the bot PR merges, `INVENTORY-INCOMPLETE`,
     `LEAK-MISSING-INVENTORY`, `INVENTORY-LOCKFILE-DRIFT` and `DOCS-INDEX-DRIFT`
     report the new page as **warnings**, and `spec-kitty docs query` does not
     find it yet. The per-PR content check is
     `tests/docs/test_docs_index_regenerates_cleanly.py`: the generators must
     run cleanly over the tree you merge.
  3. **Frontmatter `description`** — a hard **50–180 character** band on every
     published page, enforced by `tests/docs/test_docs_seo.py` (over 180 also fails
     the docsite build's frontmatter gate).

  Verify with `PYTHONPATH=. python scripts/docs/check_docs_freshness.py --ci`
  (expect `errors=0`; staleness and external-URL link-health *warnings* are fine).

  **ADRs** need only the ADR file: the bot adds the era index-table row
  (`freshen_adr_inventory --all`). An ADR's frontmatter needs `title:`, `date:`,
  `updated:`, and a 50–180 character `description`.

### `docs-lint`

- **Trips it:** a typo or British spelling in docs prose, or a changelog
  `[Unreleased]` entry that breaks the house style. Any PR can trip it, because
  the job has no path filter.
- **Job:** `docs-lint` in `.github/workflows/ci-router.yml` (display name "docs
  lint (spelling + changelog style, always-on)"). It is listed in the
  `router-gate` job's `needs`, so a red `docs-lint` blocks the merge. It is
  **blocking**: neither command's exit code is masked.
- **Why always-on:** its inputs span `docs/**`, `README.md`,
  `packs/built-in/**/*.md`, `pyproject.toml` (the `[tool.codespell]` table and
  the pinned `codespell`) and `uv.lock`. No single router path group covers all
  of them, so a path filter would let some edits skip the check.
- **What it runs:** `uv sync --frozen`, then
  `python -m scripts.docs.check_spelling` (typo, US-spelling and Unreleased
  passes) and `python -m scripts.docs.check_changelog_style`. It runs **no
  pytest**. The planted-violation and live-tree tests for the two scripts
  (`tests/docs/test_check_spelling.py`, `tests/docs/test_changelog_style.py`,
  `tests/docs/test_docs_spelling_live.py`) run in the `tests-docs` job.
- **Exit codes:** `0` clean; `1` findings; `2` the check could not run or could
  not prove it looked at anything: a usage error, `codespell` missing, no
  `[tool.codespell]` table in `pyproject.toml`, an unreadable changelog (both
  scripts), a `typo` or `us` pass that scanned 0 files, or an `unreleased`
  scratch file that a `[tool.codespell]` `skip` glob would drop. A changelog with
  no `[Unreleased]` section is `0` (nothing to check). The changelog guard also
  exits `0` on warnings alone.
- **Scope:** Markdown only. `docs/archive/`, `docs/reports/`, `docs/plans/` and
  the generated CLI reference (`docs/api/cli-commands.md`) are skipped through
  the `[tool.codespell]` `skip` list, so a finding never comes from them. A
  relative `--changelog` resolves against the repository root in both scripts
  (against `--repo-root` for the spelling check), not the current directory.
- **Symptom:** the job log lists one finding per line as
  `path:line: [rule] ... — fix`, ending in a summary line. It is not one of the
  docs-freshness or registration errors above. The guard's rules include
  `bullet-marker` (a column-0 `* ` or `+ ` bullet), `conflict-marker` (a leftover
  `<<<<<<<`, `|||||||` or `>>>>>>>` line) and banned-token checks on
  prose between a `###`/`####` heading and its first bullet; the how-to lists
  every rule and the false-positive shapes (`WP-D-1`, `SC-2086`,
  `DEFAULT-branch`) to put in backticks.
- **Fix / repro:** `make docs-lint` from the repository root reproduces the job
  (it runs the same two commands). The how-to has the steps: [run the checks,
  allow a word, exempt a quoted literal, and read a
  failure](/development/how-to/review-gates.md#changelog-update-and-style). Never run bare
  `codespell`, which scans the whole repository.
- **Owning files:** `scripts/docs/check_spelling.py`,
  `scripts/docs/check_changelog_style.py`, and the `[tool.codespell]` table
  (`skip`, `ignore-words-list`) plus the exact `codespell==2.4.3` pin in
  `pyproject.toml`. The pin is exact on purpose: a new `codespell` release
  changes its dictionary, so bump it deliberately, together with the docs it
  newly flags.

### Touching any docs path can surface a pre-existing docs-test flake

- **Trips it:** touching any `docs/**` path flips the docs-test path filter,
  which can run a `tests/docs/` test that never ran on your branch before.
- **Symptom:** 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.
- **Fix / repro:** 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.

### Where the docs site deploys from

`docs.spec-kitty.ai` is deployed by `.github/workflows/docs-pages.yml` from
this repository's `main`. The workflow runs on pushes to `main` that touch an
input of the doc-kitty build (`docs/**`, `site/**`, the `scripts/docs` 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 `build`
job then calls `.github/workflows/docs-site-build.yml`, so `main` deploys only
a site built by the definition the required `docs-site` pull-request gate runs.
The `deploy` job runs only for `spec-kitty/spec-kitty` on
`refs/heads/main`; a `workflow_dispatch` on another branch builds but does not
deploy. After each deploy, the `smoketest` job runs
`scripts/docs/site_live_probe.py` against `https://docs.spec-kitty.ai`, 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.

### The docsite's Python steps need `PYTHONPATH`

- **Trips it:** the shared docsite build and the deploy's `smoketest` run
  Python modules under `scripts/docs/` with the runner's `python3`, without
  installing the package. Several of them import `from kernel.clock import ...`
  or other `scripts.docs.*` modules, so a step with no `PYTHONPATH` raises
  `ModuleNotFoundError: No module named 'kernel'` (or `'scripts'`).
- **Symptom:** a docsite build step or the smoketest fails at import. A failed
  build skips the deploy, so merged `docs/` changes never go live.
- **Fix / repro:** give each such step `PYTHONPATH: .:src` (`..:../src` for
  steps that run in `site/`). The shared build runs on every pull request that
  touches the docsite, through the `docs-site` gate. `docs-pages.yml` itself has
  no `pull_request` trigger, so a change to it is exercised only by its
  job-graph tests (`tests/release/test_release_ci_ownership.py`) before merge.

## Accept-to-consolidate gates

The `accept` → `consolidate` close-out has several gates that block silently until fed
exactly what they expect.

### The issue-matrix verdict gate blocks WP approval

- **Trips it:** `move-task <WP> --to approved` when a gating `#NNN` reference in
  the mission's artifacts has no verdict row in `issue-matrix.json`. Not every
  reference gates: context-only and PR/commit references are recorded but do
  not block.
- **Symptom:** the approval is blocked, and the error lists the missing rows.
- **Fix:** seed the matrix up front with `spec-kitty agent issue-verdict`. The
  verdict values, which references gate, and the evidence-token rule for
  `deferred-with-followup` are documented once, in the
  [Issue-Matrix Verdict Reference](/development/reference/issue-matrix-verdicts.md). The per-WP
  reviewer should **refuse to fabricate** verdicts for unfixed issues; the
  orchestrator fills them honestly and flips `in-mission` rows to a terminal
  verdict at accept.

### The other close-out gates

- **Lane branches reject any `kitty-specs/` change** ("kitty-specs/ changes are
  not allowed on lane branches"). Before moving a task to `for_review` or
  `approved`, 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.
- **Record `acceptance-matrix.json` verdicts with `spec-kitty agent
  acceptance-verdict`; do not hand-edit the file.** `spec-kitty agent
  acceptance-verdict --mission <m> --criterion FR-001 --result pass --evidence
  <ref>` writes the criterion through the matrix seam, commits it, and
  recomputes `overall_verdict`. Its negative-invariant mode (`--negative-invariant
  <id> --description ... --verification-method grep_absence|route_check|custom_command
  --verification-command ...`) registers an invariant through the same seam and
  runs it at once (`--no-execute` registers only). `accept` also fails on a
  dirty tree, so commit or clean the dossier state first.
- **`spec-kitty consolidate` refuses a dirty coordination worktree** — commit the
  status files and clear ignored `.kittify/` state in the coordination worktree,
  then `--resume`.
- **The graph-manifest check verifies the pack manifest, not just the graph
  files.** Regenerating the reference graph alone leaves the manifest stale; run
  the full `spec-kitty charter pack regenerate-graph`, which regenerates both.
- **The post-merge stale-assertion analyzer** 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.

## Contracts gates

The `mission-status` and `mission-write` contracts, their tools and the Mission Status API service
live in `spec-kitty-events` (`contracts/`, `service/`; ADR
[`2026-10-29-1`](/adr/4.x/2026-10-29-1-the-events-domain-and-its-java-services-live-in-spec-kitty-events.md)),
which builds, checks and releases them on its `service-v*` line. Core keeps only the five handoff
fixtures `contracts/fixtures/fixture_0*.json` and pins one release in
`pins/read-service.source.yaml` (#6915). The contract tests in core read the pinned
`contract-bundles`, `contract-tools` and `conformance-fixtures` extras, which `make sync-services`
(`make dev-setup` fetches the extras only) and the `.github/actions/sync-services` action fetch and
digest-verify; `tests/pinned_service_assets.py` fails closed when they are missing.

### What runs where

- **`tests (contract tools)`** (`tests-contract-tools` in `ci-router.yml`, a required check
  through `router-gate`): `pytest -m "corpus and not windows_ci" tests/contract` minus three
  `--ignore` modules, after the sync-services action. It runs when the `corpus` filter group
  matches (`contracts/fixtures/**`, `pins/**`) or the `contract_tools` group matches
  (`tests/contract/**`, `pins/**`, `scripts/sync_services.py`, the sync-services action,
  `tests/pinned_service_assets.py`, the lock and pytest configuration, `tests/conftest.py` and the
  `src/` modules the mission-status reference reader imports, spelled `**/<module path>` so the
  group stays non-src). Unmarked `tests/contract` modules run in the module matrix.
- **The reality check and its payload helper** (`tests/contract/test_mission_status_reality.py`
  and `tests/contract/test_mission_status_payloads.py`) read the committed corpus and run in
  `tests (corpus-blocking)` (`tests-corpus-blocking`), together with the example round trip,
  `tests/integration/test_mission_review_contract_gate.py`,
  `tests/specify_cli/migration/test_corpus_wp_snapshot_parity.py` and one performance class.
  The modules of both router jobs are deselected from the Packs advisory corpus run, so each runs
  once. `tests/ci/test_contracts_routing.py` fails when a corpus-marked `tests/contract` module is
  run by neither router job, or by both, and when Packs deselects a module that does not exist.
  **The reality check reads the repository's primary worktree**, not the checkout that imports it
  (`oracles.primary_worktree_root`; #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 `kitty-specs/` tree and read Missions out of another whenever the
  checkout is a linked worktree — the drift read then refuses the whole report with
  `500 drift_scan_unreadable` and the Project read reports an `outside root` fallback the oracle
  never derives. From a `git worktree` 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.
- **The nightly corpus compare** (`mission-status-corpus` in `ci-nightly.yml`) starts the pinned
  native read-service binary and compares it with the Python reference over the whole corpus, with
  no exemption list (`scripts/ci/mission_status_corpus_compare.py`).
- **Pins.** `tests/ci/test_service_pins_gate.py` checks every committed pin; `release.yml`
  fetches and checks the service pins before it builds (`scripts/sync_services.py --service all
  --check`) and asserts the wheel carries the pins and no service binary.
- **Absence.** `tests/architectural/test_events_cutover_absent.py` (on the always-on
  `architectural-fast` roster) fails if `services/`, the removed `contracts/` modules or the
  retired `contracts.yml`, `contracts-release.yml` and `mission-status-api.yml` workflows come
  back, or if a CI, build or script file names them.

### A reader or test-only change selects no corpus job

- **Trips it:** a pull request that edits a status reader the reality check imports
  (anything under `src/specify_cli/status/**`), the reality check's own test files or
  fixture, or a Mission's `meta.json` or `status.events.jsonl`. The router's `corpus`
  group matches `contracts/fixtures/**` and `pins/**` but none of those, so `tests (corpus-blocking)`, the job
  that runs the reality check, is not selected. An edit under `tests/contract/**`
  selects `tests (contract tools)` through the `contract_tools` group, which does not
  run the reality check. The Packs run on a push to `main` does not help: `packs.yml`
  passes `--deselect` for every `tests/contract` module that runs in a router job, so
  the `built-in-corpus-suite` never runs them.
- **Symptom:** a green pull request. The drift is first seen by the nightly run
  (`ci-nightly.yml`, job `interpreter-matrix-shard-4`, which runs `tests/contract`,
  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.
- **Fix / repro:** run the check before pushing:
  `PWHEADLESS=1 .venv/bin/python -m pytest -q tests/contract/test_mission_status_reality.py`,
  and dispatch the router in full mode on the branch:
  `gh workflow run ci-router.yml -f mode=full --ref <branch>`.

### Mission Status API workflow

Retired with core's copy of the service (#6915): the Mission Status API's build, native legs,
lock-interop job and release run in `spec-kitty-events` (`.github/workflows/service.yml`,
`service-release.yml`). Core runs the nightly corpus compare against the pinned binary (above).

### What only a merge can confirm

- The fleet-verdict job is triggered by `workflow_run`, 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.
- The Packs `built-in-corpus-suite` does **not** run the reality check or the other
  contract tests on a push to `main`: it deselects them, because the router job
  `tests (corpus-blocking)` owns the reality check and the router job
  `tests (contract tools)` owns the rest. The runs after the merge that execute
  them are the router on `main` (each job runs only for a change that selects it) and
  the nightly shard 4.
- A release tag is a maintainer act and is never pushed from a pull request.

## See also

- [Known Current Friction Points](/development/reference/known-friction-points.md) — the fast-drifting,
  time-stamped list of what is red *today*.
- [Red Main and Release Readiness](/development/reference/red-main-and-release-readiness.md) — what a red
  `main` means and why CI is the release authority.
- [Parallel testing](/development/testing/testing-parallel.md) — why the make targets are
  shaped the way they are.
- [Landing contributor PRs](/development/how-to/pr-landing.md) — the maintainer landing
  runbook and red-classification step.
</content>
</invoke>

## Related

- [Landing Contributor PRs: The Maintainer Runbook](/development/how-to/pr-landing.md)
- [Known Current Friction Points](/development/reference/known-friction-points.md)
- [Red Main and Release Readiness](/development/reference/red-main-and-release-readiness.md)
- [Running the test suite in parallel](/development/testing/testing-parallel.md)

## Audience

- [Stakeholder Persona: Maintainer](/context/audience/internal/maintainer.md) - Written for the Maintainer reader.
