sauron-cli 1.3.0 → 1.4.1

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

@@ -1,142 +0,0 @@
-## 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

@@ -1,29 +0,0 @@
-## 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

@@ -1,199 +0,0 @@
-## 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

@@ -1,56 +0,0 @@
-## 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