sauron-cli 1.1.3 → 1.3.0

package/OpenSpec-main/openspec/changes/workspace-reimplementation-roadmap/POC_REFERENCE_GUIDE.md

@@ -0,0 +1,266 @@
+# Workspace POC Reference Guide
+
+This guide is for a fresh agent starting a new session with no prior context about the workspace POC.
+
+Root entry point: `START_HERE.md`.
+
+The goal is not to continue the POC. The goal is to use it as research material
+before preserving or replacing specific behavior from the current base.
+
+Current product authority lives in
+`openspec/initiatives/context-store-and-initiatives/`. Under that direction,
+workspace setup/open/update/doctor behavior remains useful local-view
+infrastructure. Workspace-level apply, verify, and archive research is deferred
+until initiative-linked repo-local changes exist.
+
+## Reference Point
+
+Use this exact commit as the stable reference:
+
+```text
+workspace-poc @ 79a45ac043f414e63d13e08b9da83b135cb20a39
+```
+
+Do not rely only on the moving branch name. Do not merge this commit into the implementation branch. Do not cherry-pick from it unless a later proposal explicitly decides that a small piece should be preserved.
+
+## What The POC Was Trying To Prove
+
+Start from the user journey:
+
+```text
+create workspace
+  -> add repos
+  -> open workspace with an agent
+  -> explore across repos
+  -> create a proposal
+  -> apply one repo slice
+  -> verify
+  -> archive
+```
+
+The POC is useful if it helps answer:
+
+- What did the user experience feel like when workspace mode worked?
+- Which CLI surfaces made the workflow easier to understand?
+- Which tests captured real product expectations?
+- Which implementation choices were shortcuts that should not survive?
+- Which terminology became misleading once the desired product shape was clearer?
+
+## First Files To Read
+
+Read these from the POC commit before implementation:
+
+```text
+WORKSPACE_REIMPLEMENTATION_DIRECTION.md
+WORKSPACE_POC_FOLLOWUP_NOTES.md
+docs/workspace.md
+docs/workspace-demo.md
+docs/cli.md
+src/commands/workspace.ts
+src/core/workspace/open.ts
+test/commands/workspace/open.test.ts
+test/core/workspace/open.test.ts
+test/cli-e2e/workspace/workspace-open-cli.test.ts
+```
+
+Optional deeper context:
+
+```text
+workspace-poc-explorer.html
+workspace-poc-phase-playground.html
+copilot-session-d4e9c61e-readable.md
+copilot-session-d4e9c61e-timeline.md
+```
+
+The optional files are historical research aids. Use them to understand how the POC evolved, not as implementation requirements.
+
+## How To Inspect The POC Safely
+
+Preferred approach: use a separate worktree or read files directly from the pinned commit.
+
+Example direct reads:
+
+```bash
+git show 79a45ac043f414e63d13e08b9da83b135cb20a39:WORKSPACE_REIMPLEMENTATION_DIRECTION.md
+git show 79a45ac043f414e63d13e08b9da83b135cb20a39:src/commands/workspace.ts
+git diff origin/main...79a45ac043f414e63d13e08b9da83b135cb20a39 --stat
+```
+
+Example separate worktree:
+
+```bash
+git worktree add ../openspec-workspace-poc 79a45ac043f414e63d13e08b9da83b135cb20a39
+```
+
+Keep the implementation branch based on the current target branch. The POC worktree is for reading and running tests only.
+
+## What To Bring Back
+
+Before implementing a slice, come back with a short POC findings note:
+
+```text
+POC findings for <slice>:
+
+User behavior to preserve:
+- ...
+
+Tests or examples worth translating:
+- ...
+
+Implementation shortcuts to avoid:
+- ...
+
+Open design questions:
+- ...
+```
+
+Put durable findings in the relevant OpenSpec proposal or design artifact. Do not leave important decisions only in chat.
+
+## Slice-Specific Reading
+
+### `workspace-foundation`
+
+Focus on:
+
+- workspace folder shape
+- metadata directory naming
+- local versus committed state
+- stable workspace name semantics
+
+Read:
+
+```text
+WORKSPACE_REIMPLEMENTATION_DIRECTION.md
+WORKSPACE_POC_FOLLOWUP_NOTES.md
+docs/workspace.md
+src/commands/workspace.ts
+```
+
+Bring back:
+
+- the storage model worth keeping
+- the metadata naming decision
+- any compatibility risks with repo-local `openspec/`
+
+### `workspace-create-and-register-repos`
+
+Focus on:
+
+- how a user creates a workspace
+- how repos or folders are linked
+- what `doctor` or equivalent status output should explain
+- how POC `create`/`add-repo` behavior maps to the target `setup`/`link`/`relink`/`doctor` flow before change creation
+- how planning-only repos and monorepo modules differ from implementation-ready repo-local OpenSpec projects
+
+Read:
+
+```text
+docs/workspace.md
+docs/workspace-demo.md
+src/commands/workspace.ts
+test/commands/workspace/setup.test.ts
+```
+
+Bring back:
+
+- expected commands
+- expected files
+- validation behavior for bad paths, duplicate workspace names, missing paths, planning-only links, and duplicate link names
+
+### `workspace-open-agent-context`
+
+Focus on:
+
+- what context the agent receives
+- how linked repos or folders become visible
+- how one-session agent selection should work
+- what should be stable guidance versus dynamic launch context
+
+Read:
+
+```text
+WORKSPACE_POC_FOLLOWUP_NOTES.md
+src/commands/workspace.ts
+src/core/workspace/open.ts
+test/commands/workspace/open.test.ts
+test/core/workspace/open.test.ts
+test/cli-e2e/workspace/workspace-open-cli.test.ts
+```
+
+Bring back:
+
+- launch-context requirements
+- agent-specific behavior to preserve
+- prompt or guidance text that should become stable instructions
+
+### `workspace-change-planning`
+
+Focus on:
+
+- when repo scope becomes a planning commitment
+- whether targets should be inferred from artifacts
+- how proposal, design, tasks, and specs should be arranged
+
+Read:
+
+```text
+WORKSPACE_REIMPLEMENTATION_DIRECTION.md
+docs/workspace.md
+docs/workspace-demo.md
+```
+
+Bring back:
+
+- the artifact shape to use
+- how targets should be confirmed
+- which POC target metadata ideas should be avoided or deferred
+
+### `workspace-apply-repo-slice`
+
+Focus on:
+
+- the terminology decision that apply means implementation
+- what context the agent needs to implement one repo slice
+- why materialization should not be the user-facing contract
+
+Read:
+
+```text
+WORKSPACE_REIMPLEMENTATION_DIRECTION.md
+WORKSPACE_POC_FOLLOWUP_NOTES.md
+```
+
+Bring back:
+
+- the normalized apply context shape
+- the user-facing apply contract
+- any POC materialization behavior that should be explicitly rejected
+
+### `workspace-verify-and-archive`
+
+Focus on:
+
+- partial repo completion versus full workspace completion
+- how verification should report gaps
+- how archive should avoid forcing repo-local planning copies
+
+Read:
+
+```text
+WORKSPACE_REIMPLEMENTATION_DIRECTION.md
+docs/workspace-demo.md
+```
+
+Bring back:
+
+- the minimum useful verify behavior
+- the archive preconditions
+- the distinction between repo-slice completion and workspace hard-done state
+
+## Ground Rules
+
+- Treat the POC as evidence, not inheritance.
+- Preserve user-visible lessons before preserving code.
+- Prefer current repo patterns over POC-only abstractions.
+- Implement one user-visible step at a time.
+- Update this roadmap when a POC lesson changes a later slice.

