sauron-cli 1.1.3 → 1.3.0

package/OpenSpec-main/openspec/specs/schema-resolution/spec.md

@@ -0,0 +1,201 @@
+# schema-resolution Specification
+
+## Purpose
+Define project-local schema resolution behavior, including precedence order (project-local, then user override, then package built-in) and backward-compatible fallback when `projectRoot` is not provided.
+## Requirements
+### Requirement: Project-local schema resolution
+
+The system SHALL resolve schemas from the project-local directory (`./openspec/schemas/<name>/`) with highest priority when a `projectRoot` is provided.
+
+#### Scenario: Project-local schema takes precedence over user override
+- **WHEN** a schema named "my-workflow" exists at `./openspec/schemas/my-workflow/schema.yaml`
+- **AND** a schema named "my-workflow" exists at `~/.local/share/openspec/schemas/my-workflow/schema.yaml`
+- **AND** `getSchemaDir("my-workflow", projectRoot)` is called
+- **THEN** the system SHALL return the project-local path
+
+#### Scenario: Project-local schema takes precedence over package built-in
+- **WHEN** a schema named "spec-driven" exists at `./openspec/schemas/spec-driven/schema.yaml`
+- **AND** "spec-driven" is a package built-in schema
+- **AND** `getSchemaDir("spec-driven", projectRoot)` is called
+- **THEN** the system SHALL return the project-local path
+
+#### Scenario: Falls back to user override when no project-local schema
+- **WHEN** no schema named "my-workflow" exists at `./openspec/schemas/my-workflow/`
+- **AND** a schema named "my-workflow" exists at `~/.local/share/openspec/schemas/my-workflow/schema.yaml`
+- **AND** `getSchemaDir("my-workflow", projectRoot)` is called
+- **THEN** the system SHALL return the user override path
+
+#### Scenario: Falls back to package built-in when no project-local or user schema
+- **WHEN** no schema named "spec-driven" exists at `./openspec/schemas/spec-driven/`
+- **AND** no schema named "spec-driven" exists at `~/.local/share/openspec/schemas/spec-driven/`
+- **AND** "spec-driven" is a package built-in schema
+- **AND** `getSchemaDir("spec-driven", projectRoot)` is called
+- **THEN** the system SHALL return the package built-in path
+
+#### Scenario: Backward compatibility when projectRoot not provided
+- **WHEN** `getSchemaDir("my-workflow")` is called without a `projectRoot` parameter
+- **THEN** the system SHALL only check user override and package built-in locations
+- **AND** the system SHALL NOT check project-local location
+
+### Requirement: Project schemas directory helper
+
+The system SHALL provide a `getProjectSchemasDir(projectRoot)` function that returns the project-local schemas directory path.
+
+#### Scenario: Returns correct path
+- **WHEN** `getProjectSchemasDir("/path/to/project")` is called
+- **THEN** the system SHALL return `/path/to/project/openspec/schemas`
+
+### Requirement: List schemas includes project-local
+
+The system SHALL include project-local schemas when listing available schemas if `projectRoot` is provided.
+
+#### Scenario: Project-local schemas appear in list
+- **WHEN** a schema named "team-flow" exists at `./openspec/schemas/team-flow/schema.yaml`
+- **AND** `listSchemas(projectRoot)` is called
+- **THEN** the returned list SHALL include "team-flow"
+
+#### Scenario: Project-local schema shadows same-named user schema in list
+- **WHEN** a schema named "custom" exists at both project-local and user override locations
+- **AND** `listSchemas(projectRoot)` is called
+- **THEN** the returned list SHALL include "custom" exactly once
+
+#### Scenario: Backward compatibility for listSchemas
+- **WHEN** `listSchemas()` is called without a `projectRoot` parameter
+- **THEN** the system SHALL only include user override and package built-in schemas
+
+### Requirement: Schema info includes project source
+
+The system SHALL indicate `source: 'project'` for project-local schemas in `listSchemasWithInfo()` results.
+
+#### Scenario: Project-local schema shows project source
+- **WHEN** a schema named "team-flow" exists at `./openspec/schemas/team-flow/schema.yaml`
+- **AND** `listSchemasWithInfo(projectRoot)` is called
+- **THEN** the schema info for "team-flow" SHALL have `source: 'project'`
+
+#### Scenario: User override schema shows user source
+- **WHEN** a schema named "my-custom" exists only at `~/.local/share/openspec/schemas/my-custom/`
+- **AND** `listSchemasWithInfo(projectRoot)` is called
+- **THEN** the schema info for "my-custom" SHALL have `source: 'user'`
+
+#### Scenario: Package built-in schema shows package source
+- **WHEN** "spec-driven" exists only as a package built-in
+- **AND** `listSchemasWithInfo(projectRoot)` is called
+- **THEN** the schema info for "spec-driven" SHALL have `source: 'package'`
+
+### Requirement: Schemas command shows source
+
+The `openspec schemas` command SHALL display the source of each schema.
+
+#### Scenario: Display format includes source
+- **WHEN** user runs `openspec schemas`
+- **THEN** the output SHALL show each schema with its source label (project, user, or package)
+
+### Requirement: Use config schema as default for new changes
+
+The system SHALL use the schema field from `openspec/config.yaml` as the default when creating new changes without explicit `--schema` flag and no planning-home default applies.
+
+#### Scenario: Create change without --schema flag and config exists
+- **WHEN** user runs `openspec new change foo`, no planning-home default applies, and config contains `schema: "tdd"`
+- **THEN** system creates change with schema "tdd"
+
+#### Scenario: Create change without --schema flag and no config
+- **WHEN** user runs `openspec new change foo`, no planning-home default applies, and no config file exists
+- **THEN** system creates change with default schema "spec-driven"
+
+#### Scenario: Create change with explicit --schema flag
+- **WHEN** user runs `openspec new change foo --schema custom` and config contains `schema: "tdd"`
+- **THEN** system creates change with schema "custom" (CLI flag overrides config)
+
+### Requirement: Resolve schema with updated precedence order
+
+The system SHALL resolve the schema for a change using the following precedence order: CLI flag, change metadata, planning-home default, project config, hardcoded default.
+
+#### Scenario: CLI flag is provided
+- **WHEN** user runs command with `--schema custom`
+- **THEN** system uses "custom" regardless of change metadata or config
+
+#### Scenario: Change metadata specifies schema
+- **WHEN** change has `.openspec.yaml` with `schema: bound` and config has `schema: tdd`
+- **THEN** system uses "bound" from change metadata
+
+#### Scenario: Planning home default overrides project config
+- **WHEN** no CLI flag or change metadata, the planning home provides default schema `workspace-planning`, and config has `schema: tdd`
+- **THEN** system uses "workspace-planning" from the planning home default
+
+#### Scenario: Only project config specifies schema
+- **WHEN** no CLI flag, change metadata, or planning-home default exists, but config has `schema: tdd`
+- **THEN** system uses "tdd" from project config
+
+#### Scenario: No schema specified anywhere
+- **WHEN** no CLI flag, change metadata, planning-home default, or project config
+- **THEN** system uses hardcoded default "spec-driven"
+
+### Requirement: Support project-local schema names in config
+
+The system SHALL allow the config schema field to reference project-local schemas defined in `openspec/schemas/`.
+
+#### Scenario: Config references project-local schema
+- **WHEN** config contains `schema: "my-workflow"` and `openspec/schemas/my-workflow/` exists
+- **THEN** system resolves to the project-local schema
+
+#### Scenario: Config references non-existent schema
+- **WHEN** config contains `schema: "nonexistent"` and that schema does not exist
+- **THEN** system shows error when attempting to load the schema with fuzzy match suggestions and list of all valid schemas
+
+### Requirement: Provide helpful error message for invalid schema
+
+The system SHALL display schema error with fuzzy match suggestions, list of available schemas, and fix instructions.
+
+#### Scenario: Schema name with typo (close match)
+- **WHEN** config contains `schema: "spce-driven"` (typo)
+- **THEN** error message includes "Did you mean: spec-driven (built-in)" as suggestion
+
+#### Scenario: Schema name with no close matches
+- **WHEN** config contains `schema: "completely-wrong"`
+- **THEN** error message shows list of all available built-in and project-local schemas
+
+#### Scenario: Error message includes fix instructions
+- **WHEN** config references invalid schema
+- **THEN** error message includes "Fix: Edit openspec/config.yaml and change 'schema: X' to a valid schema name"
+
+#### Scenario: Error distinguishes built-in vs project-local schemas
+- **WHEN** error lists available schemas
+- **THEN** output clearly labels each as "built-in" or "project-local"
+
+### Requirement: Maintain backwards compatibility for existing changes
+
+The system SHALL continue to work with existing changes that do not have project config.
+
+#### Scenario: Existing change without config
+- **WHEN** change was created before config feature and no config file exists
+- **THEN** system resolves schema using existing logic (change metadata or hardcoded default)
+
+#### Scenario: Existing change with config added later
+- **WHEN** config file is added to project with existing changes
+- **THEN** existing changes continue to use their bound schema from `.openspec.yaml`
+
+### Requirement: Workspace planning schema resolution
+Schema resolution SHALL support the built-in workspace planning schema.
+
+#### Scenario: Listing workspace planning schema
+- **WHEN** a user runs `openspec schemas`
+- **THEN** the output SHALL include `workspace-planning`
+- **AND** it SHALL identify it as a package-provided schema unless overridden by a higher-precedence schema
+
+#### Scenario: Resolving workspace planning schema by name
+- **WHEN** a workflow command requests schema `workspace-planning`
+- **THEN** schema resolution SHALL resolve it using the normal project, user, then package precedence order
+
+#### Scenario: Workspace default schema for new changes
+- **GIVEN** the command creates a change in a workspace planning home
+- **AND** the user did not pass an explicit `--schema`
+- **AND** no change metadata schema applies to the new change
+- **WHEN** OpenSpec resolves the schema for the new change
+- **THEN** it SHALL use the planning-home default schema `workspace-planning`
+- **AND** it SHALL use that planning-home default before any project or global config schema value
+
+#### Scenario: Explicit schema override for workspace change
+- **GIVEN** the command creates a change in a workspace planning home
+- **WHEN** the user passes an explicit `--schema <name>`
+- **THEN** OpenSpec SHALL use the explicitly requested schema
+- **AND** it SHALL validate that schema using normal schema resolution

