sauron-cli 1.3.0 → 1.4.1

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

@@ -1,279 +0,0 @@
-# Connect Repo-Local Changes To Initiatives
-
-## Status
-
-Implemented. The original decision text below is preserved as design record;
-current completion evidence lives in `tasks.md` and `evidence.md`.
-
-## Source Of Truth
-
-Start from `../../direction.md` and the Item 8 roadmap entry.
-
-The relevant boundary is:
-
-```text
-Initiatives coordinate shared context.
-Repo-local changes own implementation plans.
-Workspaces open local views.
-```
-
-## Goal
-
-Let an agent create or link a repo-local OpenSpec change to a shared
-initiative without copying initiative prose, storing machine-local paths, or
-making the initiative own repo implementation artifacts.
-
-Example user prompt:
-
-```text
-Using initiative billing-launch, create a proposal for API work.
-```
-
-## Decisions
-
-### 1. Initiative Link Location
-
-Decision: Store the initiative link in the repo-local change `.openspec.yaml`.
-
-Suggested metadata shape:
-
-```yaml
-schema: spec-driven
-created: 2026-05-22
-initiative:
-  store: platform
-  id: billing-launch
-```
-
-Rules:
-
-- Store only the context store id and initiative id.
-- Do not store local context-store paths.
-- Do not store local repo paths.
-- Do not create a checked-in `initiative.md` snapshot by default.
-- Do not write backlinks into the initiative.
-
-Rationale:
-
-- `.openspec.yaml` is already the per-change machine-readable metadata file.
-- The link is durable repo context and should be checked in with the change.
-- The canonical initiative context remains in the context store.
-- The metadata stays portable across teammates and machines.
-
-### 2. Create Command Shape
-
-Decision: Add initiative linking to the repo-local change creation command 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
-```
-
-Rules:
-
-- The command starts from `new change` because the change is repo-owned.
-- `--initiative` modifies repo-local change creation; it does not make the
-  initiative create or own the change.
-- `--json` should be added to `new change` for agent-readable handoff output.
-- A separate initiative-owned create command is not part of the first slice.
-
-Rationale:
-
-- The expected user flow is agent-first: "using initiative X, create a proposal
-  for repo work."
-- Agents need one normal repo-local create command that can also write the
-  initiative reference.
-- Keeping the verb rooted in `new change` preserves the boundary that changes
-  implement repo-owned slices.
-
-### 3. Initiative Lookup Behavior
-
-Decision: Reuse `initiative show` lookup semantics for `--initiative`.
-
-Rules:
-
-- Bare `--initiative <id>` searches all registered context stores.
-- Bare lookup succeeds only when exactly one readable registered store contains
-  the initiative id.
-- Duplicate initiative ids across stores fail as ambiguous.
-- Any unreadable registered store makes bare lookup incomplete and fails before
-  writing change metadata.
-- `--initiative <store>/<id>` selects one registered store by id.
-- `--initiative <id> --store <store>` also selects one registered store by id.
-- `--initiative <id> --store-path <path>` validates the explicit local context
-  store path, reads its store id, and writes only `{ store, id }` to metadata.
-- `--store-path` does not auto-register the context store.
-- Do not write repo-local initiative metadata until lookup is complete and
-  unambiguous.
-
-Rationale:
-
-- Agents can use the short form when it is safe.
-- Durable repo-local links should not be created from partial knowledge.
-- The behavior matches existing agent-first discovery semantics.
-
-### 4. Repo-Local Only For V1
-
-Decision: Item 8 supports initiative links only on repo-local changes.
-
-Rules:
-
-- `openspec new change <id> --initiative ...` creates an initiative-linked
-  change only when the current planning home is repo-local.
-- If the command runs from a workspace planning home, v1 refuses with clear
-  guidance to run the command from the repo that owns the implementation plan.
-- Existing workspace-planning changes remain compatibility behavior and are not
-  extended with initiative linkage in this slice.
-
-Rationale:
-
-- The current product boundary assigns implementation plans to repo-local
-  OpenSpec changes.
-- Workspaces are local views, not the durable planning owner for initiative
-  work.
-- Extending workspace-planning changes would revive the superseded
-  workspace-owns-the-plan model.
-
-### 5. Repo Ownership Matching
-
-Decision: Do not attempt repo ownership matching in v1.
-
-Rules:
-
-- Creating a repo-local change with an initiative link records participation in
-  the initiative.
-- The link does not claim that OpenSpec verified repo ownership, repo impact, or
-  initiative area coverage.
-- The command should not block or warn solely because the current repo is absent
-  from initiative content.
-
-Rationale:
-
-- Item 8 should not invent repo ownership or monorepo area semantics.
-- Ownership matching belongs with later initiative resolution or explicit
-  initiative metadata.
-- Keeping v1 small lets teams test whether linked repo-local changes are useful
-  before adding policy gates.
-
-### 6. JSON And Human Output
-
-Decision: Keep create output factual and minimal.
-
-Rules:
-
-- Output should report what the command did, not recommend workflow next steps.
-- Human output should confirm the created change location, schema, and initiative
-  link.
-- JSON output should include stable fields for the created change and initiative
-  link.
-- JSON output should not include a `next` command or suggested workflow action.
-- Output should not include initiative summaries, repo ownership claims,
-  resolved local context-store paths, or progress/status-like fields.
-
-Suggested JSON shape:
-
-```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"
-  }
-}
-```
-
-Rationale:
-
-- CLI/API-style responses should state operation results or errors.
-- Accurately choosing the next action depends on agent context and should remain
-  the agent's responsibility.
-- Keeping output factual avoids coupling change creation to later lifecycle
-  design.
-
-### 7. Existing Change Recovery
-
-Decision: Include a recovery command for setting the initiative link on an
-existing repo-local change.
-
-Command shape:
-
-```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
-```
-
-Rules:
-
-- `openspec set change <id> --initiative ...` is a validated setter for
-  repo-local change metadata.
-- In Item 8, the only supported settable field is the initiative link.
-- The command only mutates `openspec/changes/<id>/.openspec.yaml`.
-- The command does not edit proposal, design, tasks, specs, or initiative-store
-  files.
-- The command uses the same initiative lookup semantics as
-  `openspec new change <id> --initiative ...`.
-- If the same initiative link already exists, the command succeeds as an
-  idempotent no-op.
-- If a different initiative link already exists, the command fails without
-  writing. Replacement, relink, unlink, and dry-run behavior are not part of v1.
-- If the command runs from a workspace planning home, it refuses for the same
-  reason as initiative-linked `new change`.
-
-Rationale:
-
-- Agents can forget to pass `--initiative` during change creation; v1 needs a
-  friendly recovery path.
-- `set change` describes the real operation: setting checked-in change metadata,
-  not creating an initiative-owned relationship.
-- Keeping the command limited to `.openspec.yaml` avoids a broad edit surface.
-- Avoid `openspec change ...` because that namespace is currently deprecated.
-- Avoid `edit` because it implies opening an editor, and avoid `update` because
-  OpenSpec already uses update for local guidance/tool refresh.
-
-### 8. Status And Instructions Visibility
-
-Decision: Surface the initiative link in status and instructions output without
-resolving or displaying the initiative itself.
-
-Rules:
-
-- Human status output should show that the change is linked to an initiative.
-- 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 must not read, summarize, validate, or resolve the
-  initiative from the context store in v1.
-- Missing or unavailable context stores must not make repo-local status or
-  instructions fail.
-- Output should not add next-step recommendations.
-
-Rationale:
-
-- The initiative link should be visible in normal repo-local workflow output so
-  users and agents do not miss the relationship.
-- Keeping visibility to stored metadata avoids introducing context-store
-  availability as a dependency for repo-local workflow commands.
-- Initiative resolution belongs to initiative-specific commands, not status or
-  instructions in this slice.
-
-## Open Decisions
-
-None. Decision pass complete; confirm the decisions before implementation.
-
-## Latest Suggested Resolutions
-
-These were the suggested answers carried into implementation:
-
-- Surface the stored initiative link in status and instructions without reading
-  or displaying the initiative itself.

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

@@ -1,22 +0,0 @@
-# Connect Repo-Local Changes To Initiatives Tasks
-
-## Decisions
-
-- [x] Decide where the initiative link lives.
-- [x] Decide command shape for creating initiative-linked changes.
-- [x] Decide initiative lookup behavior for `--initiative`.
-- [x] Decide whether workspace-scoped changes are allowed in this slice.
-- [x] Decide whether repo ownership matching is attempted in v1.
-- [x] Decide JSON and human output shape.
-- [x] Decide whether Item 8 includes linking existing changes.
-- [x] Decide whether status/instructions surface initiative links.
-- [x] Confirm latest suggested resolutions in `plan.md` before implementation.
-
-## Implementation
-
-- [x] Extend change metadata schema with an optional initiative link.
-- [x] Persist initiative metadata when creating repo-local changes.
-- [x] Add command support for creating initiative-linked changes.
-- [x] Add tests for metadata validation and persistence.
-- [x] Add tests for command output and lookup failures.
-- [x] Add status/instruction visibility for stored initiative links.

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/09-add-initiative-resolve/decision-review.md

@@ -1,64 +0,0 @@
-# Item 9 Decision: Reject Initiative Resolve
-
-## Final Decision
-
-Do not implement a standalone `openspec initiative resolve <id>` command, now
-or later.
-
-The command is unnecessary because it tries to do work that already belongs to
-other concepts:
-
-- `initiative show` finds the canonical initiative.
-- A workspace is the local view over repos and folders.
-- Repo-local changes link themselves to initiatives.
-- Repo-local status reports work progress.
-
-## Decision 1: No Command
-
-No separate initiative command is needed.
-
-If the user only has a context store, `initiative show` is enough. If the user
-has a workspace, the local view is already represented by that workspace. If the
-user is inside a repo, repo-local commands are enough.
-
-## Decision 2: Local Resolution Belongs To Workspace
-
-A workspace maps local repos and folders to paths on one machine. Future
-initiative-aware local opening belongs in workspace behavior.
-
-## Decision 3: Agent Behavior
-
-Agents should:
-
-- Use `openspec initiative show <id> --json` for shared context.
-- Use the current workspace view when the user is working in a workspace.
-- Use repo-local commands when the user is working in a repo.
-- Let the user decide which repos are present locally.
-
-## Decision 4: Rejected Scope
-
-Remove all standalone resolve behavior:
-
-- no `initiative resolve`
-- no all-repo scan
-- no all-workspace scan
-- no `--path` search roots
-- no Git remote matching
-- no cloning
-- no worktree or branch creation
-- no initiative backlinks
-- no local availability dashboard
-
-## Decision 5: Roadmap Update
-
-Convert Item 9 into a decision-only checkpoint.
-
-Replacement:
-
-```text
-Item 9. Reject Initiative Resolve
-
-Decision: do not add `openspec initiative resolve`, now or later. Initiative
-discovery belongs to `initiative show`; local path mapping belongs to
-workspaces; implementation progress belongs to repo-local changes.
-```

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/09-add-initiative-resolve/evidence.md

@@ -1,106 +0,0 @@
-# Reject Initiative Resolve Evidence
-
-## Decision Summary
-
-Date: 2026-05-25.
-
-After review, the standalone `openspec initiative resolve <id>` command should
-not be implemented, now or later.
-
-The useful distinction is already covered by existing concepts:
-
-- `initiative show` resolves canonical shared initiative context.
-- A workspace is the local view over repos and folders.
-- Repo-local changes link themselves to initiatives through checked-in metadata.
-- Repo-local status reports implementation progress.
-
-A standalone resolve command would mostly duplicate workspace local-view state
-or provide weak output when no workspace is present.
-
-## Pressure Test
-
-Scenario:
-
-```bash
-git clone git@github.com:acme/context.git
-openspec context-store register ./context --id platform
-openspec initiative show billing-launch --json
-```
-
-This can locate:
-
-```text
-platform/billing-launch
-./context/initiatives/billing-launch
-./context/initiatives/billing-launch/initiative.yaml
-```
-
-It cannot know:
-
-```text
-which implementation repos should exist locally
-where those repos are on this machine
-which repos the user intends to work in
-which repos should be cloned
-which workspace view the user wants
-```
-
-That knowledge belongs to the user and the workspace, not the initiative.
-
-## Why Workspace Changes The Answer
-
-When a user has a workspace, the local view is already resolved by the
-workspace:
-
-```text
-workspace -> link names -> machine-local paths
-```
-
-The agent can operate from the workspace context. A separate
-`initiative resolve` command would add another layer that mostly reprints what
-the workspace already owns.
-
-If future UX needs initiative-aware opening, it should be part of workspace
-behavior, such as opening or preparing a workspace around a selected initiative.
-It should not be a standalone initiative command pretending to infer local repo
-availability.
-
-## Research Notes Retained
-
-The earlier investigation is still useful as background:
-
-- `initiative show` already has correct context-store lookup behavior,
-  ambiguity handling, incomplete lookup handling, and JSON locator output.
-- Item 8 stores initiative links in repo-local `.openspec.yaml` as
-  `{ store, id }`.
-- Workspace state owns local path mappings and generated open surfaces.
-- Existing repo-local status and instructions expose initiative links but do not
-  resolve or summarize the initiative.
-
-Those findings support the final decision: do not add a standalone command; keep
-each responsibility in its existing owner.
-
-## Rejected Scope
-
-Rejected for Item 9:
-
-- `openspec initiative resolve <id>`
-- path-resolution dashboards
-- progress dashboards
-- all-workspace scans
-- all-repo scans
-- explicit path scanning as an initiative command
-- Git remote matching
-- repo ownership inference
-- cloning or branch/worktree orchestration
-- initiative backlinks
-
-## Verification
-
-This pass updates decision artifacts only.
-
-```bash
-git diff --check
-```
-
-Result: passed after this revision.

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/09-add-initiative-resolve/plan.md

@@ -1,141 +0,0 @@
-# Reject Initiative Resolve
-
-## Status
-
-Final decision: do not implement a standalone `openspec initiative resolve`
-command, now or later.
-
-## Source Of Truth
-
-Start from `../../direction.md` and the boundary:
-
-```text
-Context stores sync truth.
-Collections shape truth.
-Initiatives coordinate work.
-Workspaces open local views.
-Changes implement repo-owned slices.
-```
-
-Item 8 already established that repo-local changes may reference initiatives
-through portable checked-in metadata:
-
-```yaml
-initiative:
-  store: platform
-  id: billing-launch
-```
-
-## Final Decision
-
-Do not ship `openspec initiative resolve <id>` as a user-facing command in this
-slice or any future slice.
-
-The earlier command framing was too broad. It tried to join initiative identity,
-workspace local paths, explicit repo roots, and linked repo-local changes into a
-new CLI surface. That makes the command look authoritative even though the
-initiative does not own local repo paths, repo participation, or implementation
-state.
-
-## Why The Command Is Not Needed
-
-If a user only has a context store clone, OpenSpec can already resolve the
-canonical initiative with:
-
-```bash
-openspec initiative show billing-launch --json
-```
-
-That answers:
-
-```text
-What initiative is this, which context store contains it, and where is the
-canonical initiative folder?
-```
-
-It cannot answer:
-
-```text
-Which local implementation repos should exist on this machine?
-```
-
-because that information is not in the context store.
-
-If a user has a workspace, the workspace is already the local view. It already
-maps local repos and folders to paths on this machine. A separate
-`initiative resolve` command would mostly re-describe the workspace the user is
-already using.
-
-If a user is in a repo, the repo-local change commands and status commands
-already operate from that repo. The user or agent can inspect the current repo's
-changes directly.
-
-## Product Rule
-
-Do not create a new command whose main job is to discover local paths that the
-workspace already represents.
-
-Rules:
-
-- `initiative show` remains the command for canonical initiative discovery.
-- Workspaces remain the local view over repos, folders, context stores, and
-  initiatives.
-- Repo-local changes remain the implementation artifacts.
-- Agents should use the current workspace or current repo context rather than
-  asking a standalone initiative command to infer local availability.
-- OpenSpec should not infer repo ownership, scan arbitrary repos, clone repos,
-  create worktrees, or write backlinks to make resolve appear smarter than it
-  is.
-
-## What To Do Instead
-
-Keep the pieces separate:
-
-- Use `openspec initiative show <id> --json` to locate canonical shared context.
-- Use workspace commands to set up, link, relink, list, open, update, and doctor
-  local views.
-- Use repo-local `openspec new change ... --initiative ...` and
-  `openspec set change ... --initiative ...` to create durable links from repo
-  work to initiative context.
-- Use `openspec status --change <id> --json` inside the owning repo to inspect
-  implementation progress.
-
-If a future workspace workflow needs to open an initiative-specific view, it
-should be designed under workspace behavior, not as a standalone initiative
-resolve command.
-
-## Deferred Or Replaced Scope
-
-The following ideas are not part of Item 9 implementation:
-
-- `openspec initiative resolve <id>`
-- scanning all registered workspaces
-- scanning all repos on disk
-- explicit `--path` based initiative resolution
-- Git remote matching
-- repo ownership inference
-- cloning, fetching, pulling, pushing
-- branch or worktree creation
-- initiative backlinks
-- progress dashboards
-- local availability dashboards
-
-## Roadmap Disposition
-
-Item 9 is a decision-only checkpoint. It records that standalone initiative
-resolution is rejected permanently.
-
-Roadmap framing:
-
-```text
-Item 9. Reject Initiative Resolve
-
-Decision: do not add `openspec initiative resolve`, now or later. Initiative
-discovery belongs to `initiative show`; local path mapping belongs to
-workspaces; implementation progress belongs to repo-local changes.
-```
-
-## Next Useful Work
-
-The next useful implementation slice is workspace initiative opening, without a
-standalone resolve prerequisite.

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/09-add-initiative-resolve/tasks.md

@@ -1,22 +0,0 @@
-# Reject Initiative Resolve Tasks
-
-## Decisions
-
-- [x] Create Item 9 work-item tracking notes.
-- [x] Pressure-test whether a standalone `initiative resolve` command is needed.
-- [x] Decide that a standalone user-facing `initiative resolve` command should
-  not be implemented now or later.
-- [x] Decide `initiative show` remains sufficient for canonical initiative
-  discovery.
-- [x] Decide workspace local-view state is the right place for local repo/path
-  mapping.
-- [x] Decide repo-local status remains the right place for work progress.
-- [x] Decide not to add all-repo scanning, all-workspace scanning, Git remote
-  matching, cloning, worktree creation, or initiative backlinks.
-
-## Follow-Up
-
-- [x] Update the central roadmap entry for Item 9.
-- [x] Update the initiative task tracker.
-- [x] Record workspace initiative opening as the next useful implementation
-  slice.