<?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/cutover-guard/">
  <id>https://docs.spec-kitty.ai/development/how-to/cutover-guard/</id>
  <title>Cut-over guard: fail-closed pre-merge gate for runtime-state cut-over</title>
  <updated>2026-10-30T00: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/cutover-guard/"/>
  <summary>What `spec-kitty cutover-guard` checks, how it is wired into CI so it cannot be silently skipped, and how to register it as a required status check.</summary>
  <content type="html">&lt;span id=&quot;cut-over-guard-fail-closed-pre-merge-gate-for-runtime-state-cut-over&quot;&gt;&lt;/span&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Status&lt;/strong&gt;: stable&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Authority&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/kitty-specs/runtime-state-birth-cutover-all-paths-01KYH654/contracts/pre-merge-guard.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-specs/runtime-state-birth-cutover-all-paths-01KYH654/contracts/pre-merge-guard.md&lt;/code&gt;&lt;/a&gt;
(IC-03 / IC-04; FR-002, FR-003, FR-008, FR-009, NFR-002, NFR-003)&lt;/li&gt;
&lt;li&gt;Mission &lt;code dir=&quot;auto&quot;&gt;runtime-state-birth-cutover-all-paths-01KYH654&lt;/code&gt;, WP03 (guard CLI)
and WP04 (CI wiring, this document)&lt;/li&gt;
&lt;/ul&gt;
&lt;/blockquote&gt;
&lt;h2 id=&quot;what-the-guard-does&quot;&gt;What the guard does&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty cutover-guard&lt;/code&gt; is a diff-scoped, fail-closed check that blocks a
pull request unless every &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&amp;#x3C;mission&gt;/&lt;/code&gt; corpus touched by that PR’s
diff has been &lt;strong&gt;cut over&lt;/strong&gt; to event-log-authoritative runtime state, or is a
&lt;a href=&quot;#pre-accept-missions&quot;&gt;pre-accept Mission&lt;/a&gt;, which is exempt from the stamp check.&lt;/p&gt;
&lt;p&gt;“Cut over” is decided using the same event-log-evidence authority the
dogfood corpus lock uses
(&lt;code dir=&quot;auto&quot;&gt;specify_cli.status.cutover_eligibility.is_cut_over&lt;/code&gt;) — a mission carries a
runtime-state event log
(&lt;code dir=&quot;auto&quot;&gt;_mission_carries_event_log_runtime&lt;/code&gt;) AND satisfies the non-empty-snapshot
birth invariant (&lt;code dir=&quot;auto&quot;&gt;_assert_birth_invariant_holds&lt;/code&gt;). &lt;code dir=&quot;auto&quot;&gt;verify_backfill.ok&lt;/code&gt; is
checked but is &lt;strong&gt;not sufficient on its own&lt;/strong&gt; — it is vacuous for
natively-born missions (they never ran a backfill and can still report
&lt;code dir=&quot;auto&quot;&gt;ok&lt;/code&gt;), so the guard never keys solely on it.&lt;/p&gt;
&lt;p&gt;The guard is a second, independent caller of that same authority; it is not a
fork of the decision logic.&lt;/p&gt;
&lt;h3 id=&quot;exit-behavior&quot;&gt;Exit behavior&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Exit 0&lt;/strong&gt; — every mission touched by the diff is cut over or pre-accept
(including the
vacuous case where the diff touches no &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt; mission at all).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Exit 1&lt;/strong&gt; — one or more touched missions are un-cut-over, OR the diff
itself could not be determined (unknown base ref, unreadable
&lt;code dir=&quot;auto&quot;&gt;--paths-from&lt;/code&gt; file, missing project root). The guard &lt;strong&gt;never&lt;/strong&gt; passes on
uncertainty (NFR-003) — any verify error, ambiguous corpus, missing
&lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt;, or missing mission directory is treated as a failure, not a
skip.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;On failure the guard prints the un-cut-over mission slug(s) and a remedy
specific to the reason (see &lt;a href=&quot;#remedies&quot;&gt;Remedies&lt;/a&gt;). The default remedy is:&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;plaintext&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;spec-kitty migrate backfill-runtime-state --mission &amp;#x3C;slug&gt;&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-accept-missions&quot;&gt;Pre-accept Missions&lt;/h2&gt;
&lt;p&gt;A Mission driven only by the canonical commands carries event-log runtime
evidence from its first claim, but the &lt;code dir=&quot;auto&quot;&gt;status_phase&lt;/code&gt; stamp is written only at
accept/consolidate, by design (#2917). Before this exemption, every in-flight
Mission failed the guard on its first push (#5835, #5300).&lt;/p&gt;
&lt;p&gt;A Mission is exempt, and passes with the note
&lt;code dir=&quot;auto&quot;&gt;pre-accept: status_phase stamp deferred to accept/consolidate&lt;/code&gt;, when all of
these hold:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;it has event-log evidence of runtime state;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; has no &lt;code dir=&quot;auto&quot;&gt;status_phase&lt;/code&gt;, or a well-formed one below &lt;code dir=&quot;auto&quot;&gt;1&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;it has no terminal evidence: no &lt;code dir=&quot;auto&quot;&gt;accepted_at&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;merged_at&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;accept_commit&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;merged_commit&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;acceptance_history&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;mission_number&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;no work package carries legacy claim runtime in its WP frontmatter;&lt;/li&gt;
&lt;li&gt;it has a &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;What counts as legacy claim runtime.&lt;/strong&gt; Only a non-empty &lt;code dir=&quot;auto&quot;&gt;shell_pid&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;shell_pid_created_at&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;assignee&lt;/code&gt;, or a completed review override, in a WP
file. &lt;code dir=&quot;auto&quot;&gt;agent&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;agent_profile&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;role&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;model&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;tracker_refs&lt;/code&gt; do not count:
the canonical tasks-packages step writes them at planning time, before any claim
(operator ruling of 2026-10-07). Checked &lt;code dir=&quot;auto&quot;&gt;tasks.md&lt;/code&gt; subtask rows do not count
either. &lt;code dir=&quot;auto&quot;&gt;spec-kitty migrate backfill-runtime-state&lt;/code&gt; still seeds all of them.&lt;/p&gt;
&lt;p&gt;The guard lists exempt Missions in a separate section of the report and in the
&lt;code dir=&quot;auto&quot;&gt;exempt&lt;/code&gt; key of &lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt;. It does not call them cut over. Each &lt;code dir=&quot;auto&quot;&gt;exempt&lt;/code&gt; item is
&lt;code dir=&quot;auto&quot;&gt;{&quot;slug&quot;: &quot;&amp;#x3C;mission slug&gt;&quot;, &quot;reasons&quot;: [&quot;&amp;#x3C;pre-accept note&gt;&quot;]}&lt;/code&gt;. The key is
additive: consumers that ignore unknown keys are unaffected.&lt;/p&gt;
&lt;p&gt;The exemption fails closed. Each of these makes the Mission fail, never pass:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;a malformed or negative &lt;code dir=&quot;auto&quot;&gt;status_phase&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;a missing or unparsable &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; (reported as an absent &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt;);&lt;/li&gt;
&lt;li&gt;an &lt;code dir=&quot;auto&quot;&gt;accepted_at&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;merged_at&lt;/code&gt; that is present but not a non-empty string;&lt;/li&gt;
&lt;li&gt;a top-level key repeated in &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; (the last value would win);&lt;/li&gt;
&lt;li&gt;a &lt;code dir=&quot;auto&quot;&gt;tasks/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tasks.md&lt;/code&gt; or WP file the guard cannot read to rule out legacy
runtime. The failure reason names the file and the error.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;remedies&quot;&gt;Remedies&lt;/h3&gt;





































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Reason&lt;/th&gt;&lt;th&gt;Remedy&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;Accepted or merged, but no stamp; or legacy WP frontmatter&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty migrate backfill-runtime-state --mission &amp;#x3C;slug&gt;&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Legacy Mission whose &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt; is its own slug (a ULID was never minted), and the cutover refuses with &lt;code dir=&quot;auto&quot;&gt;claim mismatch (deterministic seed payload diverged)&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty migrate backfill-runtime-state --mission &amp;#x3C;slug&gt;&lt;/code&gt; (&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6689&quot;&gt;#6689&lt;/a&gt;).&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;status_phase&lt;/code&gt; malformed&lt;/td&gt;&lt;td&gt;remove the malformed &lt;code dir=&quot;auto&quot;&gt;status_phase&lt;/code&gt; from &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&amp;#x3C;slug&gt;/meta.json&lt;/code&gt; (accept and consolidate stamp it), or, for an accepted Mission, run &lt;code dir=&quot;auto&quot;&gt;spec-kitty migrate backfill-runtime-state --mission &amp;#x3C;slug&gt;&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;accepted_at&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;merged_at&lt;/code&gt; is not a non-empty string&lt;/td&gt;&lt;td&gt;set it to an ISO-8601 string (or remove the key) in &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&amp;#x3C;slug&gt;/meta.json&lt;/code&gt;, then rerun&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;A top-level key repeats in &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;&lt;/td&gt;&lt;td&gt;remove the repeated key from &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&amp;#x3C;slug&gt;/meta.json&lt;/code&gt;, then rerun&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;A file unreadable (&lt;code dir=&quot;auto&quot;&gt;tasks.md&lt;/code&gt;, a WP file, or &lt;code dir=&quot;auto&quot;&gt;tasks/&lt;/code&gt; itself)&lt;/td&gt;&lt;td&gt;repair the file the reason names, then rerun&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Absent &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt; (also a missing or unparsable &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;repair &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&amp;#x3C;slug&gt;/meta.json&lt;/code&gt; if it is missing or not valid JSON; otherwise &lt;code dir=&quot;auto&quot;&gt;spec-kitty migrate backfill-identity --mission &amp;#x3C;slug&gt;&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h3 id=&quot;known-limits&quot;&gt;Known limits&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;A Mission merged to &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; without accept, and with no legacy runtime state,
stays exempt: nothing marks it terminal (&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5850&quot;&gt;#5850&lt;/a&gt;).&lt;/li&gt;
&lt;li&gt;A coordination-topology Mission’s event log may be absent from a PR head.
This is pre-existing; a follow-up tracks it.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;how-it-is-invoked&quot;&gt;How it is invoked&lt;/h2&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;# CI usage — diff against the PR&apos;s base ref&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;spec-kitty&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;cutover-guard&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;--base-ref&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;origin/main&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;# CI usage — host already has the changed-file list (e.g. a PR file listing)&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;spec-kitty&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;cutover-guard&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;--paths-from&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;changed-files.txt&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/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;# Either form, machine-readable&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;spec-kitty&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;cutover-guard&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;--base-ref&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;origin/main&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;--json&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Exactly one of &lt;code dir=&quot;auto&quot;&gt;--base-ref&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;--paths-from&lt;/code&gt; is required.&lt;/p&gt;
&lt;h2 id=&quot;how-it-triggers-in-ci-the-corpus-only-pr-requirement&quot;&gt;How it triggers in CI (the corpus-only-PR requirement)&lt;/h2&gt;
&lt;p&gt;The guard runs as the &lt;code dir=&quot;auto&quot;&gt;cutover-guard&lt;/code&gt; job in
&lt;code dir=&quot;auto&quot;&gt;.github/workflows/release-readiness.yml&lt;/code&gt;, &lt;strong&gt;not&lt;/strong&gt; in &lt;code dir=&quot;auto&quot;&gt;ci-quality.yml&lt;/code&gt; or the
modular CI. This placement is deliberate:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The test workflows decide which jobs run from a paths filter over the
&lt;em&gt;source&lt;/em&gt; areas a diff touches (today &lt;code dir=&quot;auto&quot;&gt;ci-router.yml&lt;/code&gt;’s &lt;code dir=&quot;auto&quot;&gt;changes&lt;/code&gt; job). A
diff that touches &lt;strong&gt;only&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;kitty-specs/**&lt;/code&gt; does not set the &lt;code dir=&quot;auto&quot;&gt;src&lt;/code&gt;-family
outputs, so a guard job hosted there and gated the same way would never
execute on a corpus-only PR — exactly the leak this WP exists to close (risk R1, and
the general “a required check that is &lt;code dir=&quot;auto&quot;&gt;if:&lt;/code&gt;-skipped reports neutral and
does not block merge” footgun).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;release-readiness.yml&lt;/code&gt; is a small, &lt;code dir=&quot;auto&quot;&gt;pull_request&lt;/code&gt;-scoped workflow with no
such gate on its own trigger. Its &lt;code dir=&quot;auto&quot;&gt;on.pull_request.paths&lt;/code&gt; filter has been
extended to include &lt;code dir=&quot;auto&quot;&gt;kitty-specs/**&lt;/code&gt; specifically so that a corpus-only
PR triggers this workflow (and therefore the &lt;code dir=&quot;auto&quot;&gt;cutover-guard&lt;/code&gt; job) at all.
&lt;strong&gt;If &lt;code dir=&quot;auto&quot;&gt;kitty-specs/**&lt;/code&gt; is ever removed from that &lt;code dir=&quot;auto&quot;&gt;paths&lt;/code&gt; list, the guard
stops firing on corpus-only PRs with no other symptom&lt;/strong&gt; — treat that path
entry as load-bearing.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;cutover-guard&lt;/code&gt; job itself carries &lt;strong&gt;no&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;changes&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;dorny&lt;/code&gt; step gate.
It has exactly one conditional: the standard repo-wide
&lt;code dir=&quot;auto&quot;&gt;pr:deferred&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;pr:skip-ci&lt;/code&gt; label skip (the same explicit,
operator-visible opt-out also used in &lt;code dir=&quot;auto&quot;&gt;ci-windows.yml&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;check-spec-kitty-events-alignment.yml&lt;/code&gt;). Beyond that label check, the job runs unconditionally whenever
the workflow runs — it does not sit behind any src-changes-shaped filter
that a corpus-only diff could fail to satisfy.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;registering-it-as-a-required-check-operator-action&quot;&gt;Registering it as a required check (operator action)&lt;/h2&gt;
&lt;p&gt;Wiring the job into the workflow is necessary but &lt;strong&gt;not sufficient&lt;/strong&gt;. GitHub
branch protection only blocks a merge on checks that are explicitly
registered as required. The operator must:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Open the repository’s branch protection settings for the target branch
(&lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;; the workflow’s &lt;code dir=&quot;auto&quot;&gt;pull_request.branches&lt;/code&gt; list also still names the
legacy &lt;code dir=&quot;auto&quot;&gt;2.x&lt;/code&gt; branch).&lt;/li&gt;
&lt;li&gt;Under “Require status checks to pass before merging”, add
&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;cutover-guard&lt;/code&gt;&lt;/strong&gt; (the job name from &lt;code dir=&quot;auto&quot;&gt;release-readiness.yml&lt;/code&gt;) to the
required-checks list.&lt;/li&gt;
&lt;li&gt;Confirm the setting was saved — GitHub’s UI only offers checks that have
run at least once on that branch, so the job must have executed on some
PR before it appears in the picker.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;the-skipped-required-check-footgun&quot;&gt;The skipped-required-check footgun&lt;/h3&gt;
&lt;p&gt;A required check whose job is &lt;code dir=&quot;auto&quot;&gt;if:&lt;/code&gt;-skipped for a given run reports a
&lt;strong&gt;neutral/“skipped”&lt;/strong&gt; conclusion in GitHub’s UI, not a failure — and GitHub
treats a skipped required check as satisfied, letting the PR merge. This is
exactly why the job above avoids any conditional beyond the label skip: a
required check that &lt;em&gt;can&lt;/em&gt; legitimately be skipped for reasons unrelated to
the label opt-out is a required check that can silently fail open.&lt;/p&gt;
&lt;p&gt;If this job is ever refactored, re-verify — with a live scratch PR touching
only &lt;code dir=&quot;auto&quot;&gt;kitty-specs/**&lt;/code&gt; — that it still executes (not skips) on a corpus-only
diff. Do not trust a reading of the &lt;code dir=&quot;auto&quot;&gt;paths:&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;if:&lt;/code&gt; YAML alone; the mission
that produced this guard (&lt;code dir=&quot;auto&quot;&gt;runtime-state-birth-cutover-all-paths-01KYH654&lt;/code&gt;)
was itself created to close a gap that a path-filter reading alone had
missed (see &lt;code dir=&quot;auto&quot;&gt;#2968&lt;/code&gt;).&lt;/p&gt;
&lt;h2 id=&quot;local-verification-ci-equivalent-simulation&quot;&gt;Local verification (CI-equivalent simulation)&lt;/h2&gt;
&lt;p&gt;Because a real GitHub Actions run only happens once a PR is opened, the
job’s behavior can be simulated locally with &lt;code dir=&quot;auto&quot;&gt;--paths-from&lt;/code&gt;, which accepts
exactly the changed-path list the CI job would otherwise obtain from a real
diff:&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;# 1. A synthetic corpus-only changed-path list (as if only this file changed)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;echo&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;kitty-specs/&amp;#x3C;mission-slug&gt;/status.events.jsonl&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;/tmp/changed-paths.txt&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/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;# 2. Run the guard exactly as CI would&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;spec-kitty&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;cutover-guard&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;--paths-from&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;/tmp/changed-paths.txt&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;This proves, without needing a live GitHub run:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;the guard triggers (evaluates the mission) on a changed-path set that
touches only &lt;code dir=&quot;auto&quot;&gt;kitty-specs/**&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;it exits non-zero and names the mission plus the remedy command when that
mission is un-cut-over;&lt;/li&gt;
&lt;li&gt;it exits &lt;code dir=&quot;auto&quot;&gt;0&lt;/code&gt; when the named mission is cut over.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The true end-to-end verification — that GitHub itself schedules and runs
the &lt;code dir=&quot;auto&quot;&gt;cutover-guard&lt;/code&gt; job for a real corpus-only PR — is recorded as a
separate, mandatory piece of evidence (subtask T019) gathered against a real
scratch PR, since it cannot be produced from a local git checkout.&lt;/p&gt;</content>
</entry>
