<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/development/how-to/review-gates/">
  <id>https://docs.spec-kitty.ai/development/how-to/review-gates/</id>
  <title>Review Gates: Pre-PR Hygiene, Review-Cycle Mechanics, and the Consolidation Gate</title>
  <updated>2026-11-01T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/development/how-to/review-gates/"/>
  <summary>Review-cycle-artifact and consolidation-gate mechanics, the --skip-review-artifact-check override, and issue-matrix discovery, so review focuses on substance.</summary>
  <content type="html">&lt;span id=&quot;review-gates-pre-pr-hygiene-review-cycle-mechanics-and-the-consolidation-gate&quot;&gt;&lt;/span&gt;
&lt;p&gt;This page documents (1) the small set of hygiene steps a contributor should
run locally before requesting review or opening a PR, so the actual review
focuses on the substance of the change and not on confusing failures
unrelated to it; and (2) the mechanics of the review-cycle artifact / consolidation
gate and the issue-matrix discovery surface that a WP actually has to
satisfy to reach &lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt;. The issue-matrix verdict vocabulary and
the rule for which references need a row are owned by the
&lt;a href=&quot;/development/reference/issue-matrix-verdicts/&quot;&gt;Issue-Matrix Verdict Reference&lt;/a&gt;; review
error codes live in
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/src/specify_cli/cli/commands/review/ERROR_CODES.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;ERROR_CODES.md&lt;/code&gt;&lt;/a&gt;.
This page cites them rather than restating them.&lt;/p&gt;
&lt;h2 id=&quot;environment-hygiene-before-reviewpr&quot;&gt;Environment hygiene before review/PR&lt;/h2&gt;
&lt;p&gt;Run the documented sync command from the repository root &lt;strong&gt;before&lt;/strong&gt;
running the test gates:&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;uv&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;sync&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;--frozen&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;why&quot;&gt;Why&lt;/h3&gt;
&lt;p&gt;The CLI consumes &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;spec-kitty-tracker&lt;/code&gt; from PyPI.
Compatibility ranges live in &lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt;; &lt;strong&gt;exact pins&lt;/strong&gt; live in
&lt;code dir=&quot;auto&quot;&gt;uv.lock&lt;/code&gt;. If your installed copy of either shared package drifts away
from &lt;code dir=&quot;auto&quot;&gt;uv.lock&lt;/code&gt; (for example, after an ad-hoc &lt;code dir=&quot;auto&quot;&gt;pip install&lt;/code&gt; against a
sibling checkout, or after switching branches without re-syncing), the
review-gate test suite can fail in ways that look like real defects but
are actually pure environment drift.&lt;/p&gt;
&lt;h3 id=&quot;what-uv-sync---frozen-does&quot;&gt;What &lt;code dir=&quot;auto&quot;&gt;uv sync --frozen&lt;/code&gt; does&lt;/h3&gt;
&lt;p&gt;It installs the &lt;strong&gt;exact resolved versions from &lt;code dir=&quot;auto&quot;&gt;uv.lock&lt;/code&gt;&lt;/strong&gt; into your
active virtualenv without re-resolving the dependency graph. This is
the cheapest possible “snap me back to the lockfile” operation:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;It does not modify &lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;It does not modify &lt;code dir=&quot;auto&quot;&gt;uv.lock&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;It does not contact the resolver — only the package index for the
pinned wheels.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;when-to-run-it&quot;&gt;When to run it&lt;/h3&gt;
&lt;p&gt;Run &lt;code dir=&quot;auto&quot;&gt;uv sync --frozen&lt;/code&gt; any time:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;You pull &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; (or any branch with new lock changes).&lt;/li&gt;
&lt;li&gt;You switch branches.&lt;/li&gt;
&lt;li&gt;You change &lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;uv.lock&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;You temporarily installed an editable / sibling-checkout copy of
&lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;spec-kitty-tracker&lt;/code&gt; for cross-package work
(see &lt;a href=&quot;/development/how-to/local-overrides/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;local-overrides.md&lt;/code&gt;&lt;/a&gt; for the dev workflow).&lt;/li&gt;
&lt;li&gt;A review gate or local command reports dependency drift.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;uv sync --frozen&lt;/code&gt; is the &lt;strong&gt;only&lt;/strong&gt; documented sync command for this purpose. Do not
substitute &lt;code dir=&quot;auto&quot;&gt;uv pip sync&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;uv pip install&lt;/code&gt;, or any other variant — they
either re-resolve the graph or skip the lockfile entirely, both of which
defeat the point.&lt;/p&gt;
&lt;h2 id=&quot;typerclick-version-skew-spec-kitty-review-preflight&quot;&gt;Typer/click version skew (&lt;code dir=&quot;auto&quot;&gt;spec-kitty review&lt;/code&gt; preflight)&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty review&lt;/code&gt; also checks that the active interpreter’s &lt;code dir=&quot;auto&quot;&gt;typer&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;click&lt;/code&gt; versions match the exact versions pinned in &lt;code dir=&quot;auto&quot;&gt;uv.lock&lt;/code&gt;. CI always
installs via &lt;code dir=&quot;auto&quot;&gt;uv sync --frozen --all-extras&lt;/code&gt;; a local &lt;code dir=&quot;auto&quot;&gt;.venv&lt;/code&gt; built without
&lt;code dir=&quot;auto&quot;&gt;--frozen&lt;/code&gt; can drift onto a newer release — including a &lt;code dir=&quot;auto&quot;&gt;typer&gt;=0.26&lt;/code&gt;
release that vendors &lt;code dir=&quot;auto&quot;&gt;click&lt;/code&gt; internally and stops re-exporting it (see the
TID251 Gap-5 ban in &lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt;) — so local CLI-shard test runs can
silently diverge from CI without this check.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Warn-loud by default&lt;/strong&gt;: a divergence prints a &lt;code dir=&quot;auto&quot;&gt;MISSION_REVIEW_ENV_SKEW&lt;/code&gt;
warning (see
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/src/specify_cli/cli/commands/review/ERROR_CODES.md#env_skew&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;ERROR_CODES.md&lt;/code&gt;&lt;/a&gt;)
and &lt;code dir=&quot;auto&quot;&gt;spec-kitty review&lt;/code&gt; proceeds.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Fail-closed is opt-in&lt;/strong&gt;: set &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_ENV_SKEW_FAIL_CLOSED=1&lt;/code&gt; to make
the preflight exit non-zero on divergence instead of warning. This is
intentionally opt-in — a legitimately forward-compat dev loop (testing
against a newer &lt;code dir=&quot;auto&quot;&gt;typer&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;click&lt;/code&gt; ahead of the repo’s pin bump) must not be
bricked by default.&lt;/p&gt;
&lt;p&gt;Resolve a skew warning the same way as any other lock 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;uv&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;sync&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;--frozen&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;--all-extras&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;pre-review-regression-gate-move-task---to-for_review&quot;&gt;Pre-review regression gate (&lt;code dir=&quot;auto&quot;&gt;move-task --to for_review&lt;/code&gt;)&lt;/h2&gt;
&lt;p&gt;When a work package moves to &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt;, Spec Kitty runs a &lt;strong&gt;doctrine-resolved&lt;/strong&gt;
transition gate. Rather than a hardcoded call into one repo-specific engine, the
hook resolves &lt;em&gt;which&lt;/em&gt; named handlers the repo’s active doctrine binds to the
current lane edge (&lt;code dir=&quot;auto&quot;&gt;in_progress-&gt;for_review&lt;/code&gt;), dispatches each, and aggregates
their verdicts (mission &lt;code dir=&quot;auto&quot;&gt;doctrine-controlled-transition-gates&lt;/code&gt;, epic #2535
half A). In the Spec-Kitty source tree the built-in &lt;code dir=&quot;auto&quot;&gt;software-dev/review&lt;/code&gt;
step-contract binds the &lt;code dir=&quot;auto&quot;&gt;spec-kitty-pre-review&lt;/code&gt; handler. This repository
declares &lt;code dir=&quot;auto&quot;&gt;make test-fast&lt;/code&gt; as its test command, so the gate runs that fast tier
and compares its JUnit results with the implement-time baseline. By default
the gate is &lt;strong&gt;warn-only&lt;/strong&gt; — it reports a new failure but the move still
proceeds.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;How the impl is selected.&lt;/strong&gt; Activation, not repo shape, decides whether the
gate fires. A repo whose active doctrine binds no handler to the edge runs &lt;em&gt;no&lt;/em&gt;
gate (a distinguishable &lt;code dir=&quot;auto&quot;&gt;NO_COVERAGE&lt;/code&gt; warn, never a silent skip); a repo that
activates a handler runs it. Toggling the binding’s handler in doctrine flips
whether the gate fires with &lt;strong&gt;no code change&lt;/strong&gt; between states.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Fail-open and hard-stops.&lt;/strong&gt; Every handler &lt;em&gt;execution&lt;/em&gt; error degrades to exactly
one visible unverified &lt;code dir=&quot;auto&quot;&gt;NO_COVERAGE&lt;/code&gt; warning — a faulting handler never removes
another’s block from the computation. Exactly &lt;strong&gt;two&lt;/strong&gt; hard-stops survive: a
terminal interruption (&lt;code dir=&quot;auto&quot;&gt;TIMED_OUT&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;CANCELLED&lt;/code&gt;) aborts the move with the
transition unapplied, and the opt-in &lt;code dir=&quot;auto&quot;&gt;NEW_FAILURES&lt;/code&gt; block (below) refuses the
move. Terminal is checked before the block. This is the closure of the
pre-review facet of #2534: a consumer repo never imports Spec-Kitty’s internal
&lt;code dir=&quot;auto&quot;&gt;_gate_coverage&lt;/code&gt; authority, and even under &lt;em&gt;erroneous&lt;/em&gt; activation of the
&lt;code dir=&quot;auto&quot;&gt;spec-kitty-pre-review&lt;/code&gt; handler the internal import is refused and degrades to a
&lt;code dir=&quot;auto&quot;&gt;NO_COVERAGE&lt;/code&gt; warn — the closure is structural, not configuration-dependent.&lt;/p&gt;
&lt;p&gt;Configuration (&lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt;, under &lt;code dir=&quot;auto&quot;&gt;review:&lt;/code&gt;):&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;review.fail_on_pre_review_regression&lt;/code&gt; (bool, default &lt;code dir=&quot;auto&quot;&gt;false&lt;/code&gt;) — opt in to
&lt;strong&gt;block&lt;/strong&gt; the move when the gate finds a new failure. &lt;code dir=&quot;auto&quot;&gt;move-task --force&lt;/code&gt;
records an override and proceeds anyway.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;review.test_command&lt;/code&gt; — selects the test command (&lt;code dir=&quot;auto&quot;&gt;resolve_scope_source&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;scope_source.py&lt;/code&gt;). This repository sets
&lt;code dir=&quot;auto&quot;&gt;PYTEST_ADDOPTS=&quot;--junitxml={output_file}&quot; make test-fast&lt;/code&gt;, reusing the existing
fast-tier target while providing a JUnit artifact for comparison. A repository
without this key records a quiet &lt;code dir=&quot;auto&quot;&gt;skipped&lt;/code&gt; verdict; no tests run. To enable
the gate in another repository, add &lt;code dir=&quot;auto&quot;&gt;review.test_command&lt;/code&gt; under &lt;code dir=&quot;auto&quot;&gt;review:&lt;/code&gt;
in &lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt;, with a command that writes JUnit XML to
&lt;code dir=&quot;auto&quot;&gt;{output_file}&lt;/code&gt;. The block can only be &lt;em&gt;enforced&lt;/em&gt; when a command is available;
opting in without one yields a loud warning.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;review.pre_review_test_command&lt;/code&gt; — &lt;strong&gt;deprecated&lt;/strong&gt; and aliased to
&lt;code dir=&quot;auto&quot;&gt;review.test_command&lt;/code&gt;. A config that still sets it keeps working but earns a
one-time deprecation warning; move the value to &lt;code dir=&quot;auto&quot;&gt;review.test_command&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;review.test_timeout_seconds&lt;/code&gt; — the per-run budget for both legs (baseline
and candidate). See
&lt;a href=&quot;/configuration/review-test-budget/&quot;&gt;Review test execution budget&lt;/a&gt;.
The default depends on the &lt;strong&gt;scope shape&lt;/strong&gt; the gate chose (below).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Scope shapes and the budget (#6865).&lt;/strong&gt; The gate runs one of two shapes, and
says which one on every refusal:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;whole declared command&lt;/strong&gt; — the active &lt;code dir=&quot;auto&quot;&gt;ScopeSource&lt;/code&gt; contributes no
per-file narrowing (&lt;code dir=&quot;auto&quot;&gt;DeclaredCommandScopeSource&lt;/code&gt;, the shipped source, runs
&lt;code dir=&quot;auto&quot;&gt;review.test_command&lt;/code&gt; in full), so the declared command &lt;em&gt;is&lt;/em&gt; the scope. This
shape is bounded by &lt;code dir=&quot;auto&quot;&gt;review.test_timeout_seconds&lt;/code&gt; when the project declares
one, otherwise by the whole-command default (1,200 s).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;bounded target list&lt;/strong&gt; — an explicit target list narrows the run: either a
per-WP &lt;code dir=&quot;auto&quot;&gt;pre_review_test_scope&lt;/code&gt; (below) or a source that derives targets per
changed file. This shape keeps the scoped default (300 s).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;A &lt;code dir=&quot;auto&quot;&gt;timed_out&lt;/code&gt; refusal names the shape, the command that ran, the resolved
budget, the policy metadata that classifies scopes
(&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/review/gate_budget.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_RULES&lt;/code&gt;) and the recovery for that
shape, so an operator can act without reading the source.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pinning a bounded scope for one work package.&lt;/strong&gt; Add the documented
frontmatter key to the WP file:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;yaml&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;# kitty-specs/&amp;#x3C;mission&gt;/tasks/WP01-*.md&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:#7FDBCA;--1:#111111&quot;&gt;pre_review_test_scope&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;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;tests/review tests/status&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;The value is a whitespace-separated pytest target list. The gate then runs
exactly those targets at head instead of the whole declared command; the same
resolved budget bounds it. The key is part of the strict &lt;code dir=&quot;auto&quot;&gt;WPMetadata&lt;/code&gt;
surface, so a WP carrying it stays readable to every consumer (including the
subtask-roster guard) — a documented, gate-consumed field may never make a WP
unreadable. An empty value is treated as absent. The pinned scope applies to
the candidate (head) leg; the baseline capture still runs the whole declared
command, so it remains a whole-suite reference to diff against.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Opaque (unparseable) results.&lt;/strong&gt; A declared command that exits nonzero without
emitting a &lt;code dir=&quot;auto&quot;&gt;FAIL &amp;#x3C;test&gt;&lt;/code&gt; line yields one synthetic whole-run failure. Its identity
is its exit status plus a digest of the run’s full output, so it counts as
pre-existing only when the baseline failed in exactly the same way; any other
opaque candidate failure is a &lt;strong&gt;new failure&lt;/strong&gt;, never a silent pass. A
&lt;code dir=&quot;auto&quot;&gt;no_new_failures&lt;/code&gt; verdict records the candidate’s observed exit status and says in
its reason that the result is baseline-relative — it does not assert that the
candidate exited 0 (#6751).&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Inherited limitation (#2741, P1 — inherited, NOT fixed by this mission).&lt;/strong&gt;
The gate scopes off the WP worktree’s &lt;em&gt;working-tree&lt;/em&gt; diff rather than the WP
commit range. The doctrine-controlled-transition-gates inversion is
behaviour-preserving and therefore &lt;em&gt;preserves&lt;/em&gt; this by design; it is tracked
separately and must not be mistaken for a fix or flagged as a regression. Only
the &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt; pre-review facet of the repo-shape coupling is inverted here.
The remaining scope — falling back to the WP’s committed evidence window — is
tracked in #6851.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;A planning-lane WP records why the gate did not inspect its commit (#6792).&lt;/strong&gt;
A &lt;code dir=&quot;auto&quot;&gt;planning_artifact&lt;/code&gt; WP commits its deliverables in the repository root
checkout, which is also the workspace the gate resolves for it. The gate diffs
that workspace against the branch checked out there (a default Mission’s topic
branch until it lands, or the target branch of a Mission that commits to it),
so the merge-base diff is empty by construction, and a committed, clean tree
adds no dirty paths. The gate skips cheaply and records
&lt;code dir=&quot;auto&quot;&gt;planning-lane WP — committed diff not inspected (a planning_artifact WP commits in the repository root checkout, on the branch the gate diffs against, so no workspace diff exists)&lt;/code&gt;
as its &lt;code dir=&quot;auto&quot;&gt;no_coverage&lt;/code&gt; reason, and the transition is never blocked by it. Every
other WP with an empty diff keeps the &lt;code dir=&quot;auto&quot;&gt;no changed files detected for this WP&lt;/code&gt;
wording. Classification asks the WP’s declared &lt;code dir=&quot;auto&quot;&gt;execution_mode&lt;/code&gt; first and,
when the frontmatter is silent, requires BOTH &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt; conditions — the WP
sits in a lane &lt;code dir=&quot;auto&quot;&gt;is_planning_lane&lt;/code&gt; owns &lt;strong&gt;and&lt;/strong&gt; its &lt;code dir=&quot;auto&quot;&gt;planning_artifact_wps&lt;/code&gt; kind
view names it — because a &lt;code dir=&quot;auto&quot;&gt;single_branch&lt;/code&gt; mission’s one repo-root lane also
holds code work packages. An unreadable manifest falls back to the incumbent
wording rather than claiming a planning lane.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h2 id=&quot;review-cycle-artifacts-and-the-consolidation-gate&quot;&gt;Review-cycle artifacts and the consolidation gate&lt;/h2&gt;
&lt;p&gt;Every WP that reaches a terminal review lane (&lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt; —
&lt;code dir=&quot;auto&quot;&gt;TERMINAL_REVIEW_LANES&lt;/code&gt; in
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/src/specify_cli/review/artifacts.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;review/artifacts.py&lt;/code&gt;&lt;/a&gt;) is
checked against one invariant:
&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;terminal_wp_latest_review_artifact_must_not_be_rejected&lt;/code&gt;&lt;/strong&gt;. It is
implemented by &lt;code dir=&quot;auto&quot;&gt;find_rejected_review_artifact_conflicts&lt;/code&gt; in
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/src/specify_cli/post_merge/review_artifact_consistency.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;post_merge/review_artifact_consistency.py&lt;/code&gt;&lt;/a&gt;
and is the &lt;strong&gt;single shared implementation&lt;/strong&gt; behind three call sites:
&lt;code dir=&quot;auto&quot;&gt;spec-kitty consolidate&lt;/code&gt;
(&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/src/specify_cli/consolidation/preflight.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;consolidation/preflight.py&lt;/code&gt;&lt;/a&gt;),
&lt;code dir=&quot;auto&quot;&gt;spec-kitty consolidate --dry-run&lt;/code&gt;
(&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/src/specify_cli/consolidation/forecast.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;consolidation/forecast.py&lt;/code&gt;&lt;/a&gt;), and
&lt;code dir=&quot;auto&quot;&gt;spec-kitty review&lt;/code&gt;’s Gate 1 lane check
(&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/src/specify_cli/cli/commands/review/_lane_gate.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;cli/commands/review/_lane_gate.py&lt;/code&gt;&lt;/a&gt;)
— so the three surfaces cannot drift from one another.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;The gate is purely event-sourced.&lt;/strong&gt; It reads the reduced status
snapshot’s &lt;code dir=&quot;auto&quot;&gt;review_result&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;review&lt;/code&gt; slots (via &lt;code dir=&quot;auto&quot;&gt;materialize_snapshot&lt;/code&gt;)
and never parses on-disk &lt;code dir=&quot;auto&quot;&gt;review-cycle-N.md&lt;/code&gt; frontmatter. A WP is blocked
only when the lane is terminal &lt;strong&gt;and&lt;/strong&gt; the event-sourced verdict is
&lt;code dir=&quot;auto&quot;&gt;changes_requested&lt;/code&gt;; a &lt;code dir=&quot;auto&quot;&gt;complete&lt;/code&gt; override (see below) clears the gate
unconditionally and is checked first. An absent or damaged event slot is
treated as “no signal” — a safety gate that only detects rejections fails
open on missing data, never fabricates a block.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;No hand-authored artifact can satisfy the gate.&lt;/strong&gt; Because the gate never
reads the on-disk file, hand-editing a &lt;code dir=&quot;auto&quot;&gt;review-cycle-N.md&lt;/code&gt; to read
&lt;code dir=&quot;auto&quot;&gt;verdict: approved&lt;/code&gt; has no effect on whether consolidation or review passes — only
a genuine &lt;code dir=&quot;auto&quot;&gt;move-task&lt;/code&gt; transition can change the event-sourced verdict:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;An ordinary &lt;code dir=&quot;auto&quot;&gt;move-task --to approved&lt;/code&gt; (or &lt;code dir=&quot;auto&quot;&gt;--to done&lt;/code&gt;) out of &lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt;
writes its own &lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;ReviewResult&lt;/code&gt; into the event log from the fact
that the transition itself is happening
(&lt;code dir=&quot;auto&quot;&gt;_mt_plan_review_result&lt;/code&gt; in
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/src/specify_cli/cli/commands/agent/tasks_move_task_hops.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;tasks_move_task_hops.py&lt;/code&gt;&lt;/a&gt;)
— no artifact content is read to decide this.&lt;/li&gt;
&lt;li&gt;When the WP’s current event-sourced verdict was &lt;code dir=&quot;auto&quot;&gt;changes_requested&lt;/code&gt;,
that same approval transition additionally synthesizes a durable
&lt;code dir=&quot;auto&quot;&gt;review-cycle-N.md&lt;/code&gt; record on disk
(&lt;code dir=&quot;auto&quot;&gt;_persist_approved_review_cycle&lt;/code&gt; in
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/src/specify_cli/cli/commands/agent/tasks_verdict_persistence.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;tasks_verdict_persistence.py&lt;/code&gt;&lt;/a&gt;),
with a machine-written body (&lt;code dir=&quot;auto&quot;&gt;&quot;Approved by {reviewer}: {reference}&quot;&lt;/code&gt;), so
the on-disk history stays consistent with the event log. This is the
CLI’s own record of a genuine approval that already happened — never a
hand-authored one — and it is a no-op when there was no prior rejection to
close out. &lt;strong&gt;Never instruct an agent to hand-write an &lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt;
review-cycle artifact to unblock a gate&lt;/strong&gt;; if the latest verdict is
wrongly &lt;code dir=&quot;auto&quot;&gt;changes_requested&lt;/code&gt;, roll the WP back to &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt; and run a
real, independent review cycle.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;The &lt;code dir=&quot;auto&quot;&gt;--skip-review-artifact-check&lt;/code&gt; escape hatch.&lt;/strong&gt;
&lt;code dir=&quot;auto&quot;&gt;move-task --to approved --skip-review-artifact-check --note &quot;&amp;#x3C;reason&gt;&quot;&lt;/code&gt; is
the arbiter-override path — &lt;code dir=&quot;auto&quot;&gt;--note&lt;/code&gt; is mandatory here; omitting it is
refused before the override can fire
(&lt;code dir=&quot;auto&quot;&gt;_guard_rejected_verdict&lt;/code&gt; in
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/src/specify_cli/cli/commands/agent/tasks_transition_core.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;tasks_transition_core.py&lt;/code&gt;&lt;/a&gt;).
It records a &lt;code dir=&quot;auto&quot;&gt;ReviewOverride {at, actor, wp_id, reason}&lt;/code&gt;
(&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/src/specify_cli/status/models.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;status/models.py&lt;/code&gt;&lt;/a&gt;) via a
single, topology-resolved &lt;code dir=&quot;auto&quot;&gt;InnerStateChanged&lt;/code&gt; event emit
(&lt;code dir=&quot;auto&quot;&gt;_persist_review_artifact_override&lt;/code&gt; in
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/src/specify_cli/cli/commands/agent/tasks_materialization.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;tasks_materialization.py&lt;/code&gt;&lt;/a&gt;)
— one write, not a &lt;strong&gt;PRIMARY-partition-plus-coord&lt;/strong&gt; frontmatter mirror (that dual-write
is retired; the reduced &lt;code dir=&quot;auto&quot;&gt;review&lt;/code&gt; snapshot slot is the single authority both
partitions resolve). The gate only treats the override as clearing when
&lt;code dir=&quot;auto&quot;&gt;ReviewOverride.complete&lt;/code&gt; is true, i.e. all four fields are non-empty — a
partially-filled override still blocks. Use this only over a genuinely
superseded rejection, never as a substitute for a real re-review.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;--review-feedback-file&lt;/code&gt; provenance guard.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;move-task --to planned --review-feedback-file &amp;#x3C;path&gt;&lt;/code&gt; reads &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;path&gt;&lt;/code&gt; as the rejection body and
writes it into a freshly allocated, properly frontmattered
&lt;code dir=&quot;auto&quot;&gt;review-cycle-N.md&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;create_rejected_review_cycle&lt;/code&gt; in
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/src/specify_cli/review/cycle.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;review/cycle.py&lt;/code&gt;&lt;/a&gt;; cycle
numbers are allocated under a lock as &lt;code dir=&quot;auto&quot;&gt;max(existing) + 1&lt;/code&gt;, never a file
count, so a numbering gap can’t collide). The command refuses &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;path&gt;&lt;/code&gt;
outright — by path identity &lt;strong&gt;and&lt;/strong&gt; by content (does &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;path&gt;&lt;/code&gt; itself parse
as a &lt;code dir=&quot;auto&quot;&gt;ReviewCycleArtifact&lt;/code&gt;?) — when it resolves to one of this WP’s own
prior &lt;code dir=&quot;auto&quot;&gt;review-cycle-N.md&lt;/code&gt; files
(&lt;code dir=&quot;auto&quot;&gt;_guard_feedback_source_provenance&lt;/code&gt;, same module): a verdict record must
never be re-submitted as if it were new reviewer feedback. Plain reviewer
prose is always admissible, even when it is byte-identical to a prior
cycle’s body (a reviewer re-reporting a recurring defect is not the attack
this guard exists to refuse).&lt;/p&gt;
&lt;h2 id=&quot;issue-matrix-discovery-and-issue-verdict---actor&quot;&gt;Issue-matrix discovery and &lt;code dir=&quot;auto&quot;&gt;issue-verdict --actor&lt;/code&gt;&lt;/h2&gt;
&lt;p&gt;Issue-matrix &lt;strong&gt;verdict vocabulary&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;fixed&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;verified-already-fixed&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;deferred-with-followup&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;in-mission&lt;/code&gt;), the JSON &lt;strong&gt;schema&lt;/strong&gt;, the
&lt;code dir=&quot;auto&quot;&gt;.json&lt;/code&gt;-canonical rule (a legacy &lt;code dir=&quot;auto&quot;&gt;.md&lt;/code&gt; matrix is read via failover, never
re-authored), and the &lt;code dir=&quot;auto&quot;&gt;in-mission&lt;/code&gt; semantics (accepted at per-WP &lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt;,
&lt;strong&gt;rejected on the mission &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt; transition&lt;/strong&gt;) are already documented in
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/src/specify_cli/cli/commands/review/ERROR_CODES.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;ERROR_CODES.md&lt;/code&gt;&lt;/a&gt;
and the Gate 4 section of
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/src/charter/offering/skills/spec-kitty-mission-review/SKILL.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty-mission-review/SKILL.md&lt;/code&gt;&lt;/a&gt;
(C-008) — see those two for the full vocabulary and worked examples. This
section covers only the genuinely-absent operational half: how a reference
is &lt;em&gt;discovered&lt;/em&gt;, and how a verdict is &lt;em&gt;recorded&lt;/em&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Discovery runs over every mission doc, not just &lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt;.&lt;/strong&gt;
&lt;code dir=&quot;auto&quot;&gt;discover_issue_references&lt;/code&gt;
(&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/src/specify_cli/tasks/issue_reference_discovery.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;tasks/issue_reference_discovery.py&lt;/code&gt;&lt;/a&gt;)
scans &lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;plan.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;research.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;analysis-report.md&lt;/code&gt; (each
optional), plus every &lt;code dir=&quot;auto&quot;&gt;.md&lt;/code&gt; file directly under &lt;code dir=&quot;auto&quot;&gt;tasks/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;contracts/&lt;/code&gt;
(non-recursive, sorted by filename), in that fixed order. It reuses the one
canonical &lt;code dir=&quot;auto&quot;&gt;#NNNN&lt;/code&gt; detector
(&lt;code dir=&quot;auto&quot;&gt;tasks.issue_matrix.detect_issue_references&lt;/code&gt;) per file, so there remains
exactly one issue-reference pattern definition in the codebase. When the
same issue number appears in more than one file, the &lt;strong&gt;first&lt;/strong&gt; file+line it
appears in (in scan order) wins both the context snippet and the recorded
&lt;code dir=&quot;auto&quot;&gt;source_file&lt;/code&gt; — never re-derived independently later.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;The consolidation-time completeness gate.&lt;/strong&gt;
&lt;code dir=&quot;auto&quot;&gt;_evaluate_issue_matrix_completeness_gate&lt;/code&gt;
(&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/src/specify_cli/policy/merge_gates.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;policy/merge_gates.py&lt;/code&gt;&lt;/a&gt;)
diffs &lt;code dir=&quot;auto&quot;&gt;discover_issue_references&lt;/code&gt;’s output against
&lt;code dir=&quot;auto&quot;&gt;load_issue_matrix&lt;/code&gt;’s rows and fails (blocking) when a discovered &lt;code dir=&quot;auto&quot;&gt;#NNNN&lt;/code&gt;
has no matrix row at all — it does not check verdicts (that is Gate 4’s
job, cited above). A mission with &lt;strong&gt;zero&lt;/strong&gt; discovered references is a
&lt;code dir=&quot;auto&quot;&gt;PASS&lt;/code&gt; — there is nothing to enforce, not a warning.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;issue-verdict&lt;/code&gt; requires &lt;code dir=&quot;auto&quot;&gt;--actor&lt;/code&gt;.&lt;/strong&gt;
&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent issue-verdict --mission &amp;#x3C;slug&gt; --issue &amp;#x3C;#N&gt; --verdict &amp;#x3C;verdict&gt; --actor &amp;#x3C;identity&gt;&lt;/code&gt;
(&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/src/specify_cli/cli/commands/agent/issue_verdict.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;cli/commands/agent/issue_verdict.py&lt;/code&gt;&lt;/a&gt;)
sets or upserts one issue-matrix row. &lt;code dir=&quot;auto&quot;&gt;--actor&lt;/code&gt; has no default and is
validated non-empty (&lt;code dir=&quot;auto&quot;&gt;do_issue_verdict&lt;/code&gt; raises &lt;code dir=&quot;auto&quot;&gt;IssueVerdictError&lt;/code&gt; /
&lt;code dir=&quot;auto&quot;&gt;empty_actor&lt;/code&gt; otherwise) — there is no anonymous or implicit-actor path for
recording a verdict.&lt;/p&gt;
&lt;h2 id=&quot;pr-draft-and-wip-title-conventions&quot;&gt;PR draft and WIP-title conventions&lt;/h2&gt;
&lt;p&gt;A &lt;code dir=&quot;auto&quot;&gt;WIP&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;[WIP]&lt;/code&gt; prefix on your PR title marks the PR as author-declared
not-ready. Use the GitHub &lt;strong&gt;draft&lt;/strong&gt; flag for the same purpose: keep the PR in
draft until it is ready, and drop any &lt;code dir=&quot;auto&quot;&gt;WIP&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;[WIP]&lt;/code&gt; prefix before you mark it
ready for review. A non-draft PR that still carries a WIP prefix is a
contradiction — reviewers will send it back.&lt;/p&gt;
&lt;p&gt;No CI job currently gates on the draft flag or the WIP title: the modular CI
(&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;, &lt;code dir=&quot;auto&quot;&gt;ci-aggregate.yml&lt;/code&gt;) and &lt;code dir=&quot;auto&quot;&gt;ci-quality.yml&lt;/code&gt;’s
&lt;code dir=&quot;auto&quot;&gt;quality-gate&lt;/code&gt; run the same way on draft and ready PRs. The earlier
draft-gated suites (&lt;code dir=&quot;auto&quot;&gt;integration-tests-core-misc&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;e2e-cross-cutting&lt;/code&gt;) no
longer exist.&lt;/p&gt;
&lt;h2 id=&quot;pr-body-style-consumer-focused-bluf&quot;&gt;PR body style: consumer-focused BLUF&lt;/h2&gt;
&lt;p&gt;A PR description leads with &lt;strong&gt;impact&lt;/strong&gt; — what changes for a user or operator
of Spec Kitty, stated plainly, in the first paragraph. Technical detail
(architecture, seams, test strategy) comes after, for the reviewer who wants
it. The first paragraph should make sense to someone who will &lt;em&gt;use&lt;/em&gt; the
change, not only to someone who will &lt;em&gt;review&lt;/em&gt; it — a PR body is not a
maintainer diary.&lt;/p&gt;
&lt;p&gt;This is checked again at landing time; see
&lt;a href=&quot;/development/how-to/pr-landing/#7-review-focus-areas-beyond-ci&quot;&gt;Landing runbook, step 7&lt;/a&gt;.&lt;/p&gt;
&lt;h2 id=&quot;changelog-update-and-style&quot;&gt;Changelog update and style&lt;/h2&gt;
&lt;p&gt;Every user-facing change adds a changelog fragment: one file per section in
&lt;code dir=&quot;auto&quot;&gt;docs/changelog/unreleased/&lt;/code&gt;, named &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;id&gt;.&amp;#x3C;section&gt;.md&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;id&gt;&lt;/code&gt; is the PR number, the issue
number or a short slug; &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;section&gt;&lt;/code&gt; is &lt;code dir=&quot;auto&quot;&gt;breaking&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;upgrade-notes&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;added&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;changed&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;fixed&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;internal&lt;/code&gt;). Do not edit &lt;code dir=&quot;auto&quot;&gt;docs/changelog/CHANGELOG.md&lt;/code&gt;
directly: two PRs that edit it conflict on every merge, and the release
assembles the fragments into its &lt;code dir=&quot;auto&quot;&gt;[Unreleased]&lt;/code&gt; section
(&lt;code dir=&quot;auto&quot;&gt;python -m scripts.release.changelog_fragments assemble --write&lt;/code&gt;). The entry
mirrors the PR body’s style: consumer-focused, impact-first, one line a user
understands — e.g. “&lt;code dir=&quot;auto&quot;&gt;spec-kitty research&lt;/code&gt; now finds its templates through
the same resolver as every other mission template” — not an
internal-mechanism summary. The fragment holds the entry exactly as it will
read in &lt;a href=&quot;/changelog/CHANGELOG/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs/changelog/CHANGELOG.md&lt;/code&gt;&lt;/a&gt;, with no
heading; see &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/docs/changelog/unreleased/README.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs/changelog/unreleased/README.md&lt;/code&gt;&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;Two automated checks keep docs prose and that &lt;code dir=&quot;auto&quot;&gt;[Unreleased]&lt;/code&gt; section in shape:
a spelling check and a changelog style guard. Both run in CI as the always-on
&lt;code dir=&quot;auto&quot;&gt;docs-lint&lt;/code&gt; job (see &lt;a href=&quot;/development/reference/ci-gate-mechanics/#docs-lint&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs-lint&lt;/code&gt; in the CI gate
mechanics&lt;/a&gt;), so run them locally
first.&lt;/p&gt;
&lt;h3 id=&quot;run-the-docs-checks-locally&quot;&gt;Run the docs checks locally&lt;/h3&gt;
&lt;p&gt;From the repository root, after a one-time &lt;code dir=&quot;auto&quot;&gt;uv sync --frozen&lt;/code&gt; (it installs the
pinned &lt;code dir=&quot;auto&quot;&gt;codespell&lt;/code&gt; from the dev group):&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;make&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;docs-lint&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;        &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# both checks; stops at the first one that fails&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;# or one at a time (`make docs-lint` runs each of these through `uv run --frozen`):&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;uv&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;run&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;--frozen&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;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.docs.check_spelling&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;                     &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# all three spelling passes&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;uv&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;run&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;--frozen&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;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.docs.check_spelling&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;--pass&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;typo&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;         &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# typos in docs prose&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;uv&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;run&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;--frozen&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;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.docs.check_spelling&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;--pass&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;us&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;           &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# US spelling in guides and context&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;uv&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;run&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;--frozen&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;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.docs.check_spelling&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;--pass&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;unreleased&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;   &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# US spelling in [Unreleased]&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;uv&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;run&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;--frozen&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;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.docs.check_changelog_style&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;              &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# changelog entry style&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Exit code &lt;code dir=&quot;auto&quot;&gt;0&lt;/code&gt; means clean, &lt;code dir=&quot;auto&quot;&gt;1&lt;/code&gt; means findings, and &lt;code dir=&quot;auto&quot;&gt;2&lt;/code&gt; means the tool could not
run or could not prove it looked at anything. Exit &lt;code dir=&quot;auto&quot;&gt;2&lt;/code&gt; covers:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;codespell&lt;/code&gt; is not installed, or &lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt; has no &lt;code dir=&quot;auto&quot;&gt;[tool.codespell]&lt;/code&gt;
table (spelling check).&lt;/li&gt;
&lt;li&gt;The changelog cannot be read (both scripts).&lt;/li&gt;
&lt;li&gt;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 scanned zero files (&lt;code dir=&quot;auto&quot;&gt;the &amp;#x3C;pass&gt; pass scanned 0 file(s)&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;unreleased&lt;/code&gt; pass would scan a scratch copy of the section 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 drops, so nothing would be checked.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;A changelog with no &lt;code dir=&quot;auto&quot;&gt;[Unreleased]&lt;/code&gt; section is not an error: the &lt;code dir=&quot;auto&quot;&gt;unreleased&lt;/code&gt;
pass scans &lt;code dir=&quot;auto&quot;&gt;0&lt;/code&gt; lines and the guard prints &lt;code dir=&quot;auto&quot;&gt;nothing to check&lt;/code&gt;, and both exit &lt;code dir=&quot;auto&quot;&gt;0&lt;/code&gt;.
The checks run no pytest.&lt;/p&gt;
&lt;p&gt;Two options help when you test against another tree: &lt;code dir=&quot;auto&quot;&gt;--repo-root PATH&lt;/code&gt; on the
spelling check, and &lt;code dir=&quot;auto&quot;&gt;--changelog PATH&lt;/code&gt; on both. 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), so the result does not depend on your current directory.&lt;/p&gt;
&lt;p&gt;Do &lt;strong&gt;not&lt;/strong&gt; run bare &lt;code dir=&quot;auto&quot;&gt;codespell&lt;/code&gt;. Without the script’s scope roots it scans the
whole repository, including skipped trees (&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 generated files, and reports hundreds of hits that are not
yours.&lt;/p&gt;
&lt;h3 id=&quot;what-gets-checked&quot;&gt;What gets checked&lt;/h3&gt;
&lt;p&gt;The spelling check runs three passes. Each covers Markdown only; the
&lt;code dir=&quot;auto&quot;&gt;skip&lt;/code&gt; list in &lt;code dir=&quot;auto&quot;&gt;[tool.codespell]&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt; excludes &lt;code dir=&quot;auto&quot;&gt;docs/archive/&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;docs/reports/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;docs/plans/&lt;/code&gt;, the generated CLI reference
(&lt;code dir=&quot;auto&quot;&gt;docs/api/cli-commands.md&lt;/code&gt;) and non-Markdown files. A page under those paths is
never spell-checked, so respell it by hand if you touch it.&lt;/p&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Pass&lt;/th&gt;&lt;th&gt;Looks for&lt;/th&gt;&lt;th&gt;Scope&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;typo&lt;/code&gt;&lt;/td&gt;&lt;td&gt;real typos&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;docs/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;packs/built-in/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;README.md&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;us&lt;/code&gt;&lt;/td&gt;&lt;td&gt;British spellings (&lt;code dir=&quot;auto&quot;&gt;behaviour&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;colour&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;docs/guides/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;docs/context/&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;unreleased&lt;/code&gt;&lt;/td&gt;&lt;td&gt;British spellings&lt;/td&gt;&lt;td&gt;the &lt;code dir=&quot;auto&quot;&gt;[Unreleased]&lt;/code&gt; section of the changelog and the fragments in &lt;code dir=&quot;auto&quot;&gt;docs/changelog/unreleased/&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;The two American-spelling passes ignore code spans, fenced blocks and
&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;a id=&quot;…&quot;&gt;&amp;#x3C;/a&gt;&lt;/code&gt; heading anchors, and accept &lt;code dir=&quot;auto&quot;&gt;dialogue&lt;/code&gt;. The typo pass has no
such exemption.&lt;/p&gt;
&lt;p&gt;The changelog guard reads the &lt;code dir=&quot;auto&quot;&gt;[Unreleased]&lt;/code&gt; section and every fragment in
&lt;code dir=&quot;auto&quot;&gt;docs/changelog/unreleased/&lt;/code&gt; (each checked as if it sat under its section, and reported at its
own file and line, plus a &lt;code dir=&quot;auto&quot;&gt;[fragment]&lt;/code&gt; finding for a bad name or shape); released
sections are never restyled. Both scripts find that section through one shared locator, which
ignores a release-looking heading inside a fenced block (fenced with &lt;code dir=&quot;auto&quot;&gt;```&lt;/code&gt; or
&lt;code dir=&quot;auto&quot;&gt;~~~&lt;/code&gt;) and accepts a heading written without a space (&lt;code dir=&quot;auto&quot;&gt;##[Unreleased]&lt;/code&gt;). The
guard enforces:&lt;/p&gt;





























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Area&lt;/th&gt;&lt;th&gt;Rule (finding id)&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;Headings&lt;/td&gt;&lt;td&gt;Only &lt;code dir=&quot;auto&quot;&gt;### Breaking&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;Upgrade Notes&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;Added&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;Changed&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;Fixed&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;Internal&lt;/code&gt;, each at most once and in that order (&lt;code dir=&quot;auto&quot;&gt;heading-unknown&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;heading-duplicate&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;heading-order&lt;/code&gt;). A &lt;code dir=&quot;auto&quot;&gt;####&lt;/code&gt; heading is allowed only under &lt;code dir=&quot;auto&quot;&gt;### Fixed&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;subheading-placement&lt;/code&gt;).&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Entry shape&lt;/td&gt;&lt;td&gt;Entries in every section except Internal start with a bold headline (&lt;code dir=&quot;auto&quot;&gt;headline-missing&lt;/code&gt;). Every entry is a &lt;code dir=&quot;auto&quot;&gt;- &lt;/code&gt; bullet at column 0; a &lt;code dir=&quot;auto&quot;&gt;* &lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;+ &lt;/code&gt; bullet fails (&lt;code dir=&quot;auto&quot;&gt;bullet-marker&lt;/code&gt;). A leftover merge-conflict marker line (&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;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Internal entries&lt;/td&gt;&lt;td&gt;One physical line, with no nested items and no &lt;code dir=&quot;auto&quot;&gt;**Before:**&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;internal-shape&lt;/code&gt;).&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Banned tokens&lt;/td&gt;&lt;td&gt;No requirement IDs such as &lt;code dir=&quot;auto&quot;&gt;FR-012&lt;/code&gt; outside backticks, no 26-character ULID (any one, not only a mission’s), no &lt;code dir=&quot;auto&quot;&gt;.kittify/evidence/&lt;/code&gt; paths, no &lt;code dir=&quot;auto&quot;&gt;planning#&lt;/code&gt; references, no all-caps &lt;code dir=&quot;auto&quot;&gt;DEFAULT&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;REFUSE&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;FAIL&lt;/code&gt; outside backticks, no “Bug-fix; no CLI version bump” boilerplate, and no mention of the retired &lt;code dir=&quot;auto&quot;&gt;merge&lt;/code&gt; command (write &lt;code dir=&quot;auto&quot;&gt;spec-kitty consolidate&lt;/code&gt;; only an entry that also names &lt;code dir=&quot;auto&quot;&gt;spec-kitty consolidate&lt;/code&gt;, such as the rename entry, may name the old command). The same tokens are banned in the text above the first heading and in prose between a &lt;code dir=&quot;auto&quot;&gt;###&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;####&lt;/code&gt; heading and its first bullet (&lt;code dir=&quot;auto&quot;&gt;banned-token&lt;/code&gt;).&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Length&lt;/td&gt;&lt;td&gt;Measured in characters. An entry over 900 warns (&lt;code dir=&quot;auto&quot;&gt;length-warning&lt;/code&gt;); over 1,200 fails (&lt;code dir=&quot;auto&quot;&gt;length&lt;/code&gt;). Each nested bullet is measured on its own. A warning does not change the exit code.&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;A compliant entry looks like this (illustrative content; the guidance test runs
this exact block through the guard, so it stays valid):&lt;/p&gt;

&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;markdown&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:#D9F5DD;--1:#111111&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;**&lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;`&lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--0fw:bold;--1:#3B61B0;--1fw:bold&quot;&gt;spec-kitty consolidate&lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;`&lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--0fw:bold;--1:#3B61B0;--1fw:bold&quot;&gt; no longer deletes a lane branch that still holds unmerged commits&lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;**&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; (#1234).&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 class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;**&lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--0fw:bold;--1:#3B61B0;--1fw:bold&quot;&gt;Before:&lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;**&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; cleanup removed the branch as soon as its Work Package was approved, so late commits were lost. &lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;**&lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--0fw:bold;--1:#3B61B0;--1fw:bold&quot;&gt;After:&lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;**&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; cleanup checks the branch tip first and refuses, naming the commit to restore.&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;false-positives&quot;&gt;False positives&lt;/h3&gt;
&lt;p&gt;The banned-token rules match shapes, not meanings, so some legitimate text is
flagged. In an entry headline or body these all fail: &lt;code dir=&quot;auto&quot;&gt;WP-D-1&lt;/code&gt; (the shape &lt;code dir=&quot;auto&quot;&gt;D-1&lt;/code&gt;
reads as a requirement ID), &lt;code dir=&quot;auto&quot;&gt;ISO C-3&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;C-3&lt;/code&gt;), &lt;code dir=&quot;auto&quot;&gt;SC-2086&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;SC-&lt;/code&gt; plus digits),
&lt;code dir=&quot;auto&quot;&gt;DEFAULT-branch&lt;/code&gt; (the all-caps word &lt;code dir=&quot;auto&quot;&gt;DEFAULT&lt;/code&gt;), and &lt;code dir=&quot;auto&quot;&gt;C#10&lt;/code&gt; in a bold headline
(&lt;code dir=&quot;auto&quot;&gt;refs-in-bold&lt;/code&gt;, because of &lt;code dir=&quot;auto&quot;&gt;#10&lt;/code&gt;). Put the literal in backticks, for example
&lt;code dir=&quot;auto&quot;&gt;`SC-2086`&lt;/code&gt;. That clears requirement IDs and all-caps words. It does not
clear a ULID, which is matched even inside a code span.&lt;/p&gt;
&lt;h3 id=&quot;read-a-failure&quot;&gt;Read a failure&lt;/h3&gt;
&lt;p&gt;Each finding is one line. The spelling check prints
&lt;code dir=&quot;auto&quot;&gt;path:line: [typo] word — fix: suggestion&lt;/code&gt; (or &lt;code dir=&quot;auto&quot;&gt;[us-spelling]&lt;/code&gt;), then a summary:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;text&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:#d6deeb;--1:#403f53&quot;&gt;docs/guides/example.md:12: [us-spelling] colour — fix: color&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:#d6deeb;--1:#403f53&quot;&gt;1 finding(s) across 1 file(s); scanned: typo=665 file(s), us=134 file(s), unreleased=276 line(s)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;The guard prints &lt;code dir=&quot;auto&quot;&gt;path:line: [rule] [Section] headline excerpt — fix&lt;/code&gt;, with
&lt;code dir=&quot;auto&quot;&gt;warning:&lt;/code&gt; in front of warnings, then an &lt;code dir=&quot;auto&quot;&gt;N error(s), M warning(s)&lt;/code&gt; summary:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;text&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:#d6deeb;--1:#403f53&quot;&gt;docs/changelog/CHANGELOG.md:57: [refs-in-bold] [Fixed] Stop duplicate events (#1234) — Move `(#1234)` out of the bold headline: `- **Headline** (#1234).`&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;The line number is the real line in the file, and the text after the dash says
what to do. Read the &lt;code dir=&quot;auto&quot;&gt;scanned:&lt;/code&gt; counts too: a pass that shows &lt;code dir=&quot;auto&quot;&gt;0&lt;/code&gt; looked at
nothing (a wrong &lt;code dir=&quot;auto&quot;&gt;--repo-root&lt;/code&gt;, for instance), which is not the same as a clean
pass. The check now refuses that case for the &lt;code dir=&quot;auto&quot;&gt;typo&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;us&lt;/code&gt; passes: it prints
&lt;code dir=&quot;auto&quot;&gt;error: the &amp;#x3C;pass&gt; pass scanned 0 file(s); a check that looks at nothing cannot pass&lt;/code&gt; and exits &lt;code dir=&quot;auto&quot;&gt;2&lt;/code&gt;. Only &lt;code dir=&quot;auto&quot;&gt;unreleased=0 line(s)&lt;/code&gt; can still be a clean result,
when the changelog has no &lt;code dir=&quot;auto&quot;&gt;[Unreleased]&lt;/code&gt; section.&lt;/p&gt;
&lt;h3 id=&quot;allow-a-legitimate-word&quot;&gt;Allow a legitimate word&lt;/h3&gt;
&lt;p&gt;When &lt;code dir=&quot;auto&quot;&gt;codespell&lt;/code&gt; flags a word that is correct here (a domain term, a proper
noun), add it to &lt;code dir=&quot;auto&quot;&gt;ignore-words-list&lt;/code&gt; in the &lt;code dir=&quot;auto&quot;&gt;[tool.codespell]&lt;/code&gt; table of
&lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt;. Use lowercase, comma-separated, with no spaces:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;toml&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:#C5E478;--1:#3B61B0&quot;&gt;ignore-words-list&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;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;accreting,disjointness,yourword&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;One lowercase entry covers every capitalization. The list is shared by all
three spelling passes, so add only words that are correct everywhere.&lt;/p&gt;
&lt;h3 id=&quot;exempt-a-quoted-literal&quot;&gt;Exempt a quoted literal&lt;/h3&gt;
&lt;p&gt;The two American-spelling passes flag British spellings inside quoted CLI
output, status values, config keys and identifiers, where you cannot change the
word. Put the literal in a code span (&lt;code dir=&quot;auto&quot;&gt;`like this`&lt;/code&gt;), or in a fenced block if
it spans several lines. A single-word heading anchor written as
&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;a id=&quot;behaviour&quot;&gt;&amp;#x3C;/a&gt;&lt;/code&gt; is already exempt. This exemption does not apply to the
typo pass: a real typo inside a code span is still a typo.&lt;/p&gt;
&lt;h3 id=&quot;known-blind-spots&quot;&gt;Known blind spots&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Hyphenated British tokens such as &lt;code dir=&quot;auto&quot;&gt;organisation-tier&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;behaviour-driven&lt;/code&gt;
are never flagged, because &lt;code dir=&quot;auto&quot;&gt;codespell&lt;/code&gt; treats the hyphen as part of the word.
Spell them the American way yourself.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;en-GB&lt;/code&gt; to &lt;code dir=&quot;auto&quot;&gt;en-US&lt;/code&gt; dictionary is not complete; some words, for example
&lt;code dir=&quot;auto&quot;&gt;materialised&lt;/code&gt;, slip through. Respell them by hand when you see them.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;shippable-doctrine-the-built-in-charter-pack-must-work-in-a-consumer-repo&quot;&gt;Shippable doctrine: the built-in Charter Pack must work in a consumer repo&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;The built-in Charter Pack (anything under &lt;code dir=&quot;auto&quot;&gt;packs/built-in/&lt;/code&gt;) MUST be valid
and actionable in a consumer repository that has activated the pack but has NO
access to the spec-kitty source tree, CI, or tooling.&lt;/strong&gt; A Charter Pack is
installed/activated as a &lt;em&gt;pack&lt;/em&gt; in an arbitrary customer repo — it does not ship
our &lt;code dir=&quot;auto&quot;&gt;scripts/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.github/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt;, or &lt;code dir=&quot;auto&quot;&gt;tests/&lt;/code&gt; directories, and never will.&lt;/p&gt;
&lt;p&gt;When reviewing (or authoring) a directive, styleguide, tactic, procedure,
toolguide, or glossary pack, reject any of these:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;A reference to a spec-kitty repo-local file as if the consumer has it&lt;/strong&gt; —
e.g. naming &lt;code dir=&quot;auto&quot;&gt;scripts/docs/&amp;#x3C;x&gt;.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.github/workflows/&amp;#x3C;y&gt;.yml&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/...&lt;/code&gt;, or a &lt;code dir=&quot;auto&quot;&gt;tests/...&lt;/code&gt; path as the enforcement mechanism or a
resolvable artifact. The consumer repo has none of these. Mentioning our own
CI or code-repo paths in shipped doctrine is an inconsistency waiting to
happen (and, when the doctrine is activated in a customer repo, a dangling
reference).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Consumer-facing logic (a lint, gate script, or other executable) that is
not shipped as part of the pack.&lt;/strong&gt; The canonical way to ship executable logic
or any blob to downstream repos is the &lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;asset&lt;/code&gt; doctrine kind&lt;/strong&gt; (a sidecar
&lt;code dir=&quot;auto&quot;&gt;*.asset.yaml&lt;/code&gt; manifest + the blob under the pack’s &lt;code dir=&quot;auto&quot;&gt;assets/&lt;/code&gt; tree — see
&lt;a href=&quot;/development/how-to/create-a-doctrine-artifact/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;create-a-doctrine-artifact.md&lt;/code&gt;&lt;/a&gt;
and &lt;a href=&quot;/architecture/doctrine-kinds/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;doctrine-kinds.md&lt;/code&gt;&lt;/a&gt;). Do &lt;strong&gt;not&lt;/strong&gt; force
downstream customers to add executable scripts or CI to their own repos to
satisfy our doctrine.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Quick check&lt;/strong&gt; — run &lt;strong&gt;both&lt;/strong&gt; patterns:&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:#919F9F;--1:#5F636F&quot;&gt;# repo-local tooling paths&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;grep&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;-rEn&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;scripts/|\.github/|src/specify_cli|tests/&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;packs/built-in/&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;# source-tree PREFIXES -- the content ships, the `src/` prefix does not&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;grep&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;-rEn&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;src/doctrine/|src/mission_runtime|src/charter/|src/runtime/|src/glossary/&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:#F78C6C;--1:#AA0982&quot;&gt;\&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 class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;packs/built-in/&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Neither should return anything a consumer is expected to &lt;em&gt;resolve or run&lt;/em&gt;. The
second pattern matters as much as the first and is easy to forget: an installed
consumer has the pack in site-packages, never a &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; tree prefix, so a
&lt;code dir=&quot;auto&quot;&gt;guide_path:&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;references:&lt;/code&gt; entry carrying the source-tree prefix is a
dangling reference downstream even though the artefact itself ships.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Classify before you fix — a raw hit count is not a defect count.&lt;/strong&gt; Prose that
merely describes an internal practice (“maintained by periodic review”) is fine,
as are generic conventions (&lt;code dir=&quot;auto&quot;&gt;tests/**&lt;/code&gt; globs, &lt;code dir=&quot;auto&quot;&gt;ruff check src/ tests/&lt;/code&gt;); a path
presented as a live gate or resolvable artifact is not. Measured 2026-07-28, the
first pattern returned &lt;strong&gt;84 hits across 23 files of which 52 were real&lt;/strong&gt; — the
rest were permitted prose or a regex false positive. The worked classification,
the relocation order, and the gate that currently &lt;em&gt;requires&lt;/em&gt; one of these
references live in
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/docs/archive/plans/doctrine/built-in-doctrine-repo-coupling-audit.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;built-in-doctrine-repo-coupling-audit.md&lt;/code&gt;&lt;/a&gt;.&lt;/p&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/how-to/local-overrides/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;local-overrides.md&lt;/code&gt;&lt;/a&gt; — developer-only workflow
for working across &lt;code dir=&quot;auto&quot;&gt;spec-kitty-cli&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; /
&lt;code dir=&quot;auto&quot;&gt;spec-kitty-tracker&lt;/code&gt; checkouts without committing editable sources.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/tests/architectural/test_pyproject_shape.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_pyproject_shape.py&lt;/code&gt;&lt;/a&gt;
— TOML-shape assertions for the shared-package boundary
(compatibility ranges, no committed editable sources, etc.).&lt;/li&gt;
&lt;li&gt;The CI job &lt;code dir=&quot;auto&quot;&gt;clean-install-verification&lt;/code&gt; in
&lt;code dir=&quot;auto&quot;&gt;.github/workflows/ci-quality.yml&lt;/code&gt; performs the equivalent
fresh-venv check on every PR.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
