chore: archive sync-upstream-v1-4-1

openspec/specs/ai-tool-integration/spec.md

@@ -1,16 +1,24 @@
 ## Purpose
 
 AI tool integration for OpenSpec. Generates skill files and slash commands for AI coding assistants.
-
 ## Requirements
-
 ### Requirement: AI Tool Detection
 
-The system SHALL support configuration for multiple AI coding tools.
+The system SHALL support configuration for multiple AI coding tools, and SHALL auto-detect tools present in a project. Detection MAY use explicit detection paths (files or directories) instead of the tool's default skills directory.
 
 #### Scenario: List supported tools
 - **WHEN** system initializes
 - **THEN** system supports at minimum: opencode, claude, cursor, windsurf, cline, continue, amazon-q
+- **AND** system supports the additional tools: bob, forgecode, junie, kimi, lingma, vibe
+
+#### Scenario: Detect tool by skills directory
+- **WHEN** a project contains a tool's skills directory (e.g. `.claude/`)
+- **THEN** system marks that tool as detected
+
+#### Scenario: Detect GitHub Copilot via specific paths
+- **WHEN** a project contains only a bare `.github/` directory with none of Copilot's detection paths (e.g. `.github/copilot-instructions.md`, `.github/prompts`, `.github/agents`)
+- **THEN** system does NOT falsely detect GitHub Copilot
+- **AND** system detects GitHub Copilot only when at least one configured detection path exists
 
 ### Requirement: Skill Generation
 
@@ -42,4 +50,4 @@ The system SHALL generate files in tool-specific directories.
 #### Scenario: Generate for multiple tools
 - **WHEN** user initializes with `--tools claude,cursor`
 - **THEN** system creates `.claude/` and `.cursor/` directories
-- **AND** each contains tool-appropriate configuration files
+- **AND** each contains tool-appropriate configuration files

openspec/specs/cli-commands/spec.md

@@ -1,9 +1,7 @@
 ## Purpose
 
 CLI commands for the OpenSpec Rust binary. Provides all commands for initializing projects, managing changes, viewing status, and archiving completed work.
-
 ## Requirements
-
 ### Requirement: CLI Init Command
 
 The system SHALL provide an `openspec init [path]` command that initializes OpenSpec in a project directory.
@@ -83,13 +81,18 @@ The system SHALL provide an `openspec show [item-name]` command that displays ch
 
 ### Requirement: CLI Validate Command
 
-The system SHALL provide an `openspec validate [item-name]` command that validates changes and specs.
+The system SHALL provide an `openspec validate [item-name]` command that validates changes and specs, and SHALL emit actionable hints for common authoring mistakes.
 
 #### Scenario: Validate all changes
 - **WHEN** user runs `openspec validate --all`
 - **THEN** system validates all changes and specs
 - **AND** system reports validation errors if any
 
+#### Scenario: Hint when SHALL/MUST only in header
+- **WHEN** a requirement has SHALL/MUST only in its `### Requirement:` header line and not in the requirement body
+- **THEN** system reports a hint to move the keyword onto the requirement body line
+- **AND** the hint is more specific than the generic missing-normative-keyword error
+
 ### Requirement: CLI Archive Command
 
 The system SHALL provide an `openspec archive [change-name]` command that archives a completed change.
@@ -134,3 +137,33 @@ The system SHALL provide `--version` and `--help` flags for all commands.
 #### Scenario: Show help
 - **WHEN** user runs `openspec --help`
 - **THEN** system displays available commands and options
+
+### Requirement: JSON Output Stream Separation
+
+The system SHALL keep `--json` output parseable by AI agents that combine stdout and stderr.
+
+#### Scenario: No spinner leakage with --json
+- **WHEN** a command is run with `--json`
+- **THEN** spinner/progress text is suppressed and does not leak into stderr
+- **AND** the JSON payload remains the only structured output
+
+### Requirement: CLI Initiative Command
+
+The system SHALL provide an `openspec initiative` command group for managing initiatives that group related changes.
+
+#### Scenario: Initiative command available
+- **WHEN** user runs `openspec initiative --help`
+- **THEN** system lists initiative subcommands
+
+### Requirement: CLI Workspace Command
+
+The system SHALL provide an `openspec workspace` command group for beta multi-project workspace planning.
+
+#### Scenario: Workspace command available
+- **WHEN** user runs `openspec workspace --help`
+- **THEN** system lists workspace subcommands (e.g. register, open, view)
+
+#### Scenario: Update does not route into workspace
+- **WHEN** user runs top-level `openspec update` in a project that is not a workspace root
+- **THEN** system performs a normal project update and does NOT route into workspace updates
+- **AND** a foreign root `workspace.yaml` (e.g. from another tool) does not block normal updates

