sauron-cli 1.1.3 → 1.3.0

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/decisions.md

@@ -0,0 +1,204 @@
+# Context Store And Initiatives Decisions
+
+## 2026-05-20: Track Roadmap Execution Inside The Initiative
+
+Decision: Track initiative roadmap implementation inside
+`openspec/initiatives/context-store-and-initiatives/` rather than creating an
+OpenSpec change for each roadmap item.
+
+Why: The initiative is the durable coordination object for this work. Repo-local
+OpenSpec changes should be reserved for implementation slices owned by a repo or
+team. Roadmap-item tracking belongs with the initiative until a task needs a
+repo-owned implementation plan.
+
+Implications:
+
+- Use `tasks.md` as the initiative-wide progress dashboard.
+- Use `work-items/<nn-slug>/` for detailed execution notes on one roadmap item.
+- Link repo-local OpenSpec changes back to the initiative later when
+  implementation moves into a repo-owned slice.
+
+## 2026-05-20: Lock Workspace-To-Initiative Product Boundary
+
+Decision: Workspaces are local working views, not durable shared planning
+objects. Durable coordination belongs to context stores and initiatives. Repo
+local changes own implementation.
+
+Implications:
+
+- Preserve workspace setup, link, relink, list, open, update, and doctor as
+  beta local-view infrastructure.
+- Treat workspace-planning behavior as beta or transitional compatibility.
+- Defer workspace apply, verify, and archive until initiative-linked repo-local
+  changes exist.
+
+## 2026-05-21: Leave Specs Alone Until Behavior Changes
+
+Decision: Do not use the initial direction lock to rewrite OpenSpec specs.
+Specs should describe the current behavioral contract behind the code. The
+initiative artifacts should carry product intent, roadmap decisions, and future
+direction until a later implementation change deliberately updates behavior and
+its specs together.
+
+Implications:
+
+- Initial Item 1 cleanup should focus on initiative docs, historical roadmap
+  artifacts, active proposal disposition, and user-facing docs.
+- Existing workspace-planning specs and schemas may continue to describe current
+  implemented behavior.
+- Future changes to specs should happen with the behavior they govern.
+
+## 2026-05-21: Keep Deferred Workspace Changes As Reference Placeholders
+
+Decision: Keep the active workspace changes for agent guidance, repo-slice
+apply, verify/archive, and the reimplementation roadmap as deferred reference
+placeholders.
+
+Why: These areas are still expected to matter after context stores, initiatives,
+and initiative-linked repo-local changes exist. Archiving or deleting them now
+would lose useful research and continuity.
+
+Implications:
+
+- Do not pick them up as the immediate next implementation focus.
+- Treat their current proposals as historical/deferred direction.
+- Revisit and reframe them after initiative-linked repo-local changes define the
+  durable handoff model.
+
+## 2026-05-21: Generated Workspace Guidance Routes Work By Ownership
+
+Decision: Generated workspace guidance should describe workspaces as local
+working views and route durable work to the owning artifact: initiatives own
+cross-team or cross-repo intent, repo-local OpenSpec changes own implementation
+plans, and linked repos or folders own their implementation.
+
+Why: The initiative direction supersedes the older model where a workspace-level
+`changes/` tree owned the canonical shared cross-repo plan. New agent guidance
+should not reinforce that old model.
+
+Implications:
+
+- Remove guidance that tells agents to use workspace-level `changes/` as the
+  planning home for coordinated work.
+- Keep legacy or beta workspace-planning files readable as compatibility
+  context when present.
+- Update generated workspace guidance before broad user-facing docs or specs.
+- Leave specs untouched until the corresponding behavior intentionally changes.
+
+## 2026-05-21: Workspace Action Context Is Local Compatibility Context
+
+Decision: Workspace-planning action context should no longer describe
+workspace-level artifacts as the source of truth. It should report
+`sourceOfTruth: "workspace-local"` and describe workspace-local planning
+artifacts as compatibility context for the current local view.
+
+Why: Workspace-planning artifacts can still exist in the beta workflow, but the
+initiative direction assigns durable coordination to initiatives and
+implementation planning to repo-local changes.
+
+Implications:
+
+- Keep `actionContext.mode: "workspace-planning"` for compatibility.
+- Keep `allowedEditRoots: []` until an explicit edit root is selected.
+- Keep linked repos and folders as context, not implicit edit roots.
+- Route durable coordination to initiatives when initiative context exists.
+
+## 2026-05-21: Reorder Roadmap Around Agent-First Initiative Handoff
+
+Decision: Treat initiatives as an agent-first workflow. Users should be able to
+prompt an agent with intent like "using initiative X, explore Y and create a
+proposal"; OpenSpec should provide small CLI primitives the agent can compose.
+
+Why: The practical UX is not a human manually typing every coordination command.
+Agents need reliable structured answers about where canonical initiative context
+lives and how repo-local changes reference it. Local paths come from workspace
+state, not from an initiative command.
+
+Implications:
+
+- Promote minimal context-store setup, registration, listing, and doctoring
+  before workspace initiative opening.
+- Add `initiative show --json` before broader progress/status concepts.
+- Connect repo-local changes with checked-in initiative metadata, not checked-in
+  snapshots of initiative prose.
+- Do not add `initiative resolve`; workspace local-view state owns local path
+  mapping.
+- Teach workspace opening about initiatives after show and repo-change linkage
+  semantics exist.
+
+## 2026-05-26: Workspace Initiative Opening Uses Generated Runtime Files
+
+Decision: Treat workspace initiative opening as a private local view record plus
+generated runtime files. The workspace does not contain the work. It remembers
+how this runtime opens the work.
+
+Why: Initiative context is shared truth in the context store, repo-local changes
+own implementation, and agent/editor affordances need to exist in the runtime
+where the agent actually runs. Persisting generated files as workspace truth
+would blur local view state with shared coordination and create stale or
+privacy-sensitive artifacts.
+
+Implications:
+
+- Persist only tiny private local view choices: selected store, selected
+  initiative, selected local links, opener, and selected tools.
+- Preserve the selected context-store selector inside the private workspace
+  record, so a runtime-local `--store-path` open can be reopened without writing
+  machine-local paths into checked-in repo metadata.
+- Generate agent guidance, skills, launch prompts, and editor workspace files as
+  runtime support when opening or preparing a view.
+- Open existing local paths only; do not clone, branch, create worktrees, use
+  submodules, or infer local repos in Item 10.
+- Treat generated runtime files as disposable and regenerable.
+- Allow context-only initiative open; linked repos are optional local view
+  choices.
+- Keep edit boundaries advisory in Item 10 until enforcement is designed.
+
+## 2026-05-26: Workspace Storage Is Keyed By Workspace Name
+
+Decision: Store private workspace views under
+`getGlobalDataDir()/workspaces/<workspace-name>/`. The workspace name is the
+local identity. The selected context store and initiative, if any, live inside
+one durable private `workspace.yaml` record.
+
+Why: Workspaces are generic local views, not initiative-owned directories. A
+user may want a custom workspace with linked repos and folders but no initiative,
+or multiple personal workspaces over the same initiative. Keying storage by
+store and initiative would overfit the filesystem layout to one workflow.
+
+Implications:
+
+- Keep initiative references optional inside `workspace.yaml`.
+- Store initiative context with an explicit context-store binding rather than a
+  flat store id, because workspace state may need to remember a registry selector
+  or a runtime-local path selector.
+- Generate `AGENTS.md`, opener workspace files, and tool-specific skills at the
+  managed workspace root.
+- Keep `workspace.yaml` as the only view file for Item 10; do not add a separate
+  machine-readable view file.
+- Do not introduce a separate generated-output directory for Item 10.
+- If the user opens an initiative without a workspace name, derive a friendly
+  default workspace name from the initiative id when that is unambiguous.
+- On workspace-name collisions or multiple workspaces pointing at the same
+  initiative, ask the human to choose or require an explicit workspace name in
+  non-interactive mode.
+
+## 2026-05-26: Item 10 Workspace Open UX Decisions
+
+Decision: Close the remaining Item 10 product decisions around runtime identity,
+JSON output, Codex Desktop, edit boundaries, and implementation scope.
+
+Implications:
+
+- Use `getGlobalDataDir()` as the cross-platform runtime-local boundary. Do not
+  add path translation or a separate runtime id in Item 10.
+- Keep `workspace open --json` as a machine-facing receipt for the same open
+  operation. It should return useful generated paths, selected context, opened
+  roots, skipped roots, opener, launch status, and warnings.
+- Do not add `--prepare-only` for Item 10.
+- For Codex Desktop, open the generated workspace root as the project and expose
+  attached initiative and repo/folder paths through generated guidance and
+  `workspace open --json` output.
+- Emit advisory edit boundaries only; do not enforce write restrictions.
+- Continue to open known existing local paths only. Do not clone, branch, create
+  worktrees, use submodules, or infer local repos in Item 10.

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/direction.md

