fix(telemetry): honor telemetry.enabled in global config

[FasterPHP]

Summary

• add telemetry.enabled to the validated global config surface
• honor telemetry.enabled=false in telemetry and update-check gates
• preserve OPENSPEC_TELEMETRY, DO_NOT_TRACK, and CI as higher-priority overrides
• preserve anonymousId and noticeSeen during config updates
• document precedence and the default-on opt-out model

Background

The CLI docs have advertised openspec config set telemetry.enabled false, but runtime rejects telemetry as an unknown top-level key. Related reports #895 and #754 also show that a persistent opt-out was expected but remained unimplemented.

A persisted setting is particularly useful where shell environment variables may not propagate to indirect CLI invocations, such as IDE integrations. That environment distinction is plausible but has not been tested or confirmed.

Closes #1512

Test plan

• pnpm test (3,572 tests across 122 files)
• pnpm run build
• focused telemetry/config/version-check tests (242 tests across 6 files)
• isolated XDG_CONFIG_HOME CLI set/get/unset round-trip

AI assistance

Generated with Augment Agent using GPT-5.6 by OpenAI; reviewed by a GPT-5.6 Sol validation subagent.

Summary by CodeRabbit

• New Features

  • Added global configuration support for enabling or disabling anonymous telemetry.
  • Added openspec config set telemetry.enabled false as a telemetry opt-out option.
  • Disabled telemetry also suppresses update checks, notices, and network activity.
  • Environment and CI opt-out settings continue to take precedence.

• Documentation

  • Updated README and CLI documentation with telemetry defaults, opt-out methods, and precedence details.

• Tests

  • Added coverage for configuration, validation, CI detection, precedence, and update-check behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 2d1c358b-3eef-4996-861f-48dbe9fa490d

📥 Commits

Reviewing files that changed from the base of the PR and between 3ae4c48 and b776e34.

📒 Files selected for processing (3)

• .changeset/telemetry-enabled-config.md
• docs/cli.md
• test/telemetry/index.test.ts

🚧 Files skipped from review as they are similar to previous changes (3)

• .changeset/telemetry-enabled-config.md
• test/telemetry/index.test.ts
• docs/cli.md

---

📝 Walkthrough

Walkthrough

Changes

The PR adds global telemetry.enabled configuration. It preserves telemetry identity fields, applies environment and CI precedence, suppresses update checks, adds shared CI detection, and updates tests and documentation.

Telemetry configuration and opt-out flow

Layer / File(s)	Summary
Telemetry configuration contract src/core/global-config.ts, src/core/config-schema.ts, src/telemetry/config.ts, test/core/config-schema.test.ts, test/commands/config.test.ts, test/telemetry/config.test.ts	The global schema accepts telemetry.enabled, preserves telemetry fields, and restricts CLI updates to the supported nested key.
Telemetry runtime gating src/utils/ci.ts, src/telemetry/index.ts, test/utils/ci.test.ts, test/telemetry/index.test.ts	Telemetry uses shared CI detection and global configuration. Environment variables and CI continue to override configuration.
Update-check suppression src/core/version-check.ts, test/core/version-check.test.ts	Global telemetry disablement now suppresses registry update checks.
Documentation and release notes README.md, docs/cli.md, .changeset/telemetry-enabled-config.md	Documentation describes the configuration command, default behavior, precedence, and update-check effects.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI as OpenSpec CLI
  participant Telemetry as telemetry/index.ts
  participant Config as global configuration
  participant Network as telemetry endpoint
  CLI->>Telemetry: evaluate telemetry status
  Telemetry->>Config: read telemetry.enabled
  Telemetry->>Network: send telemetry when enabled

Loading

Possibly related PRs

• Fission-AI/OpenSpec#1470: Both changes modify update-check opt-out logic and its tests.

Suggested reviewers: clay-good

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main change: honoring telemetry.enabled in the global configuration.
Linked Issues check	✅ Passed	The changes implement persistent telemetry.enabled support, preserve precedence and runtime fields, suppress update checks, and document the behavior for issue #1512.
Out of Scope Changes check	✅ Passed	The code, documentation, shared CI helper, and tests directly support issue #1512; no project-local or opt-in-default changes are included.
Docstring Coverage	✅ Passed	Docstring coverage is 83.33% which is sufficient. The required threshold is 80.00%.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.changeset/telemetry-enabled-config.md:
- Line 5: Update the changeset text to document that telemetry.enabled=false
disables anonymous telemetry and openspec update version checks, while an unset
value leaves telemetry enabled; also state that environment and CI opt-outs take
precedence.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 80d5e7eb-9fa1-4ef3-83d2-dbc3590f5d1c

📥 Commits

Reviewing files that changed from the base of the PR and between 59bfb27 and 3ae4c48.

📒 Files selected for processing (15)

• .changeset/telemetry-enabled-config.md
• README.md
• docs/cli.md
• src/core/config-schema.ts
• src/core/global-config.ts
• src/core/version-check.ts
• src/telemetry/config.ts
• src/telemetry/index.ts
• src/utils/ci.ts
• test/commands/config.test.ts
• test/core/config-schema.test.ts
• test/core/version-check.test.ts
• test/telemetry/config.test.ts
• test/telemetry/index.test.ts
• test/utils/ci.test.ts

[alfred-openspec]

Approved at exact head b776e34. The documented config opt-out now works end to end, preserves telemetry identity fields, and keeps environment/CI privacy signals authoritative; a fresh install/build/lint, all 242 focused tests, the full 3,806-test suite, and a real CLI round-trip pass.

[FasterPHP]

@clay-good Would you be able to provide the second approval for this PR please?