openspec/specs/config-management/spec.md

@@ -1,9 +1,7 @@
 ## Purpose
 
 Configuration management for OpenSpec. Handles project-level and global configuration with XDG compliance.
-
 ## Requirements
-
 ### Requirement: Project Configuration
 
 The system SHALL support project-level configuration via `openspec/config.yaml`.
@@ -44,3 +42,32 @@ The system SHALL support environment variable overrides for configuration.
 #### Scenario: Override telemetry via env
 - **WHEN** `OPENSPEC_TELEMETRY=0` is set
 - **THEN** system disables telemetry regardless of config file
+
+### Requirement: Global Directory Resolution Parity
+
+The system SHALL resolve the global config and data directories to the same locations as the upstream TypeScript CLI, so a context store / global config is shared between the two implementations.
+
+#### Scenario: XDG override honored on all platforms
+- **WHEN** `XDG_CONFIG_HOME` or `XDG_DATA_HOME` is set
+- **THEN** the global config/data dir is `$XDG_*_HOME/openspec` regardless of platform
+
+#### Scenario: macOS uses dotfile paths, not Library
+- **WHEN** no XDG override is set on macOS
+- **THEN** the global config dir is `~/.config/openspec` and the data dir is `~/.local/share/openspec` (matching upstream, not `~/Library/Application Support`)
+- **AND** an existing legacy macOS global config is migrated to the new location on a best-effort basis
+
+### Requirement: Foreign Workspace File Isolation
+
+The system SHALL ignore foreign root `workspace.yaml` files that do not belong to OpenSpec, so unrelated projects continue updating normally.
+
+#### Scenario: Ignore non-OpenSpec workspace.yaml
+- **WHEN** a project root contains a `workspace.yaml` written by another tool
+- **THEN** `openspec update` treats the project as a normal project and ignores that file
+
+### Requirement: Default Core Profile Sync Workflow
+
+The system SHALL include the `sync` workflow in the default `core` profile so new installations generate `/opsx:sync` skills and commands by default.
+
+#### Scenario: Core profile includes sync
+- **WHEN** user initializes a project with the default `core` profile
+- **THEN** system generates the `sync` workflow skill and command alongside the other core workflows

openspec/specs/context-store/spec.md

@@ -0,0 +1,37 @@
+# context-store Specification
+
+## Purpose
+TBD - created by archiving change sync-upstream-v1-4-1. Update Purpose after archive.
+## Requirements
+### Requirement: Context Store Setup and Registration
+
+The system SHALL provide an `openspec context-store` command group to set up and register local context stores that back workspace and initiative data.
+
+#### Scenario: Set up a context store
+- **WHEN** user runs `openspec context-store setup [id]`
+- **THEN** system creates and registers a local context store
+- **AND** system supports `--path <path>` (defaults to OpenSpec-managed local data) and optional `--init-git`
+
+#### Scenario: Register an existing store
+- **WHEN** user runs `openspec context-store register [path] --id <id>`
+- **THEN** system registers the existing local context store, defaulting the id from metadata or folder name
+
+### Requirement: Context Store Lifecycle
+
+The system SHALL allow listing, diagnosing, and removing context-store registrations.
+
+#### Scenario: List registered stores
+- **WHEN** user runs `openspec context-store list`
+- **THEN** system lists locally registered context stores (with `--json` support)
+
+#### Scenario: Diagnose a store
+- **WHEN** user runs `openspec context-store doctor [id]`
+- **THEN** system checks the registration and metadata of the store
+
+#### Scenario: Unregister without deleting
+- **WHEN** user runs `openspec context-store unregister <id>`
+- **THEN** system forgets the registration without deleting files
+
+#### Scenario: Remove and delete
+- **WHEN** user runs `openspec context-store remove <id> --yes`
+- **THEN** system forgets the registration and deletes its local folder

openspec/specs/initiatives/spec.md

