sauron-cli 1.1.3 → 1.3.0

package/OpenSpec-main/openspec/changes/archive/2026-05-04-workspace-foundation/proposal.md

@@ -0,0 +1,142 @@
+## Why
+
+Users need a workspace to feel like the obvious home for planning across multiple repos or folders.
+
+They should be able to think:
+
+```text
+I have repos or folders that are often planned together.
+I create an OpenSpec workspace.
+That workspace is where changes live.
+My code stays where it is.
+OpenSpec links the workspace to those local paths.
+```
+
+A workspace is not a feature. It is the durable planning home. Individual features, fixes, and projects are changes inside the workspace.
+
+Users should not have to choose a storage location, create a change early, or understand internal workspace state before OpenSpec can orient itself.
+
+The POC proved that workspace state is useful. This reimplementation should turn that into a simple product model that users and agents can explain without special-case vocabulary.
+
+## What Changes
+
+This change defines the user-facing foundation for OpenSpec workspaces.
+
+An OpenSpec workspace has a recognizable planning home:
+
+```text
+workspace-root/
+  changes/
+  .openspec-workspace/
+```
+
+`changes/` is where workspace-level planning lives. `.openspec-workspace/` identifies the directory as an OpenSpec workspace and stores workspace state.
+
+OpenSpec-managed workspaces live in one standard location:
+
+```text
+<global-data-dir>/workspaces/
+```
+
+Users should not need to choose that location. OpenSpec still shows the workspace path after setup so users know where planning files live. This foundation slice does not provide a workspace-specific environment-variable or configuration override for managed workspace storage.
+
+OpenSpec also keeps a lightweight local registry of known workspaces on the current machine. The registry powers global commands, pickers, and listing, but each workspace folder remains the source of truth.
+
+Workspace state is split by user expectation:
+
+- shared workspace information can move between machines
+- local checkout paths stay local to each machine
+- linked repos and folders are referred to by stable link names, not by absolute paths
+
+A linked path can be a full repo, a folder inside a monorepo, or another existing folder the workspace should plan against. A linked path does not need repo-local `openspec/` state before it can be included in workspace planning. Repo-local OpenSpec state may still matter later for implementation, verification, or archive workflows, but it is not a prerequisite for planning visibility.
+
+Native Windows/PowerShell and WSL2 are both supported. Each runtime uses its own path conventions. OpenSpec does not translate paths between Windows and WSL in this foundation slice.
+
+## Outcome
+
+After this change, later workspace features can rely on one clear product contract:
+
+- OpenSpec can tell when the user is inside a workspace.
+- OpenSpec knows where to create managed workspaces by default.
+- OpenSpec can keep a local registry of known workspaces.
+- A workspace has one visible planning area: `changes/`.
+- Workspace state is distinguishable from repo-local `openspec/` state.
+- Shared workspace state does not force one user's local paths onto another user.
+- Workspace planning can reference existing repos or folders by stable link names.
+- Linked repos or folders do not need repo-local OpenSpec state for workspace planning.
+- Multi-repo and large-monorepo work can use the same workspace planning model.
+- Repo-owned specs and implementation remain owned by their repos or source areas.
+- Windows, PowerShell, and WSL2 path behavior is predictable.
+
+This change does not deliver the full workspace workflow. It gives `workspace-create-and-register-repos` the foundation it needs to add the first user-facing commands.
+
+## POC Findings
+
+Behavior to preserve:
+
+- A workspace is a durable coordination home for cross-repo planning.
+- The workspace has a visible `changes/` directory at its root.
+- Linked repos and folders provide the context the workspace can plan against.
+- Stable link names matter more than local checkout paths.
+- Local machine paths should not become shared workspace state.
+- Canonical specs and implementation still belong to the owning repos.
+
+Lessons to carry forward:
+
+- The POC's hidden `.openspec/` workspace metadata shape made workspace state too easy to confuse with repo-local OpenSpec state.
+- Users should not need to run repo-local `openspec init` inside the workspace root.
+- The POC's requirement that registered repos already have `openspec/` is too strict for planning. Repos and folders should be linkable before they adopt repo-local OpenSpec state.
+- Repo or folder visibility should not depend on creating a change.
+- Workspace setup should not imply repo-local implementation, branch, worktree, apply, verify, or archive behavior.
+- `add-repo` is too narrow for the user-facing model. Linking an existing repo or folder is clearer.
+
+## Decisions
+
+- Workspace identity directory: `.openspec-workspace/`.
+- Workspace identity file: `.openspec-workspace/workspace.yaml`.
+- Workspace name: a valid folder name for the current OS, excluding empty names, `.`/`..`, and path separators.
+- Workspace name usage: stored in `workspace.yaml`, used as the default managed workspace folder name, and used as the local registry name.
+- Planning surface: top-level `changes/`.
+- Local machine state: `.openspec-workspace/local.yaml`.
+- Local machine state exclusion: OpenSpec-created workspaces exclude `.openspec-workspace/local.yaml` from portable collaboration state by default.
+- Local workspace registry: `<global-data-dir>/workspaces/registry.yaml`.
+- Default workspace base: `<global-data-dir>/workspaces/`.
+- Platform behavior: native Windows and WSL2 each use the path conventions of the runtime running OpenSpec.
+- Linked paths may be full repos, monorepo folders, or other existing folders.
+- Link names: non-empty stable names, unique within a workspace, excluding `.`/`..` and path separators.
+- Repo-local `openspec/` state is not required for workspace planning visibility.
+- Linking records the relationship only; it does not create, copy, move, initialize, or edit files in the linked repo or folder.
+
+Planning dependency:
+
+- None. This is the first implementation slice.
+
+## Non-Goals
+
+- No complete `openspec workspace setup`, `openspec workspace link`, or `openspec workspace relink` flow yet.
+- No public `openspec workspace create` command in the first user-facing workspace flow.
+- No user-facing command, environment variable, or configuration setting for changing the standard workspace location.
+- No question that asks users where OpenSpec should store workspaces by default.
+- No automatic Windows-to-WSL or WSL-to-Windows path translation.
+- No workspace-open agent launch behavior.
+- No workspace-level proposal creation.
+- No repo-slice apply, verify, archive, branch, or worktree behavior.
+- No copying workspace planning files into linked repos or folders as a side effect of creating, detecting, or linking a workspace.
+
+## Capabilities
+
+### New Capabilities
+
+- `workspace-foundation`: Defines the product foundation for OpenSpec workspaces.
+
+### Modified Capabilities
+
+- `openspec-conventions`: Describes how coordination workspaces differ from repo-local OpenSpec projects.
+
+## Impact
+
+- Workspace recognition and path behavior.
+- Workspace state parsing.
+- Local workspace registry parsing.
+- Documentation and agent guidance for the workspace mental model.
+- Later workspace slices should build on this contract instead of redefining workspace storage, identity, registry, or path behavior.

