<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/3.x/2026-08-16-4-rc-release-channel/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-08-16-4-rc-release-channel/</id>
  <title>Default-off pre-release (rc) consumer channel, gated by SPEC_KITTY_PRERELEASE</title>
  <updated>2026-08-16T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/3.x/2026-08-16-4-rc-release-channel/"/>
  <summary>A default-off SPEC_KITTY_PRERELEASE preference makes update checks pre-release-aware with a pinned rc install command, without ever nagging stable users.</summary>
  <content type="html">&lt;span id=&quot;default-off-pre-release-rc-consumer-channel-gated-by-spec_kitty_prerelease&quot;&gt;&lt;/span&gt;
&lt;p&gt;&lt;strong&gt;Filename:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;2026-08-16-4-rc-release-channel.md&lt;/code&gt;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-08-16&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Stijn Dejongh (operator); design squad (architect-alphonso design + paula-patterns adversarial review)&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt; Epic #3493 child #3496 (T3/US3, WP3 — consumer slice); mission
&lt;code dir=&quot;auto&quot;&gt;operator-config-ergonomics-01M04YK8&lt;/code&gt;; related #3047 (rc producer half)&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Early adopters and internal team members want to catfood release-candidate (&lt;code dir=&quot;auto&quot;&gt;rcN&lt;/code&gt;) builds of
&lt;code dir=&quot;auto&quot;&gt;spec-kitty-cli&lt;/code&gt; ahead of a stable release, and to be nudged toward the latest rc the same way
stable users are nudged toward the latest stable release. Before this decision there was no
opt-in mechanism: the update-check path (&lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade --agent-check&lt;/code&gt; and the throttled
startup nag) only ever compared against the newest &lt;em&gt;stable&lt;/em&gt; PyPI release, so an rc was
invisible even to someone who explicitly wanted it, and there was no risk of accidentally
surfacing an rc to someone who did not ask.&lt;/p&gt;
&lt;p&gt;The problem statement is therefore narrow and asymmetric: add a way to &lt;em&gt;opt in&lt;/em&gt; to rc
awareness without ever changing behavior for the (overwhelming majority) stable-channel
population — including on the very first invocation after upgrade, with no config file
present yet.&lt;/p&gt;
&lt;p&gt;This ADR covers the &lt;strong&gt;consumer&lt;/strong&gt; half only: how the CLI decides whether to show an rc and how
it proposes installing one. The &lt;strong&gt;producer&lt;/strong&gt; half — CI’s rc build/publish cadence, tagging
scheme, and PyPI publication mechanics — is explicitly out of scope and stays in #3047; this
decision only commits to a discovery &lt;em&gt;interface&lt;/em&gt; with that work (PEP 440 pre-release versions
on the same PyPI index the CLI already probes).&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Stable users must never be advised to install an rc — zero false positives, by construction,
not by convention.&lt;/li&gt;
&lt;li&gt;The preference must be settable without a shell export, consistent with the
&lt;code dir=&quot;auto&quot;&gt;.kitty.env&lt;/code&gt; mechanism this mission already introduces (see the companion
&lt;a href=&quot;/adr/3.x/2026-08-16-5-operator-config-env-expansion-seam/&quot;&gt;env-expansion-seam ADR&lt;/a&gt;) —
operators should not need a second, different config file for this knob.&lt;/li&gt;
&lt;li&gt;No new CLI dependency: pre-release comparison reuses &lt;code dir=&quot;auto&quot;&gt;packaging.version&lt;/code&gt;, already present.&lt;/li&gt;
&lt;li&gt;No &lt;code dir=&quot;auto&quot;&gt;--pre&lt;/code&gt;-style transitive blast radius — a pinned exact rc install, not a floating
“always latest pre-release” mode.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_&lt;/code&gt; naming convention; no bare &lt;code dir=&quot;auto&quot;&gt;KITTY_*&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;A.&lt;/strong&gt; No consumer opt-in; rc’s stay installable only via an explicit
&lt;code dir=&quot;auto&quot;&gt;pip install spec-kitty-cli==&amp;#x3C;rc&gt;&lt;/code&gt; a user already knows to type.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;B.&lt;/strong&gt; A &lt;code dir=&quot;auto&quot;&gt;--pre&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;pip&lt;/code&gt;-style always-latest-prerelease flag with no persisted preference.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;C. (chosen)&lt;/strong&gt; A default-off, persisted &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_PRERELEASE&lt;/code&gt; preference (readable from
&lt;code dir=&quot;auto&quot;&gt;.kitty.env&lt;/code&gt;) that makes “latest version” surfaces pre-release-aware and offers a pinned
&lt;code dir=&quot;auto&quot;&gt;spec-kitty-cli==&amp;#x3C;rc&gt;&lt;/code&gt; install command.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;D.&lt;/strong&gt; Fold rc awareness into the existing &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_ENABLE_SAAS_SYNC&lt;/code&gt;-style hosted-mode
gate rather than a standalone variable.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option: “C”&lt;/strong&gt;, because it is the only option that gives an explicit, durable,
per-operator opt-in without inventing a new floating-update mode or overloading an unrelated
gate.&lt;/p&gt;
&lt;p&gt;Concretely, as shipped:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_PRERELEASE&lt;/code&gt;&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/core/channel.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;prerelease_enabled()&lt;/code&gt;) is a
single-authority, default-OFF boolean read via the existing &lt;code dir=&quot;auto&quot;&gt;core/env.is_truthy&lt;/code&gt; grammar.
Since the &lt;code dir=&quot;auto&quot;&gt;.kitty.env&lt;/code&gt; pre-import loader (see the companion ADR) seeds the process
environment before any command body runs, this module reads only &lt;code dir=&quot;auto&quot;&gt;os.environ&lt;/code&gt; — it never
re-reads the file itself, matching the single-read style used elsewhere.&lt;/li&gt;
&lt;li&gt;With the preference unset (the default for every existing and new project), every “latest
version” surface — &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade --agent-check&lt;/code&gt;, the throttled startup nag, the
compat planner’s cache — reports the newest &lt;strong&gt;stable&lt;/strong&gt; release only, even when a newer rc
exists on the configured index. Stable users see no behavior change whatsoever.&lt;/li&gt;
&lt;li&gt;With the preference on, the newest PEP 440 pre-release on the configured PyPI index is
surfaced, and the proposed upgrade command is a &lt;strong&gt;pinned&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;spec-kitty-cli==&amp;#x3C;rc&gt;&lt;/code&gt; install —
never a floating &lt;code dir=&quot;auto&quot;&gt;--pre&lt;/code&gt; flag — so the operator gets exactly the version that was surfaced,
not “whatever is newest at install time”.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;doctor channel&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/_channel_doctor.py&lt;/code&gt;, a self-registering
sibling via the &lt;code dir=&quot;auto&quot;&gt;doctor.py&lt;/code&gt; auto-discovery seam) reports the active channel as an info line
(&lt;code dir=&quot;auto&quot;&gt;stable&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;prerelease-opt-in&lt;/code&gt;) — read-only, always exits 0.&lt;/li&gt;
&lt;li&gt;The preference is honored from &lt;code dir=&quot;auto&quot;&gt;.kitty.env&lt;/code&gt; with no shell export required, consistent with
every other operator knob this mission moved off ad hoc shell exports.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Zero rc advisories reach a stable user under any tested condition, even when a newer rc
exists on the index — the default-off gate is structural, not a UX nicety.&lt;/li&gt;
&lt;li&gt;Early adopters get one durable opt-in (&lt;code dir=&quot;auto&quot;&gt;.kitty.env&lt;/code&gt;, no per-shell export) instead of
remembering a flag every time.&lt;/li&gt;
&lt;li&gt;The pinned-install command removes ambiguity about which rc is about to be installed.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;A second “latest version” code path (pre-release-aware vs. stable-only) exists in the compat
planner and cache-key logic, adding a small amount of branching to maintain.&lt;/li&gt;
&lt;li&gt;Coordination risk with #3047: if the producer half never actually publishes PEP 440
pre-releases on the probed index, this consumer slice has nothing to discover — the two
halves must agree on the discovery interface independently of either one’s ship date.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;This is purely a consumer read; no new CI job, tag, or publish step is introduced by this
ADR — see #3047 for that half.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;Success signals, verified at ship time: (1) with the channel off, &lt;code dir=&quot;auto&quot;&gt;upgrade --agent-check&lt;/code&gt;
reports only the latest stable release even when a newer rc exists on the index; (2) with the
channel on, the newest pre-release is surfaced and the upgrade command is a pinned
&lt;code dir=&quot;auto&quot;&gt;spec-kitty-cli==&amp;#x3C;rc&gt;&lt;/code&gt; install; (3) the preference is honored when set only in &lt;code dir=&quot;auto&quot;&gt;.kitty.env&lt;/code&gt;,
with no shell export; (4) &lt;code dir=&quot;auto&quot;&gt;doctor channel&lt;/code&gt; reports the active channel correctly in both states.&lt;/p&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;a-no-consumer-opt-in&quot;&gt;A. No consumer opt-in&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; zero new surface area. &lt;strong&gt;Cons:&lt;/strong&gt; does nothing for the stated need — an early
adopter has to already know the exact rc version string to type, with no discovery path.&lt;/p&gt;
&lt;h3 id=&quot;b---pre-style-always-latest-prerelease-flag&quot;&gt;B. &lt;code dir=&quot;auto&quot;&gt;--pre&lt;/code&gt;-style always-latest-prerelease flag&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; familiar &lt;code dir=&quot;auto&quot;&gt;pip&lt;/code&gt;-style ergonomics. &lt;strong&gt;Cons:&lt;/strong&gt; no persisted preference means re-passing
the flag on every invocation, and “always latest pre-release” risks silently jumping to a
newer, less-tested rc than the one the operator evaluated — rejected in favor of an explicit
pinned-version proposal per check.&lt;/p&gt;
&lt;h3 id=&quot;c-default-off-persisted-spec_kitty_prerelease--pinned-install-chosen&quot;&gt;C. Default-off persisted &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_PRERELEASE&lt;/code&gt; + pinned install (chosen)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; durable, explicit, no shell export needed, pinned install avoids surprise version
drift. &lt;strong&gt;Cons:&lt;/strong&gt; a second latest-version code path to maintain.&lt;/p&gt;
&lt;h3 id=&quot;d-fold-into-spec_kitty_enable_saas_sync&quot;&gt;D. Fold into &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_ENABLE_SAAS_SYNC&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; one fewer variable. &lt;strong&gt;Cons:&lt;/strong&gt; conflates two unrelated concerns (hosted-mode gating
vs. release-channel preference); a local-only user who never touches hosted sync would have no
way to opt into rc’s, and a hosted-mode user would be opted into rc’s whether they wanted them
or not. Rejected — the two axes are orthogonal and must stay independently settable.&lt;/p&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Design source: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/operator-config-ergonomics-01M04YK8/design-record.md&lt;/code&gt;
(companion-ADR note) + &lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt; (US3) / &lt;code dir=&quot;auto&quot;&gt;plan.md&lt;/code&gt; (IC-05).&lt;/li&gt;
&lt;li&gt;Companion: &lt;a href=&quot;/adr/3.x/2026-08-16-5-operator-config-env-expansion-seam/&quot;&gt;ADR: operator config env-expansion seam&lt;/a&gt;
— the &lt;code dir=&quot;auto&quot;&gt;.kitty.env&lt;/code&gt; mechanism this preference is read through.&lt;/li&gt;
&lt;li&gt;Producer half (CI rc-cadence + publication): #3047.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