@@ -0,0 +1,30 @@
+# initiatives Specification
+
+## Purpose
+TBD - created by archiving change sync-upstream-v1-4-1. Update Purpose after archive.
+## Requirements
+### Requirement: Initiative Change Linking
+
+The system SHALL allow linking a repo-local change to an initiative.
+
+#### Scenario: Link a change to an initiative
+- **WHEN** a change is created with `--initiative <id>` (optionally `--store <id>` or `--store-path <path>`)
+- **THEN** system records the link between the repo-local change and the initiative
+
+### Requirement: Initiative Management
+
+The system SHALL provide an `openspec initiative` command group to create and list coordinated initiatives that live inside a context store and group related changes.
+
+#### Scenario: Create an initiative
+- **WHEN** user runs `openspec initiative create [id] --title <title> --summary <summary>`
+- **THEN** system creates an initiative in the resolved context store
+- **AND** system supports selecting the store via `--store <id>` or `--store-path <path>`
+
+#### Scenario: Show an initiative
+- **WHEN** user runs `openspec initiative show <id>`
+- **THEN** system reports where the initiative lives and how to read it
+
+#### Scenario: List initiatives
+- **WHEN** user runs `openspec initiative list`
+- **THEN** system lists initiatives across registered context stores
+- **AND** system supports `--json` output

openspec/specs/shell-completion/spec.md

@@ -1,9 +1,7 @@
 ## Purpose
 
 Shell completion support for OpenSpec. Generates and installs completion scripts for Bash, Zsh, and Fish shells.
-
 ## Requirements
-
 ### Requirement: Shell Completion Generation
 
 The system SHALL generate shell completion scripts for Bash, Zsh, and Fish.
@@ -22,7 +20,7 @@ The system SHALL generate shell completion scripts for Bash, Zsh, and Fish.
 
 ### Requirement: Shell Completion Installation
 
-The system SHALL install completion scripts to appropriate shell directories.
+The system SHALL install completion scripts to appropriate shell directories. Installation SHALL be opt-in (explicitly requested), and SHALL write scripts using encodings/setup compatible with each target shell.
 
 #### Scenario: Install bash completion
 - **WHEN** user runs `openspec completion install bash`
@@ -31,6 +29,16 @@ The system SHALL install completion scripts to appropriate shell directories.
 #### Scenario: Install zsh completion
 - **WHEN** user runs `openspec completion install zsh`
 - **THEN** system installs completion to zsh fpath directory
+- **AND** the installed script works under oh-my-zsh's `compinit`
+
+#### Scenario: Completion install is opt-in
+- **WHEN** user runs `openspec init` or `openspec update`
+- **THEN** system does NOT install shell completion automatically
+- **AND** completion is installed only when the user runs `openspec completion install <shell>`
+
+#### Scenario: PowerShell completion encoding
+- **WHEN** user installs PowerShell completion
+- **THEN** the generated profile content is written without encoding corruption
 
 ### Requirement: Shell Completion Uninstallation
 
@@ -46,4 +54,4 @@ The system SHALL provide completion data for changes and specs.
 
 #### Scenario: Complete change names
 - **WHEN** shell requests completion for change names
-- **THEN** system outputs list of available changes
+- **THEN** system outputs list of available changes

openspec/specs/spec-parser/spec.md

@@ -1,9 +1,7 @@
 ## Purpose
 
 Markdown spec parser for OpenSpec. Parses delta specs with ADDED/MODIFIED/REMOVED/RENAMED sections and merges them into main specs.
-
 ## Requirements
-
 ### Requirement: Delta Spec Parsing
 
 The system SHALL parse markdown spec files with ADDED, MODIFIED, REMOVED, and RENAMED sections.
@@ -27,7 +25,7 @@ The system SHALL parse markdown spec files with ADDED, MODIFIED, REMOVED, and RE
 
 ### Requirement: Requirement Extraction
 
-The system SHALL extract requirements with their scenarios from markdown.
+The system SHALL extract requirements with their scenarios from markdown. Requirement headers SHALL be matched case-insensitively, and header-looking lines nested inside fenced code blocks SHALL NOT be parsed as requirements or scenarios.
 
 #### Scenario: Extract requirement with scenarios
 - **WHEN** system parses `### Requirement: <name>` followed by `#### Scenario: <name>` blocks
@@ -39,6 +37,15 @@ The system SHALL extract requirements with their scenarios from markdown.
 - **THEN** system still extracts the requirement
 - **AND** system may warn about missing scenarios
 
