sauron-cli 1.3.0 → 1.4.0

package/OpenSpec-main/openspec/changes/archive/2025-12-24-add-artifact-graph-core/specs/artifact-graph/spec.md

@@ -1,103 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Schema Loading
-The system SHALL load artifact graph definitions from YAML schema files.
-
-#### Scenario: Valid schema loaded
-- **WHEN** a valid schema YAML file is provided
-- **THEN** the system returns an ArtifactGraph with all artifacts and dependencies
-
-#### Scenario: Invalid schema rejected
-- **WHEN** a schema YAML file is missing required fields
-- **THEN** the system throws an error with a descriptive message
-
-#### Scenario: Cyclic dependencies detected
-- **WHEN** a schema contains cyclic artifact dependencies
-- **THEN** the system throws an error listing the artifact IDs in the cycle
-
-#### Scenario: Invalid dependency reference
-- **WHEN** an artifact's `requires` array references a non-existent artifact ID
-- **THEN** the system throws an error identifying the invalid reference
-
-#### Scenario: Duplicate artifact IDs rejected
-- **WHEN** a schema contains multiple artifacts with the same ID
-- **THEN** the system throws an error identifying the duplicate
-
-### Requirement: Build Order Calculation
-The system SHALL compute a valid topological build order for artifacts.
-
-#### Scenario: Linear dependency chain
-- **WHEN** artifacts form a linear chain (A → B → C)
-- **THEN** getBuildOrder() returns [A, B, C]
-
-#### Scenario: Diamond dependency
-- **WHEN** artifacts form a diamond (A → B, A → C, B → D, C → D)
-- **THEN** getBuildOrder() returns A before B and C, and D last
-
-#### Scenario: Independent artifacts
-- **WHEN** artifacts have no dependencies
-- **THEN** getBuildOrder() returns them in a stable order
-
-### Requirement: State Detection
-The system SHALL detect artifact completion state by scanning the filesystem.
-
-#### Scenario: Simple file exists
-- **WHEN** an artifact generates "proposal.md" and the file exists
-- **THEN** the artifact is marked as completed
-
-#### Scenario: Simple file missing
-- **WHEN** an artifact generates "proposal.md" and the file does not exist
-- **THEN** the artifact is not marked as completed
-
-#### Scenario: Glob pattern with files
-- **WHEN** an artifact generates "specs/*.md" and the specs/ directory contains .md files
-- **THEN** the artifact is marked as completed
-
-#### Scenario: Glob pattern empty
-- **WHEN** an artifact generates "specs/*.md" and the specs/ directory is empty or missing
-- **THEN** the artifact is not marked as completed
-
-#### Scenario: Missing change directory
-- **WHEN** the change directory does not exist
-- **THEN** all artifacts are marked as not completed (empty state)
-
-### Requirement: Ready Artifact Query
-The system SHALL identify which artifacts are ready to be created based on dependency completion.
-
-#### Scenario: Root artifacts ready initially
-- **WHEN** no artifacts are completed
-- **THEN** getNextArtifacts() returns artifacts with no dependencies
-
-#### Scenario: Dependent artifact becomes ready
-- **WHEN** an artifact's dependencies are all completed
-- **THEN** getNextArtifacts() includes that artifact
-
-#### Scenario: Blocked artifacts excluded
-- **WHEN** an artifact has uncompleted dependencies
-- **THEN** getNextArtifacts() does not include that artifact
-
-### Requirement: Completion Check
-The system SHALL determine when all artifacts in a graph are complete.
-
-#### Scenario: All complete
-- **WHEN** all artifacts in the graph are in the completed set
-- **THEN** isComplete() returns true
-
-#### Scenario: Partially complete
-- **WHEN** some artifacts in the graph are not completed
-- **THEN** isComplete() returns false
-
-### Requirement: Blocked Query
-The system SHALL identify which artifacts are blocked and return all their unmet dependencies.
-
-#### Scenario: Artifact blocked by single dependency
-- **WHEN** artifact B requires artifact A and A is not complete
-- **THEN** getBlocked() returns `{ B: ['A'] }`
-
-#### Scenario: Artifact blocked by multiple dependencies
-- **WHEN** artifact C requires A and B, and only A is complete
-- **THEN** getBlocked() returns `{ C: ['B'] }`
-
-#### Scenario: Artifact blocked by all dependencies
-- **WHEN** artifact C requires A and B, and neither is complete
-- **THEN** getBlocked() returns `{ C: ['A', 'B'] }`

