sauron-cli 1.3.0 → 1.4.1

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/02-stabilize-workspace-as-local-view/plan.md

@@ -1,80 +0,0 @@
-# Stabilize Workspace As Local View
-
-## Status
-
-Complete for the current local-view stabilization slice. Remaining workspace
-planning/apply/verify/archive behavior stays deferred until initiative-linked
-repo-local changes exist.
-
-## 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
-
-Keep workspace setup, link, relink, list, open, update, and doctor useful while
-making it clear that a workspace is a regenerable machine-local view, not the
-durable coordination object.
-
-## Agreed Guidance Direction
-
-Generated workspace guidance should route agents by ownership:
-
-- Use the workspace to open the local view of coordinated work.
-- Use initiatives for durable cross-team or cross-repo intent, decisions,
-  requirements, and coordination context.
-- Use repo-local OpenSpec changes for implementation plans owned by a repo or
-  team.
-- Use linked repos and folders to inspect context, understand ownership, and
-  make edits in the place that owns the work.
-- Keep workspace-local files focused on local paths, opener state, agent setup,
-  and other machine-specific view state.
-- Use OpenSpec workspace commands instead of hand-editing
-  `.openspec-workspace/*.yaml`.
-- If a workspace contains legacy or beta workspace-level planning files, treat
-  them as compatibility context unless the user explicitly asks to use that beta
-  flow.
-
-## Guidance To Stop Reinforcing
-
-Do not tell agents to use workspace-level `changes/` as the planning home for
-coordinated work. That reinforces the superseded model where a workspace-level
-`changes/` tree owned the canonical shared cross-repo plan.
-
-Existing workspace-planning behavior may remain as beta or legacy
-infrastructure, but it should not steer new lifecycle design.
-
-## Likely Repo Slice
-
-- Reword generated workspace guidance in
-  `src/core/workspace/open-surface.ts`.
-- Update focused guidance tests.
-- Make `workspace update` refresh the guidance block for existing workspaces.
-- Keep specs untouched until a behavior change intentionally updates them.
-
-## Closeout
-
-Implemented:
-
-- generated workspace guidance now routes work by ownership
-- `workspace update` refreshes workspace-local guidance/open-surface files and
-  managed agent skills
-- workspace-planning action context treats beta workspace artifacts as
-  `workspace-local` compatibility context
-- live docs describe workspaces as local views instead of durable planning homes
-
-Deferred:
-
-- normal doctor installed-skill inventory
-- workspace apply, verify, and archive
-- initiative-linked repo-local change orchestration

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/02-stabilize-workspace-as-local-view/tasks.md

@@ -1,23 +0,0 @@
-# Stabilize Workspace As Local View Tasks
-
-- [x] Research current workspace runtime, guidance, and test coverage.
-- [x] Re-anchor guidance direction in `direction.md`.
-- [x] Decide that generated guidance should route durable coordination to
-  initiatives and implementation planning to repo-local changes.
-- [x] Decide that generated guidance should stop recommending workspace-level
-  `changes/` as the planning home.
-- [x] Decide that `workspace update` refreshes the generated guidance block
-  for existing workspaces.
-- [x] Update workspace-planning action context so beta workspace artifacts are
-  compatibility context, not the source of truth.
-- [x] Decide to defer normal doctor skill summaries until users need an
-  installed-skill inventory.
-- [x] Update `workspace update` wording to include workspace-local guidance and
-  agent skills.
-- [x] Define the minimal doctor/status improvement for local paths, unresolved
-  links, and installed agent skills.
-- [x] Identify the focused code/test files for the implementation slice.
-- [x] Run the targeted workspace and artifact workflow test slice before
-  landing implementation.
-- [x] Close out live docs wording that still framed workspaces as durable
-  planning homes.

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/03-add-context-store-foundation/evidence.md