package/OpenSpec-main/openspec/changes/archive/2026-05-04-workspace-foundation/specs/openspec-conventions/spec.md

@@ -0,0 +1,29 @@
+## ADDED Requirements
+
+### Requirement: Workspace Product Language
+OpenSpec conventions SHALL describe coordination workspaces in user-facing product terms.
+
+#### Scenario: Describing workspace structure
+- **WHEN** OpenSpec documentation describes workspace support
+- **THEN** it SHALL present a workspace as the planning home for work across linked repos or folders
+- **AND** it SHALL describe `changes/` as the workspace planning area
+
+#### Scenario: Avoiding internal workspace vocabulary
+- **WHEN** OpenSpec documentation explains what a workspace includes
+- **THEN** it SHALL prefer plain product language such as "repos or folders"
+- **AND** it SHALL avoid user-facing reliance on terms such as "working set", "code area", "entry", "alias", or "local overlay"
+
+#### Scenario: Distinguishing workspaces from changes
+- **WHEN** OpenSpec documentation explains workspace planning
+- **THEN** it SHALL describe a workspace as a durable planning home
+- **AND** it SHALL describe individual features, fixes, and projects as changes inside the workspace
+
+#### Scenario: Distinguishing workspace and repo-local surfaces
+- **WHEN** OpenSpec documentation compares workspace and repo-local flows
+- **THEN** it SHALL explain that workspace planning lives in the workspace root
+- **AND** it SHALL explain that repo-local specs and changes continue to live under each repo's `openspec/` directory
+
+#### Scenario: Sequencing the workspace roadmap
+- **WHEN** workspace reimplementation work is split across multiple active changes
+- **THEN** conventions SHALL allow those changes to remain flat siblings under `openspec/changes/`
+- **AND** dependency order MAY be documented in proposal prose until formal change stacking metadata is available

