sauron-cli 1.2.0 → 1.3.0

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

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

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