package/OpenSpec-main/openspec/specs/schema-validate-command/spec.md

@@ -0,0 +1,91 @@
+# schema-validate-command Specification
+
+## Purpose
+Define `openspec schema validate` behavior for validating schema syntax, structure, templates, and dependency graphs.
+
+## Requirements
+### Requirement: Schema validate checks schema structure
+The CLI SHALL provide an `openspec schema validate [name]` command that validates schema configuration and reports errors.
+
+#### Scenario: Validate specific schema
+- **WHEN** user runs `openspec schema validate my-workflow`
+- **THEN** system locates schema using resolution order
+- **AND** validates `schema.yaml` against the schema Zod type
+- **AND** displays validation result (valid or list of errors)
+
+#### Scenario: Validate all project schemas
+- **WHEN** user runs `openspec schema validate` without a name
+- **THEN** system validates all schemas in `openspec/schemas/`
+- **AND** displays results for each schema
+- **AND** exits with non-zero code if any schema is invalid
+
+#### Scenario: Schema not found
+- **WHEN** user runs `openspec schema validate nonexistent`
+- **THEN** system displays error that schema was not found
+- **AND** exits with non-zero code
+
+### Requirement: Schema validate checks YAML syntax
+The CLI SHALL report YAML parsing errors with line numbers when possible.
+
+#### Scenario: Invalid YAML syntax
+- **WHEN** user runs `openspec schema validate my-workflow` and `schema.yaml` has syntax errors
+- **THEN** system displays YAML parse error with line number
+- **AND** exits with non-zero code
+
+#### Scenario: Valid YAML but missing required fields
+- **WHEN** `schema.yaml` is valid YAML but missing `name` field
+- **THEN** system displays Zod validation error for missing required field
+- **AND** identifies the specific missing field
+
+### Requirement: Schema validate checks template existence
+The CLI SHALL verify that all template files referenced by artifacts exist.
+
+#### Scenario: Missing template file
+- **WHEN** artifact references `template: proposal.md` but file doesn't exist in schema directory
+- **THEN** system reports error: "Template file 'proposal.md' not found for artifact 'proposal'"
+- **AND** exits with non-zero code
+
+#### Scenario: All templates exist
+- **WHEN** all artifact templates exist
+- **THEN** system reports that templates are valid
+- **AND** template existence is included in validation summary
+
+### Requirement: Schema validate checks dependency graph
+The CLI SHALL verify that artifact dependencies form a valid directed acyclic graph.
+
+#### Scenario: Valid dependency graph
+- **WHEN** artifact dependencies form a valid DAG (e.g., tasks → specs → proposal)
+- **THEN** system reports dependency graph is valid
+
+#### Scenario: Circular dependency detected
+- **WHEN** artifact A requires B and artifact B requires A
+- **THEN** system reports circular dependency error
+- **AND** identifies the artifacts involved in the cycle
+- **AND** exits with non-zero code
+
+#### Scenario: Unknown dependency reference
+- **WHEN** artifact requires `nonexistent-artifact`
+- **THEN** system reports error: "Artifact 'x' requires unknown artifact 'nonexistent-artifact'"
+- **AND** exits with non-zero code
+
+### Requirement: Schema validate outputs JSON format
+The CLI SHALL support `--json` flag for machine-readable validation results.
+
+#### Scenario: JSON output for valid schema
+- **WHEN** user runs `openspec schema validate my-workflow --json` and schema is valid
+- **THEN** system outputs JSON with `valid: true`, `name`, and `path` fields
+
+#### Scenario: JSON output for invalid schema
+- **WHEN** user runs `openspec schema validate my-workflow --json` and schema has errors
+- **THEN** system outputs JSON with `valid: false` and `issues` array
+- **AND** each issue includes `level`, `path`, and `message` fields
+- **AND** format matches existing `openspec validate` output structure
+
+### Requirement: Schema validate supports verbose mode
+The CLI SHALL support `--verbose` flag for detailed validation information.
+
+#### Scenario: Verbose output shows all checks
+- **WHEN** user runs `openspec schema validate my-workflow --verbose`
+- **THEN** system displays each validation check as it runs
+- **AND** shows pass/fail status for: YAML parsing, Zod validation, template existence, dependency graph
+