package/OpenSpec-main/openspec/changes/workspace-reimplementation-roadmap/README.md

@@ -0,0 +1,107 @@
+# Workspace Reimplementation Roadmap
+
+This change is the continuity layer for reimplementing workspace support across multiple sessions and branches.
+
+## Current Status
+
+This roadmap is historical and has been reframed by
+`openspec/initiatives/context-store-and-initiatives/`. Fresh agents should use
+the initiative direction as product authority and this roadmap as reference for
+POC lessons and preserved local-view behavior.
+
+Keep:
+
+- workspace setup, link, relink, list, open, update, and doctor
+- linked repos and folders as local planning context
+- workspace-local skills as local agent guidance
+- the POC as research material only
+
+Supersede:
+
+- workspace as the durable shared planning home
+- workspace-level planning artifacts as the canonical cross-repo plan
+- workspace change planning as the long-term source of truth
+
+Defer:
+
+- workspace apply, verify, and archive as first-class lifecycle commands
+- branch/worktree orchestration, strong cross-repo validation, and dependency
+  graph enforcement
+
+Do not pick up the next unfinished flat sibling change from this roadmap unless
+a later initiative-linked repo-change design explicitly reactivates it.
+
+Root entry point for fresh agents: `START_HERE.md`.
+
+The user journey this historical roadmap was implementing is:
+
+```text
+create workspace
+  -> add repos
+  -> open workspace with agent context
+  -> plan a cross-repo change
+  -> implement one repo slice
+  -> verify and archive
+```
+
+The POC branch is reference material only:
+
+```text
+workspace-poc @ 79a45ac043f414e63d13e08b9da83b135cb20a39
+```
+
+Use it to understand behavior, tests, and lessons learned. Do not merge it or preserve its architecture by default. The full source direction document from that branch is captured in `HISTORICAL_DIRECTION.md`.
+
+Fresh agents should read `POC_REFERENCE_GUIDE.md` before implementing any slice. That guide explains how to inspect the pinned POC commit, which files to read for each slice, and what findings to bring back into the OpenSpec artifacts.
+
+## Historical Change Order
+
+The original flat sibling changes were:
+
+1. `workspace-foundation`
+2. `workspace-create-and-register-repos`
+3. `workspace-open-agent-context`
+4. `workspace-change-planning`
+5. `workspace-agent-guidance`
+6. `workspace-apply-repo-slice`
+7. `workspace-verify-and-archive`
+
+OpenSpec currently discovers active changes as immediate directories under `openspec/changes/`, and change names are kebab-case identifiers. These changes remain useful reference artifacts, but they are no longer a direct implementation queue.
+
+## Dependency Notes
+
+`workspace-foundation` establishes the storage, root detection, and naming model. Every later slice should build on that model instead of redefining workspace metadata.
+
+`workspace-create-and-register-repos` creates the workspace and makes linked repos or folders visible before a change exists. Linked items may be full repos, monorepo modules, or planning-only folders. This preserves the product rule that workspace visibility is not change commitment.
+
+`workspace-open-agent-context` gives the agent the workspace location, linked repos or folders, active changes, and selected change scope.
+
+`workspace-change-planning` created the beta workspace-level planning commitment and identified target repo slices. Under the initiative direction, this model is legacy or transitional rather than the durable shared plan.
+
+`workspace-agent-guidance` makes workspace-local workflow skills use the planning model deliberately: inspect linked context, seed workspace changes with goal and known affected areas, and preserve linked repos as read-only planning context until apply selects an edit root.
+
+`workspace-apply-repo-slice` is deferred until initiative-linked repo-local changes define the implementation handoff.
+
+`workspace-verify-and-archive` is deferred until initiative status and linked repo-local change lifecycle exist.
+
+## Session Handoff Prompt
+
+Use this prompt at the start of future implementation sessions:
+
+```text
+Continue the context-store-and-initiatives direction. Read
+openspec/initiatives/context-store-and-initiatives/direction.md and
+openspec/initiatives/context-store-and-initiatives/roadmap.md first. Use
+openspec/changes/workspace-reimplementation-roadmap/START_HERE.md,
+openspec/changes/workspace-reimplementation-roadmap/README.md,
+openspec/changes/workspace-reimplementation-roadmap/HISTORICAL_DIRECTION.md,
+openspec/changes/workspace-reimplementation-roadmap/POC_REFERENCE_GUIDE.md, and
+workspace-poc at 79a45ac043f414e63d13e08b9da83b135cb20a39 as historical
+reference material only. Preserve useful local-view workspace behavior, but do
+not implement workspace apply, verify, or archive until initiative-linked
+repo-local changes exist.
+```
+
+## Branching Guidance
+
+Each sibling change may be implemented on its own branch or PR. Keep decisions that affect later slices in this README or in the relevant proposal so future sessions do not depend on chat history.