package/OpenSpec-main/openspec/changes/archive/2026-05-04-workspace-foundation/specs/workspace-foundation/spec.md

@@ -0,0 +1,199 @@
+## ADDED Requirements
+
+### Requirement: Recognizable Workspace Home
+OpenSpec SHALL give users and agents a recognizable workspace home for cross-repo planning.
+
+#### Scenario: Planning across linked repos or folders
+- **WHEN** a user creates an OpenSpec workspace for repos or folders they plan across
+- **THEN** the workspace SHALL provide a durable planning home
+- **AND** the workspace SHALL be able to hold multiple changes over time
+
+#### Scenario: Working from inside a workspace
+- **GIVEN** a user runs OpenSpec from a workspace root or one of its subdirectories
+- **WHEN** OpenSpec resolves the current workspace
+- **THEN** it SHALL identify the workspace root
+- **AND** it SHALL use the workspace root's `changes/` directory as the workspace planning area
+
+#### Scenario: Avoiding accidental workspace mode
+- **GIVEN** a directory has `changes/` but is not an OpenSpec workspace
+- **WHEN** OpenSpec resolves the current workspace
+- **THEN** it SHALL avoid treating that directory as a workspace
+- **AND** it SHALL enter workspace mode only when the workspace identity file is present
+
+### Requirement: Stable Workspace Name
+OpenSpec SHALL use one folder-style workspace name across workspace identity, managed storage, and the local registry.
+
+#### Scenario: Using one workspace name
+- **WHEN** OpenSpec creates or registers a managed workspace
+- **THEN** the workspace name SHALL be stored in `.openspec-workspace/workspace.yaml`
+- **AND** the same name SHALL be used as the default managed workspace folder name
+- **AND** the same name SHALL be used as the local registry name
+
+#### Scenario: Rejecting invalid folder-style names
+- **WHEN** OpenSpec accepts a workspace name
+- **THEN** it SHALL reject empty names, `.` or `..`, and names containing path separators
+- **AND** setup or create flows SHALL report OS-level folder creation failures clearly
+
+### Requirement: Dedicated Workspace Identity
+OpenSpec SHALL distinguish a coordination workspace from a repo-local OpenSpec project.
+
+#### Scenario: Reading workspace identity
+- **WHEN** OpenSpec reads or writes workspace identity and workspace state
+- **THEN** it SHALL use `.openspec-workspace/`
+
+#### Scenario: Preserving repo-local OpenSpec projects
+- **GIVEN** a repo-local OpenSpec project uses `openspec/`
+- **WHEN** that repo is linked to a workspace
+- **THEN** OpenSpec SHALL continue treating `openspec/` as that repo's local OpenSpec directory
+- **AND** workspace planning SHALL remain anchored in the workspace root
+
+#### Scenario: Avoiding repo-local initialization in the workspace root
+- **WHEN** a user is working from an OpenSpec workspace root
+- **THEN** OpenSpec SHALL treat that root as a workspace coordination surface
+- **AND** users SHALL not need to initialize a repo-local `openspec/` project inside the workspace root
+
+### Requirement: Safe Workspace Sharing
+OpenSpec SHALL keep shared workspace information separate from local machine paths.
+
+#### Scenario: Sharing workspace planning
+- **WHEN** a workspace is shared with another user or machine
+- **THEN** shared workspace information SHALL include portable workspace identity and stable link names
+- **AND** it SHALL not require another user to reuse the original user's absolute checkout paths
+
+#### Scenario: Keeping checkout paths local
+- **WHEN** OpenSpec stores local paths for a workspace
+- **THEN** those paths SHALL be treated as local to the current machine and runtime
+- **AND** another machine MAY map the same link names to different local paths
+
+#### Scenario: Preserving runtime-local paths
+- **WHEN** OpenSpec reads or writes local workspace paths
+- **THEN** it SHALL preserve path strings valid for the current runtime
+- **AND** it SHALL support native Windows paths and WSL2/Linux paths as local state values
+
+#### Scenario: Excluding local state from portable collaboration
+- **WHEN** OpenSpec creates a workspace
+- **THEN** it SHALL exclude `.openspec-workspace/local.yaml` from portable collaboration state by default
+- **AND** `.openspec-workspace/workspace.yaml` SHALL remain the portable workspace identity and link-name state
+
+### Requirement: Standard Workspace Location
+OpenSpec SHALL use a standard location for OpenSpec-managed workspaces without asking most users to choose one.
+
+#### Scenario: Using the standard workspace location
+- **WHEN** OpenSpec needs the location for OpenSpec-managed workspaces
+- **THEN** it SHALL use `<global-data-dir>/workspaces`
+- **AND** `<global-data-dir>` SHALL follow existing OpenSpec XDG and platform data directory behavior
+
+#### Scenario: Avoiding workspace-specific storage overrides
+- **WHEN** OpenSpec resolves the location for OpenSpec-managed workspaces
+- **THEN** it SHALL not use a workspace-specific environment variable, command, or configuration setting in this slice
+- **AND** managed workspace storage SHALL remain under `<global-data-dir>/workspaces`
+
+#### Scenario: Running from native Windows
+- **WHEN** OpenSpec runs from native Windows shells such as PowerShell
+- **AND** `XDG_DATA_HOME` is not set
+- **THEN** OpenSpec SHALL store managed workspaces under the Windows global data location
+- **AND** paths SHALL follow native Windows path behavior
+
+#### Scenario: Running from WSL2
+- **WHEN** OpenSpec runs from WSL2
+- **THEN** OpenSpec SHALL store managed workspaces under the Linux/XDG data location inside WSL
+- **AND** paths SHALL follow Linux path behavior inside WSL
+
+#### Scenario: Using the workspace location automatically
+- **WHEN** OpenSpec creates or resolves OpenSpec-managed workspaces in later workflows
+- **THEN** it SHALL use the resolved workspace location by default
+- **AND** users SHALL be able to follow the normal workspace flow without choosing a storage location
+
+#### Scenario: Showing the workspace path
+- **WHEN** OpenSpec creates a workspace in the standard workspace location
+- **THEN** it SHALL report the workspace path to the user
+- **AND** it SHALL not hide where planning files were created
+
+#### Scenario: Staying in the current runtime
+- **WHEN** OpenSpec resolves workspace paths or local repo paths
+- **THEN** it SHALL interpret paths for the runtime running OpenSpec
+- **AND** Windows, UNC WSL, and WSL mount paths SHALL remain explicit user-provided paths
+
+### Requirement: Local Workspace Registry
+OpenSpec SHALL keep a lightweight local registry of known workspaces on the current machine.
+
+#### Scenario: Recording known workspaces
+- **WHEN** OpenSpec creates or learns about a managed workspace
+- **THEN** it SHALL be able to record the workspace name and path in a local registry
+- **AND** the registry SHALL be machine-local state
+
+#### Scenario: Keeping workspace folders authoritative
+- **WHEN** OpenSpec reads workspace details
+- **THEN** each workspace folder's `.openspec-workspace/workspace.yaml` SHALL remain the source of truth for that workspace
+- **AND** the local registry SHALL act only as an index of known workspace paths
+
+#### Scenario: Finding workspaces from anywhere
+- **WHEN** a later workspace command runs outside a workspace directory
+- **THEN** OpenSpec MAY use the local registry to find known workspaces
+- **AND** commands that need one workspace MAY use the registry to support an interactive picker
+
+### Requirement: Stable Link Names
+OpenSpec SHALL use stable link names to refer to repos and folders in workspace planning.
+
+#### Scenario: Referring to a repo or folder in workspace planning
+- **WHEN** workspace state or later workspace planning artifacts refer to a linked repo or folder
+- **THEN** they SHALL use the stable link name
+- **AND** the same link name SHALL remain valid even when local checkout paths differ
+
+#### Scenario: Reusing link names across machines
+- **WHEN** a workspace is used on another machine
+- **THEN** link names SHALL remain stable
+- **AND** local checkout paths MAY differ on that machine
+
+#### Scenario: Rejecting invalid link names
+- **WHEN** OpenSpec accepts a workspace link name
+- **THEN** it SHALL reject empty names, `.` or `..`, and names containing path separators
+- **AND** link names SHALL be unique within the workspace
+
+### Requirement: Linked Repos And Folders
+OpenSpec SHALL allow workspace planning to include linked repos and folders before they have repo-local OpenSpec state.
+
+#### Scenario: Planning with a repo that has not adopted OpenSpec
+- **WHEN** a workspace links a repo path that does not yet contain repo-local `openspec/`
+- **THEN** the repo SHALL still be available for workspace-level planning
+- **AND** implementation readiness MAY be handled by a later workflow
+
+#### Scenario: Planning across monorepo folders
+- **WHEN** planning spans multiple packages, services, apps, or directories inside one monorepo
+- **THEN** the workspace SHALL be able to link those folders separately
+- **AND** each folder SHALL not need its own repo-local `openspec/` directory to participate in workspace planning
+
+#### Scenario: Treating repos and folders consistently
+- **WHEN** a workspace plan includes both separate repos and folders inside a monorepo
+- **THEN** OpenSpec SHALL use the same planning model for both
+- **AND** users SHALL not need to create different kinds of workspace plans for multi-repo and monorepo changes
+
+#### Scenario: Recording links without changing targets
+- **WHEN** OpenSpec records a link between a workspace and a local repo or folder
+- **THEN** it SHALL store the link in workspace state
+- **AND** it SHALL not create, copy, move, initialize, or edit files inside the linked repo or folder
+
+### Requirement: Planning Before Implementation
+OpenSpec SHALL treat workspace creation and detection as planning setup, not implementation.
+
+#### Scenario: Creating or detecting a workspace
+- **WHEN** a workspace exists
+- **THEN** OpenSpec SHALL treat it as a place for workspace-level planning
+- **AND** repo implementation files SHALL remain unchanged until an explicit implementation workflow runs
+
+#### Scenario: Deferring repo implementation
+- **WHEN** repo-local implementation, apply, verify, or archive behavior is needed
+- **THEN** that behavior SHALL require an explicit later workspace workflow
+
+### Requirement: Repo Ownership Boundaries
+OpenSpec SHALL keep repo ownership legible when planning happens in a workspace.
+
+#### Scenario: Planning across owned repos
+- **WHEN** a workspace plan refers to behavior owned by a repo or source area
+- **THEN** that owner SHALL remain the home for canonical specs and implementation work
+- **AND** the workspace SHALL make the cross-boundary plan visible without taking ownership away from that owner
+
+#### Scenario: Drafting before ownership is clear
+- **WHEN** cross-repo behavior is still being explored and ownership is not clear
+- **THEN** the workspace MAY hold planning notes or draft behavior
+- **AND** those drafts SHALL remain distinguishable from canonical repo-owned specs

