sauron-cli 1.3.0 → 1.4.0

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/05-ship-initiative-mvp/plan.md

@@ -1,236 +0,0 @@
-# Ship Initiative MVP
-
-## Status
-
-Create/list operation and CLI adapter slices complete. Full read/show, update,
-and delete policy is deferred to later agent-first discovery and lifecycle
-work.
-
-## Source Of Truth
-
-Start from `../../direction.md`.
-
-The relevant model is:
-
-```text
-Context stores sync truth.
-Collections shape truth.
-Initiatives coordinate work.
-Workspaces open local views.
-Changes implement repo-owned slices.
-```
-
-## Goal
-
-Give coordinated work a durable, shared, agent-consumable home inside an
-`initiatives/` collection.
-
-## Roadmap Shape
-
-Default initiative shape:
-
-```text
-initiatives/<id>/
-  initiative.yaml
-  requirements.md
-  design.md
-  decisions.md
-  questions.md
-  tasks.md
-```
-
-Direction also leaves room for later `contracts/` content:
-
-```text
-initiatives/<id>/
-  contracts/
-```
-
-## Initial Boundaries
-
-- Initiative code should live outside `src/core/context-store/`.
-- Context-store core should not know initiative semantics.
-- Initiative APIs should consume a mounted `initiatives` collection from Item 4.
-- Repo-local OpenSpec changes remain the implementation artifacts; initiatives
-  coordinate intent, decisions, questions, and tasks.
-- Do not implement workspace opening, repo resolution, status dashboards, sync,
-  or linked change lifecycle in this item.
-
-## Locked Direction So Far
-
-- Put initiative code under `src/core/collections/initiatives/`.
-- Export initiatives from `src/core/index.ts` only after a real API exists.
-- Use visible `initiative.yaml`, not hidden `.initiative.yaml`, for the runtime
-  context-store initiative model. Existing roadmap folders may still carry
-  legacy `.initiative.yaml` progress metadata until that tracker is migrated or
-  retired.
-- Use strict YAML parsing and validation, following the existing foundation
-  patterns.
-- Do not create `links.yaml` in the initiative MVP. Repo-change wiring belongs
-  to workspace/local coordination work later.
-- Keep Markdown validation light; generate useful structure but do not validate
-  prose content yet.
-- Start implementation with initiative schema and template helpers before
-  mounted collection operations.
-- For the first mounted operation slice, add create and list only. Avoid a
-  broad `readInitiative` API until the shape of "full initiative" is clearer.
-- Treat a child folder as an initiative only when it contains a valid
-  `initiative.yaml`. Missing `initiative.yaml` means "not an initiative";
-  invalid `initiative.yaml` means broken shared state and should fail loudly.
-
-## Deferred From Item 5
-
-- Full initiative show/read behavior belongs in agent-first initiative discovery
-  once the return shape is clearer.
-- Metadata update and guarded delete belong in later lifecycle work after
-  create/list usage has shaped the policy.
-
-## Initial `initiative.yaml`
-
-Recommended shape:
-
-```yaml
-version: 1
-id: launch-billing-flow
-title: Launch Billing Flow
-summary: >
-  Coordinate the billing launch across product, API, and client surfaces.
-status: exploring
-created: "2026-05-21"
-owners: []
-metadata: {}
-```
-
-Required:
-
-- `version`
-- `id`
-- `title`
-- `summary`
-- `status`
-- `created`
-
-Defaulted or optional:
-
-- `owners`
-- `metadata`
-
-Initial statuses:
-
-- `exploring`
-- `active`
-- `complete`
-- `archived`
-
-## Initial Markdown Templates
-
-Create these files up front:
-
-- `requirements.md`: product intent, accepted requirements, out of scope.
-- `design.md`: context, approach, affected areas, dependencies, risks.
-- `decisions.md`: accepted decisions with date/title/decision/why/implications.
-- `questions.md`: open and resolved questions.
-- `tasks.md`: coordination tasks only, not repo implementation tasks.
-
-Defer `contracts/`, `README.md`, milestones, dependency graphs, external issue
-links, workspace path mappings, status dashboards, `links.yaml`, and Markdown
-content validation.
-
-## Likely Repo Slice
-
-- Add `src/core/collections/initiatives/schema.ts`.
-- Add `src/core/collections/initiatives/templates.ts`.
-- Add `src/core/collections/initiatives/index.ts`.
-- Add focused tests under `test/core/collections/initiatives/`.
-- Add types, constants, ID validation, strict `initiative.yaml`
-  parse/serialize helpers, and default template builders.
-- Add create/list mounted collection operations after schema and templates are
-  locked.
-- Keep context-store collection APIs unchanged unless a real integration gap is
-  found.
-
-## Implemented Slice
-
-- Added `src/core/collections/initiatives/schema.ts`.
-- Added `src/core/collections/initiatives/templates.ts`.
-- Added `src/core/collections/initiatives/index.ts`.
-- Added focused tests under `test/core/collections/initiatives/`.
-- Exported initiatives through `src/core/collections/index.ts` now that a
-  mounted operation API exists.
-- Kept `links.yaml` out of the initiative MVP file contract.
-
-## Operation Slice Direction
-
-- Add `src/core/collections/initiatives/operations.ts`.
-- Export initiatives through `src/core/collections/index.ts` now that a mounted
-  operation API exists.
-- `createInitiative` should create exactly the MVP file shape:
-  `initiative.yaml`, `requirements.md`, `design.md`, `decisions.md`,
-  `questions.md`, and `tasks.md`.
-- `createInitiative` should generate `created` through an injectable date
-  provider, fail if the initiative folder already exists, and clean up a
-  partially created folder on write failure.
-- `listInitiatives` should inspect immediate child directories under the
-  mounted `initiatives` collection, ignore folders without `initiative.yaml`,
-  parse and validate folders with `initiative.yaml`, require
-  `initiative.yaml.id` to match the folder name, and return initiative states
-  sorted by id.
-
-## Implemented Operation Slice
-
-- Added `src/core/collections/initiatives/operations.ts`.
-- Added `createInitiative` for creating the MVP folder shape through a mounted
-  `initiatives` collection.
-- Added `listInitiatives` using the valid-`initiative.yaml` detection rule.
-- Exported initiatives through `src/core/collections/index.ts`.
-- Added focused operation tests under
-  `test/core/collections/initiatives/operations.test.ts`.
-
-## Next Integration Enabler
-
-Before adding `openspec initiative create/list`, add a context-store
-registration/resolution facade so CLI code can resolve a named store and mount
-the initiatives collection without exposing raw registry or metadata YAML.
-
-## CLI Adapter Direction
-
-Add the first initiative CLI surface as a thin adapter over the mounted
-collection operations:
-
-```bash
-openspec initiative create <id> --store <store-id> --title <title> --summary <summary>
-openspec initiative create <id> --store-path <path> --title <title> --summary <summary>
-openspec initiative list --store <store-id>
-openspec initiative list --store-path <path>
-```
-
-Use `initiative create/list` as a deliberate noun namespace, similar to
-`workspace` and `schema`, even though newer OpenSpec conventions generally
-prefer verb-first top-level commands. The stricter alternative would spread
-initiative behavior across `new initiative` and global `list` flags, which is a
-larger surface for this slice because initiative commands must resolve a
-context store.
-
-Keep store selection explicit in the first CLI slice. Require either
-`--store <id>` or `--store-path <path>`, reject both together, and do not add
-current-directory discovery, single-store auto-selection, an interactive picker,
-a global default store, or workspace selected-store state yet.
-
-Because shell completions are manually registered, adding the runtime command
-also requires adding `initiative create/list/ls` to `COMMAND_REGISTRY`. Keep
-completion support static for now: command names and flags only, with no dynamic
-store-id or initiative-id completion.
-
-## Implemented CLI Adapter Slice
-
-- Added `src/commands/initiative.ts`.
-- Registered `openspec initiative create` and `openspec initiative list` from
-  the top-level CLI.
-- Added `openspec initiative ls` as an alias for list.
-- Required explicit context-store selection through `--store <id>` or
-  `--store-path <path>`.
-- Rejected conflicting `--store` and `--store-path` selectors.
-- Returned workspace-style JSON payloads with a top-level `status` diagnostics
-  array.
-- Added static shell completion metadata for `initiative create/list/ls`.
-- Added focused command tests under `test/commands/initiative.test.ts`.

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/05-ship-initiative-mvp/tasks.md