package/OpenSpec-main/openspec/changes/workspace-reimplementation-roadmap/START_HERE.md

@@ -0,0 +1,105 @@
+# Workspace Reimplementation Start Here
+
+This is the grep-friendly historical entry point for agents working on the
+workspace reimplementation.
+
+## Current Status
+
+The original workspace lifecycle roadmap has been reframed by the context store
+and initiatives direction. Fresh agents should treat this document and the POC
+materials as reference for preserved local-view infrastructure, not as the next
+implementation queue.
+
+Current product authority lives in:
+
+1. `openspec/initiatives/context-store-and-initiatives/direction.md`
+2. `openspec/initiatives/context-store-and-initiatives/roadmap.md`
+
+The locked boundary is:
+
+```text
+Context stores sync truth.
+Collections shape truth.
+Initiatives coordinate work.
+Workspaces open local views.
+Changes implement repo-owned slices.
+```
+
+Useful search terms:
+
+```text
+workspace reimplementation
+workspace poc
+workspace-poc
+workspace reference guide
+workspace roadmap
+fresh agent
+start here
+```
+
+## Start Here
+
+Read these files in order:
+
+1. `openspec/initiatives/context-store-and-initiatives/direction.md`
+2. `openspec/initiatives/context-store-and-initiatives/roadmap.md`
+3. `openspec/changes/workspace-reimplementation-roadmap/HISTORICAL_DIRECTION.md`
+4. `openspec/changes/workspace-reimplementation-roadmap/README.md`
+5. `openspec/changes/workspace-reimplementation-roadmap/POC_REFERENCE_GUIDE.md`
+
+The POC reference commit is:
+
+```text
+workspace-poc @ 79a45ac043f414e63d13e08b9da83b135cb20a39
+```
+
+Use the POC as research material. Do not merge it into an implementation branch.
+Do not preserve its architecture unless a later initiative or repo-local change
+design explicitly decides to do so.
+
+## Historical Implementation Order
+
+The original flat OpenSpec order was:
+
+1. `workspace-foundation`
+2. `workspace-create-and-register-repos`
+3. `workspace-open-agent-context`
+4. `workspace-change-planning`
+5. `workspace-agent-guidance`
+6. `workspace-apply-repo-slice`
+7. `workspace-verify-and-archive`
+
+Current disposition:
+
+- Keep setup, link, relink, list, open, update, and doctor as beta local-view
+  infrastructure.
+- Treat workspace planning as legacy or transitional behavior, not the durable
+  cross-repo source of truth.
+- Do not implement `workspace-apply-repo-slice` or
+  `workspace-verify-and-archive` as first-class workspace lifecycle commands
+  until initiative-linked repo-local changes exist.
+- Use `workspace-reimplementation-roadmap` as continuity and reference, not as
+  the active shipping sequence.
+
+## Before Editing
+
+For the slice you are about to implement, inspect the pinned POC commit using `POC_REFERENCE_GUIDE.md`, then write down:
+
+```text
+POC findings for <slice>:
+
+User behavior to preserve:
+- ...
+
+Tests or examples worth translating:
+- ...
+
+Implementation shortcuts to avoid:
+- ...
+
+Open design questions:
+- ...
+```
+
+Capture durable findings in the relevant initiative, context-store, or
+repo-local OpenSpec artifact so future sessions do not depend on chat history.

