sauron-cli 1.3.0 → 1.4.0

package/OpenSpec-main/openspec/specs/workspace-open/spec.md

@@ -1,205 +0,0 @@
-# workspace-open Specification
-
-## Purpose
-Define how OpenSpec opens a workspace working set through a selected agent or
-VS Code editor, including workspace selection, opener resolution, launch
-behavior, linked path visibility, and durable workspace guidance.
-
-## Requirements
-### Requirement: Workspace Open Command
-OpenSpec SHALL provide a `workspace open` command that opens an OpenSpec workspace working set through an agent or VS Code editor.
-
-#### Scenario: Opening the current workspace
-- **GIVEN** the command runs from inside an OpenSpec workspace
-- **WHEN** the user runs `openspec workspace open`
-- **THEN** OpenSpec SHALL open that current workspace
-- **AND** it SHALL use the selected opener for that workspace
-
-#### Scenario: Opening a named workspace
-- **GIVEN** a workspace named `platform` is known locally
-- **WHEN** the user runs `openspec workspace open platform`
-- **THEN** OpenSpec SHALL open the `platform` workspace
-
-#### Scenario: Opening a named workspace with the selection flag
-- **GIVEN** a workspace named `platform` is known locally
-- **WHEN** the user runs `openspec workspace open --workspace platform`
-- **THEN** OpenSpec SHALL open the `platform` workspace
-
-#### Scenario: Conflicting workspace selectors
-- **GIVEN** workspaces named `platform` and `checkout` are known locally
-- **WHEN** the user runs `openspec workspace open platform --workspace checkout`
-- **THEN** OpenSpec SHALL fail with a clear conflict error
-- **AND** the error SHALL name both conflicting selectors
-
-#### Scenario: Handling unsupported preview and JSON flags
-- **WHEN** the user runs `openspec workspace open` with `--prepare-only` or `--json`
-- **THEN** OpenSpec SHALL fail with a clear error that the root workspace open surface supports launching through a selected opener
-- **AND** the error SHALL direct preview or machine-readable context needs to a future context/query surface
-
-#### Scenario: Handling change-scoped open before workspace planning
-- **WHEN** the user runs `openspec workspace open --change <id>`
-- **THEN** OpenSpec SHALL fail with a clear error that this slice supports root workspace open
-- **AND** the error SHALL direct change-scoped open behavior to future workspace change planning
-
-### Requirement: Workspace Selection For Open
-OpenSpec SHALL resolve the workspace to open using current workspace context, local registry state, and interactive selection.
-
-#### Scenario: Current workspace wins
-- **GIVEN** the command runs from a workspace folder or one of its subdirectories
-- **AND** no workspace name is provided
-- **WHEN** the user runs `openspec workspace open`
-- **THEN** OpenSpec SHALL open the current workspace
-
-#### Scenario: Auto-selecting the only known workspace
-- **GIVEN** the command runs outside a workspace
-- **AND** exactly one workspace is known locally
-- **WHEN** the user runs `openspec workspace open`
-- **THEN** OpenSpec SHALL open that known workspace directly
-
-#### Scenario: Picking from multiple workspaces
-- **GIVEN** the command runs outside a workspace
-- **AND** multiple workspaces are known locally
-- **AND** the terminal is interactive
-- **WHEN** the user runs `openspec workspace open`
-- **THEN** OpenSpec SHALL present a picker with workspace names and locations
-- **AND** it SHALL open the workspace the user selects
-
-#### Scenario: Non-interactive ambiguous selection
-- **GIVEN** the command runs outside a workspace
-- **AND** multiple workspaces are known locally
-- **AND** the terminal is non-interactive
-- **WHEN** the user runs `openspec workspace open`
-- **THEN** OpenSpec SHALL fail with a clear message listing the known workspace names
-- **AND** it SHALL ask the user to pass a workspace name
-
-#### Scenario: No known workspace
-- **GIVEN** the command runs outside a workspace
-- **AND** no workspaces are known locally
-- **WHEN** the user runs `openspec workspace open`
-- **THEN** OpenSpec SHALL fail with a clear message
-- **AND** it SHALL suggest running `openspec workspace setup`
-
-### Requirement: Opener Resolution
-OpenSpec SHALL resolve the opener from command overrides, workspace-local preference, or an interactive prompt.
-
-#### Scenario: Conflicting opener overrides
-- **WHEN** the user runs `openspec workspace open --agent codex --editor`
-- **THEN** OpenSpec SHALL fail with a clear conflict error naming `--agent` and `--editor`
-- **AND** it SHALL avoid launching any opener
-- **AND** it SHALL leave the stored preferred opener unchanged
-
-#### Scenario: Using the stored preferred opener
-- **GIVEN** the workspace has a machine-local preferred opener
-- **WHEN** the user runs `openspec workspace open` using default opener resolution
-- **THEN** OpenSpec SHALL use the stored preferred opener
-
-#### Scenario: Overriding with an agent for one session
-- **GIVEN** the workspace has a stored preferred opener
-- **WHEN** the user runs `openspec workspace open --agent codex`
-- **THEN** OpenSpec SHALL use Codex for that open command
-- **AND** it SHALL leave the stored preferred opener unchanged
-
-#### Scenario: Overriding with VS Code editor for one session
-- **GIVEN** the workspace has a stored preferred opener
-- **WHEN** the user runs `openspec workspace open --editor`
-- **THEN** OpenSpec SHALL open the workspace in VS Code editor mode
-- **AND** it SHALL leave the stored preferred opener unchanged
-
-#### Scenario: Prompting when no opener is stored
-- **GIVEN** the workspace has no stored preferred opener
-- **AND** the terminal is interactive
-- **WHEN** the user runs `openspec workspace open` using default opener resolution
-- **THEN** OpenSpec SHALL prompt the user to choose an opener
-- **AND** it SHALL only offer openers with detected executables
-
-#### Scenario: Failing when no opener can be prompted
-- **GIVEN** the workspace has no stored preferred opener
-- **AND** the terminal is interactive
-- **AND** no supported opener executable is available on `PATH`
-- **WHEN** the user runs `openspec workspace open` using default opener resolution
-- **THEN** OpenSpec SHALL fail with a clear message that no supported opener is available
-- **AND** it SHALL avoid prompting with unlaunchable choices
-
-#### Scenario: Failing when no opener is stored in non-interactive mode
-- **GIVEN** the workspace has no stored preferred opener
-- **AND** the terminal is non-interactive
-- **WHEN** the user runs `openspec workspace open` using default opener resolution
-- **THEN** OpenSpec SHALL fail with a clear message
-- **AND** it SHALL ask the user to pass `--agent <tool>` or `--editor`
-
-### Requirement: Opener Launch Behavior
-OpenSpec SHALL launch the selected opener using existing workspace files and linked path state.
-
-#### Scenario: Opening VS Code editor
-- **GIVEN** the user selected the VS Code editor opener
-- **WHEN** `code` is available on `PATH`
-- **THEN** OpenSpec SHALL open the workspace's maintained `.code-workspace` file with VS Code
-
-#### Scenario: Opening GitHub Copilot in VS Code
-- **GIVEN** the user selected `--agent github-copilot`
-- **WHEN** `code` is available on `PATH`
-- **THEN** OpenSpec SHALL open the workspace's maintained `.code-workspace` file with VS Code
-- **AND** it SHALL treat this as the VS Code Copilot experience
-
-#### Scenario: Opening Codex
-- **GIVEN** the user selected `--agent codex`
-- **WHEN** `codex` is available on `PATH`
-- **THEN** OpenSpec SHALL launch Codex from the workspace root
-- **AND** it SHALL attach every linked repo or folder with a valid local path using Codex's supported directory attachment mechanism
-
-#### Scenario: Opening Claude
-- **GIVEN** the user selected `--agent claude`
-- **WHEN** `claude` is available on `PATH`
-- **THEN** OpenSpec SHALL launch Claude from the workspace root
-- **AND** it SHALL attach every linked repo or folder with a valid local path using Claude's supported directory attachment mechanism
-
-#### Scenario: Missing opener executable
-- **GIVEN** the selected opener requires an executable that is not available on `PATH`
-- **WHEN** the user runs `openspec workspace open`
-- **THEN** OpenSpec SHALL fail with a clear error naming the missing executable
-- **AND** it SHALL keep the selected opener as the required opener
-
-#### Scenario: Missing VS Code executable
-- **GIVEN** the selected opener is VS Code editor or GitHub Copilot in VS Code
-- **AND** `code` is not available on `PATH`
-- **WHEN** the user runs `openspec workspace open`
-- **THEN** OpenSpec SHALL fail with a clear error naming `code`
-- **AND** it SHALL include the maintained `.code-workspace` path so the user can open it manually
-
-### Requirement: Linked Working Set Visibility
-OpenSpec SHALL make linked repos and folders visible for workspace exploration and planning before change creation.
-
-#### Scenario: Attaching valid linked paths
-- **GIVEN** a workspace has linked repos or folders with valid local paths
-- **WHEN** the user opens the workspace through an opener that supports linked directory attachment
-- **THEN** OpenSpec SHALL include every valid linked path in the opened working set
-- **AND** it SHALL support opening before a workspace change exists
-
-#### Scenario: Skipping broken linked paths
-- **GIVEN** a workspace has at least one linked path that is missing or not recorded locally
-- **WHEN** the user opens the workspace
-- **THEN** OpenSpec SHALL skip the broken linked path
-- **AND** it SHALL report that the path was skipped with `openspec workspace doctor` as the repair path
-- **AND** it SHALL continue opening the workspace when the selected opener itself is available
-
-#### Scenario: Opening links with repo-local OpenSpec state absent
-- **GIVEN** a linked repo or folder has a valid local path and repo-local `openspec/` state is absent
-- **WHEN** the user opens the workspace
-- **THEN** OpenSpec SHALL include that link when its local path is valid
-- **AND** it SHALL treat missing repo-local OpenSpec state as an implementation-readiness concern for later workflows while continuing open
-
-### Requirement: Workspace Open Guidance
-OpenSpec SHALL use durable workspace guidance as the primary context source for root workspace open.
-
-#### Scenario: Launching with existing workspace guidance
-- **GIVEN** the workspace has OpenSpec-managed guidance in `AGENTS.md`
-- **WHEN** the user opens the workspace
-- **THEN** OpenSpec SHALL refresh the maintained `.code-workspace` from current linked path state
-- **AND** it SHALL launch the selected opener against refreshed workspace files
-- **AND** it SHALL use durable workspace files as the primary workspace-open artifact
-
-#### Scenario: Minimal required launch prompt
-- **GIVEN** an opener requires an initial prompt argument
-- **WHEN** OpenSpec launches that opener
-- **THEN** OpenSpec SHALL use a minimal prompt such as `Open this OpenSpec workspace.`
-- **AND** durable workspace rules SHALL remain in workspace files