@@ -1,21 +0,0 @@
-# Ship Initiative MVP Tasks
-
-- [x] Create Item 5 work-item tracking notes.
-- [x] Research initiative shape, API, module placement, and first slice.
-- [x] Decide where initiative code lives.
-- [x] Decide required `initiative.yaml` metadata.
-- [x] Decide no initiative `links.yaml` in the MVP.
-- [x] Decide first coding slice starts with initiative schema/templates before operations.
-- [x] Add initiative schema helpers and tests.
-- [x] Add default initiative templates.
-- [x] Run targeted verification for schema/templates.
-- [x] Decide create/list-only operation slice.
-- [x] Add create/list mounted initiative operations and tests.
-- [x] Run targeted verification for operations.
-- [x] Research initiative CLI adapter gaps.
-- [x] Decide explicit context-store selection for first CLI slice.
-- [x] Document noun-command and manual-completion tradeoffs.
-- [x] Add `openspec initiative create/list` CLI adapter.
-- [x] Register static shell completions for initiative commands.
-- [x] Add focused CLI tests for create/list, selection errors, and completions.
-- [x] Run targeted verification for the initiative CLI adapter.

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/06-add-minimal-context-store-ux/evidence.md

@@ -1,97 +0,0 @@
-# Add Minimal Context Store UX Evidence
-
-## Conversation Decisions
-
-- The next roadmap step should not jump straight to repo-local change linking
-  or workspace initiative opening.
-- Teams first need a simple way to create or register the shared context store
-  that holds initiatives.
-- The workflow is agent-first: the user prompts an agent, and the agent uses CLI
-  primitives to discover stores and initiatives.
-- `context-store` should be the top-level command namespace for now. It is more
-  explicit for agents than `store`, and `store` can remain shorthand in scoped
-  flags such as `initiative list --store <id>`.
-- A store can start as a local Git-backed folder. OpenSpec can help create the
-  folder, write metadata, register it locally, and optionally initialize Git.
-- When setup does not receive `--path`, it should create or use `./<id>`. This
-  keeps the real shared store visible and avoids hiding it under global data.
-- Using the current directory should require explicit `--path .`.
-- If a user registers an existing folder or clone, the default store id can be
-  the repo or folder name.
-- Portable `.openspec-store/store.yaml` metadata should be checked in and should
-  not include local paths.
-- `.openspec-store/store.yaml` is the identity file itself, not a bundle beside
-  another checked-in metadata file. It should contain only `version` and `id`
-  for now.
-- Future backend, sync, collection, permission, or policy config should not be
-  added to `store.yaml` by default.
-- The local registry maps store ids to local paths on one machine.
-- Remote-url clone/setup sugar is useful but can wait.
-- `initiative list` should list all registered stores by default; `--store`
-  should filter.
-- Interactive setup should prompt for Git initialization and default to yes
-  when no explicit Git flag is provided.
-- Non-interactive, JSON, `--init-git`, and `--no-init-git` setup should not
-  prompt.
-- `context-store register` should be idempotent for the same id/path and fail
-  for the same id with a different path until a future explicit replacement
-  option exists.
-- `context-store list` should stay a simple registry index and should not show
-  health warnings.
-- `context-store doctor` owns health diagnostics. The first slice should check
-  registry/path/metadata and cheap Git repository presence, not dirty state,
-  branch, remote, sync, pull/push, or conflicts.
-- `initiative list` should allow partial success in all-store mode: show
-  initiatives from readable stores and print one small warning pointing to
-  `context-store doctor` when other registered stores cannot be read.
-- Filtered `initiative list --store` and explicit `--store-path` should fail
-  directly when the selected store cannot be read.
-- Partial success should exit 0 with warning diagnostics in JSON. Total failure
-  should exit nonzero.
-- Register id inference should use the repo/folder name as-is with normal
-  context-store id validation. Do not add normalization in this slice.
-- Setup should reject non-empty folders without context-store metadata for now.
-- Registry conflicts should fail when the same id points at a different path or
-  the same path is already registered under a different id.
-- Empty states should stay simple: no stores registered for `context-store list`
-  and `doctor`; no initiatives found because no stores are registered for
-  `initiative list`.
-- Static shell completion metadata is now part of the shipped command surface;
-  dynamic store-id and initiative-id completions remain deferred.
-
-## Risks To Check Before Implementation
-
-- Existing command naming conventions may prefer verb-first flows, while
-  context-store commands are naturally noun namespaced.
-- Shell completions are manually registered; keep future command additions in
-  `src/core/completions/command-registry.ts` with focused registry tests.
-- Human output should match existing compact CLI output patterns.
-- JSON output should be stable enough for agents without over-modeling future
-  sync or remote behavior.
-
-## Implementation Evidence
-
-- `src/commands/context-store.ts` adds the `context-store` command namespace
-  with setup, register, list, and doctor subcommands.
-- `src/cli/index.ts` registers the context-store command.
-- `src/commands/context-store.ts` keeps strict CLI setup/register policy in the
-  command layer while reusing context-store foundation helpers.
-- `src/commands/initiative.ts` now lets `initiative list` search all registered
-  stores by default, keeps `--store` as a filter, preserves `--store-path`, and
-  reports all-store partial success with warning diagnostics.
-- `src/core/completions/command-registry.ts` registers static completion
-  metadata for the context-store command surface.
-- `test/commands/context-store.test.ts` covers setup, register, list, doctor,
-  conflict handling, non-empty setup rejection, and interactive Git init.
-- `test/commands/initiative.test.ts` covers all-store initiative listing,
-  compact human output, empty registered-store state, partial success, and all
-  unreadable stores.
-
-## Verification
-
-- `pnpm run build`
-- `pnpm exec vitest run test/commands/context-store.test.ts test/commands/initiative.test.ts`
-- `pnpm exec vitest run test/core/context-store/foundation.test.ts
-  test/core/context-store/registry.test.ts
-  test/core/collections/initiatives/operations.test.ts`
-- `pnpm run lint`

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/06-add-minimal-context-store-ux/plan.md