package/OpenSpec-main/openspec/changes/workspace-reimplementation-roadmap/proposal.md

@@ -0,0 +1,62 @@
+## Why
+
+Workspace support needs to be reimplemented as a user-facing workflow, not carried forward as a direct port of the proof of concept.
+
+Status: this roadmap is now historical reference. The active product direction is
+the context-store-and-initiatives initiative, where initiatives coordinate
+durable cross-repo work, workspaces open local views, and repo-local changes own
+implementation. Keep workspace setup/open/update/doctor infrastructure, but do
+not treat workspace apply, verify, or archive as the next shipping sequence
+until initiative-linked repo-local changes exist.
+
+A user should be able to say they have a multi-repo product goal, create a workspace, add the relevant repos, open that workspace with an agent, plan the change, implement one repo slice at a time, verify it, and archive it. The POC branch captured useful behavior and discovery, but its implementation should remain reference material rather than the base architecture.
+
+This roadmap also needs to survive multiple sessions and branches. Current OpenSpec change discovery treats active changes as flat immediate directories under `openspec/changes/`, and change names are kebab-case identifiers rather than nested paths. This change is therefore a flat planning container with sibling proposal changes instead of nested child changes.
+
+Reference material:
+
+- `workspace-poc` at `79a45ac043f414e63d13e08b9da83b135cb20a39`
+- `WORKSPACE_REIMPLEMENTATION_DIRECTION.md` on that branch
+- `WORKSPACE_POC_FOLLOWUP_NOTES.md` on that branch
+
+## What Changes
+
+Add a lightweight roadmap for reimplementing workspace support as a stack of flat sibling OpenSpec changes:
+
+- `workspace-foundation`
+- `workspace-create-and-register-repos`
+- `workspace-open-agent-context`
+- `workspace-change-planning`
+- `workspace-agent-guidance`
+- `workspace-apply-repo-slice`
+- `workspace-verify-and-archive`
+
+Each sibling change owns one step in the lived user journey. Dependencies are documented in proposal prose for now. When change stacking metadata lands, this roadmap can be migrated to explicit `parent` and `dependsOn` metadata.
+
+The intended order is:
+
+```text
+workspace-foundation
+  -> workspace-create-and-register-repos
+  -> workspace-open-agent-context
+  -> workspace-change-planning
+  -> workspace-agent-guidance
+  -> workspace-apply-repo-slice
+  -> workspace-verify-and-archive
+```
+
+## Capabilities
+
+### New Capabilities
+
+- `workspace-reimplementation-roadmap`: Coordinates the workspace reimplementation plan across multiple flat OpenSpec changes.
+
+### Modified Capabilities
+
+- `openspec-conventions`: Clarifies that this workspace effort uses flat sibling changes until nested or stacked change metadata is supported.
+
+## Impact
+
+- Planning only in this PR.
+- Future changes will affect workspace metadata, workspace CLI flows, agent context construction, workspace change planning, workspace-local agent guidance, repo-slice application, verification, and archive behavior.
+- No runtime behavior changes are introduced by this roadmap proposal.