@@ -1,43 +0,0 @@
-# Add Context Store Foundation Evidence
-
-## Research Summary
-
-Existing OpenSpec patterns point toward a small explicit foundation:
-
-- Global data uses XDG/platform locations from `getGlobalDataDir()`.
-- Workspace registries are machine-local convenience indexes under global data.
-- Workspace portable state uses versioned YAML and strict Zod validation.
-- Existing read/write helpers validate state before writing and use
-  `FileSystemUtils.writeFile()` to create parent directories.
-- Schema/backend-style code favors small explicit adapters and registries over
-  heavy framework abstractions.
-
-## Decisions
-
-- The first context-store backend is Git/local checkout config only.
-- OpenSpec records where the local checkout lives; it does not decide where real
-  team stores are cloned by default.
-- The local registry is not source of truth. It is a machine-local index.
-- Store-root metadata is portable source-of-identity for the synced store.
-- Initiatives and collections are later consumers, not part of the store
-  foundation.
-- A thin facade should hide raw registry/metadata writes before initiative CLI
-  wiring.
-
-## Implementation Evidence
-
-- `src/core/context-store/registry.ts` registers Git/local context stores,
-  lists local registry entries, and resolves registered stores with metadata id
-  validation.
-- `src/core/context-store/index.ts` exports the facade.
-- `test/core/context-store/registry.test.ts` covers registration, registry
-  merge/update, metadata mismatch rejection, listing, resolution, missing or
-  mismatched metadata, and initiative collection mounting from a resolved root.
-
-## Verification
-
-- `pnpm exec vitest run test/core/context-store/foundation.test.ts`
-- `pnpm exec vitest run test/core/context-store/registry.test.ts`
-- `pnpm run build`
-- `pnpm run lint`
-- `git diff --check`

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/03-add-context-store-foundation/plan.md

@@ -1,85 +0,0 @@
-# Add Context Store Foundation
-
-## Status
-
-Registration/resolution facade implemented.
-
-## 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
-
-Add the smallest core foundation for context stores without making the store
-layer know about initiatives, collections, workspaces, or repo-local changes.
-
-## Locked Direction
-
-- Support one backend for the first slice: a Git/local checkout backend.
-- Treat the actual context store root as a user-chosen local Git checkout or
-  synced folder.
-- Do not hide real team context stores under XDG data by default.
-- Store the machine-local registry under global data:
-  `$XDG_DATA_HOME/openspec/context-stores/registry.yaml`.
-- Store portable context-store identity inside the store root:
-  `<store-root>/.openspec-store/store.yaml`.
-- Start with backend identity/config, strict validation, path helpers, and
-  registry/metadata read-write helpers.
-- Add a thin registration/resolution facade before initiative CLI wiring so
-  callers do not manipulate raw registry and metadata YAML directly.
-- Do not reimplement the TypeScript or Node filesystem APIs as the public store
-  interface.
-- Do not add initiative, collection, workspace-open, sync, pull, push, or CLI
-  behavior in this slice.
-
-## Initial Shape
-
-Machine-local registry:
-
-```yaml
-version: 1
-stores:
-  acme-context:
-    backend:
-      type: git
-      local_path: /Users/me/repos/acme-context
-      remote: git@github.com:acme/context.git
-      branch: main
-```
-
-Portable metadata in the store root:
-
-```yaml
-version: 1
-id: acme-context
-```
-
-## Likely Repo Slice
-
-- Add `src/core/context-store/foundation.ts`.
-- Add `src/core/context-store/registry.ts`.
-- Add `src/core/context-store/index.ts`.
-- Export the core context-store foundation from `src/core/index.ts`.
-- Add focused tests under `test/core/context-store/`.
-- Keep specs untouched until a behavior/API contract is deliberately surfaced.
-
-## Implemented Facade Slice
-
-- Added `registerContextStore(...)`.
-- Added `listRegisteredContextStores(...)`.
-- Added `resolveRegisteredContextStore(...)`.
-- Registration writes portable store metadata when missing, validates existing
-  metadata when present, and merges/updates the machine-local registry.
-- Resolution validates that the registry id matches the store-root metadata id.
-- No Git clone, pull, push, sync, workspace state, collection manifest, or CLI
-  behavior was added.

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/03-add-context-store-foundation/tasks.md