package/OpenSpec-main/openspec/specs/schema-which-command/spec.md

@@ -0,0 +1,70 @@
+# schema-which-command Specification
+
+## Purpose
+Define `openspec schema which` behavior for reporting resolved schema source, location, and fallback details.
+
+## Requirements
+### Requirement: Schema which shows resolution result
+The CLI SHALL provide an `openspec schema which <name>` command that displays where a schema resolves from.
+
+#### Scenario: Schema resolves from project
+- **WHEN** user runs `openspec schema which my-workflow` and schema exists in `openspec/schemas/my-workflow/`
+- **THEN** system displays source as "project"
+- **AND** displays full path to schema directory
+
+#### Scenario: Schema resolves from user directory
+- **WHEN** user runs `openspec schema which my-workflow` and schema exists only in user data directory
+- **THEN** system displays source as "user"
+- **AND** displays full path including XDG data directory
+
+#### Scenario: Schema resolves from package
+- **WHEN** user runs `openspec schema which spec-driven` and no override exists
+- **THEN** system displays source as "package"
+- **AND** displays full path to package's schemas directory
+
+#### Scenario: Schema not found
+- **WHEN** user runs `openspec schema which nonexistent`
+- **THEN** system displays error that schema was not found
+- **AND** lists available schemas
+- **AND** exits with non-zero code
+
+### Requirement: Schema which shows shadowing information
+The CLI SHALL indicate when a schema shadows another schema at a lower priority level.
+
+#### Scenario: Project schema shadows package
+- **WHEN** user runs `openspec schema which spec-driven` and both project and package have `spec-driven`
+- **THEN** system displays that project schema is active
+- **AND** indicates it shadows the package version
+- **AND** shows path to shadowed package schema
+
+#### Scenario: No shadowing
+- **WHEN** schema exists only in one location
+- **THEN** system does not display shadowing information
+
+#### Scenario: Multiple shadows
+- **WHEN** project schema shadows both user and package schemas
+- **THEN** system lists all shadowed locations in priority order
+
+### Requirement: Schema which outputs JSON format
+The CLI SHALL support `--json` flag for machine-readable output.
+
+#### Scenario: JSON output basic
+- **WHEN** user runs `openspec schema which spec-driven --json`
+- **THEN** system outputs JSON with `name`, `source`, and `path` fields
+
+#### Scenario: JSON output with shadows
+- **WHEN** user runs `openspec schema which spec-driven --json` and schema has shadows
+- **THEN** JSON includes `shadows` array with `source` and `path` for each shadowed schema
+
+### Requirement: Schema which supports list mode
+The CLI SHALL support listing all schemas with their resolution sources.
+
+#### Scenario: List all schemas
+- **WHEN** user runs `openspec schema which --all`
+- **THEN** system displays all available schemas grouped by source
+- **AND** indicates which schemas shadow others
+
+#### Scenario: List in JSON format
+- **WHEN** user runs `openspec schema which --all --json`
+- **THEN** system outputs JSON array with resolution info for each schema
+