@@ -0,0 +1,447 @@
+# Context Store And Initiatives Direction
+
+This document captures the suggested direction from the workspace/initiative
+discussion. The main shift is that "workspace" should not be the durable shared
+planning object. The durable shared object is a synced context store, and
+initiatives are one opinionated collection inside it.
+
+## Core Model
+
+```text
+Context Store
+  = synced shared content container
+
+Collection
+  = mounted content system inside a store
+
+Initiatives
+  = first major collection for cross-team implementation context
+
+Workspace
+  = local working view over context stores and repos
+
+Change
+  = repo/team-owned implementation plan
+```
+
+The clean rule:
+
+```text
+Context stores sync truth.
+Collections shape truth.
+Initiatives coordinate work.
+Workspaces open local views.
+Changes implement repo-owned slices.
+```
+
+## Locked Product Boundary
+
+The workspace-to-initiative pivot is now the product boundary for future
+coordination work:
+
+- A workspace is a regenerable, machine-local working view. It maps context
+  stores, initiatives, projects, repos, and folders to paths the current user can
+  open.
+- A context store is the durable synced container for shared files.
+- An initiative is the durable coordination object for cross-team or cross-repo
+  implementation context.
+- A repo-local change remains the implementation plan owned by the repo or team
+  doing the work.
+
+This supersedes the older model where a workspace-level `changes/` tree owned
+the canonical shared plan for cross-repo work. Existing workspace-planning
+behavior can remain as beta or legacy infrastructure, but it should not steer
+new lifecycle design.
+
+Workspace roadmap disposition:
+
+- Keep setup, link, relink, list, open, update, and doctor.
+- Keep linked repos and folders visible for exploration before a change exists.
+- Keep workspace-local agent guidance as local view setup, refreshed by
+  `workspace update`.
+- Defer workspace apply, verify, and archive until initiatives can link to
+  repo-owned OpenSpec changes.
+- Defer branch/worktree orchestration, multi-repo apply, strong cross-repo
+  validation, and dependency graph enforcement.
+
+## Agent-First UX
+
+The primary user experience for initiatives is expected to be agent-driven:
+
+```text
+Using initiative billing-launch, explore the API work and create a proposal.
+```
+
+The user should not need to know every command. OpenSpec should expose small,
+structured CLI primitives that an agent can use to:
+
+- find the intended initiative across registered context stores
+- read canonical initiative files from the context store
+- create or link a repo-local OpenSpec change
+- use workspace state for local repo and folder views
+- respect edit boundaries instead of treating every opened folder as editable
+
+The CLI is therefore the agent's tool surface, not the whole user workflow.
+Prefer explicit, machine-readable commands such as `initiative show --json`,
+`new change --initiative ...`, and workspace local-view commands over broad
+interactive flows as the first slice.
+
+Canonical initiative context should stay in the context store. Repo-local
+changes should reference the initiative rather than checking in copied snapshots
+of initiative prose. If an agent needs a compact context pack, OpenSpec can
+generate that as command output from the live initiative context.
+
+## Context Store
+
+A context store is the shared/synced folder of files. It is content-agnostic.
+It should not know what an initiative is.
+
+Example:
+
+```text
+acme-context/
+  initiatives/
+  decisions/
+  api-catalog/
+  playbooks/
+```
+
+The first backend should be Git:
+
+```text
+create/update/delete files
+  -> commit
+  -> push
+  -> other users pull
+  -> local views update
+```
+
+But the application should talk to a store abstraction, not directly to Git, so
+the backend can later become a cloud database.
+
+## Backend
+
+A backend provides persistence and sync for a context store.
+
+Examples:
+
+- `git` backend: local clone, pull, commit, push, watch
+- `cloud` backend: database records, subscriptions, hosted sync
+- `memory` backend: tests and local prototypes
+
+The backend should expose generic file/object operations:
+
+```text
+read
+write
+delete
+list
+sync
+watch
+```
+
+It should not contain initiative-specific behavior.
+
+## Collections
+
+A collection is a mounted content system inside a context store. It is
+plugin-like, but "collection" is the user-facing term.
+
+Each collection owns:
+
+- a folder namespace
+- a content model
+- templates
+- validation/rules
+- optional agent guidance
+- optional UI views
+
+Example:
+
+```text
+context-store/
+  initiatives/      # Initiative collection
+  decisions/        # Decision collection
+  api-catalog/      # API catalog collection
+```
+
+Core should enforce that a collection only writes inside its mount.
+
+## Initiative Collection
+
+The initiative collection is the first enterprise-oriented collection.
+
+An initiative is shared, agent-consumable implementation context for a
+coordinated outcome. It can span teams, repos, services, APIs, contracts, and
+capabilities.
+
+Default shape:
+
+```text
+initiatives/
+  launch-billing-flow/
+    initiative.yaml
+    requirements.md
+    design.md
+    contracts/
+    decisions.md
+    questions.md
+    tasks.md
+```
+
+This describes the runtime initiative collection shape in context stores. This
+roadmap folder may still contain legacy `.initiative.yaml` progress metadata
+while the initiative itself is being used to manage the migration; that legacy
+tracker is not the model new context-store initiatives should copy.
+
+The default structure should be opinionated for the enterprise design
+partnership, but the collection system should allow other structures later.
+
+## Initiative Responsibilities
+
+Initiatives should own implementation-relevant shared context:
+
+- product/program intent
+- accepted requirements
+- high-level technical coordination
+- capability and ownership maps
+- API/event/schema contracts
+- dependency assumptions
+- decisions and open questions
+- workspace-readable context for repo-local implementation work
+
+Initiatives should not try to become all of Jira or Confluence. The focused
+positioning is:
+
+```text
+OpenSpec stores agreed implementation context.
+Jira tracks work.
+Confluence stores broad prose.
+GitHub/GitLab store code.
+```
+
+## Initiative And Change Scope
+
+An initiative can span one or many OpenSpec changes.
+
+Those changes may live:
+
+- in the same repo as the initiative
+- in different repos
+- in multiple context stores or OpenSpec roots later
+
+The initiative stores shared coordination context. Workspace views can associate
+that context with local repos and repo-owned changes without making the
+initiative store machine-local checkout links.
+
+This keeps grouping separate from storage:
+
+```text
+Initiative = shared grouping/context
+Change     = execution artifact
+Workspace  = local opened view of initiative + repos
+```
+
+## Workspace
+
+A workspace is a local working view, not the source of truth.
+
+It can map context stores and project identifiers to local paths, configure an
+opener, and launch coding agents with the right folders visible.
+
+A workspace can open an initiative by resolving:
+
+- the initiative's context store
+- locally selected repo-local changes
+- local checkout paths for participating repos
+
+The durable workspace record should stay tiny and private. It records this
+runtime's local view choices, not generated agent files or shared initiative
+content.
+
+```text
+getGlobalDataDir()/workspaces/<workspace-name>/
+  workspace.yaml
+```
+
+The workspace name is the local identity. The workspace record can optionally
+store a selected context store and initiative, plus stable link names to local
+paths and opener preferences. Initiative references are data inside the record,
+not path segments.
+
+Opening a workspace materializes opener-specific runtime files at the managed
+workspace root. Those files can contain generated agent guidance, skills,
+and editor workspace files. Machine-readable context is returned by JSON command
+output. These are regenerated local support, not source of truth.
+
+```text
+private local view record
+  -> generated runtime files
+  -> opener-specific launch
+  -> initiative context + selected local repos/folders
+```
+
+Workspaces should be regenerable and runtime-specific. They should not be the
+canonical home for initiative content, checked-in collaboration state, branches,
+worktrees, clones, or implementation progress.
+
+## Repo Changes
+
+Repo-local changes remain the team-owned implementation plan.
+
+An engineering team should be able to pull relevant initiative context into a
+repo and create a linked OpenSpec change.
+
+Example:
+
+```text
+repo/
+  openspec/
+    changes/
+      add-billing-api/
+        .openspec.yaml
+        proposal.md
+        design.md
+        specs/
+        tasks.md
+```
+
+The local change should reference the initiative in metadata, for example:
+
+```yaml
+initiative:
+  store: platform
+  id: billing-launch
+```
+
+This metadata is durable repo context and should be checked in. It should not
+contain machine-local paths. Agents should read the initiative's canonical files
+from the registered context store when they need the shared context.
+
+## Relationship Between Concepts
+
+```text
+Context Store
+  contains Collections
+
+Collection
+  defines structure/rules for a mounted folder
+
+Initiative Collection
+  defines initiatives/
+
+Initiative
+  coordinates one shared outcome
+
+Workspace
+  opens local views of context stores and repos
+
+Repo Change
+  implements one team's/repo's part of an initiative
+```
+
+End-to-end flow:
+
+```text
+Product/program/architect creates initiative
+  -> initiative syncs through context store
+  -> engineers open local workspace
+  -> repo team pulls relevant initiative context
+  -> repo team creates linked OpenSpec change
+  -> repo team implements locally
+  -> workspace view surfaces local progress alongside initiative context
+```
+
+## Local API Direction
+
+The app should use dependency injection:
+
+```ts
+const store = createStore({
+  id: "acme-context",
+  backend: gitBackend({
+    remote: "git@github.com:acme/context.git",
+    localPath: "~/.openspec/stores/acme-context",
+    autoSync: true,
+  }),
+  collections: [
+    initiativeCollection({ mount: "initiatives" }),
+  ],
+});
+```
+
+Usage:
+
+```ts
+const initiatives = store.collection("initiatives");
+
+await initiatives.create({ id: "launch-billing-flow" });
+await initiatives.update("launch-billing-flow", patch);
+await store.sync();
+```
+
+Important separation:
+
+```text
+Git backend knows Git.
+Store knows sync/lifecycle/events.
+Collection knows content structure.
+Initiative collection knows initiatives.
+```
+
+## UI Direction
+
+The UI should be content-agnostic at the core:
+
+- browse folders/files
+- edit Markdown/YAML
+- preview content
+- search
+- show diffs/history
+- sync status
+
+Collections can add richer views:
+
+- initiative status view
+- contract table
+- owner/dependency graph
+- linked repo-change view
+
+The UI should work no matter which collections are mounted.
+
+## Open Questions
+
+- What is the first concrete context store command surface?
+- Should stores be called `context`, `store`, or something more product-facing?
+- Where should enterprise context stores live by default: customer GitHub,
+  OpenSpec-managed Git, or later hosted cloud?
+- How do non-technical users edit Git-backed content without feeling Git?
+- What is the minimum viable auto-sync behavior before conflict handling gets
+  painful?
+- How does an initiative contract graduate into a canonical owner repo contract?
+- How should linked repo changes report status back into an initiative without
+  becoming Jira?
+- How should monorepos map capabilities, folders, and repo-local changes?
+- What should the first repo-change linking command be called?
+- Which initiative progress/status signals are useful after linked changes
+  exist?
+
+## Suggested Next Direction
+
+After the initial store, collection, and initiative create/list foundations,
+build the next slices in this order:
+
+1. Reconcile the Initiative MVP around create/list, validation, templates, and
+   explicit deferral of read/update/delete policy.
+2. Add minimal context-store UX for setup, registration, listing, and doctoring.
+3. Add agent-first initiative discovery with `initiative show --json` and
+   registered-store lookup.
+4. Add repo-local change metadata and an agent-friendly create/link flow for
+   `--initiative`.
+5. Reject standalone `initiative resolve`; local path mapping belongs to
+   workspaces, not initiative commands.
+6. Let workspaces open initiative-aware local views once show/link semantics
+   exist.
+7. Add local-to-initiative escalation UX.
+8. Harden team-shared coordination, sync, conflict guidance, and progress
+   status after real usage shapes those needs.

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/questions.md

@@ -0,0 +1,23 @@
+# Context Store And Initiatives Questions
+
+## Open
+
+- Should the user-facing command vocabulary say `context`, `store`, or
+  something more product-facing?
+- What migration or compatibility path should existing workspace-planning
+  changes get once initiatives exist?
+- How should linked repo changes report progress back into an initiative without
+  becoming a Jira clone?
+- How should monorepos map capabilities, folders, and repo-local changes?
+- Should OpenSpec support configurable change homes across context stores and
+  local OpenSpec repos, and what ownership rules keep that model safe?
+
+## Resolved
+
+- Workspaces should not be the durable shared planning object.
+- Initiative roadmap implementation should be tracked inside the initiative
+  until repo-owned implementation changes are needed.
+- The first concrete context store command surface is `context-store setup`,
+  `context-store register`, `context-store list`/`ls`, and
+  `context-store doctor`. Sync, push/pull, remotes, and conflict handling are
+  future work.