sauron-cli 1.1.3 → 1.3.0

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

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

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

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

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

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

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

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