package/OpenSpec-main/openspec/specs/specs-sync-skill/spec.md

@@ -0,0 +1,72 @@
+# specs-sync-skill Specification
+
+## Purpose
+Defines the agent skill for syncing delta specs from changes to main specs.
+
+## Requirements
+
+### Requirement: Specs Sync Skill
+The system SHALL provide an `/opsx:sync` skill that syncs delta specs from a change to the main specs.
+
+#### Scenario: Sync delta specs to main specs
+- **WHEN** agent executes `/opsx:sync` with a change name
+- **THEN** the agent reads delta specs from `openspec/changes/<name>/specs/`
+- **AND** reads corresponding main specs from `openspec/specs/`
+- **AND** reconciles main specs to match what the deltas describe
+
+#### Scenario: Idempotent operation
+- **WHEN** agent executes `/opsx:sync` multiple times on the same change
+- **THEN** the result is the same as running it once
+- **AND** no duplicate requirements are created
+
+#### Scenario: Change selection prompt
+- **WHEN** agent executes `/opsx:sync` without specifying a change
+- **THEN** the agent prompts user to select from available changes
+- **AND** shows changes that have delta specs
+
+### Requirement: Delta Reconciliation Logic
+The agent SHALL reconcile main specs with delta specs using the delta operation headers.
+
+#### Scenario: ADDED requirements
+- **WHEN** delta contains `## ADDED Requirements` with a requirement
+- **AND** the requirement does not exist in main spec
+- **THEN** add the requirement to main spec
+
+#### Scenario: ADDED requirement already exists
+- **WHEN** delta contains `## ADDED Requirements` with a requirement
+- **AND** a requirement with the same name already exists in main spec
+- **THEN** update the existing requirement to match the delta version
+
+#### Scenario: MODIFIED requirements
+- **WHEN** delta contains `## MODIFIED Requirements` with a requirement
+- **AND** the requirement exists in main spec
+- **THEN** replace the requirement in main spec with the delta version
+
+#### Scenario: REMOVED requirements
+- **WHEN** delta contains `## REMOVED Requirements` with a requirement name
+- **AND** the requirement exists in main spec
+- **THEN** remove the requirement from main spec
+
+#### Scenario: RENAMED requirements
+- **WHEN** delta contains `## RENAMED Requirements` with FROM:/TO: format
+- **AND** the FROM requirement exists in main spec
+- **THEN** rename the requirement to the TO name
+
+#### Scenario: New capability spec
+- **WHEN** delta spec exists for a capability not in main specs
+- **THEN** create new main spec file at `openspec/specs/<capability>/spec.md`
+
+### Requirement: Skill Output
+The skill SHALL provide clear feedback on what was applied.
+
+#### Scenario: Show applied changes
+- **WHEN** reconciliation completes successfully
+- **THEN** display summary of changes per capability:
+  - Number of requirements added
+  - Number of requirements modified
+  - Number of requirements removed
+  - Number of requirements renamed
+
+#### Scenario: No changes needed
+- **WHEN** main specs already match delta specs
+- **THEN** display "Specs already in sync - no changes needed"

