sauron-cli 1.3.0 → 1.4.1

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/10-let-workspaces-open-initiatives/plan.md

@@ -1,430 +0,0 @@
-# Let Workspaces Open Initiatives
-
-## Status
-
-Product decisions are locked. The remaining work is implementation design and
-delivery.
-
-## Source Of Truth
-
-Start from `../../direction.md` and the boundary:
-
-```text
-Context stores sync truth.
-Collections shape truth.
-Initiatives coordinate work.
-Workspaces open local views.
-Changes implement repo-owned slices.
-```
-
-Item 9 rejected standalone initiative resolution. Initiative discovery belongs
-to `initiative show`; local path mapping belongs to workspace local-view state.
-
-## Locked Direction
-
-A workspace does not contain the work. It remembers how this runtime opens the
-work.
-
-```text
-private local view record
-  -> generated runtime files
-  -> opener-specific launch
-  -> initiative context + selected local repos/folders
-```
-
-The durable part is the user's private local view choice. The generated part is
-runtime support for agents and editors.
-
-## Product Goal
-
-Let a user open a shared initiative in their own local runtime with the context
-and repos they care about.
-
-Examples:
-
-- A Team A developer opens `platform/billing-launch` with local Repo A and Repo
-  B.
-- A Team B developer opens the same initiative with local Repo C only.
-- A user opens the initiative context only, links repos later, and still gets
-  useful agent guidance.
-
-## Non-Goals
-
-- Do not clone repos.
-- Do not create branches or worktrees.
-- Do not use Git submodules as the workspace primitive.
-- Do not infer all participating repos from Git remotes or disk scans.
-- Do not write generated agent files into linked repos or context stores.
-- Do not make workspace-level `changes/` the durable planning model.
-- Do not enforce edit permissions in Item 10.
-
-## Decision Register
-
-### Command UX
-
-Status: decided.
-
-Use `workspace open` for initiative local-view realization:
-
-```bash
-openspec workspace open --initiative platform/billing-launch
-openspec workspace open --initiative billing-launch --store platform
-openspec workspace open --initiative billing-launch
-openspec workspace open team-a-billing --initiative platform/billing-launch
-```
-
-Rationale: the action being performed is local view realization, so the command
-belongs under `workspace open` rather than `initiative open`.
-
-Lookup behavior:
-
-- If the user provides `<store>/<initiative>`, use that exact store selector.
-- If the user provides `<initiative> --store <store>`, use that exact store
-  selector.
-- If the user provides only `<initiative>`, search registered context stores and
-  proceed when there is exactly one exact match.
-- If multiple stores contain the same initiative id, stop and show the matching
-  stores with a hint to retry using `<store>/<initiative>` or `--store`.
-- If no exact match exists, do not silently open the closest match. Show a small
-  list of likely matches when available, plus a hint to run `openspec
-  initiative list`.
-- If some registered stores cannot be read, keep the result conservative. Do not
-  choose a match that could be ambiguous behind an unreadable store unless the
-  user supplied an explicit store selector.
-
-Interactive UX may let a human choose from suggestions. JSON and non-interactive
-UX should return structured errors and suggestions without prompting.
-
-Workspace-name behavior:
-
-- The optional positional workspace name remains the local view identity.
-- If the user provides a workspace name with `--initiative`, create or reuse that
-  named local view.
-- If the user omits a workspace name, create or reuse a friendly default derived
-  from the initiative id when that is unambiguous.
-- On name collisions or multiple existing local views for the same initiative,
-  let the human choose interactively or require an explicit workspace name in
-  non-interactive mode.
-
-### Open Target
-
-Status: decided.
-
-Default to opening the initiative directory, not the whole context store.
-
-User-facing behavior:
-
-```bash
-openspec workspace open --initiative billing-launch
-```
-
-opens a focused local view:
-
-```text
-generated files in the workspace root
-context-store/initiatives/billing-launch/
-selected local repos/folders
-```
-
-It should not open the entire context store by default.
-
-Rationale:
-
-- The user asked for one initiative, so the opened context should be focused on
-  that initiative.
-- Agents receive less unrelated shared context.
-- Unrelated initiatives and shared files are not exposed by default.
-- The local view stays easier to understand: generated workspace root plus this
-  initiative plus selected implementation roots.
-
-Generated guidance and JSON output should still report the context store root
-and that broader context exists. A later explicit option may open the full
-context store, for example `--context-scope store` or `--include-store`, but
-broad store scope is not the default for Item 10.
-
-### Local View Record
-
-Status: decided.
-
-Use one private local view record: the root `workspace.yaml` file.
-
-```yaml
-version: 1
-name: billing-launch
-context:
-  kind: initiative
-  store:
-    id: platform
-    selector:
-      kind: registry
-      id: platform
-  initiative:
-    id: billing-launch
-links:
-  repo-a: /Users/me/repos/repo-a
-  repo-b: /Users/me/repos/repo-b
-preferred_opener: codex
-tools:
-  - codex
-```
-
-This decision covers the conceptual record shape and the fact that generated
-runtime files are not durable state.
-
-If the user selected a context store by local path, the private workspace record
-can keep that runtime-local selector without changing checked-in repo metadata:
-
-```yaml
-context:
-  kind: initiative
-  store:
-    id: platform
-    selector:
-      kind: path
-      path: /Users/me/context/platform
-      observed_id: platform
-  initiative:
-    id: billing-launch
-```
-
-The context binding is optional. A user can also create a workspace that is not
-linked to any initiative:
-
-```yaml
-version: 1
-name: team-a-local
-context: null
-links:
-  repo-a: /Users/me/repos/repo-a
-  repo-b: /Users/me/repos/repo-b
-preferred_opener: codex
-tools:
-  - codex
-```
-
-This is a first-class workspace shape, not only an edge case for initiative
-opening. Item 10 should preserve custom non-initiative workspaces while adding
-initiative-aware opening.
-
-### Workspace Storage And Generated Files
-
-Status: decided.
-
-Store each private workspace view under the user's OpenSpec global data
-directory, keyed by workspace name:
-
-```text
-getGlobalDataDir()/workspaces/<workspace-name>/
-```
-
-The workspace name is the local identity. The selected store and initiative, if
-any, are data inside the private record; they do not define the storage path.
-This keeps the workspace API generic enough for custom local views that are not
-initiative-linked.
-
-Initial shape:
-
-```text
-getGlobalDataDir()/workspaces/<workspace-name>/
-  workspace.yaml
-  AGENTS.md
-  <workspace-name>.code-workspace
-  .codex/
-    skills/
-  .claude/
-    skills/
-```
-
-`workspace.yaml` is the durable private view record and the only view file in
-Item 10. The other files are generated runtime support owned by OpenSpec. They
-may be overwritten by `workspace open`, `workspace update`, or a future explicit
-preparation surface.
-
-Do not add a separate generated-output directory for Item 10. The managed
-workspace root is already the private generated view.
-
-Initiative open defaults:
-
-- If the user provides a workspace name and no workspace exists, create that
-  workspace bound to the selected initiative.
-- If the user provides a workspace name and it already points at the same
-  initiative, reuse it and regenerate runtime files.
-- If the user provides a workspace name and it has no context binding, bind it
-  to the selected initiative only after clear user confirmation; in
-  non-interactive mode, fail and require an explicit future rebind/update
-  surface.
-- If the user provides a workspace name and it points at a different initiative
-  or context, do not silently repoint it. Stop with a clear error and require an
-  explicit future rebind/update surface.
-- If the user omits a workspace name and exactly one existing workspace points at
-  the selected initiative, reuse it.
-- If the user omits a workspace name and no existing workspace points at the
-  selected initiative, create a friendly default workspace name derived from the
-  initiative id only when that name is unused.
-- If the derived workspace name collides with another workspace, ask for an
-  explicit workspace name or show matching workspace choices instead of hiding
-  the collision behind a path convention.
-- If multiple workspaces point at the same initiative, let the user choose or
-  require an explicit workspace name in non-interactive mode.
-
-### Generated Runtime Files
-
-Status: decided.
-
-Generate runtime files at the workspace root, next to `workspace.yaml`.
-
-```text
-getGlobalDataDir()/workspaces/<workspace-name>/
-```
-
-The generated files can contain `AGENTS.md`, skills, launch prompts, and
-generated editor workspace files.
-
-Regeneration behavior:
-
-- `workspace open` regenerates the managed runtime files before launching the
-  opener.
-- `workspace update` regenerates the managed runtime files without changing
-  durable local view choices unless the user asked for a state change.
-- Generated files are OpenSpec-owned and may be overwritten each time.
-- `workspace.yaml` is not generated output and should not be overwritten except
-  when the local view record itself changes.
-
-### Runtime Identity
-
-Status: decided.
-
-Use `getGlobalDataDir()` as the runtime-local boundary. It is already
-cross-platform and resolves to the appropriate user data directory for macOS,
-Linux, Windows, Codespaces, WSL, SSH hosts, and containers.
-
-Local paths in `workspace.yaml` are valid only in the runtime that wrote them.
-If the same user opens the same initiative from another runtime, they create or
-relink that runtime's workspace there. Item 10 should not add path translation,
-shared machine identities, or an extra `<runtime-id>` path segment.
-
-### Prepare/JSON Surface
-
-Status: decided.
-
-Keep `workspace open --json` as a machine-facing receipt for the same open
-operation. Do not add `--prepare-only` for Item 10.
-
-The JSON response should be useful to agents and desktop integrations, not just
-a success boolean. It should include the workspace name, workspace root,
-generated file paths, selected context, opened roots, skipped or missing roots,
-opener, launch status, and warnings.
-
-Human-facing behavior remains the normal `workspace open` output. JSON mode is
-for tools that need structured facts after OpenSpec has prepared the workspace
-root and attempted the requested open.
-
-### Missing Paths At Open Time
-
-Status: decided.
-
-Workspace opening should be strict about the selected initiative/context and
-forgiving about optional linked local paths.
-
-- If the selected initiative cannot be resolved, fail before launch.
-- If the context store or initiative path is unavailable, fail before launch and
-  point to context-store registration/doctor guidance.
-- If a linked repo or folder is missing, warn and skip that root; do not block a
-  context-only or partially linked open.
-- Human output should name skipped links and suggest `workspace doctor` or
-  relink guidance.
-- JSON output should include skipped or missing roots and warnings.
-
-### Codex Desktop
-
-Status: decided.
-
-Open the generated workspace root as the Codex Desktop project. Surface the
-attached initiative path and linked repo/folder paths through generated guidance
-and the `workspace open --json` response.
-
-Do not depend on Desktop multi-root automation for Item 10. If Desktop later has
-a clearer multi-root contract, it can become an enhancement without changing the
-workspace storage model.
-
-### Edit Boundaries
-
-Status: decided.
-
-Item 10 emits advisory boundaries only. Generated context should distinguish
-coordination context from implementation targets, but it should not enforce
-write restrictions.
-
-The generated view should label initiative/context-store files as shared
-coordination context and linked repos/folders as local implementation context
-when selected. Strong enforcement can come later.
-
-## First-Run UX Sketch
-
-Status: deferred beyond the first implementation slice.
-
-This sketch captures the eventual human interactive flow. Item 10 should not
-depend on building a full guided setup wizard; the first implementation may use
-explicit flags and structured errors first.
-
-```text
-Found initiative: platform/billing-launch
-No local workspace view exists for this runtime.
-
-Create a local view?
-> Open context only
-  Link existing local repos/folders
-  Cancel
-```
-
-No option in this first-run flow should clone, branch, create worktrees, or
-create submodules.
-
-## Machine-Readable Open Contract
-
-`workspace open --json` is the machine-readable contract for the generated
-runtime context. Item 10 should not create a separate machine-readable view
-file; the durable view record is `workspace.yaml`.
-
-The JSON response should tell agents:
-
-- schema version
-- workspace name and workspace root
-- selected initiative id, title, and path
-- selected context store id and path
-- generated file paths
-- opened roots
-- skipped or missing roots
-- linked repo-local changes when known
-- advisory edit boundaries
-- next repair commands
-- warnings and launch status when produced by `workspace open --json`
-
-If no implementation target is selected, `allowedEditRoots` should be empty or
-explicitly advisory.
-
-The exact schema can evolve during implementation, but the JSON response should
-make the generated view self-describing enough for agents and desktop
-integrations without scraping human output.
-
-## Forward Compatibility
-
-The initial `context` record supports the selected context store and initiative.
-Do not design the YAML parser so narrowly that future records cannot add fields
-for configurable change homes, artifact homes, target bindings, or other
-collection/view metadata.
-
-## Compatibility Notes
-
-The current beta workspace implementation creates a managed root with
-`changes/`, `AGENTS.md`, `.gitignore`,
-`.openspec-workspace/workspace.yaml`, `.openspec-workspace/local.yaml`, and a
-durable `.code-workspace` file.
-
-Item 10's intended new shape is a root `workspace.yaml` plus generated runtime
-files at the managed workspace root. Existing beta workspaces should be treated
-as compatibility inputs. Migration or removal of all beta internals is deferred
-unless the implementation slice intentionally scopes that migration.
-
-For the initiative-opening model, generated runtime files are derived artifacts,
-not workspace truth.

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/10-let-workspaces-open-initiatives/tasks.md

