sauron-cli 1.1.3 → 1.3.0

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

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

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

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

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

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

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