package/OpenSpec-main/openspec/specs/telemetry/spec.md

@@ -0,0 +1,122 @@
+# telemetry Specification
+
+## Purpose
+
+This spec defines how OpenSpec collects anonymous usage telemetry to help improve the tool. It governs the `src/telemetry/` module, which handles PostHog integration, privacy-preserving event design, user opt-out mechanisms, and first-run notice display. The spec ensures telemetry is minimal, transparent, and respects user privacy.
+
+## Requirements
+
+### Requirement: Command execution tracking
+The system SHALL send a `command_executed` event to PostHog when any CLI command executes, including only the command name and OpenSpec version as properties.
+
+#### Scenario: Standard command execution
+- **WHEN** a user runs any openspec command
+- **THEN** the system sends a `command_executed` event with `command` and `version` properties
+
+#### Scenario: Subcommand execution
+- **WHEN** a user runs a nested command like `openspec change apply`
+- **THEN** the system sends a `command_executed` event with the full command path (e.g., `change:apply`)
+
+### Requirement: Privacy-preserving event design
+The system SHALL NOT include command arguments, file paths, project names, spec content, error messages, or IP addresses in telemetry events.
+
+#### Scenario: Command with arguments
+- **WHEN** a user runs `openspec init my-project --force`
+- **THEN** the telemetry event contains only `command: "init"` and `version: "<version>"` without arguments
+
+#### Scenario: IP address exclusion
+- **WHEN** the system sends a telemetry event
+- **THEN** the event explicitly sets `$ip: null` to prevent IP tracking
+
+### Requirement: Environment variable opt-out
+The system SHALL disable telemetry when `OPENSPEC_TELEMETRY=0` or `DO_NOT_TRACK=1` environment variables are set.
+
+#### Scenario: OPENSPEC_TELEMETRY opt-out
+- **WHEN** `OPENSPEC_TELEMETRY=0` is set in the environment
+- **THEN** the system sends no telemetry events
+
+#### Scenario: DO_NOT_TRACK opt-out
+- **WHEN** `DO_NOT_TRACK=1` is set in the environment
+- **THEN** the system sends no telemetry events
+
+#### Scenario: Environment variable takes precedence
+- **WHEN** the user has previously used the CLI (config exists)
+- **AND** the user sets `OPENSPEC_TELEMETRY=0`
+- **THEN** telemetry is disabled regardless of config state
+
+### Requirement: CI environment auto-disable
+The system SHALL automatically disable telemetry when `CI=true` environment variable is detected.
+
+#### Scenario: CI environment detection
+- **WHEN** `CI=true` is set in the environment
+- **THEN** the system sends no telemetry events
+
+#### Scenario: CI with explicit enable
+- **WHEN** `CI=true` is set
+- **AND** `OPENSPEC_TELEMETRY=1` is explicitly set
+- **THEN** telemetry remains disabled (CI takes precedence for privacy)
+
+### Requirement: First-run telemetry notice
+The system SHALL display a one-line telemetry disclosure notice on the first command execution, before any telemetry is sent.
+
+#### Scenario: First command execution
+- **WHEN** a user runs their first openspec command
+- **AND** telemetry is enabled
+- **THEN** the system displays: "Note: OpenSpec collects anonymous usage stats. Opt out: OPENSPEC_TELEMETRY=0"
+
+#### Scenario: Subsequent command execution
+- **WHEN** a user has already seen the notice (noticeSeen: true in config)
+- **THEN** the system does not display the notice
+
+#### Scenario: Notice before telemetry
+- **WHEN** displaying the first-run notice
+- **THEN** the notice appears before any telemetry event is sent
+
+### Requirement: Anonymous user identification
+The system SHALL generate a random UUID as an anonymous identifier on first telemetry send, stored in global config.
+
+#### Scenario: First telemetry event
+- **WHEN** the first telemetry event is sent
+- **AND** no anonymousId exists in config
+- **THEN** the system generates a random UUID v4 and stores it in config
+
+#### Scenario: Persistent identity
+- **WHEN** a user runs multiple commands across sessions
+- **THEN** the same anonymousId is used for all events
+
+#### Scenario: Lazy generation with opt-out
+- **WHEN** a user opts out before running any command
+- **THEN** no anonymousId is ever generated or stored
+
+### Requirement: Immediate event sending
+The system SHALL send telemetry events immediately without batching, using `flushAt: 1` and `flushInterval: 0` configuration.
+
+#### Scenario: Event transmission timing
+- **WHEN** a command executes
+- **THEN** the telemetry event is sent immediately, not queued for batch transmission
+
+### Requirement: Graceful shutdown
+The system SHALL call `posthog.shutdown()` before CLI exit to ensure pending events are flushed.
+
+#### Scenario: Normal exit
+- **WHEN** a command completes successfully
+- **THEN** the system awaits `shutdown()` before exiting
+
+#### Scenario: Error exit
+- **WHEN** a command fails with an error
+- **THEN** the system still awaits `shutdown()` before exiting
+
+### Requirement: Silent failure handling
+The system SHALL silently ignore telemetry failures without affecting CLI functionality.
+
+#### Scenario: Network failure
+- **WHEN** the telemetry request fails due to network error
+- **THEN** the CLI command completes normally without error message
+
+#### Scenario: PostHog outage
+- **WHEN** PostHog service is unavailable
+- **THEN** the CLI command completes normally without error message
+
+#### Scenario: Shutdown failure
+- **WHEN** `shutdown()` fails or times out
+- **THEN** the CLI exits normally without error message