package/OpenSpec-main/openspec/changes/archive/2025-12-24-add-artifact-graph-core/tasks.md

@@ -1,61 +0,0 @@
-## 1. Type Definitions
-- [x] 1.1 Create `src/core/artifact-graph/types.ts` with Zod schemas (`ArtifactSchema`, `SchemaYamlSchema`) and inferred types via `z.infer<>`
-- [x] 1.2 Define `CompletedSet` (Set<string>), `BlockedArtifacts`, and `ArtifactGraphResult` types for runtime state
-
-## 2. Schema Parser
-- [x] 2.1 Create `src/core/artifact-graph/schema.ts` with YAML loading and Zod validation via `.safeParse()`
-- [x] 2.2 Implement dependency reference validation (ensure `requires` references valid artifact IDs)
-- [x] 2.3 Implement duplicate artifact ID detection
-- [x] 2.4 Add cycle detection during schema load (error format: "Cyclic dependency detected: A → B → C → A")
-
-## 3. Artifact Graph Core
-- [x] 3.1 Create `src/core/artifact-graph/graph.ts` with ArtifactGraph class
-- [x] 3.2 Implement `fromYaml(path)` - load graph from schema file
-- [x] 3.3 Implement `getBuildOrder()` - topological sort via Kahn's algorithm
-- [x] 3.4 Implement `getArtifact(id)` - retrieve single artifact definition
-- [x] 3.5 Implement `getAllArtifacts()` - list all artifacts
-
-## 4. State Detection
-- [x] 4.1 Create `src/core/artifact-graph/state.ts` with state detection logic
-- [x] 4.2 Implement file existence checking for simple paths
-- [x] 4.3 Implement glob pattern matching for multi-file artifacts
-- [x] 4.4 Implement `detectCompleted(graph, changeDir)` - scan filesystem and return CompletedSet
-- [x] 4.5 Handle missing changeDir gracefully (return empty CompletedSet)
-
-## 5. Ready Calculation
-- [x] 5.1 Implement `getNextArtifacts(graph, completed)` - find artifacts with all deps completed
-- [x] 5.2 Implement `isComplete(graph, completed)` - check if all artifacts done
-- [x] 5.3 Implement `getBlocked(graph, completed)` - return BlockedArtifacts map (artifact → unmet deps)
-
-## 6. Schema Resolution
-- [x] 6.1 Create `src/core/artifact-graph/resolver.ts` with schema resolution logic
-- [x] 6.2 Add `getGlobalDataDir()` to `src/core/global-config.ts` (XDG_DATA_HOME with platform fallbacks)
-- [x] 6.3 Implement `resolveSchema(name)` - global (`${XDG_DATA_HOME}/openspec/schemas/`) → built-in fallback
-
-## 7. Built-in Schemas
-- [x] 7.1 Create `src/core/artifact-graph/schemas/spec-driven.yaml` (default: proposal → specs → design → tasks)
-- [x] 7.2 Create `src/core/artifact-graph/schemas/tdd.yaml` (alternative: tests → implementation → docs)
-
-## 8. Integration
-- [x] 8.1 Create `src/core/artifact-graph/index.ts` with public exports
-
-## 9. Testing
-- [x] 9.1 Test: Parse valid schema YAML returns correct artifact graph
-- [x] 9.2 Test: Parse invalid schema (missing fields) throws descriptive error
-- [x] 9.3 Test: Duplicate artifact IDs throws error
-- [x] 9.4 Test: Invalid `requires` reference throws error identifying the invalid ID
-- [x] 9.5 Test: Cycle in schema throws error listing cycle path (e.g., "A → B → C → A")
-- [x] 9.6 Test: Compute build order returns correct topological ordering (linear chain)
-- [x] 9.7 Test: Compute build order handles diamond dependencies correctly
-- [x] 9.8 Test: Independent artifacts return in stable order
-- [x] 9.9 Test: Empty/missing changeDir returns empty CompletedSet
-- [x] 9.10 Test: File existence marks artifact as completed
-- [x] 9.11 Test: Glob pattern specs/*.md detected as complete when files exist
-- [x] 9.12 Test: Glob pattern with empty directory not marked complete
-- [x] 9.13 Test: getNextArtifacts returns only root artifacts when nothing completed
-- [x] 9.14 Test: getNextArtifacts includes artifact when all deps completed
-- [x] 9.15 Test: getBlocked returns artifact with all unmet dependencies listed
-- [x] 9.16 Test: isComplete() returns true when all artifacts completed
-- [x] 9.17 Test: isComplete() returns false when some artifacts incomplete
-- [x] 9.18 Test: Schema resolution finds global override before built-in
-- [x] 9.19 Test: Schema resolution falls back to built-in when no global

package/OpenSpec-main/openspec/changes/archive/2025-12-25-add-change-manager/design.md

@@ -1,74 +0,0 @@
-## Context
-
-This is Slice 2 of the artifact tracker POC. The goal is to provide utilities for creating change directories programmatically.
-
-**Current state:** No programmatic way to create changes. Users must manually create directories.
-
-**Proposed state:** Utility functions for change creation with name validation.
-
-## Goals / Non-Goals
-
-### Goals
-- **Add** `createChange()` function to create change directories
-- **Add** `validateChangeName()` function for kebab-case validation
-- **Enable** automation (Claude commands, scripts) to create changes
-
-### Non-Goals
-- Refactor existing CLI commands (they work fine)
-- Create abstraction layers or manager classes
-- Change how `ListCommand` or `ChangeCommand` work
-
-## Decisions
-
-### Decision 1: Simple Utility Functions
-
-**Choice**: Add functions to `src/utils/change-utils.ts` - no class.
-
-```typescript
-// src/utils/change-utils.ts
-
-export function validateChangeName(name: string): { valid: boolean; error?: string }
-
-export async function createChange(
-  projectRoot: string,
-  name: string
-): Promise<void>
-```
-
-**Why**:
-- Simple, no abstraction overhead
-- Easy to test
-- Easy to import where needed
-- Matches existing utility patterns in `src/utils/`
-
-**Alternatives considered**:
-- ChangeManager class: Rejected - over-engineered for 2 functions
-- Add to existing command: Rejected - mixes CLI with reusable logic
-
-### Decision 2: Kebab-Case Validation Pattern
-
-**Choice**: Validate names with `^[a-z][a-z0-9]*(-[a-z0-9]+)*$`
-
-Valid: `add-auth`, `refactor-db`, `add-feature-2`, `refactor`
-Invalid: `Add-Auth`, `add auth`, `add_auth`, `-add-auth`, `add-auth-`, `add--auth`
-
-**Why**:
-- Filesystem-safe (no special characters)
-- URL-safe (for future web UI)
-- Consistent with existing change naming in repo
-
-## File Changes
-
-### New Files
-- `src/utils/change-utils.ts` - Utility functions
-- `src/utils/change-utils.test.ts` - Unit tests
-
-### Modified Files
-- None
-
-## Risks / Trade-offs
-
-| Risk | Mitigation |
-|------|------------|
-| Function might not cover all use cases | Start simple, extend if needed |
-| Naming conflicts with future work | Using clear, specific function names |

package/OpenSpec-main/openspec/changes/archive/2025-12-25-add-change-manager/proposal.md

@@ -1,45 +0,0 @@
-## Why
-
-There's no programmatic way to create a new change directory. Users must manually:
-1. Create `openspec/changes/<name>/` directory
-2. Create a `proposal.md` file
-3. Hope they got the naming right
-
-This is error-prone and blocks automation (e.g., Claude commands, scripts).
-
-**This proposal adds:**
-1. `createChange(projectRoot, name)` - Create change directories programmatically
-2. `validateChangeName(name)` - Enforce kebab-case naming conventions
-
-## What Changes
-
-### New Utilities
-
-| Function | Description |
-|----------|-------------|
-| `createChange(projectRoot, name)` | Creates `openspec/changes/<name>/` directory |
-| `validateChangeName(name)` | Returns `{ valid: boolean; error?: string }` |
-
-### Name Validation Rules
-
-Pattern: `^[a-z][a-z0-9]*(-[a-z0-9]+)*$`
-
-| Valid | Invalid |
-|-------|---------|
-| `add-auth` | `Add-Auth` (uppercase) |
-| `refactor-db` | `add auth` (spaces) |
-| `add-feature-2` | `add_auth` (underscores) |
-| `refactor` | `-add-auth` (leading hyphen) |
-
-### Location
-
-New file: `src/utils/change-utils.ts`
-
-Simple utility functions - no class, no abstraction layer.
-
-## Impact
-
-- **Affected specs**: None
-- **Affected code**: None (new utilities only)
-- **New files**: `src/utils/change-utils.ts`
-- **Breaking changes**: None

package/OpenSpec-main/openspec/changes/archive/2025-12-25-add-change-manager/specs/change-creation/spec.md

@@ -1,63 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Change Creation
-The system SHALL provide a function to create new change directories programmatically.
-
-#### Scenario: Create change
-- **WHEN** `createChange(projectRoot, 'add-auth')` is called
-- **THEN** the system creates `openspec/changes/add-auth/` directory
-
-#### Scenario: Duplicate change rejected
-- **WHEN** `createChange(projectRoot, 'add-auth')` is called and `openspec/changes/add-auth/` already exists
-- **THEN** the system throws an error indicating the change already exists
-
-#### Scenario: Creates parent directories if needed
-- **WHEN** `createChange(projectRoot, 'add-auth')` is called and `openspec/changes/` does not exist
-- **THEN** the system creates the full path including parent directories
-
-#### Scenario: Invalid change name rejected
-- **WHEN** `createChange(projectRoot, 'Add Auth')` is called with an invalid name
-- **THEN** the system throws a validation error
-
-### Requirement: Change Name Validation
-The system SHALL validate change names follow kebab-case conventions.
-
-#### Scenario: Valid kebab-case name accepted
-- **WHEN** a change name like `add-user-auth` is validated
-- **THEN** validation returns `{ valid: true }`
-
-#### Scenario: Numeric suffixes accepted
-- **WHEN** a change name like `add-feature-2` is validated
-- **THEN** validation returns `{ valid: true }`
-
-#### Scenario: Single word accepted
-- **WHEN** a change name like `refactor` is validated
-- **THEN** validation returns `{ valid: true }`
-
-#### Scenario: Uppercase characters rejected
-- **WHEN** a change name like `Add-Auth` is validated
-- **THEN** validation returns `{ valid: false, error: "..." }`
-
-#### Scenario: Spaces rejected
-- **WHEN** a change name like `add auth` is validated
-- **THEN** validation returns `{ valid: false, error: "..." }`
-
-#### Scenario: Underscores rejected
-- **WHEN** a change name like `add_auth` is validated
-- **THEN** validation returns `{ valid: false, error: "..." }`
-
-#### Scenario: Special characters rejected
-- **WHEN** a change name like `add-auth!` is validated
-- **THEN** validation returns `{ valid: false, error: "..." }`
-
-#### Scenario: Leading hyphen rejected
-- **WHEN** a change name like `-add-auth` is validated
-- **THEN** validation returns `{ valid: false, error: "..." }`
-
-#### Scenario: Trailing hyphen rejected
-- **WHEN** a change name like `add-auth-` is validated
-- **THEN** validation returns `{ valid: false, error: "..." }`
-
-#### Scenario: Consecutive hyphens rejected
-- **WHEN** a change name like `add--auth` is validated
-- **THEN** validation returns `{ valid: false, error: "..." }`

package/OpenSpec-main/openspec/changes/archive/2025-12-25-add-change-manager/tasks.md

@@ -1,30 +0,0 @@
-## Phase 1: Implement Name Validation
-
-- [x] 1.1 Create `src/utils/change-utils.ts`
-- [x] 1.2 Implement `validateChangeName()` with kebab-case pattern
-- [x] 1.3 Pattern: `^[a-z][a-z0-9]*(-[a-z0-9]+)*$`
-- [x] 1.4 Return `{ valid: boolean; error?: string }`
-- [x] 1.5 Add test: valid names accepted (`add-auth`, `refactor`, `add-feature-2`)
-- [x] 1.6 Add test: uppercase rejected
-- [x] 1.7 Add test: spaces rejected
-- [x] 1.8 Add test: underscores rejected
-- [x] 1.9 Add test: special characters rejected
-- [x] 1.10 Add test: leading/trailing hyphens rejected
-- [x] 1.11 Add test: consecutive hyphens rejected
-
-## Phase 2: Implement Change Creation
-
-- [x] 2.1 Implement `createChange(projectRoot, name)`
-- [x] 2.2 Validate name before creating
-- [x] 2.3 Create parent directories if needed (`openspec/changes/`)
-- [x] 2.4 Throw if change already exists
-- [x] 2.5 Add test: creates directory
-- [x] 2.6 Add test: duplicate change throws error
-- [x] 2.7 Add test: invalid name throws validation error
-- [x] 2.8 Add test: creates parent directories if needed
-
-## Phase 3: Integration
-
-- [x] 3.1 Export functions from `src/utils/index.ts`
-- [x] 3.2 Add JSDoc comments
-- [x] 3.3 Run all tests to verify no regressions

package/OpenSpec-main/openspec/changes/archive/2025-12-28-add-artifact-workflow-cli/design.md

@@ -1,112 +0,0 @@
-## Context
-
-Slice 4 of the artifact workflow POC. The core functionality (ArtifactGraph, InstructionLoader, change-utils) is complete. This slice adds CLI commands to expose the artifact workflow to users.
-
-**Key constraint**: This is experimental. Commands must be isolated for easy removal if the feature doesn't work out.
-
-## Goals / Non-Goals
-
-- **Goals:**
-  - Expose artifact workflow status and instructions via CLI
-  - Provide fluid UX with top-level verb commands
-  - Support both human-readable and JSON output
-  - Enable agents to programmatically query workflow state
-  - Keep implementation isolated for easy removal
-
-- **Non-Goals:**
-  - Interactive artifact creation wizards (future work)
-  - Schema management commands (deferred)
-  - Auto-detection of active change (CLI is deterministic, agents infer)
-
-## Decisions
-
-### Command Structure: Top-Level Verbs
-
-Commands are top-level for maximum fluidity:
-
-```
-openspec status --change <id>
-openspec next --change <id>
-openspec instructions <artifact> --change <id>
-openspec templates [--schema <name>]
-openspec new change <name>
-```
-
-**Rationale:**
-- Most fluid UX - fewest keystrokes
-- Commands are unique enough to avoid conflicts
-- Simple mental model for users
-
-**Trade-off accepted:** Slight namespace pollution, but commands are distinct and can be removed cleanly.
-
-### Experimental Isolation
-
-All artifact workflow commands are implemented in a single file:
-
-```
-src/commands/artifact-workflow.ts
-```
-
-**To remove the feature:**
-1. Delete `src/commands/artifact-workflow.ts`
-2. Remove ~5 lines from `src/cli/index.ts`
-
-No other files touched, no risk to stable functionality.
-
-### Deterministic CLI with Explicit `--change`
-
-All change-specific commands require `--change <id>`:
-
-```bash
-openspec status --change add-auth   # explicit, works
-openspec status                      # error: missing --change
-```
-
-**Rationale:**
-- CLI is pure, testable, no hidden state
-- Agents infer change from conversation and pass explicitly
-- No config file tracking "active change"
-- Consistent with POC design philosophy
-
-### New Change Command Structure
-
-Creating changes uses explicit subcommand:
-
-```bash
-openspec new change add-feature
-```
-
-**Rationale:**
-- `openspec new <name>` is ambiguous (new what?)
-- `openspec new change <name>` is clear and extensible
-- Can add `openspec new spec <name>` later if needed
-
-### Output Formats
-
-- **Default**: Human-readable text with visual indicators
-  - Status: `[x]` done, `[ ]` ready, `[-]` blocked
-  - Colors: green (done), yellow (ready), red (blocked)
-- **JSON** (`--json`): Machine-readable for scripts and agents
-
-### Error Handling
-
-- Missing `--change`: Error listing available changes
-- Unknown change: Error with suggestion
-- Unknown artifact: Error listing valid artifacts
-- Missing schema: Error with schema resolution details
-
-## Risks / Trade-offs
-
-| Risk | Mitigation |
-|------|------------|
-| Top-level commands pollute namespace | Commands are distinct; isolated for easy removal |
-| `status` confused with git | Context (`--change`) makes it clear |
-| Feature doesn't work out | Single file deletion removes everything |
-
-## Implementation Notes
-
-- All commands in `src/commands/artifact-workflow.ts`
-- Imports from `src/core/artifact-graph/` for all operations
-- Uses `getActiveChangeIds()` from `item-discovery.ts` for change listing
-- Follows existing CLI patterns (ora spinners, commander.js options)
-- Help text marks commands as "Experimental"

package/OpenSpec-main/openspec/changes/archive/2025-12-28-add-artifact-workflow-cli/proposal.md

@@ -1,33 +0,0 @@
-## Why
-
-The ArtifactGraph (Slice 1) and InstructionLoader (Slice 3) provide programmatic APIs for artifact-based workflow management. Users currently have no CLI interface to:
-- See artifact completion status for a change
-- Discover what artifacts are ready to create
-- Get enriched instructions for creating artifacts
-- Create new changes with proper validation
-
-This proposal adds CLI commands that expose the artifact workflow functionality to users and agents.
-
-## What Changes
-
-- **NEW**: `openspec status --change <id>` shows artifact completion state
-- **NEW**: `openspec next --change <id>` shows artifacts ready to create
-- **NEW**: `openspec instructions <artifact> --change <id>` outputs enriched template
-- **NEW**: `openspec templates [--schema <name>]` shows resolved template paths
-- **NEW**: `openspec new change <name>` creates a new change directory
-
-All commands are top-level for fluid UX. They integrate with existing core modules:
-- Uses `loadChangeContext()`, `formatChangeStatus()`, `generateInstructions()` from instruction-loader
-- Uses `ArtifactGraph`, `detectCompleted()` from artifact-graph
-- Uses `createChange()`, `validateChangeName()` from change-utils
-
-**Experimental isolation**: All commands are implemented in a single file (`src/commands/artifact-workflow.ts`) for easy removal if the feature doesn't work out. Help text marks them as experimental.
-
-## Impact
-
-- Affected specs: NEW `cli-artifact-workflow` capability
-- Affected code:
-  - `src/cli/index.ts` - register new commands
-  - `src/commands/artifact-workflow.ts` - new command implementations
-- No changes to existing commands or specs
-- Builds on completed Slice 1, 2, and 3 implementations

package/OpenSpec-main/openspec/changes/archive/2025-12-28-add-artifact-workflow-cli/specs/cli-artifact-workflow/spec.md

@@ -1,153 +0,0 @@
-# cli-artifact-workflow Specification
-
-## Purpose
-CLI commands for artifact workflow operations, exposing the artifact graph and instruction loader functionality to users and agents. Commands are top-level for fluid UX and implemented in isolation for easy removal.
-
-## ADDED Requirements
-
-### Requirement: Status Command
-The system SHALL display artifact completion status for a change.
-
-#### Scenario: Show status with all states
-- **WHEN** user runs `openspec status --change <id>`
-- **THEN** the system displays each artifact with status indicator:
-  - `[x]` for completed artifacts
-  - `[ ]` for ready artifacts
-  - `[-]` for blocked artifacts (with missing dependencies listed)
-
-#### Scenario: Status shows completion summary
-- **WHEN** user runs `openspec status --change <id>`
-- **THEN** output includes completion percentage and count (e.g., "2/4 artifacts complete")
-
-#### Scenario: Status JSON output
-- **WHEN** user runs `openspec status --change <id> --json`
-- **THEN** the system outputs JSON with changeName, schemaName, isComplete, and artifacts array
-
-#### Scenario: Missing change parameter
-- **WHEN** user runs `openspec status` without `--change`
-- **THEN** the system displays an error with list of available changes
-
-#### Scenario: Unknown change
-- **WHEN** user runs `openspec status --change unknown-id`
-- **THEN** the system displays an error indicating the change does not exist
-
-### Requirement: Next Command
-The system SHALL show which artifacts are ready to be created.
-
-#### Scenario: Show ready artifacts
-- **WHEN** user runs `openspec next --change <id>`
-- **THEN** the system lists artifacts whose dependencies are all satisfied
-
-#### Scenario: No artifacts ready
-- **WHEN** all artifacts are either completed or blocked
-- **THEN** the system indicates no artifacts are ready (with explanation)
-
-#### Scenario: All artifacts complete
-- **WHEN** all artifacts in the change are completed
-- **THEN** the system indicates the change is complete
-
-#### Scenario: Next JSON output
-- **WHEN** user runs `openspec next --change <id> --json`
-- **THEN** the system outputs JSON array of ready artifact IDs
-
-### Requirement: Instructions Command
-The system SHALL output enriched instructions for creating an artifact.
-
-#### Scenario: Show enriched instructions
-- **WHEN** user runs `openspec instructions <artifact> --change <id>`
-- **THEN** the system outputs:
-  - Artifact metadata (ID, output path, description)
-  - Template content
-  - Dependency status (done/missing)
-  - Unlocked artifacts (what becomes available after completion)
-
-#### Scenario: Instructions JSON output
-- **WHEN** user runs `openspec instructions <artifact> --change <id> --json`
-- **THEN** the system outputs JSON matching ArtifactInstructions interface
-
-#### Scenario: Unknown artifact
-- **WHEN** user runs `openspec instructions unknown-artifact --change <id>`
-- **THEN** the system displays an error listing valid artifact IDs for the schema
-
-#### Scenario: Artifact with unmet dependencies
-- **WHEN** user requests instructions for a blocked artifact
-- **THEN** the system displays instructions with a warning about missing dependencies
-
-### Requirement: Templates Command
-The system SHALL show resolved template paths for all artifacts in a schema.
-
-#### Scenario: List template paths with default schema
-- **WHEN** user runs `openspec templates`
-- **THEN** the system displays each artifact with its resolved template path using the default schema
-
-#### Scenario: List template paths with custom schema
-- **WHEN** user runs `openspec templates --schema tdd`
-- **THEN** the system displays template paths for the specified schema
-
-#### Scenario: Templates JSON output
-- **WHEN** user runs `openspec templates --json`
-- **THEN** the system outputs JSON mapping artifact IDs to template paths
-
-#### Scenario: Template resolution source
-- **WHEN** displaying template paths
-- **THEN** the system indicates whether each template is from user override or package built-in
-
-### Requirement: New Change Command
-The system SHALL create new change directories with validation.
-
-#### Scenario: Create valid change
-- **WHEN** user runs `openspec new change add-feature`
-- **THEN** the system creates `openspec/changes/add-feature/` directory
-
-#### Scenario: Invalid change name
-- **WHEN** user runs `openspec new change "Add Feature"` with invalid name
-- **THEN** the system displays validation error with guidance
-
-#### Scenario: Duplicate change name
-- **WHEN** user runs `openspec new change existing-change` for an existing change
-- **THEN** the system displays an error indicating the change already exists
-
-#### Scenario: Create with description
-- **WHEN** user runs `openspec new change add-feature --description "Add new feature"`
-- **THEN** the system creates the change directory with description in README.md
-
-### Requirement: Schema Selection
-The system SHALL support custom schema selection for workflow commands.
-
-#### Scenario: Default schema
-- **WHEN** user runs workflow commands without `--schema`
-- **THEN** the system uses the "spec-driven" schema
-
-#### Scenario: Custom schema
-- **WHEN** user runs `openspec status --change <id> --schema tdd`
-- **THEN** the system uses the specified schema for artifact graph
-
-#### Scenario: Unknown schema
-- **WHEN** user specifies an unknown schema
-- **THEN** the system displays an error listing available schemas
-
-### Requirement: Output Formatting
-The system SHALL provide consistent output formatting.
-
-#### Scenario: Color output
-- **WHEN** terminal supports colors
-- **THEN** status indicators use colors: green (done), yellow (ready), red (blocked)
-
-#### Scenario: No color output
-- **WHEN** `--no-color` flag is used or NO_COLOR environment variable is set
-- **THEN** output uses text-only indicators without ANSI colors
-
-#### Scenario: Progress indication
-- **WHEN** loading change state takes time
-- **THEN** the system displays a spinner during loading
-
-### Requirement: Experimental Isolation
-The system SHALL implement artifact workflow commands in isolation for easy removal.
-
-#### Scenario: Single file implementation
-- **WHEN** artifact workflow feature is implemented
-- **THEN** all commands are in `src/commands/artifact-workflow.ts`
-
-#### Scenario: Help text marking
-- **WHEN** user runs `--help` on any artifact workflow command
-- **THEN** help text indicates the command is experimental