sauron-cli 1.3.0 → 1.4.1

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

@@ -1,29 +0,0 @@
-# Add Minimal Context Store UX Tasks
-
-- [x] Create Item 6 work-item tracking notes.
-- [x] Capture agent-first setup and discovery direction.
-- [x] Decide `context-store` is the first CLI namespace.
-- [x] Decide setup defaults to `./<id>` when `--path` is omitted.
-- [x] Decide current-directory setup requires explicit `--path .`.
-- [x] Record that checked-in store metadata stays minimal.
-- [x] Decide checked-in store metadata is exactly `.openspec-store/store.yaml`
-  and contains portable identity only.
-- [x] Record that machine-local registry state stays outside the store.
-- [x] Record that `initiative list` should default across registered stores.
-- [x] Decide setup interactive and non-interactive behavior.
-- [x] Decide register behavior.
-- [x] Decide context-store list is registry index only.
-- [x] Decide doctor owns health checks.
-- [x] Decide initiative list partial-success behavior.
-- [x] Decide JSON and exit behavior for partial success and total failure.
-- [x] Decide id inference uses folder/repo name as-is with normal validation.
-- [x] Decide setup rejects non-empty folders without context-store metadata.
-- [x] Decide registry path/id conflicts fail for now.
-- [x] Decide empty states for list, doctor, and initiative list.
-- [x] Initially defer completion metadata; later add static metadata with the
-  rest of the shipped command surface.
-- [x] Finalize exact JSON payload fields for setup, register, list, doctor, and
-  all-store initiative list.
-- [x] Implement `context-store setup/register/list/doctor`.
-- [x] Update `initiative list` all-store behavior and output.
-- [x] Add focused tests and verification evidence.

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/07-add-agent-first-initiative-discovery/evidence.md

@@ -1,97 +0,0 @@
-# Add Agent-First Initiative Discovery Evidence
-
-## Conversation Decisions
-
-- `initiative show <id>` should be a locator/discovery command for agents.
-- The command should answer which initiative the user meant, where the
-  canonical context lives, and where the initiative metadata is.
-- The command should not concatenate markdown, summarize initiative contents,
-  compute work progress, resolve local repos, list linked changes, or open a
-  workspace.
-- Default lookup should search all registered context stores.
-- `--store <id>` should disambiguate or filter to one registered store.
-- `--store-path <path>` should remain the explicit local-path escape hatch.
-- Duplicate initiative ids across stores should fail with an ambiguity error.
-- Default all-store lookup should fail when any registered store is unreadable,
-  because uniqueness is unknowable.
-- Explicit `--store` and `--store-path` lookup should only care about the
-  selected store.
-- `initiative.status` should be omitted from the v1 output projection.
-- `owners` should be omitted from the v1 output projection.
-- Arbitrary `metadata` should be omitted from the v1 output projection.
-- `version` and `created` should stay in the v1 initiative projection.
-- `files` should be omitted from v1.
-- `initiative.metadata_path` should point to the validated `initiative.yaml`.
-- `initiative.root` is enough for an agent to inspect the folder with normal
-  filesystem tools.
-- Top-level `matches` should be omitted. Ambiguity and incomplete-lookup
-  candidates should live under the diagnostic that needs them, for example
-  `status[0].details.matches`.
-- `context_store.source` should be omitted from `initiative show` v1 because it
-  is selector provenance, not context-store identity.
-- A top-level `resolution` field is not needed in v1.
-- Existing `initiative create/list` output can keep `context_store.source` for
-  now; this item should not refactor old output shapes.
-- `readInitiative` should return `null` when the exact initiative is absent and
-  throw when `initiative.yaml` exists but is invalid or has the wrong id.
-- In default all-store lookup, any unreadable registered store should make the
-  primary error `initiative_lookup_incomplete`, even when readable stores have
-  partial matches.
-- If `initiatives/<id>/initiative.yaml` exists but is invalid or has the wrong
-  id, `initiative show` should fail as broken initiative state instead of
-  treating that store as not found.
-- Human output should be a compact locator view on success: title, id, summary,
-  context store, location, and canonical filenames.
-- Human ambiguity and incomplete-lookup errors should show matching or partial
-  matching stores inline, then point to the next command.
-- Static shell completion metadata should ship for `initiative show`.
-- Dynamic completions for store ids and initiative ids should remain deferred.
-
-## Research Notes
-
-- Current initiative create/list output spreads the full parsed
-  `initiative.yaml` state, which is useful for MVP but too broad for the first
-  `show` contract.
-- A focused per-initiative read operation is preferred over implementing `show`
-  through `listInitiatives`, because exact lookup should not fail due to an
-  unrelated malformed initiative folder.
-- Other initiative files are schema/config dependent and should not be
-  hardcoded into `show`.
-- Keeping candidates inside diagnostic details follows the same general shape as
-  GraphQL-style responses: successful data stays clean, while error-specific
-  context travels with the error.
-- If selector provenance is needed later, add a separate explicit field such as
-  `resolution` rather than putting provenance inside `context_store`.
-- Human output should stay compact: title, id, summary, context store,
-  location, and metadata path.
-
-## Implementation Evidence
-
-- `src/core/collections/initiatives/operations.ts` adds `readInitiative` for
-  exact initiative lookup.
-- `src/commands/initiative.ts` adds `initiative show <id>` with all-store
-  default lookup, `--store`, `--store-path`, JSON output, compact human output,
-  ambiguity diagnostics, and incomplete-lookup diagnostics.
-- `src/core/completions/command-registry.ts` adds static completion metadata for
-  `initiative show`.
-- `test/core/collections/initiatives/operations.test.ts` covers exact read,
-  absent initiatives, invalid exact initiatives, id mismatches, and unrelated
-  invalid folders.
-- `test/commands/initiative.test.ts` covers `initiative show` success,
-  `--store-path`, human output, ambiguity, incomplete lookup, not found,
-  invalid exact initiative state, no `context_store.source`, no `files`, no
-  top-level `matches`, and static completions.
-
-## Verification
-
-- `pnpm run build`
-- `pnpm exec vitest run test/core/collections/initiatives/operations.test.ts`
-- `pnpm exec vitest run test/commands/initiative.test.ts`
-- `pnpm exec vitest run test/commands/context-store.test.ts
-  test/commands/initiative.test.ts test/core/context-store/foundation.test.ts
-  test/core/context-store/registry.test.ts
-  test/core/collections/initiatives/operations.test.ts`
-- `pnpm run lint`
-- `git diff --check`
-- Markdown line-length check for the initiative roadmap, task tracker, and Item
-  7 work-item notes.

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/07-add-agent-first-initiative-discovery/plan.md

@@ -1,184 +0,0 @@
-# Add Agent-First Initiative Discovery
-
-## Status
-
-Implementation complete; verification in progress.
-
-## Source Of Truth
-
-Start from `../../direction.md`.
-
-This item exists because the expected workflow is agent-first:
-
-```text
-Using initiative billing-launch, explore the API work and create a proposal.
-```
-
-Before repo-local linking, local resolution, or workspace opening can work, the
-agent needs a small command that answers:
-
-- Which initiative did the user mean?
-- Which context store contains the canonical initiative?
-- Where is the initiative metadata, and what root should the agent inspect?
-
-## Goal
-
-Add agent-first initiative discovery without turning `show` into a reader,
-progress dashboard, repo resolver, or workspace launcher.
-
-## Locked Direction So Far
-
-- `initiative show <id>` is a locator/discovery command.
-- It should return identity, context-store location, initiative location, and
-  the initiative metadata path.
-- It should not concatenate markdown, summarize file contents, compute progress,
-  resolve repos, list linked changes, or open workspaces.
-- Default lookup searches all locally registered context stores.
-- `--store <id>` filters to one registered store.
-- `--store-path <path>` remains the explicit local-path escape hatch.
-- Duplicate initiative ids across stores are ambiguous. The command should not
-  auto-pick a match.
-- In default all-store lookup, unreadable stores make the lookup incomplete.
-  The command should fail rather than silently returning a possibly false
-  unique match.
-- Explicit `--store` and `--store-path` modes only consider the selected store.
-
-## Output Contract Direction
-
-The first JSON contract should be a resolver/read-pointer projection, not a
-full serialization of `initiative.yaml`.
-
-Suggested success shape:
-
-```json
-{
-  "context_store": {
-    "id": "platform",
-    "root": "/path/to/platform-context"
-  },
-  "initiative": {
-    "version": 1,
-    "id": "billing-launch",
-    "title": "Billing Launch",
-    "summary": "Coordinate billing launch work.",
-    "created": "2026-05-21",
-    "root": "/path/to/platform-context/initiatives/billing-launch",
-    "store_path": "initiatives/billing-launch",
-    "metadata_path": "/path/to/platform-context/initiatives/billing-launch/initiative.yaml"
-  },
-  "status": []
-}
-```
-
-Locked field decisions:
-
-- Keep `initiative.version`.
-- Keep `initiative.created`.
-- Keep `initiative.id`, `title`, `summary`, `root`, `store_path`, and
-  `metadata_path`.
-- Keep `context_store.id` and `root`.
-- Omit `context_store.source` from `initiative show` v1. It is selector
-  provenance, not context-store identity. Existing create/list output can remain
-  unchanged for now.
-- Omit a top-level `resolution` field from v1.
-- Omit `initiative.status` from the v1 projection.
-- Omit `initiative.owners` from the v1 projection.
-- Omit arbitrary `initiative.metadata` from the v1 projection.
-- Omit a `files` list from the v1 projection.
-- Omit top-level `matches`.
-- Put ambiguity and incomplete-lookup candidates under the relevant diagnostic
-  entry, such as `status[0].details.matches`.
-- Keep top-level `status` as command diagnostics only, not initiative work
-  progress.
-
-## Still To Decide
-
-- Nothing for the minimal v1 slice.
-
-## Human Output Direction
-
-Success output should stay locator-focused:
-
-```text
-OpenSpec initiative: Billing Launch
-
-ID: billing-launch
-Summary: Coordinate billing launch work.
-Context store: platform
-Location: /path/to/platform-context/initiatives/billing-launch
-
-Files:
-  Metadata: /path/to/platform-context/initiatives/billing-launch/initiative.yaml
-```
-
-Error output should stay plain:
-
-- Not found: say the initiative was not found in registered context stores and
-  suggest `openspec initiative list`.
-- Ambiguous: show matching stores and paths, then suggest
-  `openspec initiative show <id> --store <store>`.
-- Incomplete lookup: say some context stores could not be read, include partial
-  matches when present, then suggest `openspec context-store doctor`.
-
-## File Listing Direction
-
-`initiative show` should not list initiative folder contents in v1.
-
-Only `initiative.yaml` is required to identify and validate the initiative. All
-other files are schema/config dependent and may differ across teams. Once the
-command has resolved `initiative.root`, agents can use normal filesystem tools
-to inspect the folder. Later schema-aware views can expose important files
-without hardcoding today's default template filenames.
-
-## Completion Direction
-
-Add static shell completion metadata for:
-
-```text
-initiative show <id> --store <id> --store-path <path> --json
-```
-
-Do not add dynamic completions for registered store ids or initiative ids in
-this slice.
-
-## Core Read Operation Direction
-
-Add a focused `readInitiative` operation for exact lookup.
-
-Behavior:
-
-- Return `null` when the initiative folder or `initiative.yaml` is absent.
-- Throw when `initiative.yaml` exists but is invalid.
-- Throw when the parsed `initiative.yaml` id does not match the folder id.
-- Do not scan unrelated initiative folders.
-
-## Lookup Error Precedence
-
-For default all-store lookup, any unreadable registered store makes lookup
-incomplete.
-
-If one or more readable stores contain the initiative and one or more other
-stores cannot be read, the primary error should still be
-`initiative_lookup_incomplete`, not success or ambiguity. Include any readable
-partial matches under the diagnostic details.
-
-Explicit `--store` and `--store-path` modes are scoped to the selected store and
-do not check unrelated registered stores.
-
-Invalid exact initiative folders are broken shared state, not "not found".
-
-If `initiatives/<id>/initiative.yaml` exists but is invalid or has a mismatched
-id, `initiative show` should fail with an invalid-initiative diagnostic. In
-default all-store lookup, unreadable stores still take precedence as
-`initiative_lookup_incomplete` because the full candidate set is unknowable.
-
-## Explicitly Out Of Scope
-
-- Top-level `openspec show` integration.
-- Markdown content bundles or generated context packs.
-- Checked-in initiative snapshots in repo-local changes.
-- Repo-local change linking.
-- Local repo/workspace resolution.
-- Workspace opening.
-- Git sync status, dirty state, remotes, pull, push, or conflicts.
-- Initiative progress or status dashboards.

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/07-add-agent-first-initiative-discovery/tasks.md

@@ -1,27 +0,0 @@
-# Add Agent-First Initiative Discovery Tasks
-
-- [x] Create Item 7 work-item tracking notes.
-- [x] Decide `initiative show <id>` is a locator/discovery command.
-- [x] Decide default lookup searches all registered context stores.
-- [x] Decide `--store` and `--store-path` remain the narrowing selectors.
-- [x] Decide duplicate initiative ids are ambiguity errors.
-- [x] Decide unreadable stores make default all-store lookup incomplete.
-- [x] Decide the v1 projection omits `initiative.status`, `owners`, and
-  arbitrary `metadata`.
-- [x] Decide the v1 projection keeps `initiative.version` and `created`.
-- [x] Decide v1 omits `files` and only returns initiative root plus metadata
-  path.
-- [x] Decide ambiguity and incomplete-lookup candidates live under diagnostic
-  details, not top-level `matches`.
-- [x] Decide exact human output direction for success and error states.
-- [x] Decide `initiative show` omits `context_store.source`.
-- [x] Decide `initiative show` omits a top-level `resolution` field.
-- [x] Decide static completion metadata ships with Item 7.
-- [x] Decide `readInitiative` returns `null` for absent and throws for invalid.
-- [x] Decide incomplete lookup takes precedence over success or ambiguity in
-  default all-store mode.
-- [x] Decide invalid exact initiative folders are errors, not not-found.
-- [x] Implement a focused per-initiative read operation.
-- [x] Implement `initiative show`.
-- [x] Register static completion metadata for `initiative show`.
-- [x] Add focused tests and verification evidence.

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/08-connect-repo-local-changes-to-initiatives/evidence.md

@@ -1,239 +0,0 @@
-# Connect Repo-Local Changes To Initiatives Evidence
-
-## Decision 1: Initiative Link Location
-
-The initiative link should live in the repo-local change `.openspec.yaml`.
-
-Example:
-
-```yaml
-schema: spec-driven
-created: 2026-05-22
-initiative:
-  store: platform
-  id: billing-launch
-```
-
-This keeps repo implementation ownership in the repo while preserving a durable
-reference to canonical initiative context.
-
-The link should not include local paths, copied initiative prose, or backlinks
-inside the initiative store.
-
-## Research Notes
-
-- `createChange()` already writes `.openspec.yaml` for every change.
-- `ChangeMetadataSchema` currently allows schema, created, goal, and
-  affected-area fields. Item 8 can extend that schema with `initiative`.
-- Archive moves the whole change directory, so the initiative link will move
-  with archived changes.
-- Apply, validate, and archive should not require context-store availability in
-  this slice.
-
-## Decision 2: Create Command Shape
-
-Initiative-linked creation should use `openspec new change` with `--initiative`.
-
-Supported first-slice forms:
-
-```bash
-openspec new change add-billing-api --initiative billing-launch --json
-openspec new change add-billing-api --initiative platform/billing-launch --json
-openspec new change add-billing-api --initiative billing-launch --store platform --json
-```
-
-This keeps the operation repo-owned. The initiative is a reference on the
-change, not the actor that creates or owns the change.
-
-The first slice should also add `--json` to `new change` so agents can capture
-the created change path, metadata path, and initiative reference.
-
-## Decision 3: Initiative Lookup Behavior
-
-Bare `--initiative <id>` should reuse `initiative show` lookup semantics.
-
-It searches all registered context stores and succeeds only when the lookup is
-complete and exactly one readable store contains the initiative.
-
-Explicit store selectors narrow lookup:
-
-```bash
-openspec new change add-billing-api --initiative platform/billing-launch
-openspec new change add-billing-api --initiative billing-launch --store platform
-openspec new change add-billing-api --initiative billing-launch --store-path ./context
-```
-
-`--store-path` validates the explicit path and reads its store id, but does not
-auto-register the store. Metadata still stores only the portable store id and
-initiative id.
-
-Repo-local metadata should not be written until initiative lookup is complete
-and unambiguous.
-
-## Decision 4: Repo-Local Only For V1
-
-Item 8 should support initiative links only on repo-local changes.
-
-If `openspec new change <id> --initiative ...` runs from a workspace planning
-home, v1 should refuse and tell the user to run the command from the repo that
-owns the implementation plan.
-
-Existing workspace-planning changes remain compatibility behavior and should not
-gain initiative linkage in this slice.
-
-This preserves the boundary that initiatives coordinate shared context,
-repo-local changes own implementation plans, and workspaces open local views.
-
-## Decision 5: No Repo Ownership Matching In V1
-
-Item 8 should not verify that the current repo is named by, owned by, or inferred
-from the initiative.
-
-Creating a repo-local change with an initiative link records participation in the
-initiative. It does not prove ownership, repo impact, or coverage of an
-initiative area.
-
-Repo ownership matching can be revisited after initiative resolution or explicit
-initiative metadata has a real repo/area model.
-
-## Decision 6: JSON And Human Output
-
-Create output should stay factual and minimal.
-
-Human output should confirm:
-
-- the created change id and location
-- the schema
-- the initiative link `{ store, id }`
-
-JSON output should include:
-
-```json
-{
-  "change": {
-    "id": "add-billing-api",
-    "path": "/repo/openspec/changes/add-billing-api",
-    "metadataPath": "/repo/openspec/changes/add-billing-api/.openspec.yaml",
-    "schema": "spec-driven"
-  },
-  "initiative": {
-    "store": "platform",
-    "id": "billing-launch"
-  }
-}
-```
-
-The output should not include `next` or other suggested workflow actions. API
-responses should report operation results or errors; choosing the next action is
-the agent's responsibility and depends on broader context.
-
-## Decision 7: Existing Change Recovery
-
-Item 8 should include a friendly recovery command for existing repo-local
-changes:
-
-```bash
-openspec set change add-billing-api --initiative billing-launch --json
-openspec set change add-billing-api --initiative platform/billing-launch --json
-openspec set change add-billing-api --initiative billing-launch --store platform --json
-openspec set change add-billing-api --initiative billing-launch --store-path ../context --json
-```
-
-This command is a validated setter for checked-in repo-local change metadata. In
-Item 8, the only supported settable field is the initiative link, and the only
-file it may mutate is `openspec/changes/<id>/.openspec.yaml`.
-
-The command should not edit proposal, design, tasks, specs, or initiative-store
-files. It should not store local paths or write backlinks into the initiative.
-
-If the requested initiative link already exists, the command should succeed as
-an idempotent no-op. If a different initiative link already exists, the command
-should fail without writing. Replacement, relink, unlink, and dry-run behavior
-are deferred.
-
-Rationale:
-
-- Agents can forget to link a change during creation, so a first-class recovery
-  path is useful.
-- `set change` matches the actual side effect: writing validated change metadata
-  to `.openspec.yaml`.
-- Keeping the command scoped to `.openspec.yaml` avoids creating a broad change
-  editing surface.
-- `openspec change ...` is currently deprecated, `edit` implies opening an
-  editor, and `update` already means refreshing local OpenSpec tooling or
-  guidance.
-
-## Decision 8: Status And Instructions Visibility
-
-Status and instructions should surface that the repo-local change is linked to
-an initiative, but should not display or resolve the initiative itself.
-
-Human status output should show the stored initiative reference, and JSON status
-output should include the stored initiative `{ store, id }`. Instructions output
-should include a concise factual note that the change is linked to the
-initiative.
-
-Status and instructions should not read, summarize, validate, or resolve the
-initiative from the context store in v1. Missing or unavailable context stores
-should not make repo-local status or instructions fail.
-
-This keeps the relationship visible during ordinary repo-local workflows while
-preserving the boundary that initiative lookup and context reading belong to
-initiative-specific commands.
-
-## Latest Open-Decision Notes
-
-Date: 2026-05-23.
-
-All decisions for Item 8 are now confirmed for implementation.
-
-Implementation should keep the first slice small:
-
-- The light release should test whether initiative-linked repo-local changes are
-  useful before adding gating, ownership inference, or broader workflow
-  integration.
-- Standalone `initiative resolve` was later rejected; workspace local-view state
-  owns local path mapping.
-- Source provenance, history/export, contract maps, and target-bound
-  initiative-hosted changes remain useful future discussion points, but should
-  not block this initial slice.
-
-## Implementation Evidence
-
-Date: 2026-05-23.
-
-Implemented:
-
-- `openspec new change <id> --initiative ...` for repo-local changes, with
-  `--json`, `--store`, and `--store-path` support.
-- `openspec set change <id> --initiative ...` for existing repo-local changes.
-- Portable checked-in metadata under `initiative: { store, id }`.
-- Status and instructions visibility from stored metadata only.
-- Workspace refusal, lookup-failure no-write behavior, same-link idempotency,
-  and different-link conflict protection.
-
-Verification:
-
-```bash
-pnpm run build
-```
-
-Result: passed.
-
-```bash
-pnpm exec eslint src/commands/workflow/new-change.ts src/commands/workflow/set-change.ts src/commands/workflow/initiative-link.ts src/commands/workflow/instructions.ts src/commands/workflow/status.ts src/commands/workflow/shared.ts src/commands/initiative.ts src/core/artifact-graph/types.ts src/core/artifact-graph/instruction-loader.ts src/utils/change-utils.ts src/cli/index.ts
-```
-
-Result: passed.
-
-```bash
-pnpm exec vitest run test/utils/change-metadata.test.ts test/commands/change-initiative-link.test.ts
-```
-
-Result: passed, 39 tests.
-
-```bash
-pnpm exec vitest run test/commands/artifact-workflow.test.ts test/commands/initiative.test.ts test/core/artifact-graph/instruction-loader.test.ts
-```
-
-Result: passed, 110 tests.