package/OpenSpec-main/openspec/specs/workspace-change-planning/spec.md

@@ -0,0 +1,71 @@
+# workspace-change-planning Specification
+
+## Purpose
+Define how OpenSpec creates, tracks, and guides workspace-level changes whose planning artifacts coordinate multiple linked repos or folders before implementation ownership is finalized.
+
+## Requirements
+### Requirement: Workspace change planning home
+OpenSpec SHALL support workspace-level changes whose shared plan lives in the workspace planning home.
+
+#### Scenario: Creating a workspace change
+- **GIVEN** the command runs from an OpenSpec workspace
+- **WHEN** the user creates a change for workspace planning
+- **THEN** OpenSpec SHALL create the change under the workspace planning path
+- **AND** it SHALL treat the workspace as the planning home for that change
+- **AND** it SHALL use the workspace planning schema when no explicit schema is provided
+
+#### Scenario: Workspace planning artifact structure
+- **GIVEN** a workspace change uses the workspace planning schema
+- **WHEN** OpenSpec reports or creates planning artifacts for that change
+- **THEN** it SHALL use workspace-level artifacts for proposal, specs, cross-area design, and coordination tasks
+- **AND** those artifacts SHALL live under the workspace change root
+- **AND** it SHALL not require an additional area manifest outside those normal planning artifacts
+
+#### Scenario: Capturing the shared goal once
+- **WHEN** a workspace change is proposed
+- **THEN** OpenSpec SHALL capture the product goal at the workspace change level
+- **AND** it SHALL avoid requiring separate repo-local proposals before the affected areas are understood
+
+#### Scenario: Preserving linked repos during change creation
+- **WHEN** OpenSpec creates a workspace-level change
+- **THEN** it SHALL not create repo-local OpenSpec change directories inside linked repos or folders
+- **AND** it SHALL not edit implementation files in linked repos or folders
+
+### Requirement: Workspace affected areas
+OpenSpec SHALL represent ownership or implementation boundaries in a workspace change as affected areas.
+
+#### Scenario: Using registered workspace links as areas
+- **GIVEN** a workspace has linked repos or folders
+- **WHEN** a workspace change identifies affected areas by registered link name
+- **THEN** OpenSpec SHALL validate those area names against the workspace links
+- **AND** it SHALL report invalid area names clearly
+
+#### Scenario: Planning before all areas are known
+- **WHEN** a user is still exploring a workspace change
+- **THEN** OpenSpec SHALL allow the shared plan to exist before all affected areas are finalized
+- **AND** it SHALL keep unresolved affected area questions visible in the normal planning artifacts and status output
+
+#### Scenario: Organizing requirements by area
+- **GIVEN** a workspace change has requirements owned by one or more affected areas
+- **WHEN** OpenSpec reports or creates workspace-scoped specs
+- **THEN** it SHALL allow area-specific requirements to be organized under `specs/<area-or-repo>/<capability>/spec.md`
+- **AND** it SHALL not require separate area folders outside the normal `specs/` artifact tree
+- **AND** it SHALL preserve the area-or-repo path segment as workspace planning context rather than flattening it into a repo-local capability name
+
+#### Scenario: Separating areas from delivery slices
+- **WHEN** a workspace change reports affected areas
+- **THEN** OpenSpec SHALL distinguish affected areas from delivery slices or phases
+- **AND** it SHALL not require users to define delivery slices for a small cross-area change
+
+### Requirement: Workspace planning source of truth
+OpenSpec SHALL keep the workspace change plan as the source of truth until implementation begins for a selected affected area.
+
+#### Scenario: Exploring before implementation
+- **WHEN** an agent explores a workspace change
+- **THEN** it SHALL use workspace-level planning artifacts as the shared planning source
+- **AND** it SHALL treat linked repos and folders as available context rather than committed implementation targets
+
+#### Scenario: Deferring repo-local implementation
+- **WHEN** repo-local implementation work is needed for a workspace change
+- **THEN** OpenSpec SHALL require an explicit implementation workflow with a selected affected area
+- **AND** it SHALL expose the allowed edit root for that selected area before implementation edits begin