sourcecode 3.2.1__py3-none-any.whl → 3.2.2__py3-none-any.whl

sourcecode/cli.py

@@ -149,6 +149,88 @@ def _check_pipeline_coherence(sm: "SourceMap") -> list[str]:  # type: ignore[nam
 
     return issues
 
+# ---------------------------------------------------------------------------
+# Command tiers — what we promise about a command, published where it is read
+# ---------------------------------------------------------------------------
+
+#: The support commitment behind every command — one authority for it, read by
+#: `--help`, by the README command table and by the user guide.
+#:
+#: A tier is a **stability** promise, never a value ranking. `posture` is the most
+#: differentiated capability in the product *and* it is experimental: its shape can
+#: still change under a minor, so nobody should gate a pipeline on it yet. Those are
+#: two facts, and collapsing them onto one axis is how a surface starts lying — the
+#: first panel of `--help` still says "start here" for the commands worth learning
+#: first, and this table says what each command's output is worth relying on.
+#:
+#: This is not the pricing tier: Free/Pro is a separate axis (docs/PRODUCT_TIERS.md)
+#: and gates repository size, never capability.
+#:
+#: Assigning the tiers is a later milestone's work (commands moving between them,
+#: `parked` disappearing from the default help). Naming them is what ships here, so
+#: the vocabulary exists before it is used against a command.
+COMMAND_TIERS: "tuple[tuple[str, str, tuple[str, ...]], ...]" = (
+    ("core", "contract stable within a major — safe to gate CI on", (
+        "endpoints", "spring-audit", "migrate-check",
+        "impact", "impact-chain", "pr-impact", "verify",
+    )),
+    ("supported", "maintained; fields are added, never removed without a major", (
+        "verify-edit", "review-pr", "plan", "compare", "delta", "contract-diff",
+        "fix-bug", "rename-class", "prepare-context", "onboard", "explain",
+        "export", "repo-ir", "validation", "modernize", "chunk-file",
+        "cold-start", "baseline", "activate", "config", "schema", "version",
+        "cache", "auth", "mcp", "telemetry",
+    )),
+    ("experimental", "shape may change in a minor — do not gate CI on it", (
+        "posture", "archetype", "retrieve",
+    )),
+    ("parked", "kept working, no longer developed", ()),
+)
+
+#: Tiers whose membership is short enough to name in `--help`. `supported` is the
+#: remainder by construction, and printing twenty-six names would bury the two lists
+#: a reader acts on.
+_TIERS_NAMED_IN_HELP = ("core", "experimental", "parked")
+
+
+def command_tier(name: str) -> "str | None":
+    """The tier of a registered command, or None when it is in no tier.
+
+    None is a defect, not a state: the battery fails on it. It is returned rather
+    than defaulted so an unassigned command can never be silently published as
+    `supported`.
+    """
+    for tier, _promise, members in COMMAND_TIERS:
+        if name in members:
+            return tier
+    return None
+
+
+def _tier_help_block() -> str:
+    """The tier table as `--help` prints it — generated from `COMMAND_TIERS`, because
+    a hand-written catalogue beside a generated one drifts (it is what left
+    `endpoints` unlisted while it shipped)."""
+    import textwrap
+
+    lines = ["[bold]Command tiers[/bold] [dim](a stability promise, not a value ranking):[/dim]"]
+    indent = " " * 4
+    for tier, promise, members in COMMAND_TIERS:
+        if tier not in _TIERS_NAMED_IN_HELP:
+            listed = "every other command in the panels below"
+        elif members:
+            listed = " · ".join(members)
+        else:
+            listed = "none today"
+        lines.append(f"  [bold]{tier:<14}[/bold]{promise}")
+        # Pre-wrapped so the renderer never breaks a command name at its hyphen.
+        wrapped = textwrap.fill(
+            listed, width=70, initial_indent=indent, subsequent_indent=indent,
+            break_on_hyphens=False, break_long_words=False,
+        )
+        lines.append(f"[dim]{wrapped}[/dim]")
+    return "\n".join(lines)
+
+
 def _build_help_text() -> str:
     """Build --help text dynamically based on current license state."""
     try:
@@ -193,6 +275,8 @@ of files) in minutes. Semantic analysis itself is sub-second; repo indexing domi
 
 [dim]Every command is grouped in the panels below; full reference in docs/USER_GUIDE.md[/dim]
 
+{_tier_help_block()}
+
 [bold]Auth commands:[/bold]
   auth status                  [dim]# show current plan and auth state[/dim]
   auth logout                  [dim]# remove local credentials[/dim]
@@ -829,7 +913,7 @@ try:
 except Exception:
     pass
 
-telemetry_app = typer.Typer(help="Manage anonymous telemetry (on by default; opt-out).", rich_markup_mode="rich")
+telemetry_app = typer.Typer(help="Manage anonymous telemetry (off by default; opt-in).", rich_markup_mode="rich")
 app.add_typer(telemetry_app, name="telemetry")
 
 mcp_app = typer.Typer(help="MCP integration: setup, status, serve, remove.", rich_markup_mode="rich")
@@ -857,8 +941,9 @@ app.add_typer(retrieve_app, name="retrieve")
 def _maybe_show_telemetry_notice() -> None:
     """Show first-run telemetry notice once, on interactive TTYs only.
 
-    Telemetry is on by default (opt-out). We inform rather than ask, then
-    mark the notice as shown so it appears only once.
+    Telemetry is off by default (opt-in). The notice is an invitation, not a
+    disclosure: nothing has been collected when it appears. Marked as shown so it
+    appears only once.
     """
     try:
         from sourcecode.telemetry.config import has_been_asked, mark_asked
@@ -1699,12 +1784,21 @@ def main(
                 f"ex={_excl_key},depth={effective_depth}"
             )
             _core_h = _hashlib.sha256(_core_flags_str.encode()).hexdigest()[:8]
-            if _git_sha and _git_root_str:
-                _core_key = f"{_git_sha}-{_core_h}"
+            # Freshness comes from ONE authority (cache.worktree_signature): the exact
+            # tree state an analysis would read, not the committed HEAD. Keyed on HEAD,
+            # this cache answered for a tree it had not read — an uncommitted pom.xml
+            # gaining a dependency was served the pre-edit analysis with is_stale:false.
+            # Clean tree → the sha, so the ordinary repeat run still hits.
+            _tree_sig = _cache_mod.worktree_signature(
+                Path(_git_root_str) if _git_root_str else target,
+                scope=target,
+            )
+            if _tree_sig:
+                _core_key = f"{_tree_sig}-{_core_h}"
             else:
-                # No git history (untracked/no-commit repo) — stable synthetic key
-                # scoped per repo path via cache_dir(); invalidated by --no-cache or cache clear.
-                _core_key = f"nogit-{_core_h}"
+                # The tree cannot be described (no git, unreadable) — a stable synthetic
+                # key would answer forever from the first run, so skip the cache instead.
+                _core_key = ""
 
             # ── View flags: output presentation only (no re-analysis needed) ──
             _view_flags_str = (
@@ -1719,7 +1813,7 @@ def main(
 
             # ── Lookup ──────────────────────────────────────────────────────
             # Step 1: try L1 to obtain the core_hash needed for L2 key
-            _l1_result = _cache_mod.read_core(target, _core_key)
+            _l1_result = _cache_mod.read_core(target, _core_key) if _core_key else None
 
             # Additive overlays (--env-map / --git-context) miss L1 because they sit in
             # the core key, yet neither changes the semantic core — env walks config
@@ -1735,8 +1829,8 @@ def main(
             # we inject exactly the overlays we flipped to land the hit.
             _l1_needs_env_inject = False
             _l1_needs_git_inject = False
-            if _l1_result is None and (env_map or git_context):
-                _sha_prefix = _git_sha if _git_sha else "nogit"
+            if _l1_result is None and _core_key and (env_map or git_context):
+                _sha_prefix = _tree_sig
                 _flippable = []
                 if git_context:
                     _flippable.append("gc")   # inject git is cheap + additive
@@ -3292,10 +3386,11 @@ def prepare_context_cmd(
     from dataclasses import asdict
     import time as _time
 
-    # Task-level cache: keyed on (task, git_head, symptom) so warm calls complete in <1s.
+    # Task-level cache: keyed on (task, tree state, symptom) so warm calls complete in <1s.
+    # The tree state comes from the same authority as every other layer, so an
+    # uncommitted edit invalidates here exactly as it does for the root command.
     # Skip for diff-dependent tasks (delta, review-pr), fast mode, and llm_prompt
     # (those embed per-call content that must not be served from cache).
-    import subprocess as _pctx_sub
     import hashlib as _pctx_hash
     from sourcecode import cache as _pctx_cache
     _pctx_git_sha = ""
@@ -3303,15 +3398,19 @@ def prepare_context_cmd(
     _pctx_cacheable = task not in ("delta", "review-pr") and not fast and not llm_prompt
     if _pctx_cacheable:
         try:
-            _sha_r2 = _pctx_sub.run(
-                ["git", "-C", str(target), "rev-parse", "--short", "HEAD"],
-                capture_output=True, text=True, timeout=3,
+            _pctx_git_sha = _pctx_cache.worktree_signature(
+                _resolve_repo_root(target), scope=target
             )
-            _pctx_git_sha = _sha_r2.stdout.strip()
         except Exception:
             pass
         if _pctx_git_sha:
-            _sym_h = _pctx_hash.sha256((symptom or "").encode()).hexdigest()[:8]
+            # Every option that changes the answer belongs in the key. --all and
+            # --include-config did not, and went unnoticed only because the key
+            # required a git sha: in a non-git tree nothing was cached at all, so
+            # the collision could not surface.
+            _sym_h = _pctx_hash.sha256(
+                f"sym={symptom or ''};all={all_gaps};cfg={include_config}".encode()
+            ).hexdigest()[:8]
             _pctx_cache_key = f"pctx-{task}-{_pctx_git_sha}-{_sym_h}-{format or 'json'}"
             _cached_pctx = _pctx_cache.read(target, _pctx_cache_key)
             if _cached_pctx is not None:
@@ -3743,16 +3842,22 @@ def prepare_context_cmd(
 @telemetry_app.command("status")
 def telemetry_status() -> None:
     """Show current telemetry setting."""
-    from sourcecode.telemetry.config import config_file_path, has_been_asked, is_enabled
+    from sourcecode.telemetry.config import config_file_path, is_enabled, stored_choice
     enabled = is_enabled()
-    asked = has_been_asked()
+    choice = stored_choice()
     status = "enabled" if enabled else "disabled"
-    typer.echo(f"Telemetry: {status} (on by default; opt-out)")
-    if not asked:
-        typer.echo("  (first-run notice not yet shown — will show on next run)")
+    typer.echo(f"Telemetry: {status} (off by default; opt-in)")
+    # "off because you said so" and "off because nobody asked you" are different
+    # answers, and a buyer auditing this needs to be told which one they have.
+    if choice is None:
+        typer.echo("  No choice recorded — nothing has been collected or sent.")
+    else:
+        typer.echo(f"  Your recorded choice: {'enabled' if choice else 'disabled'}.")
     typer.echo(f"  Config: {config_file_path()}")
-    typer.echo("  Disable: ask telemetry disable")
-    typer.echo("  Or set env var: SOURCECODE_TELEMETRY=0  (or DO_NOT_TRACK=1)")
+    if enabled:
+        typer.echo("  Disable: ask telemetry disable  (or SOURCECODE_TELEMETRY=0, DO_NOT_TRACK=1)")
+    else:
+        typer.echo("  Enable:  ask telemetry enable   (or SOURCECODE_TELEMETRY=1)")
 
 
 @telemetry_app.command("enable")
@@ -3774,7 +3879,7 @@ def telemetry_disable() -> None:
     from sourcecode.telemetry.config import set_enabled
     set_enabled(False)
     typer.echo("Telemetry disabled. No data will be collected or sent.")
-    typer.echo("Telemetry is on by default; this opt-out is remembered.")
+    typer.echo("Telemetry is off by default; this choice is recorded so the notice stops asking.")
     typer.echo("Re-enable at any time: ask telemetry enable")
 
 
@@ -8172,7 +8277,7 @@ def config_cmd() -> None:
     from sourcecode.telemetry.config import config_file_path, is_enabled
     typer.echo(f"ask {__version__}")
     typer.echo(f"Config:    {config_file_path()}")
-    typer.echo(f"Telemetry: {'enabled' if is_enabled() else 'disabled'}")
+    typer.echo(f"Telemetry: {'enabled' if is_enabled() else 'disabled'} (off by default; opt-in)")
     typer.echo("")
     typer.echo("Manage telemetry:")
     typer.echo("  ask telemetry enable")
@@ -9300,17 +9405,32 @@ def cache_warm_cmd(
 ) -> None:
     """Pre-populate the cache by running a fresh analysis.
 
-    Runs a full analysis to populate L1/L2 caches and rebuild the RIS
-    (Repository Intelligence Snapshot). Useful after a merge/pull in CI.
+    Runs a full analysis to populate the snapshot cache, rebuild the RIS and build
+    the shared Canonical IR. Useful after a merge/pull in CI.
+
+    \b
+    It is not a general warm, and it says so when it finishes: it warms the
+    compact view (add --agent for the agent view), and analysis flags that change
+    what is analysed — --env-map, --depth N, --exclude — rescan anyway. Run
+    `ask cache model` for what a warm gives each command.
+
+    \b
+    In CI without a persisted cache directory, every pipeline pays the cold cost
+    this command reports. Cache ~/.sourcecode/cache and ~/.sourcecode between jobs,
+    or budget the cold run explicitly.
     """
     import shutil as _shutil
     import subprocess as _sub
+    import time as _warm_time
     # Warm exactly the path given. Resolving up to the enclosing git root warmed
     # (and reported on) the whole monorepo when asked for one module — every other
     # command scopes to the argument, so `cache warm ./service-a` populated a cache
     # for a different target than `ask ./service-a` reads.
     target = Path(path).resolve()
     _git_root = _resolve_repo_root(Path(path))
+    # Cost is reported for the whole warm, the CIR build included — that is what a
+    # pipeline pays, and quoting only the analysis half would understate it (C4-5).
+    _warm_t0 = _warm_time.monotonic()
     typer.echo(f"Warming cache for {target} …", err=True)
     if _git_root != target:
         typer.echo(
@@ -9345,6 +9465,58 @@ def cache_warm_cmd(
             err=True,
         )
 
+    # A warm that reports only what it built lets the reader assume it built
+    # everything — which is how "el warm no es un warm general" became a field
+    # finding (C4-3) rather than a documented limit. State both halves, and state
+    # the cost, because in CI it is paid per pipeline (C4-5).
+    _warm_elapsed = _warm_time.monotonic() - _warm_t0
+    _warmed_view = "compact + agent views" if (compact and agent) else (
+        "agent view" if agent else "compact view"
+    )
+    typer.echo(
+        f"Warmed in {_warm_elapsed:.0f}s: {_warmed_view}, RIS, shared CIR, parse cache.",
+        err=True,
+    )
+    typer.echo(
+        "NOT warmed: prepare-context task answers (refactor / fix-bug / generate-tests / "
+        "delta / review-pr), and any run whose analysis flags differ (--env-map, --depth N, "
+        "--exclude) — those rescan. Measured: `endpoints` and `migrate-check` gain nothing "
+        "from a warm. `ask cache model` says what a warm gives each command.",
+        err=True,
+    )
+    typer.echo(
+        f"In CI without a persisted ~/.sourcecode, every pipeline pays this {_warm_elapsed:.0f}s again.",
+        err=True,
+    )
+
+
+@cache_app.command("model")
+def cache_model_cmd(
+    json_output: bool = typer.Option(False, "--json", help="Output as JSON."),
+    markdown: bool = typer.Option(False, "--markdown", help="Output the tables published in the user guide."),
+) -> None:
+    """What each cache layer stores, what invalidates it, and what a warm helps.
+
+    \b
+    Answers, per command, the question a warm raises: will this be fast next time?
+      the answer      — a warm stores what this command returns
+      the shared work — a warm removes the Java parse / the shared IR; the command
+                        still computes its own answer
+      nothing         — a warm does not touch it
+
+    One rule covers invalidation: every layer keys on the exact tree state, so any
+    change to the analysed files invalidates it, committed or not.
+    """
+    from sourcecode import cache_model as _cmodel
+
+    if json_output:
+        import json as _j
+        typer.echo(_j.dumps(_cmodel.as_dict(), indent=2, ensure_ascii=False))
+    elif markdown:
+        typer.echo(_cmodel.render_markdown())
+    else:
+        typer.echo(_cmodel.render_text())
+
 
 @cache_app.command("freshness")
 def cache_freshness_cmd(

sourcecode/context_cache.py

@@ -190,34 +190,14 @@ def _git_head(repo_root: Path) -> str:
 def _worktree_signature(repo_root: Path) -> str:
     """Deterministic fingerprint of the *exact* tree state.
 
-    committed HEAD, plus — only when the tree is dirty — a hash of the porcelain
-    status and the diff against HEAD. Two identical tree states yield the same
-    signature (correct reuse); any tracked edit changes it (correct invalidation).
-    Returns ``""`` when the path is not a git repo (caller disables caching).
+    Thin alias of the one authority, :func:`sourcecode.cache.worktree_signature`.
+    It used to be a second implementation living here, which is how the two caches
+    ended up invalidating on different facts: this one on the tree, the snapshot
+    cache on the committed HEAD alone.
     """
-    head = _git_head(repo_root)
-    if not head:
-        return ""
-    try:
-        status = subprocess.run(
-            ["git", "-C", str(repo_root), "status", "--porcelain"],
-            capture_output=True, text=True, timeout=5,
-        )
-        porcelain = status.stdout if status.returncode == 0 else ""
-    except Exception:
-        porcelain = ""
-    if not porcelain.strip():
-        return head  # clean tree — HEAD fully describes it
-    try:
-        diff = subprocess.run(
-            ["git", "-C", str(repo_root), "diff", "HEAD"],
-            capture_output=True, text=True, timeout=10,
-        )
-        diff_txt = diff.stdout if diff.returncode == 0 else ""
-    except Exception:
-        diff_txt = ""
-    dirty = hashlib.sha256((porcelain + "\x00" + diff_txt).encode("utf-8", "replace")).hexdigest()[:16]
-    return f"{head}+dirty:{dirty}"
+    from sourcecode.cache import worktree_signature
+
+    return worktree_signature(repo_root)
 
 
 def _options_fingerprint(options: Optional[dict[str, Any]]) -> str:

sourcecode/license.py

@@ -396,7 +396,7 @@ _init()
 # ---------------------------------------------------------------------------
 
 def _emit_telemetry(event: str, **kw: object) -> None:
-    """Best-effort telemetry emit. Respects the user's opt-out; never raises or blocks."""
+    """Best-effort telemetry emit. Sends nothing unless the user opted in; never raises or blocks."""
     try:
         from sourcecode import telemetry as _tel
         _tel.record(event, **kw)  # type: ignore[arg-type]

sourcecode/mcp/server.py

@@ -33,8 +33,8 @@ def _record_tool_invocation(name: Any, success: bool, started: float) -> None:
 
     Aggregate only: which of our own tools ran, whether it succeeded, and a
     duration bucket. Never the arguments — those carry repository paths — and
-    never any result content. Honours the same opt-out as every other event
-    (`ask telemetry disable`, SOURCECODE_TELEMETRY=0, DO_NOT_TRACK=1); when
+    never any result content. Honours the same opt-in as every other event
+    (off until `ask telemetry enable` or SOURCECODE_TELEMETRY=1); when
     telemetry is off, `record` returns before building anything.
     """
     try:

sourcecode/prepare_context.py

@@ -1090,20 +1090,20 @@ class TaskContextBuilder:
     def _try_ris_fast_path(self, task_name: str, spec: "TaskSpec") -> Optional[TaskOutput]:
         """Return TaskOutput from a warm RIS without running the full scan.
 
-        Only activated for onboard/explain when git HEAD matches stored RIS.
+        Only activated for onboard/explain when the stored RIS describes the tree
+        on disk — the same freshness authority every cache layer keys on, not the
+        committed HEAD (which served this fast path through uncommitted edits).
         Falls through (returns None) on any error or cache miss.
         """
         try:
-            import subprocess as _sp
             from sourcecode.ris import load_ris as _lris
+            from sourcecode.ris import _tree_signature as _ris_sig
             _ris = _lris(self.root)
             if _ris is None or not _ris.compact_summary:
                 return None
-            _r = _sp.run(
-                ["git", "-C", str(self.root), "rev-parse", "--short", "HEAD"],
-                capture_output=True, text=True, timeout=2,
-            )
-            if _r.returncode != 0 or _r.stdout.strip() != _ris.git_head:
+            _stored_sig = (_ris.metadata or {}).get("tree_signature") or ""
+            _current_sig = _ris_sig(self.root)
+            if not _stored_sig or not _current_sig or _stored_sig != _current_sig:
                 return None
 
             compact = _ris.compact_summary

sourcecode/ris.py

@@ -258,6 +258,7 @@ def _build_from_core(
                 1.0 if agent_data else (0.5 if compact_data else 0.0)
             ),
             "partial": not bool(agent_data),
+            "tree_signature": _tree_signature(repo_root),
         },
     )
 
@@ -295,6 +296,7 @@ def maybe_update_ris(repo_root: Path, core_dict: dict, git_head: str) -> None:
                     "snapshot_source": "existing_snapshot_system",
                     "confidence": float(1.0 if agent_data else (0.5 if compact_data else 0.0)),
                     "partial": not bool(agent_data),
+                    "tree_signature": _tree_signature(repo_root),
                 },
             )
             save_ris(repo_root, updated)
@@ -433,6 +435,21 @@ def _current_git_head(repo_root: Path) -> str:
     return ""
 
 
+def _tree_signature(repo_root: Path) -> str:
+    """Tree state this snapshot describes — the one freshness authority.
+
+    Stored in ``metadata["tree_signature"]`` at write time so staleness compares
+    the tree the RIS was built from against the tree on disk now. HEAD alone
+    called a snapshot fresh while uncommitted edits made it describe nothing.
+    """
+    try:
+        from sourcecode.cache import worktree_signature
+
+        return worktree_signature(repo_root)
+    except Exception:
+        return ""
+
+
 def _has_uncommitted_changes(repo_root: Path) -> bool:
     """Return True if working tree has staged or unstaged changes to tracked files.
 
@@ -465,8 +482,17 @@ def get_cold_start_context(repo_root: Path) -> dict:
             return {"status": "no_ris"}
 
         current_head = _current_git_head(repo_root)
-        stale = bool(current_head and ris.git_head and current_head != ris.git_head)
         uncommitted = _has_uncommitted_changes(repo_root)
+        # Staleness is about the tree the snapshot describes, not the commit it was
+        # taken at: with HEAD alone a snapshot stayed `stale: false` through every
+        # uncommitted edit. Snapshots written before the signature existed fall back
+        # to the pair of facts that were available then.
+        _stored_sig = (ris.metadata or {}).get("tree_signature") or ""
+        _current_sig = _tree_signature(repo_root)
+        if _stored_sig and _current_sig:
+            stale = _stored_sig != _current_sig
+        else:
+            stale = bool(current_head and ris.git_head and current_head != ris.git_head) or uncommitted
 
         endpoints = ris.api_surface.get("endpoints", [])
         _is_java = (

sourcecode/telemetry/__init__.py

@@ -1,12 +1,13 @@
-"""sourcecode telemetry — anonymous usage metrics, on by default (opt-out).
+"""sourcecode telemetry — anonymous usage metrics, off until you turn them on (opt-in).
 
 Public API:
     is_enabled()          → bool
     record(event, **kw)   → None  (fire-and-forget)
     session_id()          → str   (ephemeral 8-char hex, new each process)
 
-Telemetry is enabled by default and stays anonymous. It can be disabled at any
-time via `sourcecode telemetry disable`, SOURCECODE_TELEMETRY=0, or DO_NOT_TRACK=1.
+Telemetry is opt-in and stays anonymous: nothing is collected until `ask telemetry
+enable` (or SOURCECODE_TELEMETRY=1). It was opt-out until 3.3.0 — see config.py for
+why the default moved.
 
 Nothing sensitive (code, paths, secrets, output) is ever collected.
 See docs/privacy.md for full details.

sourcecode/telemetry/config.py

@@ -1,11 +1,17 @@
 """Persistent telemetry configuration.
 
-Telemetry is enabled by default (opt-out). It stays anonymous and never
-collects source code, paths, secrets or repository content.
+Telemetry is **off until the user turns it on** (opt-in). It stays anonymous and
+never collects source code, paths, secrets or repository content.
+
+It was opt-out until 3.3.0. Field evaluation #3 was the first audit of regulated
+third-party code — public-sector health data — and there the default is not a
+preference but a procurement blocker: the reviewer had to disable telemetry
+*before the first run*, which the product gave them no way to do. Nothing is
+collected before an explicit choice, so there is nothing to disable in time.
 
 Config file: ~/.config/sourcecode/config.json
-Disable: `sourcecode telemetry disable`, SOURCECODE_TELEMETRY=0, or DO_NOT_TRACK=1
-Env override: SOURCECODE_TELEMETRY=0 (disable) or =1 (enable)
+Enable: `ask telemetry enable` or SOURCECODE_TELEMETRY=1
+Env override: SOURCECODE_TELEMETRY=1 (enable) or =0 (disable); DO_NOT_TRACK=1 disables
 """
 
 from __future__ import annotations
@@ -18,18 +24,6 @@ from typing import Any
 _ENV_VAR = "SOURCECODE_TELEMETRY"
 _CONFIG_FILE = Path.home() / ".config" / "sourcecode" / "config.json"
 
-# CI markers — when no explicit choice has been made, telemetry defaults OFF
-# in CI (no human to see the first-run notice), ON otherwise.
-_CI_VARS = (
-    "CI", "CONTINUOUS_INTEGRATION", "GITHUB_ACTIONS", "CIRCLECI",
-    "TRAVIS", "JENKINS_URL", "BUILDKITE", "GITLAB_CI", "TF_BUILD",
-    "TEAMCITY_VERSION", "DRONE", "SEMAPHORE",
-)
-
-
-def _in_ci() -> bool:
-    return any(os.environ.get(v) for v in _CI_VARS)
-
 
 def _load() -> dict[str, Any]:
     try:
@@ -46,14 +40,29 @@ def _save(data: dict[str, Any]) -> None:
         pass  # config write failure is non-fatal
 
 
+def stored_choice() -> "bool | None":
+    """The explicit choice on record, or None when the user has made none.
+
+    `None` is a state, not a synonym for `False`: "off because nobody has been
+    asked yet" and "off because you turned it off" are different answers, and
+    `telemetry status` prints them differently.
+    """
+    stored = _load().get("telemetry", {}).get("enabled")
+    return None if stored is None else bool(stored)
+
+
 def is_enabled() -> bool:
-    """True unless telemetry has been explicitly disabled.
+    """True only when telemetry has been explicitly turned on.
 
-    Telemetry is enabled by default (opt-out). Precedence, highest first:
+    Telemetry is **opt-in**: no choice on record means off, everywhere, CI or
+    not. Precedence, highest first:
       1. SOURCECODE_TELEMETRY env var (0 = off, 1 = on)
       2. DO_NOT_TRACK env var (any value other than ""/"0" turns it off)
       3. config file 'enabled' flag, if the user has made an explicit choice
-      4. default: True — except in CI, where it defaults to False
+      4. default: False
+
+    There is no CI special case any more, because there is nothing left for it
+    to protect against — the default it used to override is now off.
     """
     env = os.environ.get(_ENV_VAR, "").strip()
     if env == "0":
@@ -63,11 +72,10 @@ def is_enabled() -> bool:
     dnt = os.environ.get("DO_NOT_TRACK", "").strip()
     if dnt not in ("", "0"):
         return False
-    stored = _load().get("telemetry", {}).get("enabled")
+    stored = stored_choice()
     if stored is not None:
-        return bool(stored)
-    # No explicit choice yet: on by default, off under CI.
-    return not _in_ci()
+        return stored
+    return False
 
 
 def has_been_asked() -> bool: