sauron-cli 1.3.0 → 1.4.0

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/15-context-store-project-roots-and-schema-led-initiatives/tasks.md

@@ -1,39 +0,0 @@
-# Context Store Project Roots And Schema-Led Initiatives Tasks
-
-- [x] Create Item 15 work-item tracking notes.
-- [ ] Record the product decision that context stores should behave like
-      OpenSpec roots for config and schema resolution, but not as implementation
-      repos by default.
-- [ ] Define the context-store root layout, including `.openspec-store/`,
-      `openspec/config.yaml`, `openspec/schemas/`, and `initiatives/`.
-- [ ] Decide the config key for the default initiative schema, with
-      `initiative_schema` as the preferred next-release-safe direction.
-- [ ] Decide whether initiative schemas share `openspec/schemas/` with a
-      `usage: initiative` discriminator or use a separate namespace while
-      reusing the artifact graph format.
-- [ ] Add or design the built-in `product-initiative` schema for high-level
-      requirements and design artifacts.
-- [ ] Define `brief.md` as the sparse creation seed and decide whether it sits
-      outside the artifact graph or is represented as an already-complete
-      artifact.
-- [ ] Change `initiative create` from hardcoded six-file generation to sparse
-      `initiative.yaml` plus `brief.md` creation.
-- [ ] Add initiative artifact status resolution rooted at
-      `context-store/initiatives/<id>/`.
-- [ ] Add initiative artifact instructions output that returns schema guidance,
-      template content, dependencies, output path, and existing paths.
-- [ ] Ensure store-local config context and rules can be read for initiative
-      artifact instructions without confusing repo-local change config.
-- [ ] Guard planning-home resolution so context stores with
-      `openspec/config.yaml` do not silently become repo-local implementation
-      homes.
-- [ ] Update `initiative create --json`, human output, and next-command guidance
-      for sparse creation and iterative artifacts.
-- [ ] Update tests that currently assert the MVP six-file initiative shape.
-- [ ] Add compatibility tests proving old six-file initiatives still list and
-      show.
-- [ ] Add tests for context-store local schemas and store config defaults.
-- [ ] Update beta docs and agent guidance to stop telling agents to edit every
-      initiative markdown file immediately after creation.
-- [ ] Record migration behavior and a note that Item 5's six-file MVP shape has
-      been superseded by this schema-led sparse model.

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/16-add-escalation-ux/plan.md

@@ -1,26 +0,0 @@
-# Add Escalation UX
-
-## Status
-
-Future work item. Kept after first-run setup, handoff output, guide cleanup,
-and schema-led initiatives because escalation should build on a sane onboarding
-path.
-
-## Goal
-
-Let users start locally and upgrade into a coordinated initiative only when the
-work actually needs shared context.
-
-## Ship
-
-- Explore/propose guidance that starts in the current repo by default.
-- Recommendation triggers when work spans multiple owned areas.
-- Carry-forward behavior for current change name, product goal, notes, inferred
-  areas, and relevant questions.
-- Prompts grounded in concrete affected areas instead of abstract storage
-  models.
-
-## Done When
-
-- Coordinated planning feels like a continuation of local planning, not a
-  workflow restart.

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

@@ -1,7 +0,0 @@
-# Add Escalation UX Tasks
-
-- [ ] Define local-to-initiative recommendation triggers.
-- [ ] Carry current planning context into a new initiative.
-- [ ] Keep prompts grounded in affected areas.
-- [ ] Decide where escalation guidance appears in agent instructions, command
-      output, or interactive prompts.

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/17-harden-team-shared-coordination/plan.md

@@ -1,25 +0,0 @@
-# Harden Team-Shared Coordination
-
-## Status
-
-Future work item. This should follow the first-run UX and schema-led initiative
-work so team guidance is built on the stable beta path.
-
-## Goal
-
-Make initiatives practical for several teammates without turning setup into an
-admin ceremony.
-
-## Ship
-
-- Recommended Git-backed shared context-store setup.
-- Lightweight teammate onboarding.
-- Repair flows for local path mappings.
-- Sync status and conflict guidance.
-- Clear separation between committed initiative state and machine-local
-  workspace state.
-
-## Done When
-
-- Several teammates can share the same initiative while each keeps their own
-  local checkout layout.

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/17-harden-team-shared-coordination/tasks.md

@@ -1,7 +0,0 @@
-# Harden Team-Shared Coordination Tasks
-
-- [ ] Document recommended Git-backed store setup.
-- [ ] Define teammate onboarding and repair flows.
-- [ ] Add sync status and conflict guidance.
-- [ ] Define how committed initiative state and machine-local workspace state
-      should be explained in docs and generated guidance.

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/18-explore-initiative-hosted-target-bound-change-artifacts/evidence.md

@@ -1,397 +0,0 @@
-# Explore Initiative-Hosted Target-Bound Change Artifacts Evidence
-
-## Initial Research Notes
-
-- Current product direction says context stores sync shared truth, initiatives
-  coordinate work, and repo-local changes own implementation planning.
-- Roadmap Item 8 currently assumes repo-local changes linked to initiatives.
-- Existing planning-home behavior distinguishes repo-local and workspace
-  planning homes, but does not have a context-store-backed change home.
-- New artifact workflow commands already consume resolved planning paths in
-  some places, which may be a useful seam for future change-home resolution.
-- Older command surfaces still assume `openspec/changes/` under a local
-  OpenSpec project and need an explicit audit before any implementation slice.
-
-## Initial Framing
-
-Configurable change homes are a product-boundary question, not just a path
-change. A context-store-hosted artifact would still need a clear target repo or
-spec root before validation, apply, archive, or spec sync can run safely.
-
-The future exploration should keep "change home" as internal resolver language
-and use clearer product language around initiative-hosted planning artifacts,
-target-bound changes, implementation targets, and editable roots.
-
-## Agent-First Team UX Research Pass
-
-Date: 2026-05-23.
-
-Question explored:
-
-```text
-What does a great agent-first developer experience look like for teams using
-context stores, initiatives, workspaces, and repo-local changes?
-```
-
-### External Pattern Notes
-
-- Linear uses initiatives as higher-level coordination objects that group
-  projects and expose health, ownership, and active project rollups.
-- Jira planning commonly uses initiatives above epics or other child work
-  items for multi-team planning.
-- GitLab roadmaps show higher-level epics and milestones across groups or
-  projects.
-- GitHub Projects emphasize flexible planning that stays connected to issues
-  and repo work.
-
-These patterns point toward a common split:
-
-```text
-Higher-level object = coordination and rollup
-Execution item      = work owned closer to a team, project, repo, or issue
-```
-
-OpenSpec should keep that separation while making the agent handoff sharper
-than human project-management tools can.
-
-### Clean Mental Model
-
-The strongest mental model from the research pass:
-
-```text
-Initiative = shared coordination truth
-Workspace  = local lens over initiative + repos
-Repo change = executable implementation plan
-```
-
-Expanded product rule:
-
-```text
-Context stores remember.
-Initiatives coordinate.
-Workspaces open.
-Repo-local changes implement.
-```
-
-The key invariant:
-
-```text
-Work identity is not storage location.
-Storage location is not edit permission.
-```
-
-This keeps three decisions separate for agents:
-
-- What work is the user talking about?
-- Where should the planning artifact live?
-- Which files or repos may be edited now?
-
-### Suggested Artifact Types
-
-Repo context:
-
-```text
-openspec/changes/<change-id>/
-```
-
-Use for repo-owned implementation plans. A repo-local change may reference an
-initiative through portable metadata:
-
-```yaml
-initiative:
-  store: platform
-  id: billing-launch
-```
-
-Workspace context:
-
-```text
-<store>/initiatives/<initiative-id>/work-items/<work-id>/
-```
-
-Use for shared initiative planning before repo ownership or implementation
-targets are clear. These should be called initiative work items, planning
-briefs, or proposals, not executable OpenSpec changes, until Item 18 defines a
-full lifecycle for context-store-backed changes.
-
-Workspace-local changes:
-
-```text
-<workspace>/changes/<change-id>/
-```
-
-Keep as legacy or beta compatibility unless the user explicitly opts into the
-workspace-planning flow.
-
-### Agent-First UX Scenarios
-
-Single repo team:
-
-- User asks the agent to create a proposal from inside the repo.
-- Agent resolves the initiative if named.
-- Agent creates a repo-local change linked to the initiative.
-- Apply, validate, sync, and archive stay repo-local.
-
-Monorepo:
-
-- One repo-local change can cover several packages or capabilities.
-- The agent may need an area or package hint.
-- The repo remains the implementation owner; areas clarify scope but do not
-  become separate change homes.
-
-Multi-repo platform:
-
-- Workspace opens the shared initiative context plus local repo clones.
-- The initiative coordinates the platform outcome.
-- Each owning repo gets its own linked repo-local change when implementation
-  ownership is known.
-- Workspace state should report available local repos, missing local paths, and
-  edit boundaries.
-
-Central architecture team:
-
-- Architects may update initiative requirements, designs, contracts, decisions,
-  and questions without owning implementation.
-- The agent should offer to draft shared initiative context or ask for the
-  owning repo before creating a repo-local change.
-
-Ownership unknown:
-
-- The agent should not create an implementation change.
-- It should add or update initiative-level questions, or return target options
-  with a request for a repo or area decision.
-
-Teammate onboarding:
-
-```text
-Clone or register the context store.
-Run context-store doctor.
-Open or resolve the initiative.
-Link local repos through workspace mappings.
-Ask the agent to continue from the initiative.
-```
-
-### Ideal Agent JSON Blocks
-
-Agents need stable routing vocabulary across create, status, instructions,
-resolve, and list:
-
-```json
-{
-  "workTarget": {
-    "kind": "repo-change | initiative-work-item | workspace-change",
-    "id": "add-billing-api",
-    "root": "/absolute/path",
-    "storePath": "initiatives/billing-launch/work-items/add-billing-api"
-  },
-  "initiativeLink": {
-    "store": "platform",
-    "id": "billing-launch",
-    "root": "/absolute/store/initiatives/billing-launch"
-  },
-  "invocationContext": {
-    "kind": "repo | workspace",
-    "root": "/absolute/current/context"
-  },
-  "actionContext": {
-    "mode": "implementation-ready | planning-only | target-selection-required",
-    "sourceOfTruth": "repo | context-store | workspace-local",
-    "allowedEditRoots": [],
-    "requiresTargetSelection": true,
-    "constraints": [
-      "Use resolved output paths from the CLI.",
-      "Do not infer editable repos from the current working directory."
-    ]
-  },
-  "nextCommands": {}
-}
-```
-
-The important fields are:
-
-- `workTarget`: the object the agent is acting on.
-- `initiativeLink`: the canonical shared coordination context, when present.
-- `invocationContext`: where the command was run.
-- `actionContext`: what the agent may edit.
-- `nextCommands`: follow-up commands the agent should run instead of inventing
-  paths.
-
-### Lifecycle Rules
-
-- Repo-local changes are implementation-ready when the repo is the allowed edit
-  root.
-- Initiative work items are planning-only until they select or link repo-local
-  implementation changes.
-- Workspace-local changes are compatibility artifacts, not the preferred new
-  shared planning model.
-- Apply, archive, repo spec sync, and repo delta validation should remain
-  repo-local until context-store-backed change lifecycle is explicitly designed.
-- If `allowedEditRoots` is empty or target selection is required, agents should
-  stop before editing implementation files.
-
-### Edge Cases To Design For
-
-- Same initiative id exists in multiple stores.
-- Some registered stores are unreadable or out of sync.
-- A workspace can see a repo path but the user has not selected it as an edit
-  target.
-- The terminal is inside a workspace, but the intended work belongs in a linked
-  repo.
-- The terminal is inside a linked repo, but the user wants shared initiative
-  planning first.
-- A repo-local change references an initiative store that is not registered on
-  the current machine.
-- A context-store work item uses a schema that another teammate does not have.
-- A change id exists both as a repo-local change and an initiative work item.
-- A central team edits initiative context while implementation teams edit
-  linked repo-local changes.
-
-### Suggested Direction From The Pass
-
-Keep Item 8 narrow:
-
-- Add initiative metadata to repo-local changes.
-- Add `new change <id> --initiative <store>/<initiative> --json`.
-- Use `initiative show` plus workspace/repo context as the agent handoff
-  backbone.
-- Do not implement context-store-backed OpenSpec changes in Item 8.
-
-Use Item 18 to decide the larger model:
-
-- Whether initiative work items should become a first-class artifact.
-- Whether "change home" remains internal language.
-- How context-store-hosted work binds to repo targets, specs, validation,
-  apply, archive, and sync.
-- How skills and generated guidance teach agents to trust CLI JSON instead of
-  hardcoded paths or current working directory assumptions.
-
-## Target-Bound Reframe Subagent Pass
-
-Date: 2026-05-23.
-
-Question explored:
-
-```text
-Given the product tension around central versus repo-local change storage, how
-should Item 18 be reframed before implementation work begins?
-```
-
-Three subagent passes reviewed Item 18 from product semantics, agent-first UX,
-and lifecycle/implementation angles.
-
-### Product Semantics Findings
-
-- The visible work item should not be framed as generic configurable storage.
-  That makes the hard question sound like path plumbing.
-- The sharper product question is whether initiative-hosted artifacts can
-  become executable OpenSpec changes after they are bound to a target repo or
-  spec root.
-- Repo-local changes remain the default executable implementation artifact.
-- Initiative-hosted artifacts start as planning-only work items, briefs, or
-  proposals.
-- "Change home" can stay as internal resolver language, but should not be the
-  main user-facing concept.
-
-Recommended naming:
-
-```text
-Explore Initiative-Hosted Target-Bound Change Artifacts
-```
-
-### Agent-First UX Findings
-
-Agents need stable CLI output that separates the artifact from the thing the
-agent may edit:
-
-```text
-Plan lives in: repo-local OpenSpec | initiative context
-Editable target: selected repo path | none yet
-Linked initiative: platform/billing-launch
-```
-
-Commands should report structured action context rather than making generated
-skills infer paths:
-
-```json
-{
-  "workTarget": {
-    "kind": "repo-change | initiative-work-item | initiative-hosted-change",
-    "id": "add-billing-api",
-    "root": "/absolute/path"
-  },
-  "initiativeLink": {
-    "store": "platform",
-    "id": "billing-launch"
-  },
-  "implementationTarget": {
-    "kind": "repo",
-    "id": "billing-api",
-    "specRoot": "openspec"
-  },
-  "actionContext": {
-    "mode": "implementation-ready | planning-only | target-selection-required | unsupported",
-    "sourceOfTruth": "repo | context-store | workspace-local",
-    "allowedEditRoots": [],
-    "constraints": [
-      "Use CLI-reported paths.",
-      "Do not infer editable repos from the current working directory."
-    ]
-  },
-  "nextCommands": {}
-}
-```
-
-If `allowedEditRoots` is empty, the agent should stop before editing
-implementation files. If target selection is required, the command should return
-next-step options rather than silently creating an ambiguous implementation
-change.
-
-### Lifecycle And Implementation Findings
-
-Local code still has strong repo-local assumptions:
-
-- `src/core/planning-home.ts` models planning homes as `repo | workspace`.
-- `src/commands/workflow/new-change.ts` resolves storage from the current
-  planning home and does not yet expose `--initiative` or `--json`.
-- `src/commands/validate.ts` validates changes and specs from
-  `process.cwd()/openspec/...`.
-- `src/core/archive.ts` archives by reading `openspec/changes`, applying deltas
-  to `openspec/specs`, and moving the change into `openspec/changes/archive`.
-- `src/core/artifact-graph/types.ts` metadata does not yet model initiative
-  links, target repo identity, artifact home, or edit boundaries.
-- Generated skills and workflow templates still contain repo-local path
-  assumptions such as `openspec/changes/<name>/`.
-
-These are not bugs in the current repo-local model. They are evidence that an
-initiative-hosted executable change is a lifecycle design, not a small path
-switch.
-
-### Updated Recommendation
-
-Keep Item 8 narrow:
-
-- Create or link repo-local changes with initiative metadata.
-- Add JSON output for the agent handoff.
-- Do not implement context-store-hosted executable changes in Item 8.
-
-Use Item 18 to answer the bigger question:
-
-- What initiative-hosted artifacts exist before an implementation target is
-  known?
-- What target metadata lets a shared artifact graduate into an executable
-  change?
-- How do local workspace and registry mappings resolve target repo identity to
-  machine-local paths?
-- Which lifecycle commands should refuse, hand off to a repo-local change, or
-  operate directly against a resolved target?
-- How should command and skill output teach agents to trust CLI-reported paths,
-  edit roots, and next commands?
-
-Go/no-go criterion:
-
-```text
-Do not implement initiative-hosted executable changes until create/link,
-show/status/list/instructions, validate, apply, archive, spec sync, workspace
-resolution, generated skills, and JSON output all share one target-resolution
-model.
-```

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/18-explore-initiative-hosted-target-bound-change-artifacts/plan.md

@@ -1,180 +0,0 @@
-# Explore Initiative-Hosted Target-Bound Change Artifacts
-
-## Status
-
-Not started. Added as a future exploratory work item. Framing updated from
-generic "configurable change homes" to the sharper question of when shared
-initiative artifacts can become executable, target-bound OpenSpec changes.
-
-## Source Of Truth
-
-Start from `../../direction.md`, especially the current boundary:
-
-```text
-Context stores sync truth.
-Collections shape truth.
-Initiatives coordinate work.
-Workspaces open local views.
-Changes implement repo-owned slices.
-```
-
-## Why This Exists
-
-The current initiative direction assumes OpenSpec changes usually live in the
-local repo that owns implementation. That keeps validation, archive, and spec
-sync close to the code that will change.
-
-Some coordinated work may need a shared home before the owning repo is obvious.
-A team may want initiative-hosted planning artifacts, and later may want some
-of those artifacts to become implementation-ready plans for a specific repo or
-spec root.
-
-This is not just a storage preference. A shared artifact is planning-only until
-it has an explicit portable target binding and lifecycle rules for validate,
-apply, archive, spec sync, and conflict handling.
-
-## Goal
-
-Decide whether OpenSpec should support initiative-hosted artifacts that can
-graduate into executable changes only after they are bound to an implementation
-target.
-
-Repo-local changes remain the default executable implementation artifact. Item
-18 should decide if, when, and how a context-store-hosted artifact can safely be
-treated as a change.
-
-The answer should preserve three boundaries:
-
-- Initiatives coordinate shared context.
-- Changes describe executable implementation plans.
-- Workspaces open local views and must not imply edit permission.
-
-## Model To Explore
-
-```text
-Initiative artifact
-  -> planning-only by default
-  -> may become target-bound later
-
-Repo-local change
-  -> home: repo/openspec/changes/<id>/
-  -> target: implicit current repo/spec root
-  -> lifecycle: validate/apply/archive/spec sync are repo-local
-
-Initiative-hosted target-bound change
-  -> home: context-store/initiatives/<initiative>/changes/<id>/
-  -> target: explicit repo/spec root identity
-  -> lifecycle: unsupported until target resolution is designed
-
-Agent output
-  -> reports the work target
-  -> reports where the artifact lives
-  -> reports the implementation target, if any
-  -> reports allowed edit roots for this machine
-```
-
-Keep "change home" as internal resolver language. User-facing and agent-facing
-output should prefer clearer phrases like "plan lives in repo-local OpenSpec",
-"plan lives with the initiative", and "editable target".
-
-## Core Invariants
-
-- Storage location does not imply ownership, edit permission, or lifecycle.
-- Work identity, artifact home, execution target, and allowed edit roots are
-  separate decisions.
-- Shared context-store files must not store machine-local checkout paths.
-- A targetless initiative artifact is a brief, work item, or proposal, not an
-  implementation-ready OpenSpec change.
-- A context-store-hosted artifact can be considered executable only after it has
-  explicit target metadata and lifecycle command support.
-- Item 8 remains repo-local: `new change <id> --initiative ...` creates or links
-  a repo-local change only.
-
-## Questions To Answer
-
-- What exact artifact types exist under an initiative: work items, briefs,
-  target-bound changes, or something else?
-- What portable target metadata is required before an initiative-hosted artifact
-  can be executable?
-- How does local resolution map a target repo identity to a checkout path,
-  OpenSpec root, branch, and allowed edit roots?
-- Should central target-bound changes require explicit opt-in such as
-  `--home initiative`, or can initiative/store policy choose that behavior?
-- If config exists, what is the deterministic precedence across explicit CLI
-  flags, repo config, initiative preference, context-store default, user default,
-  and built-in repo-local behavior?
-- How does `openspec new change` report work target, artifact home,
-  implementation target, initiative link, action context, and next commands in
-  JSON?
-- How do validate, apply, archive, and spec sync behave when the artifact lives
-  in a context store but the target specs live in a repo?
-- Should archive for an initiative-hosted target-bound change archive centrally,
-  materialize a repo-local handoff change, or refuse until a repo-local change
-  exists?
-- Which command and skill surfaces still hardcode `openspec/changes/`, current
-  working directory, or repo-local edit assumptions?
-- What compatibility behavior preserves existing repo-local and workspace-local
-  changes?
-
-## Agent-First Output Contract
-
-Any future command that creates, reads, or resolves this work should make the
-agent's next move explicit:
-
-```json
-{
-  "workTarget": {
-    "kind": "repo-change | initiative-work-item | initiative-hosted-change",
-    "id": "add-billing-api",
-    "root": "/absolute/path/reported/by/cli"
-  },
-  "initiativeLink": {
-    "store": "platform",
-    "id": "billing-launch"
-  },
-  "implementationTarget": {
-    "kind": "repo",
-    "id": "billing-api",
-    "specRoot": "openspec"
-  },
-  "actionContext": {
-    "mode": "implementation-ready | planning-only | target-selection-required | unsupported",
-    "sourceOfTruth": "repo | context-store | workspace-local",
-    "allowedEditRoots": [],
-    "constraints": [
-      "Use CLI-reported paths.",
-      "Do not infer editable repos from the current working directory."
-    ]
-  },
-  "nextCommands": {}
-}
-```
-
-If `allowedEditRoots` is empty, the agent should not edit implementation files.
-If target selection is required, the command should return options or next
-commands instead of creating an ambiguous implementation plan.
-
-## Explicitly Out Of Scope
-
-- Implementing context-store-hosted executable changes before the model is
-  decided.
-- Moving existing repo-local changes into a context store automatically.
-- Making initiatives own implementation artifacts by default.
-- Making workspace-level changes the new shared planning model.
-- Cross-repo apply, archive, or validation orchestration.
-- Storing machine-local checkout paths in shared context-store files.
-- Adding global defaults that can surprise ordinary repo-local commands into
-  writing shared artifacts.
-
-## Go/No-Go Criteria
-
-Do not implement initiative-hosted executable changes until OpenSpec has one
-target-resolution model that can cover:
-
-- create and link output
-- status, show, list, and instructions output
-- validate, apply, archive, and spec sync behavior
-- workspace registry and local repo mapping behavior
-- generated skill guidance and command examples
-- JSON output for work target, artifact home, implementation target, edit roots,
-  unsupported lifecycle commands, and next commands