<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/development/reference/red-main-and-release-readiness/">
  <id>https://docs.spec-kitty.ai/development/reference/red-main-and-release-readiness/</id>
  <title>Red Main and Release Readiness</title>
  <updated>2026-10-04T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/development/reference/red-main-and-release-readiness/"/>
  <summary>What a red main branch means, why CI status is the authoritative release gate, how P0 bugs carry failing reproduction tests, and how maintainers prioritize recovery.</summary>
  <content type="html">&lt;span id=&quot;red-main-and-release-readiness&quot;&gt;&lt;/span&gt;
&lt;p&gt;This guide states, in operational terms, what a red &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; means and how the team acts on it. The governing decision is &lt;a href=&quot;/adr/3.x/2026-07-17-1-red-main-is-honest-ci-is-release-authority/&quot;&gt;ADR 2026-07-17-1&lt;/a&gt;, accepted by consensus (CEO/product owner, QA lead, maintainers).&lt;/p&gt;
&lt;p&gt;The one-line stance: &lt;strong&gt;it’s broken, we hate it, but it’s the truth, so we do not hide it.&lt;/strong&gt; An honest red is worth more than a convenient green.&lt;/p&gt;
&lt;h2 id=&quot;what-a-red-main-means&quot;&gt;What a red main means&lt;/h2&gt;
&lt;p&gt;A red &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; is a &lt;strong&gt;true signal&lt;/strong&gt;, not a workflow violation. It means mainline CI has found one or more known release-blocking (&lt;strong&gt;P0&lt;/strong&gt;) defects. We do &lt;strong&gt;not&lt;/strong&gt; keep &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; green by hiding failures — reverting an honest red or declining to merge a bug’s reproduction test would produce a &lt;em&gt;green-washed&lt;/em&gt; mainline that lies to everyone building on it.&lt;/p&gt;
&lt;p&gt;A red &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; should always be &lt;strong&gt;traceable to an accepted P0&lt;/strong&gt;: a filed issue, ideally with a failing test that reproduces the defect.&lt;/p&gt;
&lt;h2 id=&quot;ci-status-is-the-release-authority&quot;&gt;CI status is the release authority&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Mainline CI status is authoritative for release readiness. Red CI means no release.&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;No release is cut while mainline CI is red — there is no “known-red, ship anyway” path.&lt;/li&gt;
&lt;li&gt;Because CI is the single gate, it must mean one thing. That is exactly why we refuse to green-wash: a CI signal that is sometimes decorative is authoritative for nothing.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;See the release process in &lt;a href=&quot;/development/contributing/&quot;&gt;CONTRIBUTING&lt;/a&gt;; this guide governs &lt;em&gt;whether&lt;/em&gt; a release may proceed, which is gated on green mainline CI.&lt;/p&gt;
&lt;h2 id=&quot;filing-or-accepting-a-p0-add-a-failing-test&quot;&gt;Filing or accepting a P0: add a failing test&lt;/h2&gt;
&lt;p&gt;When you file or accept a P0 bug, you are &lt;strong&gt;free and encouraged&lt;/strong&gt; to land a test that reproduces it — a red-first reproduction at mainline scope.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;A P0 that carries a failing test is unambiguous, self-documenting, and impossible to lose track of. A P0 described only in prose drifts and gets rediscovered downstream.&lt;/li&gt;
&lt;li&gt;Turning &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; red this way is &lt;strong&gt;honouring the process, not breaking it.&lt;/strong&gt; The red is the point: it makes the defect visible until it is fixed.&lt;/li&gt;
&lt;li&gt;This is the mainline-scope extension of the red-first / never-retry-to-green discipline already applied per-PR — see &lt;a href=&quot;/development/testing/testing-flakiness/&quot;&gt;test-flakiness handling&lt;/a&gt; and the red classification bins in the &lt;a href=&quot;/development/how-to/pr-landing/&quot;&gt;PR-landing runbook&lt;/a&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;where-the-reproduction-runs-the-nightly-p0-repro-lane&quot;&gt;Where the reproduction runs: the nightly &lt;code dir=&quot;auto&quot;&gt;p0-repro&lt;/code&gt; lane&lt;/h3&gt;
&lt;p&gt;Mark the reproduction &lt;code dir=&quot;auto&quot;&gt;@pytest.mark.p0_repro(issue=N)&lt;/code&gt;, where &lt;code dir=&quot;auto&quot;&gt;N&lt;/code&gt; is the P0 issue. It runs &lt;strong&gt;only&lt;/strong&gt; in the nightly &lt;code dir=&quot;auto&quot;&gt;p0-repro&lt;/code&gt; job (&lt;code dir=&quot;auto&quot;&gt;.github/workflows/ci-nightly.yml&lt;/code&gt;). A pull request never runs it, so pull requests always land on a green per-PR gate, and the nightly stays red until the P0 is fixed.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;How it is held out.&lt;/strong&gt; The plugin &lt;code dir=&quot;auto&quot;&gt;tests/_support/p0_repro.py&lt;/code&gt; deselects every &lt;code dir=&quot;auto&quot;&gt;p0_repro&lt;/code&gt; test unless &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_RUN_P0_REPRO=1&lt;/code&gt; is set, and only the &lt;code dir=&quot;auto&quot;&gt;p0-repro&lt;/code&gt; job sets it. A &lt;code dir=&quot;auto&quot;&gt;-m&lt;/code&gt; expression cannot pull it into another lane. &lt;code dir=&quot;auto&quot;&gt;make test-fast&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;make test-full&lt;/code&gt; never run it either.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;How it fails.&lt;/strong&gt; Each failure starts with &lt;code dir=&quot;auto&quot;&gt;[OPEN P0 #N] … expected to fail until that bug is fixed&lt;/code&gt;. The job summary and &lt;code dir=&quot;auto&quot;&gt;::error&lt;/code&gt; annotations name every red reproduction, and the JUnit report records the issue as a &lt;code dir=&quot;auto&quot;&gt;p0_issue&lt;/code&gt; property. The lane opens no generic “Nightly suite red” issue, because each reproduction already has its own P0 issue.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Why it still blocks a release.&lt;/strong&gt; A release needs a green nightly for the exact release SHA (&lt;code dir=&quot;auto&quot;&gt;scripts/ci/release_nightly_gate.py&lt;/code&gt;), so the red keeps blocking releases. The same gate also needs a green nightly from the last 7 days in which the weekly &lt;code dir=&quot;auto&quot;&gt;performance&lt;/code&gt; job executed, on the release SHA or a &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; ancestor of it; the newest such run is the verdict, so a newer performance red blocks a release even after an older green (#7704).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A pin without an issue is rejected.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;p0_repro&lt;/code&gt; without a positive &lt;code dir=&quot;auto&quot;&gt;issue=&lt;/code&gt; number is a collection error in every run, including per-PR runs.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;When the fix lands.&lt;/strong&gt; The fix PR removes the &lt;code dir=&quot;auto&quot;&gt;p0_repro&lt;/code&gt; marker in the same change. The test then runs per PR as an ordinary guard (mark it &lt;code dir=&quot;auto&quot;&gt;regression&lt;/code&gt; only if it is an end-to-end replay of the bug’s exact sequence) and must pass there. If a reproduction passes in the nightly before its marker is removed, the run ends with a &lt;code dir=&quot;auto&quot;&gt;[P0 #N REPRO PASSES]&lt;/code&gt; line: either the fix landed without removing the marker, or the reproduction is broken.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Run it locally:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_RUN_P0_REPRO=1 uv run --frozen pytest -m p0_repro -q&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;expensive-qa-and-manual-testing-wait-for-green&quot;&gt;Expensive QA and manual testing wait for green&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Expensive QA runs and internal manual testing do not execute on a red mainline build.&lt;/strong&gt; There is no value in validating a base that is already known-broken; that effort waits until &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; is green. This protects scarce QA and human-tester time from being spent certifying a base whose result is already known.&lt;/p&gt;
&lt;h2 id=&quot;maintainers-prioritize-red-builds&quot;&gt;Maintainers prioritize red builds&lt;/h2&gt;
&lt;p&gt;Green &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; is the goal. A red &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; is &lt;strong&gt;not an acceptable resting state&lt;/strong&gt; — it is an alarm that pulls to the front of the maintainer queue.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Treat mainline recovery as top priority; do not let “red is allowed” erode into “red is tolerated.”&lt;/li&gt;
&lt;li&gt;Land the fix through the normal PR flow (no-direct-push is unchanged — see &lt;a href=&quot;/guides/how-to/missions/keep-main-clean/&quot;&gt;Keep Main Clean&lt;/a&gt;); this policy governs what a red CI &lt;em&gt;means&lt;/em&gt;, not how commits arrive.&lt;/li&gt;
&lt;li&gt;The landing-pass runbook’s &lt;a href=&quot;/development/how-to/pr-landing/#4-classify-every-red-check&quot;&gt;red-classification step&lt;/a&gt; tells you how to tell a genuine P0 red from a flake or a pre-existing breakage while you work the queue.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;see-also&quot;&gt;See also&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/adr/3.x/2026-07-17-1-red-main-is-honest-ci-is-release-authority/&quot;&gt;ADR 2026-07-17-1 — Red main is honest signal; CI status is the release authority&lt;/a&gt; — the governing decision.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/development/testing/testing-flakiness/&quot;&gt;Test-flakiness handling policy&lt;/a&gt; — the never-retry-to-green rule and budget-gate tuning.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/development/how-to/pr-landing/&quot;&gt;Landing Contributor PRs: The Maintainer Runbook&lt;/a&gt; — red classification and the merge-ready hand-off.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/guides/how-to/missions/keep-main-clean/&quot;&gt;How to Keep Main Clean&lt;/a&gt; — the branch and no-direct-push discipline.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