package/OpenSpec-main/openspec-parallel-merge-plan.md

@@ -1,98 +0,0 @@
-# OpenSpec Parallel Delta Remediation Plan
-
-## Problem Summary
-- Active changes apply requirement-level replacements when archiving. When two changes touch the same requirement, the second archive overwrites the first and silently drops scenarios (e.g., Windsurf vs. Kilo Code slash command updates).
-- The archive workflow (`src/core/archive.ts:191` and `src/core/archive.ts:501`) rebuilds main specs by replacing entire requirement blocks with the content contained in the change delta. The delta format (`src/core/parsers/requirement-blocks.ts:113`) has no notion of base versions or scenario-level operations.
-- The tooling cannot detect divergence between the change author’s starting point and the live spec, so parallel development corrupts the source of truth without warning.
-
-## Observed Failure Mode
-- Change A (`add-windsurf-workflows`) adds a Windsurf scenario under `Slash Command Configuration`.
-- Change B (`add-kilocode-workflows`) adds a Kilo Code scenario to the same requirement, starting from the pre-Windsurf spec.
-- After Change A archives, the main spec contains both scenarios.
-- When Change B archives, `buildUpdatedSpec` sees a `MODIFIED` block for `Slash Command Configuration` and replaces the requirement with the four-scenario variant shipped in that change. Because that file never learned about Windsurf, the Windsurf scenario disappears.
-- There is no warning, diff, or conflict indicator—the archive completes successfully, and the source-of-truth spec now omits a shipped scenario.
-
-## Root Causes
-1. **Replace-only semantics.** `buildUpdatedSpec` performs hash-map substitution of requirement blocks and cannot merge or compare individual scenarios (`src/core/archive.ts:455`-`src/core/archive.ts:526`).
-2. **Missing base fingerprint.** Changes do not persist the requirement content they were authored against, so the archive step cannot tell if the live spec diverged.
-3. **Single-level granularity.** The delta language only understands requirements. Even if we introduced scenario-level parsing, we would still lose sibling edits without an accompanying merge strategy.
-4. **Lack of conflict UX.** The CLI never forces contributors to reconcile parallel updates. There is no equivalent of `git merge`, `git rebase`, or conflict markers.
-
-## Design Objectives
-- Preserve every approved scenario regardless of archive order.
-- Detect and block speculative archives when the live spec diverges from the author’s base.
-- Provide a deterministic, reviewable conflict resolution flow that mirrors source-control best practices.
-- Keep the authoring experience ergonomic: deltas should remain human-editable markdown.
-- Support incremental adoption so existing repositories can roll forward without breaking active work.
-
-## Proposed Fix: Layered Remediation
-
-### Phase 0 – Stop the Bleeding (Detection & Guardrails)
-1. **Persist requirement fingerprints alongside each change.**
-   - When scaffolding or validating a change, capture the current requirement body for every `MODIFIED`/`REMOVED`/`RENAMED` entry and write it to `changes/<id>/meta.json`.
-   - Store a stable hash (e.g., SHA-256) of the base requirement content and the raw text itself for later merges.
-2. **Validate fingerprints during archive.**
-   - Before `buildUpdatedSpec` mutates specs, recompute the requirement hash from the live spec.
-   - If the hash differs from the stored base, abort and instruct the user to rebase. This makes the destructive path impossible.
-3. **Surface intent in CLI output.**
-   - Show which requirements are stale, when they diverged, and which change last touched them.
-4. **Document interim manual mitigation.**
-   - Update `openspec/AGENTS.md` and docs so contributors know to rerun `openspec change sync` (see Phase 1) whenever another change lands.
-
-_Outcome:_ We prevent data loss immediately while we work on a richer merge story.
-
-### Phase 1 – Add a Rebase Workflow (Author-Side Merge)
-1. **Introduce `openspec change sync <id>` (or `rebase`).**
-   - Reads the stored base snapshot, the current spec, and the author’s delta.
-   - Performs a 3-way merge per requirement. A naive diff3 on markdown lines is acceptable initially because we already operate on requirement-sized chunks.
-   - If the merge is clean, rewrite the `MODIFIED` block with the merged text and refresh the stored fingerprint.
-   - On conflict, write conflict markers inside the change delta (similar to Git) and require the author to hand-edit before re-running validation.
-2. **Enrich validator messages.**
-   - `openspec validate` should flag unresolved conflict markers or fingerprint mismatches so errors appear early in the workflow.
-3. **Optional:** Offer a `--rewrite-scenarios` helper that merges bullet lists of scenarios to reduce manual editing noise.
-
-_Outcome:_ Contributors can safely reconcile their work with the latest spec before archiving, restoring true parallel development.
-
-### Phase 2 – Increase Delta Granularity
-1. **Extend the delta language with scenario-level directives.**
-   - Allow `## MODIFIED Requirements` + `## ADDED Scenarios` / `## MODIFIED Scenarios` sections nested under the requirement header.
-   - Backed by stable scenario identifiers (explicit IDs or generated hashes) stored in `meta.json`. This lets the system reason about individual scenarios.
-2. **Teach the parser to understand nested operations.**
-   - Update `parseDeltaSpec` to emit scenario-level operations in addition to requirement blocks.
-   - Update `buildUpdatedSpec` (or its replacement) to merge scenario lists, preserving order while inserting new entries in a deterministic fashion.
-3. **Automate migration.**
-   - Provide a one-time command that inspects each existing spec, injects scenario IDs, and rewrites in-flight change deltas into the richer format.
-4. **Continue to rely on the Phase 1 rebase flow for conflicts when two changes edit the same scenario body or description.**
-
-_Outcome:_ Most concurrent updates become commutative, drastically reducing the odds of human merges.
-
-### Phase 3 – Structured Spec Graph (Long-Term)
-1. **Define stable requirement IDs.**
-   - Embed `Requirement ID: <uuid>` markers in specs so renames and moves are trackable.
-   - This enables future features like cross-capability references and better diff visualizations.
-2. **Model spec edits as operations over an AST.**
-   - Build an intermediate representation (IR) for requirements/scenarios/metadata.
-   - Use operational transforms or CRDT-like techniques to guarantee merge associativity.
-3. **Integrate with Git directly.**
-   - Offer optional `openspec branch` scaffolding that aligns spec changes with Git branches, letting teams leverage Git’s conflict editor for the markdown IR.
-
-_Outcome:_ OpenSpec graduates from replace-based updates to a resilient, intent-preserving spec management platform.
-
-## Migration & Product Impacts
-- **Backfill metadata:** add hashes for all active changes and the current main specs during the initial rollout.
-- **CLI UX:** new commands (`change sync`, enhanced `archive`) require documentation, help text, and release notes.
-- **Docs & AGENTS updates:** reinforce the rebase workflow and explain conflict resolution to AI assistants.
-- **Testing:** introduce fixtures covering divergent requirement fingerprints and merge resolution logic.
-- **Telemetry (optional):** log fingerprint mismatches so we can see how often teams hit conflicts after the rollout.
-
-## Open Questions / Risks
-- How should we order scenarios when multiple changes insert at different points? (Consider optional `position` metadata or deterministic alphabetical fallbacks.)
-- What is the graceful failure mode if contributors delete the `meta.json` file? (CLI should recreate fingerprints on demand.)
-- Do we need to support offline authors who cannot easily re-run the sync command before archiving? (Potential `--accept-outdated` escape hatch for emergencies.)
-- How will archived historical changes be handled? We may need a migration script to embed fingerprints retroactively so re-validation succeeds.
-
-## Immediate Next Steps
-1. Prototype fingerprint capture during `openspec change validate` and block archive on mismatches.
-2. Ship `openspec change sync` with line-based diff3 merging and conflict markers.
-3. Update contributor docs and AI instructions to mandate running `sync` before archiving.
-4. Plan the scenario-level delta extension and migration path as a follow-up RFC.