@@ -1,17 +0,0 @@
-# Add Context Store Foundation Tasks
-
-- [x] Research existing config, registry, file-system, and schema/backend
-  patterns.
-- [x] Decide to start with Git/local backend identity only, not a generic file
-  API.
-- [x] Decide that real context store roots are user-chosen Git checkouts or
-  synced folders.
-- [x] Decide that the local registry lives under global data and portable store
-  metadata lives inside the store root.
-- [x] Add context-store foundation types, path helpers, parse/serialize, and
-  read/write helpers.
-- [x] Add focused tests for validation, paths, registry roundtrip, metadata
-  roundtrip, and Git/local backend path resolution.
-- [x] Run targeted verification.
-- [x] Decide registration/resolution facade should precede initiative CLI.
-- [x] Add context-store registration/list/resolve facade and tests.

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/04-add-collection-foundation/evidence.md

@@ -1,77 +0,0 @@
-# Add Collection Foundation Evidence
-
-## Research Summary
-
-Subagent and local review converged on the same direction:
-
-- Item 4 should define the boundary between store identity and product-specific
-  content meaning.
-- The collection layer should own mounted namespaces and logical path fences.
-- The context-store layer should stay content-agnostic.
-- Initiative CRUD and initiative file shape belong to Item 5.
-- A runtime injected registry is enough for now; persisted manifests and dynamic
-  plugins are premature.
-- A thin registration facade should hide metadata and local registry writes, but
-  Item 4 should not depend on that facade.
-
-## Clean-Code Notes
-
-- Use module boundaries and mounted objects to carry context.
-- Prefer `validateMount`, `parseCollectionPath`, `createCollectionRegistry`,
-  and `mountCollections` inside the collection module.
-- Avoid public helper names that stack every concept together, such as
-  `validateContextStoreCollectionRelativePath`.
-- Keep path resolution pure and lexical until a future write-capable layer
-  deliberately handles symlinks, canonical parent paths, and backend behavior.
-- Keep persisted YAML shape below the public setup surface. Runtime/public
-  handles should use camelCase fields such as `storeRoot`; persisted backend
-  state can continue to use `local_path`.
-
-## Chosen Pattern
-
-Use a two-step pattern:
-
-```ts
-const store = await registerContextStore({
-  id: "acme-context",
-  backend: gitLocalBackend({
-    localPath: "/Users/me/repos/acme-context",
-    remote: "git@github.com:acme/context.git",
-    branch: "main",
-  }),
-});
-
-const collections = createCollectionRegistry([
-  { id: "initiatives", mount: "initiatives" },
-]);
-
-const mounted = mountCollections({
-  storeRoot: store.storeRoot,
-  collections,
-});
-```
-
-For Item 4 itself, `mountCollections({ storeRoot, collections })` is the
-canonical API. One-call setup facades, store lifecycle objects, builder DSLs,
-and initiative-specific setup presets are deferred.
-
-## Implementation Evidence
-
-- `src/core/collections/runtime.ts` defines runtime collection
-  definitions, registries, mounted collection contexts, logical path parsing,
-  and mount/path resolution.
-- `src/core/collections/index.ts` exports the collection module, and
-  `src/core/index.ts` re-exports it for core consumers.
-- `test/core/collections/runtime.test.ts` covers mount and id validation,
-  logical path parsing, duplicate id/mount rejection, Windows-style roots,
-  `createHandle(context)`, no filesystem creation, and generic `initiatives/`
-  mounting.
-
-## Verification
-
-- `pnpm exec vitest run test/core/collections/runtime.test.ts`
-- `pnpm run build`
-- `pnpm exec vitest run test/core/collections/runtime.test.ts test/core/context-store/foundation.test.ts test/core/planning-home.test.ts`
-- `pnpm exec vitest run test/utils/file-system.test.ts`
-- `pnpm run lint`
-- `git diff --check`

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/04-add-collection-foundation/plan.md