package/OpenSpec-main/openspec/changes/archive/2026-05-04-workspace-foundation/tasks.md

@@ -0,0 +1,56 @@
+## 1. POC Findings And Model Decisions
+
+- [x] 1.1 Capture the foundation POC findings in the proposal/design artifacts
+- [x] 1.2 Settle `.openspec-workspace/` as the workspace metadata directory
+- [x] 1.3 Define the minimal workspace root shape and root marker
+- [x] 1.4 Define committed workspace state versus machine-local workspace state
+- [x] 1.5 Capture that workspace setup is useful only after at least one repo or folder is linked
+- [x] 1.6 Capture that repo-owned specs and implementation remain owned by repos
+- [x] 1.7 Capture that planning can include repos or monorepo folders without repo-local OpenSpec state
+- [x] 1.8 Capture that workspaces hold many changes and are not feature containers
+- [x] 1.9 Capture `link`/`relink` as the user-facing model instead of `add-repo`/`update-repo`
+
+## 2. Foundation Helpers
+
+- [x] 2.1 Add workspace path constants and helpers for `.openspec-workspace/`, `workspace.yaml`, `local.yaml`, and root `changes/`
+- [x] 2.2 Add workspace root detection from an arbitrary starting directory
+- [x] 2.3 Add typed parsing and validation for minimal shared workspace state
+- [x] 2.4 Add typed parsing and validation for minimal machine-local workspace state
+- [x] 2.5 Ensure repo-local `openspec/` projects are not mistaken for coordination workspaces
+- [x] 2.6 Add a standard workspace location resolver using `getGlobalDataDir()/workspaces`
+- [x] 2.7 Ensure workspace path helpers use platform path APIs and avoid hardcoded POSIX separators
+- [x] 2.8 Add local workspace registry path constants and helpers
+
+## 3. Metadata And Local State
+
+- [x] 3.1 Define the versioned shared-state shape with workspace name and stable link map
+- [x] 3.2 Define the versioned local-state shape with stable link names mapped to local paths
+- [x] 3.3 Ensure local-state files are treated as machine-local and OpenSpec-created workspaces exclude `.openspec-workspace/local.yaml` from portable collaboration state
+- [x] 3.4 Add validation for invalid versions, invalid link names, malformed link maps, and malformed local path maps
+- [x] 3.5 Preserve native Windows and WSL2 path strings when reading and writing local path state
+- [x] 3.6 Define the versioned local registry shape with workspace names mapped to workspace roots
+- [x] 3.7 Ensure the local registry is treated as a convenience index, not the workspace source of truth
+
+## 4. Documentation And Guidance
+
+- [x] 4.1 Document the coordination workspace mental model
+- [x] 4.2 Document how `.openspec-workspace/` differs from repo-local `openspec/`
+- [x] 4.3 Document stable link names as the way to refer to linked repos and folders
+- [x] 4.4 Document which behavior is intentionally deferred to later workspace slices
+- [x] 4.5 Document native Windows/PowerShell and WSL2 path behavior for managed workspace storage
+- [x] 4.6 Document linked repos/folders without repo-local OpenSpec and large-monorepo planning behavior
+- [x] 4.7 Document the local workspace registry and global command model
+
+## 5. Verification
+
+- [x] 5.1 Add unit tests for root detection and non-detection cases
+- [x] 5.2 Add unit tests for shared-state and local-state parsing
+- [x] 5.3 Add unit tests for standard workspace location resolution with XDG/Linux fallback and native Windows fallback
+- [x] 5.4 Add unit tests that local-state parsing preserves native Windows and WSL2-style paths
+- [x] 5.5 Add unit tests for repo-local compatibility boundaries
+- [x] 5.6 Add tests or docs coverage that linked repos/folders do not require repo-local `openspec/`
+- [x] 5.7 Add tests or docs coverage for monorepo folder links under the same workspace model
+- [x] 5.8 Add tests for local registry parsing and stale registry entries
+- [x] 5.9 Add tests or docs coverage for `.openspec-workspace/local.yaml` exclusion in OpenSpec-created workspaces
+- [x] 5.10 Run `openspec validate workspace-foundation --strict`
+- [x] 5.11 Run targeted test coverage for the new workspace foundation helpers