package/OpenSpec-main/openspec/changes/workspace-verify-and-archive/proposal.md

@@ -0,0 +1,57 @@
+## Why
+
+Status: deferred by the context-store-and-initiatives direction. Per-repo
+progress visibility remains important, but verify/archive should be redesigned
+around initiative status and linked repo-local OpenSpec changes, not around
+workspace-owned final archive state. Do not implement this as a first-class
+workspace lifecycle command until that linkage exists.
+
+The remaining sections preserve the original workspace verify/archive direction
+for later reference. This work is still expected to matter after initiatives and
+initiative-linked repo-local changes exist; it is not the immediate next focus.
+
+Users need to know whether a cross-repo workspace change is complete without flattening all repo progress into one ambiguous done state.
+
+The desired lifecycle is:
+
+```text
+Verify each repo slice.
+See which slices are complete or still open.
+Archive repo-local results when appropriate.
+Archive the workspace change when the cross-repo goal is done.
+```
+
+Verification and archive should make the user's cross-repo status clearer, not force them to reason about internal artifact placement.
+
+## What Changes
+
+Add workspace-aware verify and archive behavior:
+
+- verify workspace-level change structure and target repo status
+- show per-repo slice progress
+- support repo-local archive work where needed
+- support explicit workspace-level archive when the coordinated goal is complete
+- avoid treating partial repo completion as full workspace completion
+
+Planning dependency:
+
+- Depends on `workspace-apply-repo-slice`.
+
+## Capabilities
+
+### New Capabilities
+
+- `workspace-verify-archive`: Verifies and archives workspace changes with per-repo progress visibility.
+
+### Modified Capabilities
+
+- `cli-archive`: Adds workspace-aware archive semantics.
+- `opsx-verify-skill`: Adds workspace verification guidance.
+- `opsx-archive-skill`: Adds workspace archive guidance.
+
+## Impact
+
+- Workspace status, verify, and archive behavior.
+- Per-repo slice completion reporting.
+- Workspace-level hard-done marker or equivalent archive state.
+- Tests for partial completion, final workspace archive, and compatibility with standalone repo-local archive flows.

package/OpenSpec-main/openspec/config.yaml

@@ -0,0 +1,36 @@
+schema: spec-driven
+
+context: |
+  Tech stack: TypeScript, Node.js (≥20.19.0), ESM modules
+  Package manager: pnpm
+  CLI framework: Commander.js
+
+  Product language:
+  - Write OpenSpec proposals and specs in user-facing product behavior language
+  - Requirements should describe the experience, observable behavior, and product contract
+  - Avoid implementation-negative SHALL statements when a positive user outcome can express the same rule
+  - Put internal mechanisms in design.md or tasks.md unless the mechanism is itself part of the user-facing contract
+
+  Cross-platform requirements:
+  - This tool runs on macOS, Linux, AND Windows
+  - Always use path.join() or path.resolve() for file paths - never hardcode slashes
+  - Never assume forward-slash path separators
+  - Tests must use path.join() for expected path values, not hardcoded strings
+  - Consider case sensitivity differences in file systems
+
+rules:
+  specs:
+    - Include scenarios for Windows path handling when dealing with file paths
+    - Requirements involving paths must specify cross-platform behavior
+    - Prefer user-facing product behavior and observable outcomes over internal implementation mechanics
+    - Include HOW details only when the mechanism is part of the product contract
+    - If we generate artifacts, specify deletion/modification by explicit list lookup, not pattern matching
+  tasks:
+    - Add Windows CI verification as a task when changes involve file paths
+    - Include cross-platform testing considerations
+  design:
+    - Document any platform-specific behavior or limitations
+    - Prefer Node.js path module over string manipulation for paths
+    - Use existing constants and lists - don't invent detection mechanisms
+    - Prefer explicit lookups over pattern matching or regex
+    - If we generate it, we track it by name in a constant