@@ -1,198 +0,0 @@
-# Add Collection Foundation
-
-## Status
-
-First implementation slice implemented.
-
-## 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
-
-Add the smallest collection foundation that lets product-specific content
-systems mount inside a context store without making the context-store layer know
-what those systems mean.
-
-## Locked Direction So Far
-
-- Treat Item 4 as a mount/path foundation, not a collection runtime.
-- Keep collection composition runtime-only and dependency-injected.
-- Keep context-store registration separate from runtime collection mounting.
-- Use a future thin registration facade for metadata/registry setup instead of
-  showing raw registry or metadata state writes in public examples.
-- Do not add a persisted collection manifest yet.
-- Do not add CLI behavior yet.
-- Do not add generic `read`, `write`, `list`, or `delete` helpers.
-- Do not add initiative file shape, initiative CRUD, or initiative validation
-  yet.
-- Prove `initiatives/` can mount through generic collection definitions, not
-  through initiative-specific context-store logic.
-
-## Naming Direction
-
-Use the module/object boundary to carry context instead of growing helper names.
-
-Use a focused generic module such as `src/core/collections/runtime.ts` with
-short names:
-
-```ts
-validateCollectionId(id);
-validateMount(mount);
-parseCollectionPath(input);
-
-createCollectionRegistry(...);
-mountCollections(...);
-```
-
-Prefer mounted objects for context-aware operations:
-
-```ts
-const mounted = collections.require("initiatives");
-
-mounted.resolvePath("launch-billing-flow/initiative.yaml");
-mounted.toStorePath("launch-billing-flow/initiative.yaml");
-```
-
-Avoid names like `validateContextStoreCollectionRelativePath`. They indicate
-that too much context has leaked into a standalone helper name.
-
-## Minimal API Shape
-
-The first slice should stay close to this:
-
-```ts
-interface CollectionDefinition<THandle = unknown> {
-  id: string;
-  mount: string;
-  metadata?: CollectionMetadata;
-  hooks?: CollectionHooks;
-  createHandle?: (context: MountedCollectionContext) => THandle;
-}
-
-interface MountedCollectionContext {
-  storeRoot: string;
-  collectionId: string;
-  mount: string;
-  mountRoot: string;
-  resolvePath(relativePath?: string): string;
-  toStorePath(relativePath?: string): string;
-}
-
-interface MountedCollection<THandle = unknown> {
-  collectionId: string;
-  mount: string;
-  mountRoot: string;
-  context: MountedCollectionContext;
-  handle: THandle | undefined;
-}
-```
-
-Use `id` on definitions, but `collectionId` on mounted handles and contexts so
-domain object IDs such as initiative IDs do not collide with collection type IDs.
-
-## Setup And Mounting Pattern
-
-Use two separate layers:
-
-1. A context-store registration facade for setup.
-2. A pure runtime collection mounting API for Item 4.
-
-Registration should hide persisted YAML details:
-
-```ts
-const store = await registerContextStore({
-  id: "acme-context",
-  backend: gitLocalBackend({
-    localPath: "/Users/me/repos/acme-context",
-    remote: "git@github.com:acme/context.git",
-    branch: "main",
-  }),
-});
-```
-
-The registration facade can call lower-level helpers such as backend config
-normalization, metadata writes, and local registry writes internally. Public
-examples should not call raw `writeContextStoreMetadataState(...)`,
-`writeContextStoreRegistryState(...)`, or expose persisted snake_case backend
-state such as `local_path`.
-
-Item 4 mounting should stay independent of registration and accept only the
-authority it needs:
-
-```ts
-const collections = createCollectionRegistry([
-  { id: "initiatives", mount: "initiatives" },
-]);
-
-const mounted = mountCollections({
-  storeRoot: store.storeRoot,
-  collections,
-});
-
-mounted.require("initiatives").resolvePath(
-  "launch-billing-flow/initiative.yaml"
-);
-```
-
-Prefer `mountCollections({ storeRoot, collections })` as the canonical first
-API. Passing a whole store handle can wait until there is a real need.
-
-## Path Direction
-
-- Mount names are single-segment kebab-case folder names such as `initiatives`,
-  `decisions`, or `api-catalog`.
-- Collection-relative paths are logical portable paths inside a mount.
-- The path resolver is lexical only. It proves that a logical path belongs under
-  a collection mount; it does not claim to be a filesystem security sandbox.
-- Future write-capable helpers must revisit symlink and canonical parent-path
-  handling before touching disk.
-
-Reject:
-
-- empty mounts
-- `.`
-- `..`
-- hidden/reserved mounts such as `.openspec-store`
-- absolute paths
-- Windows drive paths
-- UNC paths
-- NUL bytes
-- traversal segments
-- sibling-prefix escapes
-
-## Deferred
-
-- Store-level collection config files.
-- Dynamic plugin loading.
-- One-call `setupContextStore({ id, backend, collections })` APIs.
-- `createStore(...).setup()` lifecycle APIs.
-- Builder-style setup DSLs.
-- Initiative-specific setup presets in the generic context-store layer.
-- Template override search paths.
-- Rich validation execution.
-- Agent guidance generation.
-- Workspace integration.
-- Git sync, commits, pull, push, watch, or conflict behavior.
-
-## Implemented Slice
-
-- Added a pure runtime collection module at
-  `src/core/collections/runtime.ts`.
-- Exported the module through `src/core/collections/index.ts` and
-  `src/core/index.ts`.
-- Added focused tests under `test/core/collections/runtime.test.ts`.
-- Proved a generic `{ id: "initiatives", mount: "initiatives" }` definition can
-  mount and resolve paths without initiative-specific store logic.
-- Kept validation/template hooks as inert extension fields for now; rich hook
-  execution remains deferred.

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/04-add-collection-foundation/tasks.md