+#### Scenario: Case-insensitive requirement header
+- **WHEN** a spec uses a header such as `### requirement: <name>` or `### REQUIREMENT: <name>`
+- **THEN** system parses it as a requirement regardless of capitalization
+
+#### Scenario: Ignore requirement inside a fenced code block
+- **WHEN** a spec contains a `### Requirement:` or `#### Scenario:` line inside a fenced code block (```` ``` ```` or `~~~`)
+- **THEN** system does NOT parse the fenced line as a requirement or scenario
+- **AND** only real, non-fenced requirements are counted
+
 ### Requirement: Spec Merging
 
 The system SHALL merge delta specs into main specs during archive.
@@ -65,4 +72,4 @@ The system SHALL discover spec files matching glob patterns.
 
 #### Scenario: Discover main specs
 - **WHEN** system looks for specs in `openspec/specs/`
-- **THEN** system finds all `spec.md` files organized by capability
+- **THEN** system finds all `spec.md` files organized by capability

openspec/specs/telemetry/spec.md

@@ -1,9 +1,7 @@
 ## Purpose
 
 Optional anonymous telemetry for OpenSpec. Collects usage statistics to improve the tool with user consent and easy opt-out.
-
 ## Requirements
-
 ### Requirement: Anonymous Usage Tracking
 
 The system MAY collect anonymous usage statistics when telemetry is enabled, and SHALL NOT collect any data when telemetry is disabled.
@@ -46,3 +44,16 @@ The system SHALL send telemetry asynchronously to avoid blocking CLI operations.
 - **WHEN** system sends telemetry
 - **THEN** command execution is not delayed
 - **AND** telemetry failures do not affect command results
+
+### Requirement: Resilient Telemetry Delivery
+
+The system SHALL fail silently when telemetry delivery is blocked, so that firewalled or offline environments never surface network errors to the user.
+
+#### Scenario: Network blocked by firewall
+- **WHEN** telemetry is enabled but the analytics endpoint is unreachable or blocked
+- **THEN** system swallows the network error without printing it
+- **AND** system does not retry indefinitely (delivery uses a short ~1s timeout with retries and remote config disabled)
+
+#### Scenario: No impact on command exit
+- **WHEN** a telemetry send fails
+- **THEN** the command still completes and exits normally

openspec/specs/workspace/spec.md

@@ -0,0 +1,57 @@
+# workspace Specification
+
+## Purpose
+TBD - created by archiving change sync-upstream-v1-4-1. Update Purpose after archive.
+## Requirements
+### Requirement: Workspace Setup and Linking
+
+The system SHALL provide a beta `openspec workspace` command group that sets up coordination workspaces and links existing repos or folders to them.
+
+#### Scenario: Set up a workspace
+- **WHEN** user runs `openspec workspace setup`
+- **THEN** system creates a workspace and records its configuration
+- **AND** system can link existing repos or folders during setup
+
+#### Scenario: Link an existing repo
+- **WHEN** user runs `openspec workspace link [nameOrPath] [path]`
+- **THEN** system links the repo or folder to the workspace under a link name
+
+#### Scenario: Relink a moved repo
+- **WHEN** user runs `openspec workspace relink <name> <path>`
+- **THEN** system updates the local path for the existing workspace link
+
+### Requirement: Workspace Inspection
+
+The system SHALL allow listing and diagnosing workspaces.
+
+#### Scenario: List workspaces
+- **WHEN** user runs `openspec workspace list` (or `ls`)
+- **THEN** system lists known OpenSpec workspaces
+
+#### Scenario: Diagnose workspace resolution
+- **WHEN** user runs `openspec workspace doctor`
+- **THEN** system reports what the workspace can resolve on this machine
+
+### Requirement: Workspace Open and View State
+
+The system SHALL open a workspace in an agent or editor, and SHALL persist beta workspace view state under `.openspec-workspace/view.yaml`.
+
+#### Scenario: Open a workspace
+- **WHEN** user runs `openspec workspace open [name]`
+- **THEN** system opens the workspace in a selected agent or VS Code editor
+
+#### Scenario: Persist view state
+- **WHEN** workspace view state changes
+- **THEN** system stores it under `.openspec-workspace/view.yaml`
+
+### Requirement: Workspace Update Isolation
+
+The system SHALL keep workspace updates separate from project updates.
+
+#### Scenario: Refresh workspace guidance
+- **WHEN** user runs `openspec workspace update [name]`
+- **THEN** system refreshes workspace-local OpenSpec guidance and agent skills
+
+#### Scenario: Top-level update stays project-scoped
+- **WHEN** user runs top-level `openspec update` outside a workspace root
+- **THEN** system does not route into workspace updates