<?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-04-11-1-saas-rollout-and-readiness/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-04-11-1-saas-rollout-and-readiness/</id>
  <title>SaaS Rollout Gate and Hosted Readiness Split</title>
  <updated>2026-04-11T00: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-04-11-1-saas-rollout-and-readiness/"/>
  <summary>Separates hosted rollout visibility from per-prerequisite readiness diagnostics into one saas package, leaving the old flag modules as thin re-export shims.</summary>
  <content type="html">&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Superseded (2026-09-06)&lt;/strong&gt; by
&lt;a href=&quot;/adr/3.x/2026-09-06-1-convergence-retirement-and-client-repo-inversion/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;2026-09-06-1-convergence-retirement-and-client-repo-inversion.md&lt;/code&gt;&lt;/a&gt;.
The &lt;code dir=&quot;auto&quot;&gt;specify_cli.saas&lt;/code&gt; rollout/readiness package this ADR governs was deleted by the Convergence
(#3881 / #3824); residual readiness re-homed to &lt;code dir=&quot;auto&quot;&gt;tracker/saas_readiness.py&lt;/code&gt;, the SaaS-sync flag to
&lt;code dir=&quot;auto&quot;&gt;core/saas_sync_config.py&lt;/code&gt;. Retained as historical record.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Spec Kitty uses &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_ENABLE_SAAS_SYNC=1&lt;/code&gt; as the explicit opt-in gate
controlling whether the hosted tracker/sync surface is visible at all.  On
customer machines where the variable is absent the CLI fails closed — no hosted
commands appear, no SaaS network traffic occurs.  On internally designated test
machines the variable is set and the full hosted surface becomes available.&lt;/p&gt;
&lt;p&gt;Before this mission the rollout gate had two structural problems:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Duplicated gate logic.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;is_saas_sync_enabled()&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;saas_sync_disabled_message()&lt;/code&gt; were duplicated verbatim in both
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/tracker/feature_flags.py&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/sync/feature_flags.py&lt;/code&gt;.  Neither module was the clear owner;
every new consumer had to choose one arbitrarily.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Single generic gate error inside enabled mode.&lt;/strong&gt; Once the env var was set
the CLI hid the tracker command group correctly at registration time, but
inside that enabled surface each command performed ad hoc preflight checks and
emitted one generic “not enabled” error regardless of what prerequisite was
actually missing.  NFR-002 (“100% of readiness failures must name the missing
prerequisite”) was unachievable under the old model.&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;There was also no structured policy for background-daemon auto-start.
&lt;code dir=&quot;auto&quot;&gt;ensure_sync_daemon_running()&lt;/code&gt; would unconditionally start the daemon from any
call site, including help and local-only dashboard commands that should never
trigger hosted network activity.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;NFR-001&lt;/strong&gt; — In the absence of &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_ENABLE_SAAS_SYNC&lt;/code&gt;, 100% of hosted
tracker visibility and execution paths must remain hidden or blocked.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;NFR-002&lt;/strong&gt; — In enabled mode, 100% of readiness failures must name the
missing prerequisite and the next corrective action.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;NFR-003&lt;/strong&gt; — Help and local-only commands must not start hosted background
networking even on enabled internal machines.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;C-001&lt;/strong&gt; — The stealth rollout posture (hidden by default) must be preserved;
the env var is not removed in this mission.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;C-002&lt;/strong&gt; — &lt;code dir=&quot;auto&quot;&gt;spec-kitty-tracker&lt;/code&gt; is a pinned external dependency and must not
carry rollout logic.&lt;/li&gt;
&lt;li&gt;Backwards compatibility across existing call sites without a flag-day
migration.&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;Option 1:&lt;/strong&gt; Per-command flag in each tracker command instead of a shared
evaluator.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 2:&lt;/strong&gt; Single unified gate that mixes visibility control and readiness
evaluation.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 3:&lt;/strong&gt; Add rollout logic to &lt;code dir=&quot;auto&quot;&gt;spec-kitty-tracker==0.3.0&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 4:&lt;/strong&gt; Environment variable for background-daemon policy.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 5:&lt;/strong&gt; Project-level daemon config in this mission.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 6 (chosen):&lt;/strong&gt; New shared &lt;code dir=&quot;auto&quot;&gt;saas/&lt;/code&gt; package for rollout + readiness;
intent-gated daemon; user-level config key for daemon policy.&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: Option 6&lt;/strong&gt;, because it separates the two concerns (visibility
and per-prerequisite diagnostics) into cohesive abstractions without a flag-day
migration, while preserving the existing rollout posture for all customer machines.&lt;/p&gt;
&lt;h3 id=&quot;core-decisions&quot;&gt;Core Decisions&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Decision 1 — Consolidate rollout gating into &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/saas/&lt;/code&gt;.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;A new top-level package &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/saas/&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;rollout.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;readiness.py&lt;/code&gt;)
is the single owner of the &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_ENABLE_SAAS_SYNC&lt;/code&gt; check and of the
hosted-readiness evaluator.  The existing &lt;code dir=&quot;auto&quot;&gt;tracker/feature_flags.py&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;sync/feature_flags.py&lt;/code&gt; become thin re-export shims that delegate to
&lt;code dir=&quot;auto&quot;&gt;specify_cli.saas.rollout&lt;/code&gt; — no call-site renaming is required in this mission.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Decision 2 — Introduce &lt;code dir=&quot;auto&quot;&gt;HostedReadiness&lt;/code&gt; evaluator with a 6-state enum.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/saas/readiness.py&lt;/code&gt; exposes &lt;code dir=&quot;auto&quot;&gt;ReadinessState&lt;/code&gt; (a closed &lt;code dir=&quot;auto&quot;&gt;Enum&lt;/code&gt;
with six members) and &lt;code dir=&quot;auto&quot;&gt;evaluate_readiness()&lt;/code&gt;, which checks prerequisites in a
defined order and returns a frozen &lt;code dir=&quot;auto&quot;&gt;ReadinessResult&lt;/code&gt; whose &lt;code dir=&quot;auto&quot;&gt;message&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;next_action&lt;/code&gt; fields describe the first failing prerequisite.  The check order is:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Rollout gate (&lt;code dir=&quot;auto&quot;&gt;ROLLOUT_DISABLED&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;Auth token (&lt;code dir=&quot;auto&quot;&gt;MISSING_AUTH&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;Host URL via &lt;code dir=&quot;auto&quot;&gt;specify_cli.auth.config.get_saas_base_url()&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;MISSING_HOST_CONFIG&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;Network reachability — only when &lt;code dir=&quot;auto&quot;&gt;probe_reachability=True&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;HOST_UNREACHABLE&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;Tracker binding — only when &lt;code dir=&quot;auto&quot;&gt;require_mission_binding=True&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;MISSING_MISSION_BINDING&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;All checks passed (&lt;code dir=&quot;auto&quot;&gt;READY&lt;/code&gt;)&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;The &lt;code dir=&quot;auto&quot;&gt;MISSING_HOST_CONFIG&lt;/code&gt; check reads &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_SAAS_URL&lt;/code&gt; through
&lt;code dir=&quot;auto&quot;&gt;specify_cli.auth.config.get_saas_base_url()&lt;/code&gt; — the authoritative D-5 source.
&lt;code dir=&quot;auto&quot;&gt;SyncConfig.get_server_url()&lt;/code&gt; is &lt;strong&gt;not&lt;/strong&gt; used here.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Decision 3 — Background-daemon policy is a user-level config key.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;BackgroundDaemonPolicy&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;AUTO&lt;/code&gt; | &lt;code dir=&quot;auto&quot;&gt;MANUAL&lt;/code&gt;, default &lt;code dir=&quot;auto&quot;&gt;AUTO&lt;/code&gt;) is added to the
existing &lt;code dir=&quot;auto&quot;&gt;SyncConfig&lt;/code&gt; class in &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/sync/config.py&lt;/code&gt;, persisted as
&lt;code dir=&quot;auto&quot;&gt;[sync] background_daemon&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;~/.spec-kitty/config.toml&lt;/code&gt;.  Project-level
override is explicitly deferred (see Consequences).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Decision 4 — Daemon startup is intent-gated via &lt;code dir=&quot;auto&quot;&gt;DaemonIntent&lt;/code&gt;.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;DaemonIntent&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;LOCAL_ONLY&lt;/code&gt; | &lt;code dir=&quot;auto&quot;&gt;REMOTE_REQUIRED&lt;/code&gt;) is a new enum in
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/sync/daemon.py&lt;/code&gt; required as a mandatory keyword-only argument
on &lt;code dir=&quot;auto&quot;&gt;ensure_sync_daemon_running()&lt;/code&gt;.  The function returns a typed
&lt;code dir=&quot;auto&quot;&gt;DaemonStartOutcome&lt;/code&gt; and refuses to start the daemon when:&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;intent != DaemonIntent.REMOTE_REQUIRED&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 style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;OR&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;policy == BackgroundDaemonPolicy.MANUAL&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;Decision 5 — &lt;code dir=&quot;auto&quot;&gt;spec-kitty-tracker==0.3.0&lt;/code&gt; remains ungated.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;No rollout logic is added to the tracker package.  Tracker is a pinned external
dependency and is not the owner of rollout posture (C-002).  The CLI and SaaS
own the gate; tracker is a downstream consumer.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Decision 6 — The &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_ENABLE_SAAS_SYNC&lt;/code&gt; gate is not removed.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;The stealth rollout posture is preserved unchanged.  The env var continues to
control whether the hosted surface is visible.  Removing it is explicitly out of
scope for this mission.&lt;/p&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;h3 id=&quot;positive&quot;&gt;Positive&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;HostedReadiness&lt;/code&gt; is the single fan-in point for any new hosted prerequisite —
future missions add &lt;code dir=&quot;auto&quot;&gt;ReadinessState&lt;/code&gt; members rather than sprinkling ad hoc
checks across commands.&lt;/li&gt;
&lt;li&gt;Operators gain a new config knob (&lt;code dir=&quot;auto&quot;&gt;[sync].background_daemon&lt;/code&gt;) that controls
auto-start behavior without touching rollout gating.&lt;/li&gt;
&lt;li&gt;The three daemon call sites (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/dashboard/server.py&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/dashboard/handlers/api.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/sync/events.py&lt;/code&gt;)
now declare intent explicitly, and a CI grep guard in
&lt;code dir=&quot;auto&quot;&gt;tests/sync/test_daemon_intent_gate.py&lt;/code&gt; prevents silent proliferation.&lt;/li&gt;
&lt;li&gt;NFR-002 is achievable: every non-&lt;code dir=&quot;auto&quot;&gt;READY&lt;/code&gt; state has a frozen message and a
&lt;code dir=&quot;auto&quot;&gt;next_action&lt;/code&gt; that names the specific missing prerequisite.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;negative&quot;&gt;Negative&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;BC shims at &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/tracker/feature_flags.py&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/sync/feature_flags.py&lt;/code&gt; remain; collapsing them is a future
cleanup mission once every call site migrates to &lt;code dir=&quot;auto&quot;&gt;specify_cli.saas.rollout&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;SyncConfig&lt;/code&gt; is a plain class (not a dataclass); the new
&lt;code dir=&quot;auto&quot;&gt;get_background_daemon()&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;set_background_daemon()&lt;/code&gt; methods follow the
existing getter/setter pattern rather than a simpler field declaration.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;neutral&quot;&gt;Neutral&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Project-level override of daemon policy is explicitly deferred.  The migration
path is a &lt;code dir=&quot;auto&quot;&gt;resolve_background_daemon_policy(repo_root)&lt;/code&gt; helper that layers
project config over user config; the new enum and intent gate stay unchanged
when that helper is introduced.&lt;/li&gt;
&lt;li&gt;Subdividing &lt;code dir=&quot;auto&quot;&gt;MISSING_AUTH&lt;/code&gt; into &lt;code dir=&quot;auto&quot;&gt;NO_TOKEN | EXPIRED_TOKEN&lt;/code&gt; is deferred — the
current auth lookup does not distinguish between the two states.  Adding a
member is additive and requires no structural change to the evaluator.&lt;/li&gt;
&lt;li&gt;The rollout env-var itself is &lt;strong&gt;not removed&lt;/strong&gt; — stealth rollout remains in
force during the current internal-testing window.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;This decision is validated when:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;A machine without &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_ENABLE_SAAS_SYNC&lt;/code&gt; shows no hosted tracker
surface and &lt;code dir=&quot;auto&quot;&gt;is_saas_sync_enabled()&lt;/code&gt; returns &lt;code dir=&quot;auto&quot;&gt;False&lt;/code&gt; from a single canonical
location (&lt;code dir=&quot;auto&quot;&gt;specify_cli.saas.rollout&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;With &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_ENABLE_SAAS_SYNC=1&lt;/code&gt;, readiness failures each name their
specific missing prerequisite rather than a generic gate message.&lt;/li&gt;
&lt;li&gt;Local-only and help commands do not start the background daemon.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;[sync] background_daemon = manual&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;~/.spec-kitty/config.toml&lt;/code&gt; suppresses
daemon auto-start even when &lt;code dir=&quot;auto&quot;&gt;REMOTE_REQUIRED&lt;/code&gt; intent is declared.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/sync/test_daemon_intent_gate.py&lt;/code&gt; fails if any new call site omits the
&lt;code dir=&quot;auto&quot;&gt;intent=&lt;/code&gt; argument.&lt;/li&gt;
&lt;/ol&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;option-1-per-command-flag-in-each-tracker-command&quot;&gt;Option 1: Per-command flag in each tracker command&lt;/h3&gt;
&lt;p&gt;Each hosted tracker command carries its own readiness-check logic and calls the
gate function directly.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Localized — each command is self-contained.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Duplicates the env-var read at every command.&lt;/li&gt;
&lt;li&gt;No per-prerequisite messaging; NFR-002 is still unachievable.&lt;/li&gt;
&lt;li&gt;Any new prerequisite requires touching every command.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-2-single-unified-gate-mixing-visibility-and-readiness&quot;&gt;Option 2: Single unified gate mixing visibility and readiness&lt;/h3&gt;
&lt;p&gt;One gate function controls both whether commands are visible and whether they
have all required prerequisites.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Fewer abstractions.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Conflates stealth rollout (product policy) with operational diagnostics
(runtime state).  NFR-002 is unachievable because the gate cannot name
which prerequisite is missing without knowing the caller’s context.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-3-add-rollout-logic-to-spec-kitty-tracker030&quot;&gt;Option 3: Add rollout logic to &lt;code dir=&quot;auto&quot;&gt;spec-kitty-tracker==0.3.0&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;Push the gate into the tracker package itself.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Gate travels with the functionality.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Explicitly forbidden by C-002.  Tracker is a pinned external dependency and
is not the owner of rollout posture.  The CLI and SaaS own that boundary.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-4-environment-variable-for-background-daemon-policy&quot;&gt;Option 4: Environment variable for background-daemon policy&lt;/h3&gt;
&lt;p&gt;Use a second env var (e.g., &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_DAEMON_MODE&lt;/code&gt;) to control daemon startup.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Easy to set in CI pipelines.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Overloads the env-var surface and risks confusing the rollout story.
&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_ENABLE_SAAS_SYNC&lt;/code&gt; already carries rollout intent; a sibling var
for daemon policy creates ambiguity about which var does what.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-5-project-level-daemon-config-in-this-mission&quot;&gt;Option 5: Project-level daemon config in this mission&lt;/h3&gt;
&lt;p&gt;Add &lt;code dir=&quot;auto&quot;&gt;[sync] background_daemon&lt;/code&gt; to &lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt; alongside user-level
config.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Per-repo CI policy without touching the user config file.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Scope creep for this mission.  The layering adds complexity before any use
case requires it.  Documented as the future migration path instead.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Mission artifacts governing this ADR:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-specs/082-stealth-gated-saas-sync-hardening/spec.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-specs/082-stealth-gated-saas-sync-hardening/plan.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-specs/082-stealth-gated-saas-sync-hardening/research.md&lt;/code&gt; (R-001 through R-006)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-specs/082-stealth-gated-saas-sync-hardening/contracts/saas_rollout.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-specs/082-stealth-gated-saas-sync-hardening/contracts/hosted_readiness.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-specs/082-stealth-gated-saas-sync-hardening/contracts/background_daemon_policy.md&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Implementation seams this ADR governs:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/saas/rollout.py&lt;/code&gt; (WP01 — canonical rollout gate)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/saas/readiness.py&lt;/code&gt; (WP02 — hosted-readiness evaluator)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/sync/config.py&lt;/code&gt; (WP03 — &lt;code dir=&quot;auto&quot;&gt;BackgroundDaemonPolicy&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;get_background_daemon()&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/sync/daemon.py&lt;/code&gt; (WP04 — &lt;code dir=&quot;auto&quot;&gt;DaemonIntent&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;DaemonStartOutcome&lt;/code&gt;, intent-gated &lt;code dir=&quot;auto&quot;&gt;ensure_sync_daemon_running()&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/tracker.py&lt;/code&gt; (WP05 — tracker CLI uses &lt;code dir=&quot;auto&quot;&gt;evaluate_readiness()&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/tracker/feature_flags.py&lt;/code&gt; (BC shim — re-exports &lt;code dir=&quot;auto&quot;&gt;specify_cli.saas.rollout&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/sync/feature_flags.py&lt;/code&gt; (BC shim — re-exports &lt;code dir=&quot;auto&quot;&gt;specify_cli.saas.rollout&lt;/code&gt;)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Prior ADRs in the same rollout-gate lineage:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;2026-02-27-1-cli-tracker-surface-gated-by-saas-sync-flag.md&lt;/code&gt; — original decision to gate tracker via &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_ENABLE_SAAS_SYNC&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;2026-02-27-2-host-owned-tracker-persistence-boundary.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;2026-04-19-1-cli-auth-uses-encrypted-file-only-session-storage.md&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