@@ -1,14 +0,0 @@
-# Add Collection Foundation Tasks
-
-- [x] Research what Item 4 needs to decide.
-- [x] Compare collection model options.
-- [x] Run clean-code and design-pattern review.
-- [x] Decide to keep Item 4 as a runtime mount/path foundation.
-- [x] Decide to avoid long context-stacked helper names.
-- [x] Decide to separate context-store registration from runtime collection
-  mounting.
-- [x] Define exact collection mount and path rules.
-- [x] Define the minimal runtime registry and mounted collection API.
-- [x] Implement collection foundation helpers and tests.
-- [x] Prove `initiatives/` can mount without store-specific initiative logic.
-- [x] Run targeted verification.

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

@@ -1,99 +0,0 @@
-# Ship Initiative MVP Evidence
-
-## Research Summary
-
-- Initiative code should live in `src/core/collections/initiatives/`, outside
-  `src/core/context-store/`.
-- Initiative APIs should consume a mounted `initiatives` collection from Item 4
-  rather than raw context-store roots.
-- The first coding slice should lock metadata and templates before mounted
-  create/list operations.
-- Visible `initiative.yaml` is preferred for the new shared initiative model.
-- `links.yaml` should not exist in the initiative MVP. Repo-change wiring is a
-  workspace/local coordination concern to revisit later.
-- Read/show, update, and delete have extra policy risk, so create/list should
-  come before broader lifecycle behavior.
-- The first mounted operation slice should do create/list only. A full
-  `readInitiative` API is deferred until the return shape is clearer.
-
-## Decisions
-
-- Use `src/core/collections/initiatives/` for initiative-domain code.
-- Do not put initiative semantics into `src/core/context-store/`.
-- Add `initiative.yaml` strict parse/serialize helpers.
-- Generate Markdown files up front, but do not validate Markdown content beyond
-  existence/templates in the first pass.
-- Defer workspace opening, repo resolution, status dashboards, sync, linked
-  change lifecycle, `links.yaml`, `contracts/`, and CLI behavior.
-- Detect initiatives by valid `initiative.yaml`: missing means ignore, invalid
-  means fail loudly, and the YAML `id` must match the folder name.
-
-## Suggested First Coding Slice
-
-Add:
-
-- `src/core/collections/initiatives/schema.ts`
-- `src/core/collections/initiatives/templates.ts`
-- `src/core/collections/initiatives/operations.ts`
-- `src/core/collections/initiatives/index.ts`
-- focused tests under `test/core/collections/initiatives/`
-
-Cover:
-
-- constants for initiative file names
-- `validateInitiativeId`
-- strict `initiative.yaml` parse/serialize
-- create/list operations through a mounted `initiatives` collection
-- template builders for `requirements.md`, `design.md`, `decisions.md`,
-  `questions.md`, and `tasks.md`
-- tests for valid and invalid metadata, invalid IDs, unknown YAML fields,
-  required `created`, and generated template names/content shape
-
-## Implementation Evidence
-
-- `src/core/collections/initiatives/schema.ts` defines initiative constants,
-  strict persisted `initiative.yaml` parsing/serialization, required
-  `created`, bounded JSON-like metadata, statuses, and portable kebab-case
-  initiative IDs.
-- `src/core/collections/initiatives/templates.ts` defines deterministic default
-  Markdown file builders for requirements, design, decisions, questions, and
-  tasks.
-- `src/core/collections/initiatives/index.ts` exports the initiative
-  schema/template surface inside the initiative module only.
-- `src/core/collections/initiatives/operations.ts` creates MVP initiative
-  folders and lists initiative states using the valid-`initiative.yaml`
-  detection rule.
-- `src/core/collections/index.ts` exports the initiative module now that it has
-  a mounted operation API.
-- `test/core/collections/initiatives/schema.test.ts` covers file constants,
-  no `links.yaml`, ID validation, strict YAML behavior, required `created`,
-  default owners/metadata, metadata validation, and serialization round trips.
-- `test/core/collections/initiatives/templates.test.ts` covers generated
-  Markdown file names, deterministic ordering, trailing newlines, and expected
-  section headings.
-- `test/core/collections/initiatives/operations.test.ts` covers create, list,
-  duplicate protection, cleanup on partial write failure, missing
-  `initiative.yaml` ignored, invalid `initiative.yaml` failure, and folder/id
-  mismatch failure.
-- `src/core/context-store/registry.ts` was added as the next integration
-  enabler before CLI wiring.
-- `src/commands/initiative.ts` adds `openspec initiative create/list` as a thin
-  CLI adapter over the context-store facade and mounted initiatives collection.
-- `src/cli/index.ts` registers the initiative command.
-- `src/core/completions/command-registry.ts` registers static completion
-  metadata for `initiative create/list/ls`.
-- `test/commands/initiative.test.ts` covers JSON create, `--store-path` list,
-  human output, selector errors, duplicate create errors, and completion
-  registry entries.
-
-## Verification
-
-- `pnpm exec vitest run test/core/collections/initiatives/schema.test.ts test/core/collections/initiatives/templates.test.ts`
-- `pnpm exec vitest run test/core/collections/initiatives/operations.test.ts`
-- `pnpm exec vitest run test/core/collections/initiatives/schema.test.ts test/core/collections/initiatives/templates.test.ts test/core/collections/initiatives/operations.test.ts test/core/collections/runtime.test.ts test/core/context-store/foundation.test.ts test/core/planning-home.test.ts`
-- `pnpm exec vitest run test/commands/initiative.test.ts`
-- `pnpm exec vitest run test/core/context-store/registry.test.ts test/core/collections/initiatives/operations.test.ts test/core/collections/initiatives/schema.test.ts test/core/collections/initiatives/templates.test.ts test/core/collections/runtime.test.ts`
-- `pnpm exec vitest run test/commands/workspace.test.ts`
-- `pnpm run build`
-- `pnpm run lint`
-- `git diff --check`