@@ -1,333 +0,0 @@
-# Add Minimal Context Store UX
-
-## Status
-
-Minimal context-store CLI and all-store initiative listing implemented.
-
-## Source Of Truth
-
-Start from `../../direction.md`.
-
-The current roadmap order is:
-
-```text
-Context stores sync truth.
-Collections shape truth.
-Initiatives coordinate work.
-Workspaces open local views.
-Changes implement repo-owned slices.
-```
-
-This item exists because agent-first initiative workflows need a usable shared
-store before repo-local handoff and workspace opening can feel coherent.
-
-## Goal
-
-Let a user or agent create, register, list, and diagnose local context stores
-without knowing the internal registry layout.
-
-## Agent-First Framing
-
-The expected user prompt is closer to:
-
-```text
-Using initiative billing-launch, explore the API work and create a proposal.
-```
-
-Before an agent can do that, it needs to answer:
-
-- Which context stores are registered locally?
-- Which store contains the named initiative?
-- Is the registered store path valid?
-- Is store metadata present and consistent?
-- If no store exists yet, how should one be created?
-
-This work item should provide those primitives. It should not implement
-repo-local initiative linking, initiative resolution, workspace opening, or
-progress/status dashboards.
-
-## Locked Direction So Far
-
-- Keep the user-facing term `store` for now; naming polish is deferred.
-- Use `context-store` as the top-level CLI namespace for this slice. It is more
-  explicit for agents and avoids overloading a broad top-level `store` command.
-  Keep `store` as shorthand only when the context is already scoped, such as
-  `initiative list --store <id>`.
-- `context-store setup <id>` should create or use a local folder, write portable
-  store metadata, register the local path, and optionally initialize Git.
-- When `--path` is omitted, `context-store setup <id>` should default to
-  `./<id>`.
-- Using the current directory should be explicit with `--path .`; setup should
-  not silently turn the current repo into a context store.
-- The actual shared context store should be visible on disk, not hidden under
-  XDG/global data. XDG/global data is only for the machine-local registry.
-- `context-store register <path>` should register an existing clone or folder.
-- Registration means "this folder already exists on my machine; remember it as
-  a known context store." It should not create the folder, initialize Git, pull,
-  push, commit, or create remotes.
-- Default the store id from the repo or folder name when metadata is missing.
-- Portable store metadata is exactly `.openspec-store/store.yaml`. It should be
-  checked into the context-store repo and contain only portable identity for
-  now:
-
-```yaml
-version: 1
-id: team-context
-```
-
-- Do not put backend config, local paths, remote URLs, collection config, sync
-  policy, or permissions in `store.yaml`.
-- If future collection/store config is needed, add a separate explicit file
-  rather than expanding the identity file by default.
-- Machine-local registry state should stay outside the checked-in store and map
-  store ids to local paths.
-- Registration should not pull, push, commit, or create remote repositories.
-- Remote-url registration or clone sugar can come later.
-- `initiative list` should default to all registered stores. `--store` should
-  filter to one store, and `--store-path` should remain an explicit escape
-  hatch.
-- Human output should stay compact and avoid a `Status` column for now.
-
-## Suggested Command Shape
-
-```bash
-openspec context-store setup <id> [--path <path>] [--init-git|--no-init-git] [--json]
-openspec context-store register <path> [--id <id>] [--json]
-openspec context-store list [--json]
-openspec context-store doctor [id] [--json]
-openspec initiative list [--store <id>] [--store-path <path>] [--json]
-```
-
-## Command Behavior
-
-### `context-store setup`
-
-`context-store setup <id>` creates or uses a visible local store root and
-registers it on the current machine.
-
-Locked behavior:
-
-- Default path is `./<id>` when `--path` is omitted.
-- Current-directory setup is allowed only with explicit `--path .`.
-- Missing folders are created.
-- Existing folders are allowed when metadata is missing or matches the requested
-  id.
-- Non-empty folders without context-store metadata are not supported for setup
-  in this slice.
-- Existing metadata with a different id fails.
-- File paths fail.
-- `.openspec-store/store.yaml` is written when missing.
-- The store is registered in the machine-local registry.
-- Interactive TTY mode prompts for Git initialization when neither
-  `--init-git` nor `--no-init-git` is provided; the default answer is yes.
-- `--json`, non-TTY execution, `--init-git`, and `--no-init-git` do not prompt.
-- Git is initialized only when the prompt answer is yes or `--init-git` is
-  passed.
-- Setup does not commit, push, pull, create remotes, or create hosted repos.
-- If a user wants to initialize an existing non-empty folder, fail with a clear
-  message and suggest filing the use case or using `context-store register` for
-  an existing context store.
-
-Suggested human output:
-
-```text
-Context store setup complete
-
-ID: team-context
-Location: /Users/me/work/team-context
-Metadata: /Users/me/work/team-context/.openspec-store/store.yaml
-Registry: /Users/me/.local/share/openspec/context-stores/registry.yaml
-Git: initialized
-```
-
-### `context-store register`
-
-`context-store register <path>` records an existing local folder or clone as a
-known context store on the current machine.
-
-Locked behavior:
-
-- Path must already exist and be a directory.
-- If `.openspec-store/store.yaml` exists, use its id.
-- `--id` may confirm the metadata id but cannot conflict with it.
-- If metadata is missing, infer the id from the folder or repo name unless
-  `--id` is passed.
-- Inference uses the folder or repo name as-is and then applies normal context
-  store id validation. Do not do clever normalization in this slice.
-- Missing metadata is written.
-- The machine-local registry is updated.
-- Same id and same path is an idempotent success.
-- Same id and different path fails for now; a future `--replace` can make
-  replacement explicit.
-- Same path already registered under a different id fails for now.
-- Register does not create the folder, initialize Git, pull, push, commit,
-  create remotes, or clone.
-
-Suggested human output:
-
-```text
-Context store registered
-
-ID: team-context
-Location: /Users/me/src/team-context
-Metadata: /Users/me/src/team-context/.openspec-store/store.yaml
-Registry: /Users/me/.local/share/openspec/context-stores/registry.yaml
-```
-
-### `context-store list`
-
-`context-store list` is an index view of the local registry.
-
-Locked behavior:
-
-- Reads the local registry.
-- Shows registered id and location only.
-- Sorts by store id.
-- Does not check metadata, path health, Git, sync, remote, dirty state, or
-  conflicts.
-- Does not mutate anything.
-- Prints no health warnings; health belongs to `context-store doctor`.
-
-Suggested human output:
-
-```text
-OpenSpec context stores (2)
-
-ID              Location
-platform        /Users/me/src/platform-context
-team-context    /Users/me/src/team-context
-```
-
-Empty output:
-
-```text
-No context stores registered.
-
-Next:
-  openspec context-store setup team-context
-  openspec context-store register /path/to/context-store
-```
-
-### `context-store doctor`
-
-`context-store doctor [id]` is the non-mutating health and repair surface.
-
-Locked behavior:
-
-- Checks all registered stores by default.
-- Checks one store when `id` is passed.
-- Checks registry presence, path existence, directory shape, metadata presence,
-  metadata parsing, and metadata id matching.
-- Includes a cheap Git repository presence check.
-- Does not check dirty state, branch, remote, sync, pull/push, or conflicts in
-  this slice.
-- Does not mutate anything.
-
-Empty output:
-
-```text
-No context stores registered.
-```
-
-Suggested human output:
-
-```text
-Context store doctor
-
-team-context
-  Location: /Users/me/src/team-context
-  Metadata: ok
-  Git: repository detected
-  Issues: none
-```
-
-### `initiative list`
-
-`initiative list` becomes the agent-friendly discovery command across
-registered stores.
-
-Locked behavior:
-
-- Without `--store` or `--store-path`, list initiatives from all readable
-  registered stores.
-- If no context stores are registered, print a concise empty message.
-- Sort by store id, then initiative id.
-- Do not show a `Status` column in human output.
-- Do not print detailed health diagnostics.
-- If some stores cannot be read, still show initiatives from readable stores
-  and print one small warning that points to `context-store doctor`.
-- If all registered stores are unreadable, print a concise failure/empty message
-  and point to `context-store doctor`.
-- With `--store <id>`, filter to one registered store.
-- With `--store-path <path>`, list from that explicit store path.
-- Filtered `--store` or `--store-path` mode fails directly if that store cannot
-  be read, because there are no fallback stores.
-
-Suggested all-store output:
-
-```text
-OpenSpec initiatives (3 across 2 stores)
-
-ID                   Store       Title
-billing-launch       platform    Billing Launch
-docs-refresh         platform    Docs Refresh
-api-cleanup          team        API Cleanup
-
-Some registered context stores could not be read.
-Run: openspec context-store doctor
-```
-
-No registered stores output:
-
-```text
-No initiatives found because no context stores are registered.
-```
-
-Suggested filtered output:
-
-```text
-OpenSpec initiatives in platform (2)
-
-ID                   Title
-billing-launch       Billing Launch
-docs-refresh         Docs Refresh
-
-Location: /Users/me/src/platform-context
-```
-
-## Boundaries
-
-Do not implement in this item:
-
-- initiative `show`
-- repo-local change metadata
-- `new change --initiative`
-- initiative local resolution
-- workspace initiative opening
-- sync, pull, push, remote repository creation, or conflict handling
-
-## Remaining Decisions
-
-None before implementation. JSON shapes can follow the existing command pattern:
-top-level result objects plus a `status` diagnostics array. Partial success
-returns exit code 0 with warning diagnostics; total failure returns nonzero.
-
-## Implemented Slice
-
-- Added `openspec context-store setup/register/list/doctor`.
-- Registered the `context-store` command from the top-level CLI.
-- Initially kept shell completion metadata out of scope; static metadata was
-  added later with the shipped command surface.
-- Implemented strict CLI registration policy without changing the permissive
-  lower-level registry facade.
-- Added setup behavior for default `./<id>`, explicit `--path .`, interactive
-  Git init prompt, non-interactive/JSON no-prompt behavior, non-empty directory
-  rejection, and metadata writing.
-- Added register behavior for existing folders, id inference from folder name,
-  metadata writing, id/path conflict rejection, and registry updates.
-- Added list behavior as a registry index only.
-- Added doctor behavior for registry/path/metadata health and cheap Git
-  presence.
-- Updated `initiative list` so no selector lists across registered stores,
-  `--store` filters, `--store-path` remains an escape hatch, human output is
-  compact, and all-store partial success returns warning diagnostics.