@@ -1,43 +0,0 @@
-# Let Workspaces Open Initiatives Tasks
-
-## Decisions
-
-- [x] Create Item 10 work-item tracking notes.
-- [x] Lock the high-level direction: private local view record plus generated
-  runtime files.
-- [x] Decide command UX.
-- [x] Decide default open target.
-- [x] Decide private local view record shape.
-- [x] Decide private local view record storage namespace and keying.
-- [x] Decide generated runtime file location and lifetime.
-- [x] Decide runtime identity rules.
-- [x] Decide prepare/JSON surface.
-- [x] Decide Codex Desktop behavior.
-- [x] Decide Item 10 edit-boundary semantics.
-
-## Implementation Scope To Confirm Later
-
-- [x] Add or adapt workspace local-view state for initiative opening.
-- [x] Preserve non-initiative custom workspaces as first-class local views.
-- [x] Resolve initiative context through existing `initiative show` semantics.
-- [x] Implement workspace-name reuse and collision behavior for initiative open.
-- [x] Generate opener-specific runtime files.
-- [x] Return explicit machine-readable view context from `workspace open --json`.
-- [x] Launch agent/editor with generated workspace root plus initiative context and
-  selected local repos/folders.
-- [x] Warn and skip missing linked repos/folders at open time while failing on
-  missing selected initiative/context.
-- [x] Add doctor guidance for missing context stores, missing local links, stale
-  view records, and advisory edit boundaries.
-- [x] Ensure Item 10 opens known local paths only and does not clone, branch,
-  create worktrees, or use submodules.
-
-## Deferred
-
-- [ ] Multiple saved views per initiative.
-- [ ] Shared/exported workspace templates.
-- [ ] Repo auto-discovery or Git remote matching.
-- [ ] Strong edit-boundary enforcement.
-- [ ] Codex Desktop multi-root automation if the Desktop contract is not clear
-  enough for Item 10.
-- [ ] Migration or removal of all existing beta workspace root artifacts.