sauron-cli 1.1.3 → 1.3.0

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

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

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

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

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

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

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

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

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

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