<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/2.x/2026-02-27-1-cli-tracker-surface-gated-by-saas-sync-flag/">
  <id>https://docs.spec-kitty.ai/adr/2.x/2026-02-27-1-cli-tracker-surface-gated-by-saas-sync-flag/</id>
  <title>CLI Tracker Surface Gated by SaaS Sync Flag</title>
  <updated>2026-02-27T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/2.x/2026-02-27-1-cli-tracker-surface-gated-by-saas-sync-flag/"/>
  <summary>Registers tracker commands only when the hosted sync flag is enabled, so a local-only install never discovers a half-working surface it has no way to complete.</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 in-place CLI→SaaS sync transport this gating served was removed by the Convergence (#3881 /
#3824). The &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_ENABLE_SAAS_SYNC&lt;/code&gt; gate &lt;strong&gt;survives&lt;/strong&gt; — but now only as an auth/hosted-visibility
gate for the surviving &lt;code dir=&quot;auto&quot;&gt;tracker&lt;/code&gt; command group, not as a sync-transport gate. Retained as historical
record with that clarification.&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;SpecKitty already uses &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_ENABLE_SAAS_SYNC&lt;/code&gt; as the rollout boundary for SaaS-synced functionality. Introducing tracker commands outside this boundary creates policy drift, user confusion, and inconsistent behavior between installations.&lt;/p&gt;
&lt;p&gt;The tracker integration introduces new CLI commands (&lt;code dir=&quot;auto&quot;&gt;spec-kitty tracker ...&lt;/code&gt;) and sync orchestration paths. Without strict gating, users with SaaS sync disabled could still discover partially functional tracker behavior.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Preserve existing feature-flag contract for SaaS-dependent capabilities.&lt;/li&gt;
&lt;li&gt;Avoid fragmented UX where command help exposes disabled products.&lt;/li&gt;
&lt;li&gt;Ensure deterministic behavior in environments where SaaS sync is intentionally off.&lt;/li&gt;
&lt;li&gt;Minimize operational/support burden from accidental partial enablement.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Always register tracker commands and show runtime warnings.&lt;/li&gt;
&lt;li&gt;Gate only mutating commands, keep read-only commands visible.&lt;/li&gt;
&lt;li&gt;Register tracker command group only when SaaS sync flag is enabled (chosen).&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option:&lt;/strong&gt; register tracker commands only when &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_ENABLE_SAAS_SYNC&lt;/code&gt; is enabled, and hard-fail through legacy/direct paths with existing disabled-message semantics.&lt;/p&gt;
&lt;h3 id=&quot;required-behavior&quot;&gt;Required Behavior&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tracker&lt;/code&gt; command group is not registered when flag is disabled.&lt;/li&gt;
&lt;li&gt;Any direct/legacy invocation path uses the same disabled response pattern as sync/auth command guards.&lt;/li&gt;
&lt;li&gt;No background tracker sync hooks run when flag is disabled.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ol&gt;
&lt;li&gt;Feature rollout remains consistent with established policy.&lt;/li&gt;
&lt;li&gt;Help surface accurately reflects usable command set.&lt;/li&gt;
&lt;li&gt;Lower risk of unsupported local states.&lt;/li&gt;
&lt;/ol&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ol&gt;
&lt;li&gt;Teams wanting tracker-only local mode must enable SaaS sync flag in v1.&lt;/li&gt;
&lt;li&gt;Additional guard-path tests are required.&lt;/li&gt;
&lt;/ol&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ol&gt;
&lt;li&gt;Future decoupling from SaaS flag remains possible but is explicitly deferred.&lt;/li&gt;
&lt;/ol&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;&lt;code dir=&quot;auto&quot;&gt;spec-kitty --help&lt;/code&gt; excludes tracker commands when flag is off.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty --help&lt;/code&gt; includes tracker commands when flag is on.&lt;/li&gt;
&lt;li&gt;Direct invocation while disabled returns standard disabled guidance.&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-always-register--runtime-warnings&quot;&gt;Option 1: Always register + runtime warnings&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Easier command discoverability during development.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Violates established gate model.&lt;/li&gt;
&lt;li&gt;Increases accidental usage/support overhead.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;option-2-partially-gate-command-set&quot;&gt;Option 2: Partially gate command set&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Offers limited read-only visibility.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Blurry policy boundary.&lt;/li&gt;
&lt;li&gt;Inconsistent user expectations.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;option-3-full-command-registration-gating-chosen&quot;&gt;Option 3: Full command registration gating (Chosen)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Clear binary rollout behavior.&lt;/li&gt;
&lt;li&gt;Aligns with existing sync/auth guard patterns.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Defers tracker-only mode experimentation.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;CLI command registration:
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/__init__.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Tracker command module:
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/tracker.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Flag guard helper:
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/tracker/feature_flags.py&lt;/code&gt;&lt;/li&gt;
&lt;/ol&gt;</content>
</entry>
