sauron-cli 1.1.3 → 1.3.0

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

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

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

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

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

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