Add tests

feat: add bulk validation and interactive selection for OpenSpec commands

OPENSPEC_COMPREHENSIVE_RETROSPECTIVE.md

@@ -0,0 +1,343 @@
+# Comprehensive Retrospective: Creating an OpenSpec Change Proposal
+
+## Executive Summary
+
+This document consolidates learnings from creating the `bulk-validation-interactive-selection` change proposal for OpenSpec. The process revealed critical gaps in documentation, unhelpful error messages, and areas where the system could be more user-friendly. While OpenSpec's core functionality works correctly, the user experience for creating changes needs significant improvement.
+
+## Table of Contents
+1. [Errors Encountered](#errors-encountered)
+2. [System Issues vs User Errors](#system-issues-vs-user-errors)
+3. [Documentation Gaps Analysis](#documentation-gaps-analysis)
+4. [Key Learnings](#key-learnings)
+5. [Recommendations](#recommendations)
+6. [Conclusion](#conclusion)
+
+---
+
+## Errors Encountered
+
+### Error 1: Misunderstanding Delta Structure
+**Error Message:** `✗ [ERROR] deltas: Change must have at least one delta`
+
+**What Happened:**
+Initially attempted to define deltas directly in the `proposal.md` file using markdown sections like:
+```markdown
+### Delta: Add validate-all command
+**Type**: Feature addition
+**Effort**: Small (< 100 lines)
+```
+
+**Root Cause:**
+Fundamental misunderstanding of how OpenSpec processes deltas. Deltas are derived from spec files in the change's `specs/` directory, not from the proposal itself.
+
+**Discovery Process:**
+- Examined `ChangeParser` class in `/src/core/parsers/change-parser.ts`
+- Found that `parseDeltaSpecs()` method looks for spec files in `specs/` subdirectory
+- Learned that deltas are extracted by comparing spec files against existing specs
+
+### Error 2: Missing Operation Prefix in Section Headers
+**Error Message:** `✗ [ERROR] deltas: Change must have at least one delta`
+
+**What Happened:**
+Created new spec files with standard `## Requirements` headers instead of operation-prefixed headers.
+
+**Root Cause:**
+Failed to understand that ALL spec files in a change need operation prefixes (`ADDED`, `MODIFIED`, etc.) in their section headers, regardless of whether they're new specs or modifications.
+
+**Discovery Process:**
+- Created new specs with `## Requirements` → No deltas detected
+- Changed to `## ADDED Requirements` → Deltas detected successfully!
+- Realized creating new specs works perfectly fine once properly formatted
+
+**Important Clarification:**
+OpenSpec fully supports creating new specs. They appear as ADDED operations in the deltas. My initial analysis incorrectly suggested this was a limitation, but it was actually just a formatting issue.
+
+### Error 3: Improper Scenario Formatting
+**Error Message:** 
+```
+✗ [ERROR] deltas.0.requirements.0.scenarios: Requirement must have at least one scenario
+✗ [ERROR] deltas.1.requirements.0.scenarios: Requirement must have at least one scenario
+```
+
+**What Happened:**
+Formatted scenarios as bullet lists under a bold "Scenarios:" label:
+```markdown
+**Scenarios:**
+- **WHEN** executing command
+- **THEN** expected behavior
+```
+
+**Root Cause:**
+OpenSpec's parser expects scenarios to be defined as level 4 headers (`####`) with specific formatting:
+```markdown
+#### Scenario: Descriptive scenario name
+
+- **WHEN** executing command
+- **THEN** expected behavior
+```
+
+**Discovery Process:**
+- Checked parsed JSON output: `npx openspec change show bulk-validation-interactive-selection --json`
+- Saw `"scenarios": []` empty array despite having scenario content
+- Examined working spec files and found the `#### Scenario:` header pattern
+
+### Error 4: File Path Confusion
+**Initial Confusion:**
+Wasn't clear whether to create specs that would become part of the main `openspec/specs/` or just define them in the change.
+
+**Resolution:**
+Learned that changes can:
+1. Create new specs (they start in `changes/{change-name}/specs/` and move to `openspec/specs/` when archived)
+2. Modify existing specs (by creating a spec file with the same name as one in `openspec/specs/`)
+3. The validation system detects both patterns and creates appropriate deltas
+
+---
+
+## System Issues vs User Errors
+
+### System Issues / Bugs
+
+#### 1. Unhelpful Error Messages ⚠️
+**Issue:** `✗ [ERROR] deltas: Change must have at least one delta`
+
+**Why This Is a System Problem:**
+- Error message provides no guidance on HOW to create deltas
+- Doesn't mention that deltas come from `specs/` subdirectory
+- Doesn't explain the required section headers
+- A better error would be: "No deltas found. Ensure your change has a specs/ directory with .md files containing sections like '## ADDED Requirements'"
+
+#### 2. Silent Scenario Parsing Failures ⚠️
+**Issue:** When scenarios were formatted incorrectly, they were silently ignored
+
+**Why This Is a System Problem:**
+- Parser silently returns empty scenarios array instead of warning
+- No validation error explaining the format issue
+- User gets "Requirement must have at least one scenario" without knowing their scenarios exist but aren't parsed
+
+**Evidence:**
+```json
+{
+  "text": "The CLI SHALL provide a top-level `show` command with interactive selection.",
+  "scenarios": []  // Silent failure - scenarios existed but weren't parsed
+}
+```
+
+#### 3. No Validation for Proposal Structure During Creation
+**Issue:** System allows creating invalid proposals without early feedback
+
+**Why This Is a System Problem:**
+- No scaffolding or template commands
+- No incremental validation as you build
+- Must fully create the change before discovering structural issues
+
+### User Errors (My Mistakes)
+
+#### 1. Trying to Define Deltas in Proposal.md
+- Incorrectly assumed deltas could be inline in the proposal
+- System correctly expects deltas in separate spec files
+
+#### 2. Using Wrong Section Headers
+- Used `## Requirements` instead of `## ADDED Requirements`
+- Convention is documented in existing changes, but I didn't examine carefully
+
+#### 3. Wrong Scenario Format
+- Used bullet lists instead of `#### Scenario:` headers
+- Made assumptions instead of checking existing patterns
+
+### Gray Areas
+
+1. **Documentation gaps** - While examples exist, there's no comprehensive "How to Create a Change" guide
+2. **Lack of tooling** - No scaffolding commands to create properly structured changes
+
+---
+
+## Documentation Gaps Analysis
+
+### Critical Gaps in openspec/README.md
+
+#### 1. Scenario Format - COMPLETELY MISSING ⚠️
+**What README Shows:** No scenario examples at all
+
+**What's Actually Required:**
+```markdown
+#### Scenario: Descriptive name
+- **WHEN** condition
+- **THEN** expected outcome
+- **AND** additional outcomes
+```
+
+**Impact:** This was the biggest struggle. The README mentions requirements but never shows how to write scenarios. Without this, requirements fail validation.
+
+#### 2. Complete Spec File Example - MISSING
+**What README Shows:** Only fragments
+
+**What's Actually Needed:** A complete working example showing:
+- Full spec file structure
+- Proper requirement format
+- Scenario formatting
+- All required elements
+
+#### 3. Validation Commands - NOT MENTIONED
+**Missing from README:**
+- `npx openspec change validate <change-name>`
+- `npx openspec change show <change-name> --json`
+- The `--strict` flag for catching warnings
+
+#### 4. Delta Detection Explanation - INCOMPLETE
+**What's Missing:**
+- WHERE the system looks for specs (specs/ subdirectory)
+- THAT deltas are automatically extracted
+- HOW to debug when deltas aren't detected
+- WHAT error messages mean
+
+### Misleading Documentation
+
+#### "Store only the changes" - MISLEADING
+**Line 145:** `# - Store only the changes (not complete future state)`
+
+**Problem:** This suggests storing diffs or partial content. In reality, you need:
+- Complete requirements in their final form
+- Full scenario definitions
+- The entire requirement text
+
+### Documentation That Was Helpful
+1. Delta section headers (`## ADDED Requirements`) - clearly documented
+2. Directory structure - excellent visualization
+3. When to create proposals - well defined
+
+---
+
+## Key Learnings
+
+### 1. OpenSpec's Delta Detection Algorithm
+The system follows this process:
+1. Scans `openspec/changes/{change-name}/specs/` directory
+2. For each spec file found, parses for delta sections (`ADDED`, `MODIFIED`, `REMOVED`, `RENAMED`)
+3. Creates delta objects with operation type, affected spec, and requirements
+4. Validates that at least one delta exists for the change to be valid
+
+**Important:** Creating entirely new specs is fully supported! New specs use `## ADDED Requirements` and appear as ADDED operations in the deltas.
+
+### 2. Spec File Structure Requirements
+Valid spec files must follow this structure:
+```markdown
+# Spec Title
+
+## [ADDED|MODIFIED|REMOVED|RENAMED] Requirements
+
+### Requirement: Clear requirement statement
+
+The requirement description using SHALL/SHOULD/MAY.
+
+#### Scenario: Scenario name
+
+- **WHEN** condition
+- **THEN** expected outcome
+- **AND** additional outcomes
+```
+
+### 3. Change Proposal Structure
+A valid change must have:
+- `## Why` section - explaining the motivation
+- `## What Changes` section - summarizing the changes
+- `specs/` directory with properly formatted spec files containing deltas
+- Each delta must have at least one requirement with at least one scenario
+
+### 4. Validation Commands Are Essential
+```bash
+# Basic validation
+npx openspec change validate {change-name}
+
+# Strict validation (recommended)
+npx openspec change validate {change-name} --strict
+
+# Debug delta detection
+npx openspec change show {change-name} --json | jq '.deltas'
+```
+
+---
+
+## Recommendations
+
+### High Priority (System Bugs to Fix)
+
+1. **Improve Error Messages**
+   - Add actionable guidance to error messages
+   - Example: "No deltas found. Check: 1) specs/ directory exists, 2) Files use ## ADDED Requirements headers, 3) Each requirement has #### Scenario: sections"
+
+2. **Add Warnings for Malformed Content**
+   - Warn when scenarios exist but aren't properly formatted
+   - Show which line/file has the issue
+
+3. **Add Delta Detection Debugging**
+   - Command like `openspec change debug-deltas {change-name}`
+   - Show which files were scanned, what was found, what was rejected
+
+### Medium Priority (Documentation Improvements)
+
+1. **Add Complete Working Example to README**
+   - Full change proposal with all files
+   - Properly formatted specs with scenarios
+   - Show the validation output
+
+2. **Add Troubleshooting Section**
+   - Common errors and their solutions
+   - How to debug delta detection
+   - Scenario formatting requirements
+
+3. **Add Validation Best Practices**
+   - When to use `--strict`
+   - How to use JSON output for debugging
+   - Common validation patterns
+
+### Low Priority (Developer Experience)
+
+1. **Add Scaffolding Command**
+   ```bash
+   openspec change scaffold {change-name}
+   ```
+   - Creates proper directory structure
+   - Includes template files with correct formatting
+   - Adds example scenarios
+
+2. **Add Interactive Creation Wizard**
+   - Guide users through change creation
+   - Validate as they go
+   - Suggest fixes for common issues
+
+3. **Add Auto-fix Capability**
+   - `--fix` flag to correct common formatting issues
+   - Convert bullet list scenarios to proper headers
+   - Add missing operation prefixes
+
+---
+
+## Conclusion
+
+The OpenSpec system works correctly for its intended design, but the user experience for creating changes needs significant improvement. The core issues stem from:
+
+### System Issues
+- **Unhelpful error messages** that don't guide users to solutions
+- **Silent parsing failures** that provide no feedback about malformed content
+- **Lack of debugging tools** to understand what went wrong
+
+### Documentation Issues
+- **Critical formatting requirements missing** (especially scenario format)
+- **No complete working examples** showing all required elements
+- **Validation commands not documented** despite being essential
+
+### User Issues
+- **Incorrect assumptions** about how the system works
+- **Not examining existing patterns** carefully enough
+- **Trying to shortcut** instead of following established conventions
+
+### The Path Forward
+
+With better error messages, complete documentation, and basic tooling support, most of the errors encountered could be prevented. The system's delta-centric approach is powerful and ensures changes are atomic and trackable, but it needs to be more discoverable and user-friendly.
+
+The most impactful improvements would be:
+1. Adding scenario format documentation to the README
+2. Improving error messages with actionable guidance
+3. Creating a scaffolding command for new changes
+
+These changes would transform OpenSpec from a system that works correctly but is hard to use, into one that actively helps developers succeed.

README.md

@@ -0,0 +1,119 @@
+# OpenSpec
+
+A specification-driven development system for maintaining living documentation alongside your code.
+
+## Installation
+
+```bash
+npm install -g openspec
+```
+
+## Quick Start
+
+```bash
+# Initialize OpenSpec in your project
+openspec init
+
+# Update existing OpenSpec instructions (team-friendly)
+openspec update
+
+# List specs or changes
+openspec spec list        # specs (IDs by default; use --long for details)
+openspec change list      # changes (IDs by default; use --long for details)
+
+# Show differences between specs and proposed changes
+openspec diff [change-name]
+
+# Archive completed changes
+openspec archive [change-name]
+```
+
+## Commands
+
+### `openspec init`
+
+Initializes OpenSpec in your project by creating:
+- `openspec/` directory structure
+- `openspec/README.md` with OpenSpec instructions
+- AI tool configuration files (based on your selection)
+
+### `openspec update`
+
+Updates OpenSpec instructions to the latest version. This command is **team-friendly** and only updates files that already exist:
+
+- Always updates `openspec/README.md` with the latest OpenSpec instructions
+- **Only updates existing AI tool configuration files** (e.g., CLAUDE.md, CURSOR.md)
+- **Never creates new AI tool configuration files**
+- Preserves content outside of OpenSpec markers in AI tool files
+
+This allows team members to use different AI tools without conflicts. Each developer can maintain their preferred AI tool configuration file, and `openspec update` will respect their choice.
+
+### `openspec spec`
+
+Manage and view specifications.
+
+Examples:
+- `openspec spec show <spec-id>`
+  - Text mode: prints raw `spec.md` content
+  - JSON mode (`--json`): returns minimal, stable shape
+    - Filters are JSON-only: `--requirements`, `--no-scenarios`, `-r/--requirement <1-based>`
+- `openspec spec list`
+  - Prints IDs only by default
+  - Use `--long` to include `title` and `[requirements N]`
+- `openspec spec validate <spec-id>`
+  - Text: human-readable summary to stdout/stderr
+  - `--json` for structured report
+
+### `openspec change`
+
+Manage and view change proposals.
+
+Examples:
+- `openspec change show <change-id>`
+  - Text mode: prints raw `proposal.md` content
+  - JSON mode (`--json`): `{ id, title, deltaCount, deltas }`
+  - Filtering is JSON-only: `--deltas-only` (alias: `--requirements-only`, deprecated)
+- `openspec change list`
+  - Prints IDs only by default
+  - Use `--long` to include `title` and counts `[deltas N] [tasks x/y]`
+- `openspec change validate <change-id>`
+  - Text: human-readable result
+  - `--json` for structured report
+
+### `openspec diff [change-name]`
+
+Shows the differences between current specs and proposed changes:
+- Displays a unified diff format
+- Helps review what will change before implementation
+- Useful for pull request reviews
+
+### `openspec archive [change-name]`
+
+Archives a completed change:
+- Moves change from `openspec/changes/` to `openspec/changes/archive/`
+- Adds a date prefix to the archived change
+- Updates specs to reflect the new state
+- Use `--skip-specs` to archive without updating specs (for abandoned changes)
+
+## Team Collaboration
+
+OpenSpec is designed for team collaboration:
+
+1. **AI Tool Flexibility**: Each team member can use their preferred AI assistant (Claude, Cursor, etc.)
+2. **Non-Invasive Updates**: The `update` command only modifies existing files, never forcing tools on team members
+3. **Specification Sharing**: The `openspec/` directory contains shared specifications that all team members work from
+4. **Change Tracking**: Proposed changes are visible to all team members for review before implementation
+
+## Contributing
+
+See `openspec/specs/` for the current system specifications and `openspec/changes/` for pending improvements.
+
+## Notes
+
+- The legacy `openspec list` command is deprecated. Use `openspec spec list` and `openspec change list`.
+- Text output is raw-first (no formatting or filtering). Prefer `--json` for tooling-friendly output.
+- Global `--no-color` disables ANSI colors and respects `NO_COLOR`.
+
+## License
+
+MIT

openspec/README.md

@@ -43,9 +43,9 @@ openspec/
 │   │   ├── proposal.md     # Why, what, impact (consolidated)
 │   │   ├── tasks.md        # Implementation checklist
 │   │   ├── design.md       # Technical decisions (optional, for complex changes)
-│   │   └── specs/          # Future state of affected specs
+│   │   └── specs/          # Delta changes to specs
 │   │       └── [capability]/
-│   │           └── spec.md # Clean markdown (no diff syntax)
+│   │           └── spec.md # Delta format (ADDED/MODIFIED/REMOVED/RENAMED)
 │   └── archive/            # Completed changes (dated)
 ```
 
@@ -94,7 +94,35 @@ Before any task:
 - If adding dependencies, frameworks, or architectural patterns, document why simpler alternatives won't work
 - Default to single-file implementations until proven insufficient
 
-### 3. Creating a Change Proposal
+### 3. Delta-Based Change Format
+
+Changes use a delta format with clear sections:
+
+```markdown
+## ADDED Requirements
+### Requirement: New Feature
+[Complete requirement content in structured format]
+
+## MODIFIED Requirements  
+### Requirement: Existing Feature
+[Complete modified requirement (header must match current spec)]
+
+## REMOVED Requirements
+### Requirement: Old Feature
+**Reason for removal**: [Why removing]
+**Migration path**: [How to handle existing usage]
+
+## RENAMED Requirements
+- FROM: `### Requirement: Old Name`
+- TO: `### Requirement: New Name`
+```
+
+Key rules:
+- Headers are matched using `normalize(header) = trim(header)`
+- Include complete requirements (not diffs)
+- Use standard symbols in CLI output: + (added), ~ (modified), - (removed), → (renamed)
+
+### 4. Creating a Change Proposal
 
 When a user requests a significant change:
 
@@ -113,13 +141,21 @@ openspec/changes/[descriptive-name]/
 - Affected specs: [list capabilities that will change]
 - Affected code: [list key files/systems]
 
-# 3. Create future state specs for ALL affected capabilities
-# - Store complete spec files as they will exist after the change
-# - Use clean markdown without diff syntax (+/- prefixes)
-# - Include all formatting and structure of the final intended state
+# 3. Create delta specs for ALL affected capabilities
+# - Store only the changes (not complete future state)
+# - Use sections: ## ADDED, ## MODIFIED, ## REMOVED, ## RENAMED
+# - Include complete requirements in their final form
+# Example spec.md content:
+#   ## ADDED Requirements
+#   ### Requirement: Password Reset
+#   Users SHALL be able to reset passwords via email...
+#   
+#   ## MODIFIED Requirements
+#   ### Requirement: User Authentication
+#   [Complete modified requirement with new password reset hook]
 specs/
 └── [capability]/
-    └── spec.md
+    └── spec.md  # Contains delta sections
 
 # 4. Create tasks.md with implementation steps
 ## 1. [Task Group]
@@ -130,16 +166,16 @@ specs/
 [Technical decisions and trade-offs]
 ```
 
-### 4. The Change Lifecycle
+### 5. The Change Lifecycle
 
-1. **Propose** → Create change directory with all documentation
+1. **Propose** → Create change directory with delta-based documentation
 2. **Review** → User reviews and approves the proposal
 3. **Implement** → Follow the approved tasks.md (can be multiple PRs)
 4. **Deploy** → User confirms deployment
-5. **Update Specs** → Sync specs/ with new reality (IF the change affects system capabilities)
+5. **Update Specs** → Apply deltas to sync specs/ with new reality (IF the change affects system capabilities)
 6. **Archive** → Move to `changes/archive/YYYY-MM-DD-[name]/`
 
-### 5. Implementing Changes
+### 6. Implementing Changes
 
 When implementing an approved change:
 1. Follow the tasks.md checklist exactly
@@ -154,7 +190,7 @@ When implementing an approved change:
 - Different developers can work on different task groups
 - Example: PR #1 completes tasks 1.1-1.3, PR #2 completes tasks 2.1-2.4
 
-### 6. Updating Specs and Archiving After Deployment
+### 7. Updating Specs and Archiving After Deployment
 
 **Create a separate PR after deployment** that:
 1. Moves change to `changes/archive/YYYY-MM-DD-[name]/`
@@ -163,7 +199,7 @@ When implementing an approved change:
 
 This ensures changes are only archived when truly complete and deployed.
 
-### 7. Types of Changes That Don't Require Specs
+### 8. Types of Changes That Don't Require Specs
 
 Some changes only affect development infrastructure and don't need specs:
 - Initial project setup (package.json, tsconfig.json, etc.)
@@ -216,7 +252,16 @@ User: "Add password reset functionality"
 You should:
 1. Read specs/user-auth/spec.md
 2. Check changes/ for pending auth changes
-3. Create changes/add-password-reset/ with proposal
+3. Create changes/add-password-reset/ with:
+   - proposal.md describing the change
+   - specs/user-auth/spec.md with:
+     ## ADDED Requirements
+     ### Requirement: Password Reset
+     [Complete requirement for password reset]
+     
+     ## MODIFIED Requirements
+     ### Requirement: User Authentication
+     [Updated to integrate with password reset]
 4. Wait for approval before implementing
 ```
 

openspec/changes/IMPLEMENTATION_ORDER.md

@@ -0,0 +1,68 @@
+# Implementation Order and Dependencies
+
+## Required Implementation Sequence
+
+The following changes must be implemented in this specific order due to dependencies:
+
+### Phase 1: Foundation
+**1. add-zod-validation** (No dependencies)
+- Creates all core schemas (RequirementSchema, ScenarioSchema, SpecSchema, ChangeSchema, DeltaSchema)
+- Implements markdown parser utilities
+- Implements validation infrastructure and rules
+- Establishes validation patterns used by all commands
+- Must be completed first
+
+### Phase 2: Change Commands
+**2. add-change-commands** (Depends on: add-zod-validation)
+- Imports ChangeSchema and DeltaSchema from zod validation
+- Reuses markdown parsing utilities
+- Implements change command with built-in validation
+- Uses validation infrastructure for change validate subcommand
+- Cannot start until schemas and validation exist
+
+### Phase 3: Spec Commands
+**3. add-spec-commands** (Depends on: add-zod-validation, add-change-commands)
+- Imports RequirementSchema, ScenarioSchema, SpecSchema from zod validation
+- Reuses markdown parsing utilities
+- Implements spec command with built-in validation
+- Uses validation infrastructure for spec validate subcommand
+- Builds on patterns established by change commands
+
+## Dependency Graph
+```
+add-zod-validation
+    ↓
+add-change-commands
+    ↓
+add-spec-commands
+```
+
+## Key Dependencies
+
+### Shared Code Dependencies
+1. **Schemas**: All schemas created in add-zod-validation, used by both command implementations
+2. **Validation**: Infrastructure created in add-zod-validation, integrated into both commands
+3. **Parsers**: Markdown parsing utilities created in add-zod-validation, used by both commands
+
+### File Dependencies
+- `src/core/schemas/*.schema.ts` (created by add-zod-validation) → imported by both commands
+- `src/core/validation/validator.ts` (created by add-zod-validation) → used by both commands
+- `src/core/parsers/markdown-parser.ts` (created by add-zod-validation) → used by both commands
+
+## Implementation Notes
+
+### For Developers
+1. Complete each phase fully before moving to the next
+2. Run tests after each phase to ensure stability
+3. The legacy `list` command remains functional throughout
+
+### For CI/CD
+1. Each change can be validated independently
+2. Integration tests should run after each phase
+3. Full system tests required after Phase 3
+
+### Parallel Work Opportunities
+Within each phase, the following can be done in parallel:
+- **Phase 1**: Schema design, validation rules, and parser implementation
+- **Phase 2**: Change command features and legacy compatibility work
+- **Phase 3**: Spec command features and final integration

openspec/changes/add-change-commands/design.md

@@ -0,0 +1,56 @@
+# Design: Change Commands
+
+## Architecture Decisions
+
+### Command Structure
+Similar to spec commands, we use subcommands (`change show`, `change list`, `change validate`) for:
+- Consistency with spec command pattern
+- Clear separation of concerns
+- Future extensibility for change management features
+
+### JSON Schema for Changes
+```typescript
+{
+  version: string,           // Schema version
+  format: "change",         // Identifies as change document
+  sourcePath: string,       // Original markdown file path
+  id: string,              // Change identifier
+  title: string,           // Change title
+  why: string,            // Motivation section
+  whatChanges: Array<{
+    type: "ADDED" | "MODIFIED" | "REMOVED" | "RENAMED",
+    deltas: Array<{
+      specId: string,
+      description: string,
+      requirements?: Array<Requirement>  // Only for ADDED/MODIFIED
+    }>
+  }>
+}
+```
+
+**Rationale:**
+- Group deltas by operation type for clearer organization
+- Optional requirements field (only relevant for ADDED/MODIFIED)
+- Reuse RequirementSchema from spec commands for consistency
+
+### Delta Operations
+**Four operation types:**
+1. **ADDED**: New requirements added to specs
+2. **MODIFIED**: Changes to existing requirements
+3. **REMOVED**: Requirements being deleted
+4. **RENAMED**: Spec identifier changes
+
+**Design choice:** Explicit operation types rather than diff-based approach for:
+- Human readability in markdown
+- Clear intent communication
+- Easier validation and tooling
+
+### Dependency on Spec Commands
+- **Shared schemas**: RequirementSchema and ScenarioSchema reused
+- **Implementation order**: spec commands must be implemented first
+- **Common parser utilities**: Share markdown parsing logic
+
+### Legacy Compatibility
+- Keep existing `list` command functional with deprecation warning
+- Migration path: `list` → `change list` with same functionality
+- Gradual transition to avoid breaking existing workflows

openspec/changes/add-change-commands/proposal.md

@@ -0,0 +1,17 @@
+# Change: Add Change Commands with JSON Output
+
+## Why
+
+OpenSpec change proposals currently can only be viewed as markdown files, creating the same programmatic access limitations as specs. Additionally, the current `openspec list` command only lists changes, which is inconsistent with the new resource-based command structure.
+
+## What Changes
+
+- **cli-change:** Add new command for managing change proposals with show, list, and validate subcommands
+- **cli-list:** Add deprecation notice for legacy list command to guide users to the new change list command
+
+## Impact
+
+- **Affected specs**: cli-list (modify to add deprecation notice)
+- **Affected code**:
+  - src/cli/index.ts (register new command)
+  - src/core/list.ts (add deprecation notice)

openspec/changes/add-change-commands/specs/cli-change/spec.md

@@ -0,0 +1,48 @@
+## ADDED Requirements
+
+### Requirement: Change Command
+
+The system SHALL provide a `change` command with subcommands for displaying, listing, and validating change proposals.
+
+#### Scenario: Show change as JSON
+
+- **WHEN** executing `openspec change show update-error --json`
+- **THEN** parse the markdown change file
+- **AND** extract change structure and deltas
+- **AND** output valid JSON to stdout
+
+#### Scenario: List all changes
+
+- **WHEN** executing `openspec change list`
+- **THEN** scan the openspec/changes directory
+- **AND** return list of all pending changes
+- **AND** support JSON output with `--json` flag
+
+#### Scenario: Show only requirement changes
+
+- **WHEN** executing `openspec change show update-error --requirements-only`
+- **THEN** display only the requirement changes (ADDED/MODIFIED/REMOVED/RENAMED)
+- **AND** exclude why and what changes sections
+
+#### Scenario: Validate change structure
+
+- **WHEN** executing `openspec change validate update-error`
+- **THEN** parse the change file
+- **AND** validate against Zod schema
+- **AND** ensure deltas are well-formed
+
+### Requirement: Legacy Compatibility
+
+The system SHALL maintain backward compatibility with the existing `list` command while showing deprecation notices.
+
+#### Scenario: Legacy list command
+
+- **WHEN** executing `openspec list`
+- **THEN** display current list of changes (existing behavior)
+- **AND** show deprecation notice: "Note: 'openspec list' is deprecated. Use 'openspec change list' instead."
+
+#### Scenario: Legacy list with --all flag
+
+- **WHEN** executing `openspec list --all`
+- **THEN** display all changes (existing behavior)
+- **AND** show same deprecation notice

openspec/changes/add-change-commands/specs/cli-list/spec.md

@@ -0,0 +1,12 @@
+## MODIFIED Requirements
+
+### Requirement: List Command Behavior
+
+The current `list` command behavior SHALL be preserved but marked as deprecated.
+
+#### Scenario: Deprecation notice
+
+- **WHEN** using the legacy `list` command
+- **THEN** continue to work as before
+- **AND** display deprecation notice
+- **AND** suggest using `openspec change list` instead

openspec/changes/add-change-commands/tasks.md

@@ -0,0 +1,34 @@
+# Implementation Tasks (Phase 2: Builds on add-zod-validation)
+
+## 1. Command Implementation
+- [x] 1.1 Create src/commands/change.ts
+- [x] 1.2 Import ChangeSchema and DeltaSchema from src/core/schemas/change.schema.ts
+- [x] 1.3 Import markdown parser from src/core/parsers/markdown-parser.ts
+- [x] 1.4 Import ChangeValidator from src/core/validation/validator.ts
+- [x] 1.5 Import JSON converter from src/core/converters/json-converter.ts
+- [x] 1.6 Implement show subcommand with JSON output using existing converter
+- [x] 1.7 Implement list subcommand
+- [x] 1.8 Implement validate subcommand using existing ChangeValidator
+- [x] 1.9 Add --requirements-only filtering option
+- [x] 1.10 Add --strict mode support (leveraging existing validation infrastructure)
+- [x] 1.11 Add --json flag for validation reports
+
+## 2. Change-Specific Parser Extensions
+- [x] 2.1 Create src/core/parsers/change-parser.ts (extends base markdown parser)
+- [x] 2.2 Parse proposal structure (Why, What Changes sections)
+- [x] 2.3 Extract ADDED/MODIFIED/REMOVED/RENAMED sections
+- [x] 2.4 Parse delta operations within each section
+- [x] 2.5 Add tests for change parser
+
+## 3. Legacy Compatibility
+- [x] 3.1 Update src/core/list.ts to add deprecation notice
+- [x] 3.2 Ensure existing list command continues to work
+- [x] 3.3 Add console warning for deprecated command usage
+
+## 4. Integration
+- [x] 4.1 Register change command in src/cli/index.ts
+- [ ] 4.2 Add integration tests for all subcommands
+- [x] 4.3 Test JSON output for changes
+- [x] 4.4 Test legacy compatibility
+- [x] 4.5 Test validation with strict mode
+- [x] 4.6 Update CLI help documentation (add 'change' command to main help, document subcommands: show, list, validate)

openspec/changes/add-interactive-show-command/proposal.md

@@ -0,0 +1,20 @@
+## Why
+
+Users frequently need to view changes and specs but must know in advance whether they're looking at a change or spec. The current subcommand structure (`change show`, `spec show`) creates friction when:
+- Users want to quickly view an item without remembering its type
+- Exploring the codebase requires switching between different show commands
+- Show commands without arguments return errors instead of helpful guidance
+
+## What Changes
+
+- Add new top-level `show` command for displaying changes or specs with intelligent selection
+- Support direct item display: `openspec show <item>` with automatic type detection
+- Interactive selection when no arguments provided
+- Enhance existing `change show` and `spec show` to support interactive selection (backwards compatibility)
+- Maintain all existing format options (--json, --deltas-only, --requirements, etc.)
+
+## Impact
+
+- New specs to create: cli-show
+- Specs to enhance: cli-change, cli-spec (for backwards compatibility)
+- Affected code: src/cli/index.ts, src/commands/show.ts (new), src/commands/spec.ts, src/commands/change.ts

openspec/changes/add-interactive-show-command/specs/cli-change/spec.md

@@ -0,0 +1,23 @@
+# CLI Change Command Spec
+
+## ADDED Requirements
+
+### Requirement: Interactive show selection
+
+The change show command SHALL support interactive selection when no change name is provided.
+
+#### Scenario: Interactive change selection for show
+
+- **WHEN** executing `openspec change show` without arguments
+- **THEN** display an interactive list of available changes
+- **AND** allow the user to select a change to show
+- **AND** display the selected change content
+- **AND** maintain all existing show options (--json, --deltas-only)
+
+#### Scenario: Non-interactive fallback keeps current behavior
+
+- **GIVEN** stdin is not a TTY or `--no-interactive` is provided or environment variable `OPEN_SPEC_INTERACTIVE=0`
+- **WHEN** executing `openspec change show` without a change name
+- **THEN** do not prompt interactively
+- **AND** print the existing hint including available change IDs
+- **AND** set `process.exitCode = 1`

openspec/changes/add-interactive-show-command/specs/cli-show/spec.md

@@ -0,0 +1,83 @@
+# CLI Show Command Spec
+
+## ADDED Requirements
+
+### Requirement: Top-level show command
+
+The CLI SHALL provide a top-level `show` command for displaying changes and specs with intelligent selection.
+
+#### Scenario: Interactive show selection
+
+- **WHEN** executing `openspec show` without arguments
+- **THEN** prompt user to select type (change or spec)
+- **AND** display list of available items for selected type
+- **AND** show the selected item's content
+
+#### Scenario: Non-interactive environments do not prompt
+
+- **GIVEN** stdin is not a TTY or `--no-interactive` is provided or environment variable `OPEN_SPEC_INTERACTIVE=0`
+- **WHEN** executing `openspec show` without arguments
+- **THEN** do not prompt
+- **AND** print a helpful hint with examples for `openspec show <item>` or `openspec change/spec show`
+- **AND** exit with code 1
+
+#### Scenario: Direct item display
+
+- **WHEN** executing `openspec show <item-name>`
+- **THEN** automatically detect if item is a change or spec
+- **AND** display the item's content
+- **AND** use appropriate formatting based on item type
+
+#### Scenario: Type detection and ambiguity handling
+
+- **WHEN** executing `openspec show <item-name>`
+- **THEN** if `<item-name>` uniquely matches a change or a spec, show that item
+- **AND** if it matches both, print an ambiguity error and suggest `--type change|spec` or using `openspec change show`/`openspec spec show`
+- **AND** if it matches neither, print not-found with nearest-match suggestions
+
+#### Scenario: Explicit type override
+
+- **WHEN** executing `openspec show --type change <item>`
+- **THEN** treat `<item>` as a change ID and show it (skipping auto-detection)
+
+- **WHEN** executing `openspec show --type spec <item>`
+- **THEN** treat `<item>` as a spec ID and show it (skipping auto-detection)
+
+### Requirement: Output format options
+
+The show command SHALL support various output formats consistent with existing commands.
+
+#### Scenario: JSON output
+
+- **WHEN** executing `openspec show <item> --json`
+- **THEN** output the item in JSON format
+- **AND** include parsed metadata and structure
+- **AND** maintain format consistency with existing change/spec show commands
+
+#### Scenario: Flag scoping and delegation
+
+- **WHEN** showing a change or a spec via the top-level command
+- **THEN** accept common flags such as `--json`
+- **AND** pass through type-specific flags to the corresponding implementation
+  - Change-only flags: `--deltas-only` (alias `--requirements-only` deprecated)
+  - Spec-only flags: `--requirements`, `--no-scenarios`, `-r/--requirement`
+- **AND** ignore irrelevant flags for the detected type with a warning
+
+### Requirement: Interactivity controls
+
+- The CLI SHALL respect `--no-interactive` to disable prompts.
+- The CLI SHALL respect `OPEN_SPEC_INTERACTIVE=0` to disable prompts globally.
+- Interactive prompts SHALL only be shown when stdin is a TTY and interactivity is not disabled.
+
+#### Scenario: Change-specific options
+
+- **WHEN** showing a change with `openspec show <change-name> --deltas-only`
+- **THEN** display only the deltas in JSON format
+- **AND** maintain compatibility with existing change show options
+
+#### Scenario: Spec-specific options  
+
+- **WHEN** showing a spec with `openspec show <spec-id> --requirements`
+- **THEN** display only requirements in JSON format
+- **AND** support other spec options (--no-scenarios, -r)
+- **AND** maintain compatibility with existing spec show options

openspec/changes/add-interactive-show-command/specs/cli-spec/spec.md

@@ -0,0 +1,23 @@
+# CLI Spec Command Spec
+
+## ADDED Requirements
+
+### Requirement: Interactive spec show
+
+The spec show command SHALL support interactive selection when no spec-id is provided.
+
+#### Scenario: Interactive spec selection for show
+
+- **WHEN** executing `openspec spec show` without arguments
+- **THEN** display an interactive list of available specs
+- **AND** allow the user to select a spec to show
+- **AND** display the selected spec content
+- **AND** maintain all existing show options (--json, --requirements, --no-scenarios, -r)
+
+#### Scenario: Non-interactive fallback keeps current behavior
+
+- **GIVEN** stdin is not a TTY or `--no-interactive` is provided or environment variable `OPEN_SPEC_INTERACTIVE=0`
+- **WHEN** executing `openspec spec show` without a spec-id
+- **THEN** do not prompt interactively
+- **AND** print the existing error message for missing spec-id
+- **AND** set non-zero exit code

openspec/changes/add-skip-specs-archive-option/proposal.md

@@ -0,0 +1,13 @@
+## Why
+The archive command currently forces users to either accept spec updates or cancel the entire archive operation. Users need flexibility to archive changes without updating specs, either through explicit flags or by declining the confirmation prompt. This is especially important for changes that don't modify specs (like tooling, documentation, or infrastructure updates).
+
+## What Changes
+- Add new `--skip-specs` flag to the archive command that bypasses all spec update operations
+- Fix confirmation behavior: when users decline spec updates interactively, proceed with archiving instead of cancelling the entire operation
+- When `--skip-specs` flag is used, skip both the spec discovery and update confirmation steps entirely
+- Display clear message when specs are skipped (either via flag or user choice)
+- Flag can be combined with existing `--yes` flag for fully automated archiving without spec updates
+
+## Impact
+- Affected specs: cli-archive
+- Affected code: src/core/archive.ts, src/cli/index.ts

openspec/changes/add-skip-specs-archive-option/specs/cli-archive/spec.md

@@ -0,0 +1,191 @@
+# CLI Archive Command Specification
+
+## Purpose
+The archive command moves completed changes from the active changes directory to the archive folder with date-based naming, following OpenSpec conventions.
+
+## Command Syntax
+```bash
+openspec archive [change-name] [--yes|-y] [--skip-specs]
+```
+
+Options:
+- `--yes`, `-y`: Skip confirmation prompts (for automation)
+- `--skip-specs`: Skip spec update operations entirely (for changes without spec modifications)
+
+## Behavior
+
+### Requirement: Change Selection
+
+The command SHALL support both interactive and direct change selection methods.
+
+#### Scenario: Interactive selection
+
+- **WHEN** no change-name is provided
+- **THEN** display interactive list of available changes (excluding archive/)
+- **AND** allow user to select one
+
+#### Scenario: Direct selection
+
+- **WHEN** change-name is provided
+- **THEN** use that change directly
+- **AND** validate it exists
+
+### Requirement: Task Completion Check
+
+The command SHALL verify task completion status before archiving to prevent premature archival.
+
+#### Scenario: Incomplete tasks found
+
+- **WHEN** incomplete tasks are found (marked with `- [ ]`)
+- **THEN** display all incomplete tasks to the user
+- **AND** prompt for confirmation to continue
+- **AND** default to "No" for safety
+
+#### Scenario: All tasks complete
+
+- **WHEN** all tasks are complete OR no tasks.md exists
+- **THEN** proceed with archiving without prompting
+
+### Requirement: Archive Process
+
+The archive operation SHALL follow a structured process to safely move changes to the archive.
+
+#### Scenario: Performing archive
+
+- **WHEN** archiving a change
+- **THEN** execute these steps:
+  1. Create archive/ directory if it doesn't exist
+  2. Generate target name as `YYYY-MM-DD-[change-name]` using current date
+  3. Check if target directory already exists
+  4. Update main specs from the change's future state specs unless `--skip-specs` is provided (see Spec Update Process below)
+  5. Move the entire change directory to the archive location
+
+#### Scenario: Archive already exists
+
+- **WHEN** target archive already exists
+- **THEN** fail with error message
+- **AND** do not overwrite existing archive
+
+#### Scenario: Successful archive
+
+- **WHEN** move succeeds
+- **THEN** display success message with archived name and list of updated specs (if any)
+
+### Requirement: Spec Update Process
+
+Before moving the change to archive, the command SHALL update main specs to reflect the deployed reality unless the `--skip-specs` flag is provided.
+
+#### Scenario: Skipping spec updates
+
+- **WHEN** the `--skip-specs` flag is provided
+- **THEN** skip all spec discovery and update operations
+- **AND** proceed directly to moving the change to archive
+- **AND** display message indicating specs were skipped
+
+#### Scenario: Updating specs from change
+
+- **WHEN** the change contains specs in `changes/[name]/specs/` AND `--skip-specs` is NOT provided
+- **THEN** execute these steps:
+  1. Analyze which specs will be affected by comparing with existing specs
+  2. Display a summary of spec updates to the user (see Confirmation Behavior below)
+  3. Prompt for confirmation unless `--yes` flag is provided
+  4. If confirmed, for each capability spec in the change directory:
+     - Copy the spec from `changes/[name]/specs/[capability]/spec.md` to `openspec/specs/[capability]/spec.md`
+     - Create the target directory structure if it doesn't exist
+     - Overwrite existing spec files (specs represent current reality, change specs are the new reality)
+     - Track which specs were updated for the success message
+
+#### Scenario: No specs in change
+
+- **WHEN** no specs exist in the change AND `--skip-specs` is NOT provided
+- **THEN** skip the spec update step
+- **AND** proceed with archiving
+
+### Requirement: Confirmation Behavior
+
+The spec update confirmation SHALL provide clear visibility into changes before they are applied.
+
+#### Scenario: Displaying confirmation
+
+- **WHEN** prompting for confirmation AND `--skip-specs` is NOT provided
+- **THEN** display a clear summary showing:
+  - Which specs will be created (new capabilities)
+  - Which specs will be updated (existing capabilities)
+  - The source path for each spec
+- **AND** format the confirmation prompt as:
+  ```
+  The following specs will be updated:
+  
+  NEW specs to be created:
+    - cli-archive (from changes/add-archive-command/specs/cli-archive/spec.md)
+  
+  EXISTING specs to be updated:
+    - cli-init (from changes/update-init-command/specs/cli-init/spec.md)
+  
+  Update 2 specs and archive 'add-archive-command'? [y/N]:
+  ```
+#### Scenario: Handling confirmation response
+
+- **WHEN** waiting for user confirmation
+- **THEN** default to "No" for safety (require explicit "y" or "yes")
+- **AND** skip confirmation when `--yes` or `-y` flag is provided
+- **AND** skip entire spec confirmation when `--skip-specs` flag is provided
+
+#### Scenario: User declines spec update confirmation
+
+- **WHEN** user declines the spec update confirmation
+- **THEN** skip the spec update operations
+- **AND** display message: "Skipping spec updates. Proceeding with archive."
+- **AND** continue with the archive operation
+- **AND** display success message indicating specs were not updated
+
+## Error Handling
+
+### Requirement: Error Conditions
+
+The command SHALL handle various error conditions gracefully.
+
+#### Scenario: Handling errors
+
+- **WHEN** errors occur
+- **THEN** handle the following conditions:
+  - Missing openspec/changes/ directory
+  - Change not found
+  - Archive target already exists
+  - File system permissions issues
+
+## Why These Decisions
+
+**Interactive selection**: Reduces typing and helps users see available changes
+**Task checking**: Prevents accidental archiving of incomplete work
+**Date prefixing**: Maintains chronological order and prevents naming conflicts
+**No overwrite**: Preserves historical archives and prevents data loss
+**Spec updates before archiving**: Specs in the main directory represent current reality; when a change is deployed and archived, its future state specs become the new reality and must replace the main specs
+**Confirmation for spec updates**: Provides visibility into what will change, prevents accidental overwrites, and ensures users understand the impact before specs are modified
+**Non-blocking confirmation**: Declining spec updates doesn't cancel archiving - users can review specs and choose to update them separately if needed
+**--yes flag for automation**: Allows CI/CD pipelines to archive without interactive prompts while maintaining safety by default for manual use
+**--skip-specs flag**: Enables archiving of changes that don't modify specs (like infrastructure, tooling, or documentation changes) without unnecessary spec update prompts or operations
+
+## ADDED Requirements
+
+### Requirement: Skip Specs Option
+
+The archive command SHALL support a `--skip-specs` flag that skips all spec update operations and proceeds directly to archiving.
+
+#### Scenario: Skipping spec updates with flag
+
+- **WHEN** executing `openspec archive <change> --skip-specs`
+- **THEN** skip spec discovery and update confirmation
+- **AND** proceed directly to moving the change to archive
+- **AND** display a message indicating specs were skipped
+
+### Requirement: Non-blocking confirmation
+
+The archive operation SHALL proceed when the user declines spec updates instead of cancelling the entire operation.
+
+#### Scenario: User declines spec update confirmation
+
+- **WHEN** the user declines spec update confirmation
+- **THEN** skip spec updates
+- **AND** continue with the archive operation
+- **AND** display a success message indicating specs were not updated

openspec/changes/add-skip-specs-archive-option/tasks.md

@@ -0,0 +1,57 @@
+## 1. Update Archive Command Implementation
+- [x] 1.1 Add `skipSpecs` option to the archive command options interface
+- [x] 1.2 Modify the execute method to skip spec operations when flag is set
+- [x] 1.3 Fix confirmation behavior: when user declines spec updates, proceed with archiving instead of cancelling
+- [x] 1.4 Update console output to indicate when specs are being skipped (via flag or user choice)
+- [x] 1.5 Ensure archive continues after declining spec updates
+
+## 2. Update CLI Interface
+- [x] 2.1 Add `--skip-specs` flag to the archive command definition
+- [x] 2.2 Pass the flag value to the archive command execute method
+
+## 3. Update Tests
+- [x] 3.1 Add test case for archiving with --skip-specs flag
+- [x] 3.2 Add test case for declining spec updates but continuing with archive
+- [x] 3.3 Verify that spec updates are skipped when flag is used
+- [x] 3.4 Verify that archive proceeds when user declines spec updates
+- [x] 3.5 Ensure existing behavior remains unchanged when flag is not used
+
+## 4. Update Documentation
+- [x] 4.1 Update the cli-archive spec to document the new --skip-specs flag
+- [x] 4.2 Document the new behavior when declining spec updates interactively
+
+## Implementation Notes
+
+### Key Design Decisions
+
+1. **Non-blocking Confirmation Behavior**: When users decline spec updates interactively, the archive operation continues rather than cancelling entirely. This was a critical UX improvement because:
+   - Users may want to review specs separately before updating them
+   - Archiving work shouldn't be blocked by spec review decisions
+   - Maintains flexibility in the deployment workflow
+
+2. **Flag Naming Convention**: Chose `--skip-specs` for clarity and consistency:
+   - Clearly indicates the action (skipping) and target (specs)
+   - Follows kebab-case convention for CLI flags
+   - Converts naturally to `skipSpecs` camelCase in code
+
+3. **Console Messaging Strategy**: Added explicit messages for all spec-skipping scenarios:
+   - When flag is used: "Skipping spec updates (--skip-specs flag provided)."
+   - When user declines: "Skipping spec updates. Proceeding with archive."
+   - Ensures users always understand what's happening with their specs
+
+4. **Test Coverage Approach**: Created separate test cases for:
+   - Flag-based skipping (explicit user choice via CLI)
+   - Interactive declining (runtime user decision)
+   - Both verify the same outcome but test different code paths
+
+### Use Cases Addressed
+
+- **Infrastructure Changes**: Changes to build tools, CI/CD, dependencies
+- **Documentation Updates**: README updates, comment improvements
+- **Tooling Modifications**: Developer tools, scripts, configuration files
+- **Refactoring**: Code improvements that don't change functionality/specs
+
+### Future Considerations
+
+- Could potentially auto-detect when changes don't include specs and suggest using the flag
+- May want to track which archives skipped spec updates for audit purposes

openspec/changes/add-spec-commands/design.md

@@ -0,0 +1,45 @@
+# Design: Spec Commands
+
+## Architecture Decisions
+
+### Command Hierarchy
+We chose a subcommand pattern (`spec show`, `spec list`, `spec validate`) to:
+- Group related functionality under a common namespace
+- Enable future extensibility without polluting the top-level CLI
+- Maintain consistency with the planned `change` command structure
+
+### JSON Schema Structure
+The spec JSON schema follows this structure:
+```typescript
+{
+  version: string,        // Schema version for compatibility
+  format: "spec",        // Identifies this as a spec document
+  sourcePath: string,    // Original markdown file path
+  id: string,           // Spec identifier from filename
+  title: string,        // Human-readable title
+  overview?: string,    // Optional overview section
+  requirements: Array<{
+    id: string,
+    text: string,
+    scenarios: Array<{
+      id: string,
+      text: string
+    }>
+  }>
+}
+```
+
+**Rationale:**
+- Flat structure for requirements array (vs nested objects) for easier iteration
+- Scenarios nested within requirements to maintain relationship
+- Metadata fields (version, format, sourcePath) for tooling integration
+
+### Parser Architecture
+- **Markdown-first approach**: Parse markdown headings rather than custom syntax
+- **Streaming parser**: Process line-by-line to handle large files efficiently
+- **Strict heading hierarchy**: Enforce ##/###/#### structure for consistency
+
+### Validation Strategy
+- **Parse-time validation**: Catch structural issues during parsing
+- **Schema validation**: Use Zod for runtime type checking of parsed data
+- **Separate validation command**: Allow validation without full parsing/conversion

openspec/changes/add-spec-commands/proposal.md

@@ -0,0 +1,19 @@
+# Change: Add Spec Commands with JSON Output
+
+## Why
+
+Currently, OpenSpec specs can only be viewed as markdown files. This makes programmatic access difficult and prevents integration with CI/CD pipelines, external tools, and automated processing.
+
+## What Changes
+
+- Add new `openspec spec` command with three subcommands: `show`, `list`, and `validate`
+- Implement JSON output capability for specs using heading-based parsing
+- Add Zod schemas for spec structure validation
+- Enable content filtering options (requirements only, no scenarios, specific requirement)
+
+## Impact
+
+- **Affected specs**: None (new capability)
+- **Affected code**: 
+  - src/cli/index.ts (register new command)
+  - package.json (add zod dependency)

openspec/changes/add-spec-commands/specs/cli-spec/spec.md

@@ -0,0 +1,43 @@
+## ADDED Requirements
+
+### Requirement: Spec Command
+
+The system SHALL provide a `spec` command with subcommands for displaying, listing, and validating specifications.
+
+#### Scenario: Show spec as JSON
+
+- **WHEN** executing `openspec spec show init --json`
+- **THEN** parse the markdown spec file
+- **AND** extract headings and content hierarchically
+- **AND** output valid JSON to stdout
+
+#### Scenario: List all specs
+
+- **WHEN** executing `openspec spec list`
+- **THEN** scan the openspec/specs directory
+- **AND** return list of all available capabilities
+- **AND** support JSON output with `--json` flag
+
+#### Scenario: Filter spec content
+
+- **WHEN** executing `openspec spec show init --requirements`
+- **THEN** display only requirement names and SHALL statements
+- **AND** exclude scenario content
+
+#### Scenario: Validate spec structure
+
+- **WHEN** executing `openspec spec validate init`
+- **THEN** parse the spec file
+- **AND** validate against Zod schema
+- **AND** report any structural issues
+
+### Requirement: JSON Schema Definition
+
+The system SHALL define Zod schemas that accurately represent the spec structure for runtime validation.
+
+#### Scenario: Schema validation
+
+- **WHEN** parsing a spec into JSON
+- **THEN** validate the structure using Zod schemas
+- **AND** ensure all required fields are present
+- **AND** provide clear error messages for validation failures

openspec/changes/add-spec-commands/tasks.md

@@ -0,0 +1,22 @@
+# Implementation Tasks (Phase 3: Builds on add-zod-validation and add-change-commands)
+
+## 1. Command Implementation
+- [x] 1.1 Create src/commands/spec.ts
+- [x] 1.2 Import RequirementSchema, ScenarioSchema, SpecSchema from src/core/schemas/
+- [x] 1.3 Import markdown parser from src/core/parsers/markdown-parser.ts
+- [x] 1.4 Import SpecValidator from src/core/validation/validator.ts
+- [x] 1.5 Import JSON converter from src/core/converters/json-converter.ts
+- [x] 1.6 Implement show subcommand with JSON output using existing converter
+- [x] 1.7 Implement list subcommand
+- [x] 1.8 Implement validate subcommand using existing SpecValidator
+- [x] 1.9 Add filtering options (--requirements, --no-scenarios, -r)
+- [x] 1.10 Add --strict mode support (leveraging existing validation infrastructure)
+- [x] 1.11 Add --json flag for validation reports
+
+## 2. Integration
+- [x] 2.1 Register spec command in src/cli/index.ts
+- [x] 2.2 Add integration tests for all subcommands
+- [x] 2.3 Test JSON output validation
+- [x] 2.4 Test filtering options
+- [x] 2.5 Test validation with strict mode
+- [x] 2.6 Update CLI help documentation (add 'spec' command to main help, document subcommands: show, list, validate)

openspec/changes/add-status-command/proposal.md

@@ -1,19 +0,0 @@
-# Add Status Command to OpenSpec CLI
-
-## Why
-
-Developers need to know which changes have all tasks completed and are ready to archive.
-
-## What Changes
-
-- Add `openspec status` command that scans the changes/ directory
-- Parse each tasks.md file to count `[x]` (complete) and `[ ]` (incomplete) tasks
-- Display each change with its completion status (e.g., "auth-feature: 5/5" or "auth-feature: ✓")
-- Skip the archive/ subdirectory
-
-## Impact
-
-- Affected specs: New capability `cli-status` will be added
-- Affected code:
-  - `src/cli/index.ts` - Add status command
-  - `src/core/status.ts` - New file with simple scanning and parsing logic (~50 lines)

openspec/changes/add-status-command/specs/cli-status/spec.md

@@ -1,58 +0,0 @@
-# CLI Status Command Specification
-
-## Purpose
-
-The status command shows which OpenSpec changes are ready to archive by displaying task completion status for each change.
-
-## Command Interface
-
-```bash
-# Show status of all changes
-openspec status
-```
-
-## Behavior
-
-WHEN the status command runs:
-1. Scan the `openspec/changes/` directory
-2. Skip the `archive/` subdirectory
-3. For each change directory with a `tasks.md` file:
-   - Count tasks marked with `[x]` (case-insensitive)
-   - Count tasks marked with `[ ]`
-   - Display the change name and completion status
-
-## Output Format
-
-```
-add-auth-feature: 15/15
-fix-payment-bug: 8/8
-refactor-api: 3/10
-update-docs: 0/5
-```
-
-Or with checkmark for fully complete:
-
-```
-add-auth-feature: ✓
-fix-payment-bug: ✓  
-refactor-api: 3/10
-update-docs: 0/5
-```
-
-## Task Detection
-
-The command recognizes these patterns as tasks:
-- `- [ ]` Incomplete task
-- `- [x]` Complete task (lowercase)
-- `- [X]` Complete task (uppercase)
-
-## Error Handling
-
-- If no `tasks.md` exists, skip that change
-- If `tasks.md` is empty or has no tasks, skip that change
-- Continue scanning even if individual files have errors
-
-## Exit Codes
-
-- `0`: Success - status displayed
-- `1`: Error - unable to scan changes directory

openspec/changes/add-status-command/tasks.md

@@ -1,8 +0,0 @@
-# Implementation Tasks for Status Command
-
-## Core Implementation
-- [ ] Add status command to `src/cli/index.ts`
-- [ ] Create `src/core/status.ts` with directory scanning logic
-- [ ] Parse tasks.md files to count `[x]` and `[ ]` patterns
-- [ ] Display each change with completion status (name: complete/total)
-- [ ] Skip the archive/ subdirectory when scanning

openspec/changes/add-zod-validation/design.md

@@ -0,0 +1,104 @@
+# Design: Zod Validation Framework
+
+## Architecture Decisions
+
+### Validation Levels
+Three-tier validation system:
+1. **ERROR**: Structural issues that prevent parsing (must fix)
+2. **WARNING**: Quality issues that should be addressed (recommended fix)
+3. **INFO**: Suggestions for improvement (optional)
+
+**Rationale:** 
+- Gradual enforcement allows teams to adopt validation incrementally
+- CI/CD can fail on errors but allow warnings initially
+- Info level provides guidance without blocking
+
+### Validation Rules Hierarchy
+
+#### Spec Validation Rules
+```
+ERROR level:
+- Missing ## Overview or ## Requirements sections
+- Invalid heading hierarchy
+- Malformed requirement/scenario structure
+
+WARNING level:
+- Requirements without scenarios
+- Requirements missing SHALL keyword
+- Empty overview section
+
+INFO level:
+- Very long requirement text (>500 chars)
+- Scenarios without Given/When/Then structure
+```
+
+#### Change Validation Rules
+```
+ERROR level:
+- Missing ## Why or ## What Changes sections
+- Invalid delta operation types
+- Malformed delta structure
+
+WARNING level:
+- Why section too brief (<50 chars)
+- Deltas without clear descriptions
+- Missing requirements in ADDED/MODIFIED
+
+INFO level:
+- Very long why section (>1000 chars)
+- Too many deltas in single change (>10)
+```
+
+### Strict Mode
+- **Default**: Show all levels, fail on ERROR only
+- **--strict flag**: Fail on both ERROR and WARNING
+- **Use case**: Gradual quality improvement in CI/CD pipelines
+
+### Archive Command Safety
+**Problem:** Invalid specs could be archived, polluting the archive.
+
+**Solution:** 
+1. Pre-archive validation (default behavior)
+2. --no-validate flag with safeguards:
+   - Interactive confirmation prompt
+   - Prominent warning message
+   - Console logging with timestamp
+   - Not recommended for CI/CD usage
+
+**Rationale:**
+- Protect archive integrity by default
+- Allow emergency overrides with accountability
+- Clear audit trail for validation bypasses
+
+### Validation Report Format
+```json
+{
+  "valid": boolean,
+  "issues": [
+    {
+      "level": "ERROR" | "WARNING" | "INFO",
+      "path": "requirements[0].scenarios",
+      "message": "Requirement must have at least one scenario",
+      "line": 15,
+      "column": 0
+    }
+  ],
+  "summary": {
+    "errors": 2,
+    "warnings": 5,
+    "info": 3
+  }
+}
+```
+
+**Benefits:**
+- Machine-readable for tooling integration
+- Human-friendly messages
+- Line/column info for IDE integration
+- Summary for quick assessment
+
+### Implementation Strategy
+1. **Zod schemas with refinements**: Built-in validation in type definitions
+2. **Custom validators**: Additional business logic validation
+3. **Composable rules**: Mix and match for different contexts
+4. **Extensible framework**: Easy to add new rules without refactoring

openspec/changes/add-zod-validation/proposal.md

@@ -0,0 +1,22 @@
+# Change: Add Zod Runtime Validation
+
+## Why
+
+While the spec and change commands can output JSON, they currently don't perform strict runtime validation beyond basic structure checking. This can lead to invalid specs or changes being processed, silent failures when required fields are missing, and poor error messages.
+
+## What Changes
+
+- Enhance existing `spec validate` and `change validate` commands with strict Zod validation
+- Add validation to the archive command to ensure changes are valid before applying
+- Add validation to the diff command to ensure changes are well-formed
+- Provide detailed validation reports in JSON format
+- Add `--strict` mode that fails on warnings
+
+## Impact
+
+- **Affected specs**: cli-spec, cli-change, cli-archive, cli-diff
+- **Affected code**:
+  - src/commands/spec.ts (enhance validate subcommand)
+  - src/commands/change.ts (enhance validate subcommand)
+  - src/core/archive.ts (add pre-archive validation)
+  - src/core/diff.ts (add validation check)

openspec/changes/add-zod-validation/specs/cli-archive/spec.md

@@ -0,0 +1,18 @@
+## ADDED Requirements
+
+### Requirement: Archive Validation
+
+The archive command SHALL validate changes before applying them to ensure data integrity.
+
+#### Scenario: Pre-archive validation
+
+- **WHEN** executing `openspec archive change-name`
+- **THEN** validate the change structure first
+- **AND** only proceed if validation passes
+- **AND** show validation errors if it fails
+
+#### Scenario: Force archive without validation
+
+- **WHEN** executing `openspec archive change-name --no-validate`
+- **THEN** skip validation (unsafe mode)
+- **AND** show warning about skipping validation

openspec/changes/add-zod-validation/specs/cli-diff/spec.md

@@ -0,0 +1,12 @@
+## MODIFIED Requirements
+
+### Requirement: Diff Command Enhancement
+
+The diff command SHALL validate change structure before displaying differences.
+
+#### Scenario: Validate before diff
+
+- **WHEN** executing `openspec diff change-name`
+- **THEN** validate change structure
+- **AND** show validation warnings if present
+- **AND** continue with diff display

openspec/changes/add-zod-validation/tasks.md

@@ -0,0 +1,59 @@
+# Implementation Tasks (Foundation Phase)
+
+## 1. Core Schemas
+- [x] 1.1 Add zod dependency to package.json
+- [x] 1.2 Create src/core/schemas/base.schema.ts with ScenarioSchema and RequirementSchema
+- [x] 1.3 Create src/core/schemas/spec.schema.ts with SpecSchema
+- [x] 1.4 Create src/core/schemas/change.schema.ts with DeltaSchema and ChangeSchema
+- [x] 1.5 Create src/core/schemas/index.ts to export all schemas
+
+## 2. Parser Implementation
+- [x] 2.1 Create src/core/parsers/markdown-parser.ts
+- [x] 2.2 Implement heading extraction (##, ###, ####)
+- [x] 2.3 Implement content capture between headings
+- [x] 2.4 Add tests for parser edge cases
+
+## 3. Validation Infrastructure
+- [x] 3.1 Create src/core/validation/types.ts with ValidationLevel, ValidationIssue, ValidationReport types
+- [x] 3.2 Create src/core/validation/constants.ts with validation rules and thresholds
+- [x] 3.3 Create src/core/validation/validator.ts with SpecValidator and ChangeValidator classes
+
+## 4. Enhanced Validation Rules
+- [x] 4.1 Add RequirementValidation refinements (must have scenarios, must contain SHALL)
+- [x] 4.2 Add SpecValidation refinements (must have requirements)
+- [x] 4.3 Add ChangeValidation refinements (must have deltas, why section length)
+- [x] 4.4 Implement custom error messages for each rule
+
+## 5. JSON Converter
+- [x] 5.1 Create src/core/converters/json-converter.ts
+- [x] 5.2 Implement spec-to-JSON conversion
+- [x] 5.3 Implement change-to-JSON conversion
+- [x] 5.4 Add metadata fields (version, format, sourcePath)
+
+## 6. Archive Command Enhancement
+- [x] 6.1 Add pre-archive validation check using new validators
+- [x] 6.2 Add --no-validate flag with required confirmation prompt and warning message: "⚠️  WARNING: Skipping validation may archive invalid specs. Continue? (y/N)"
+- [x] 6.3 Display validation errors before aborting
+- [x] 6.4 Log all --no-validate usages to console with timestamp and affected files
+- [x] 6.5 Add tests for validation scenarios including --no-validate confirmation flow
+
+## 7. Diff Command Enhancement
+- [x] 7.1 Add validation check before diff using new validators
+- [x] 7.2 Show validation warnings (non-blocking)
+- [x] 7.3 Continue with diff even if warnings present
+
+## 8. Testing
+- [x] 8.1 Unit tests for all schemas
+- [x] 8.2 Unit tests for parser
+- [x] 8.3 Unit tests for validation rules
+- [x] 8.4 Integration tests for validation reports
+- [x] 8.5 Test various invalid spec/change formats
+- [x] 8.6 Test strict mode behavior
+- [x] 8.7 Test pre-archive validation
+- [x] 8.8 Test validation report JSON output
+
+## 9. Documentation
+- [x] 9.1 Document schema structure and validation rules (openspec/VALIDATION.md)
+- [x] 9.2 Update CLI help for archive (document --no-validate flag and its warnings)
+- [x] 9.3 Update CLI help for diff (document validation warnings behavior)
+- [x] 9.4 Create migration guide for future command integration (openspec/MIGRATION.md)

openspec/changes/adopt-delta-based-changes/proposal.md

@@ -0,0 +1,93 @@
+# Adopt Delta-Based Changes for Specifications
+
+## Why
+
+The current approach of storing complete future states in change proposals creates a poor review experience. When reviewing changes on GitHub, reviewers see entire spec files (often 100+ lines) as "added" in green, making it impossible to identify what actually changed. With the recent structured format adoption, we now have clear section boundaries that enable a better approach: storing only additions and modifications.
+
+## What Changes
+
+Store only the requirements that actually change, not complete future states:
+
+- **ADDED Requirements**: New capabilities being introduced
+- **MODIFIED Requirements**: Existing requirements being changed (must match current header)
+- **REMOVED Requirements**: Deprecated capabilities
+- **RENAMED Requirements**: Explicit header changes (e.g., `FROM: Old Name` → `TO: New Name`)
+
+The archive command will programmatically apply these deltas using normalized header matching (trim leading/trailing whitespace) instead of manually copying entire files.
+
+## Impact
+
+**Affected specs**: openspec-conventions, cli-archive, cli-diff
+
+**Benefits**:
+- GitHub diffs show only actual changes (25 lines instead of 150+)
+- Reviewers immediately see what's being added, modified, or removed
+- Conflicts are more apparent when two changes modify the same requirement
+- Archive command can programmatically apply changes
+
+**Format**: Delta format only - all changes must use ADDED/MODIFIED/REMOVED sections.
+
+## Example
+
+Instead of storing a 150-line complete future spec, store only:
+
+```markdown
+# User Authentication - Changes
+
+## ADDED Requirements
+
+### Requirement: OAuth Support
+Users SHALL authenticate via OAuth providers including Google and GitHub.
+
+#### Scenario: OAuth login flow
+- **WHEN** user selects OAuth provider
+- **THEN** redirect to provider authorization
+- **AND** exchange authorization code for tokens
+
+## MODIFIED Requirements
+
+### Requirement: Session Management
+Sessions SHALL expire after 30 minutes of inactivity.
+
+#### Scenario: Inactive session timeout  
+- **WHEN** no activity for 30 minutes ← (was 60 minutes)
+- **THEN** invalidate session token
+- **AND** require re-authentication
+
+## RENAMED Requirements
+- FROM: `### Requirement: Basic Authentication`
+- TO: `### Requirement: Email Authentication`
+```
+
+This makes reviews focused and changes explicit.
+
+## Conflict Resolution
+
+Git naturally detects conflicts when two changes modify the same requirement header. This is actually better than full-state storage where Git might silently merge incompatible changes.
+
+## Decisions and Product Guidelines
+
+To keep the archive flow lean and predictable, the following decisions apply:
+
+- New spec creation: When a target spec does not exist, auto-generate a minimal skeleton and insert ADDED requirements only. Skeleton format:
+  - `# [Spec Name] Specification`
+  - `## Purpose` with placeholder: "TBD — created by archiving change [change-name]. Update Purpose after archive."
+  - `## Requirements`
+  - If a non-existent spec includes MODIFIED/REMOVED/RENAMED, abort with guidance to create via ADDED-only first.
+
+- Requirement identification: Match requirements by exact header `### Requirement: [Name]` with trim-only normalization and case-sensitive comparison. Use a requirement-block extractor that preserves the exact header and captures full content (including scenarios) for both main specs and delta files.
+
+- Application order and atomicity: Apply deltas in order RENAMED → REMOVED → MODIFIED → ADDED. Validate all operations first, apply in-memory, and write each spec once. On any validation failure, abort without writing partial results. An aggregated totals line is displayed across all specs: `Totals: + A, ~ M, - R, → N`.
+
+- Validation matrix: Enforce that MODIFIED/REMOVED exist; ADDED do not exist; RENAMED FROM exists and TO does not; no duplicates after all operations; and no cross-section conflicts (e.g., same item in MODIFIED and REMOVED). When a rename and modify apply to the same item, MODIFIED must reference the NEW header.
+
+- Idempotency: Keep v1 simple. Abort on precondition failures (e.g., ADDED already exists) with clear errors. Do not implement no-op detection in v1.
+
+- Output and UX: For each spec, display operation counts using standard symbols `+ ~ - →`. Optionally include a short aggregated totals line at the end. Keep messages concise and actionable.
+
+- Error messaging: Standardize messages as `[spec] [operation] failed for header "### Requirement: X" — reason`. On abort, explicitly state: `Aborted. No files were changed.`
+- Subsections: Any subsections under a requirement (e.g., `#### Scenario: ...`) are preserved verbatim during parsing and application.
+
+- Backward compatibility: Reject full future-state spec copies for existing specs with guidance to convert to deltas. Allow brand-new specs to be created via ADDED-only deltas using the skeleton above.
+
+- Dry-run: Deferred for v1 to keep scope minimal.

openspec/changes/adopt-delta-based-changes/specs/cli-archive/spec.md

@@ -0,0 +1,46 @@
+# CLI Archive Command - Changes
+
+## MODIFIED Requirements
+
+### Requirement: Spec Update Process
+
+Before moving the change to archive, the command SHALL apply delta changes to main specs to reflect the deployed reality.
+
+#### Scenario: Applying delta changes
+
+- **WHEN** archiving a change with delta-based specs
+- **THEN** parse and apply delta changes as defined in openspec-conventions
+- **AND** validate all operations before applying
+
+#### Scenario: Validating delta changes
+
+- **WHEN** processing delta changes
+- **THEN** perform validations as specified in openspec-conventions
+- **AND** if validation fails, show specific errors and abort
+
+#### Scenario: Conflict detection
+
+- **WHEN** applying deltas would create duplicate requirement headers
+- **THEN** abort with error message showing the conflict
+- **AND** suggest manual resolution
+
+### Requirement: Display Output
+
+The command SHALL provide clear feedback about delta operations.
+
+#### Scenario: Showing delta application
+
+- **WHEN** applying delta changes
+- **THEN** display for each spec:
+  - Number of requirements added
+  - Number of requirements modified
+  - Number of requirements removed
+  - Number of requirements renamed
+- **AND** use standard output symbols (+ ~ - →) as defined in openspec-conventions:
+  ```
+  Applying changes to specs/user-auth/spec.md:
+    + 2 added
+    ~ 3 modified
+    - 1 removed
+    → 1 renamed
+  ```

openspec/changes/adopt-delta-based-changes/specs/cli-diff/spec.md

@@ -0,0 +1,43 @@
+# CLI Diff Command - Changes
+
+## REMOVED Requirements
+
+### Requirement: Display Format
+
+The diff command SHALL display unified diff output in text format.
+
+**Reason for removal**: The standard unified diff format is replaced by requirement-level side-by-side comparison that better shows semantic changes rather than line-by-line text differences.
+
+#### Scenario: Unified diff output (deprecated)
+
+- **WHEN** running `openspec diff <change>`
+- **THEN** show a unified text diff of files
+- **AND** include `+`/`-` prefixed lines representing additions and removals
+
+## MODIFIED Requirements
+
+### Requirement: Diff Output
+
+The command SHALL show a requirement-level comparison displaying only changed requirements.
+
+#### Scenario: Side-by-side comparison of changes
+
+- **WHEN** running `openspec diff <change>`
+- **THEN** display only requirements that have changed
+- **AND** show them in a side-by-side format that:
+  - Clearly shows the current version on the left
+  - Shows the future version on the right
+  - Indicates new requirements (not in current)
+  - Indicates removed requirements (not in future)
+  - Aligns modified requirements for easy comparison
+
+### Requirement: Validation
+
+The command SHALL validate that changes can be applied successfully.
+
+#### Scenario: Invalid delta references
+
+- **WHEN** delta references non-existent requirement
+- **THEN** show error message with specific requirement
+- **AND** continue showing other valid changes
+- **AND** clearly mark failed changes in the output

openspec/changes/adopt-delta-based-changes/specs/openspec-conventions/spec.md

@@ -0,0 +1,117 @@
+# OpenSpec Conventions - Changes
+
+## ADDED Requirements
+
+### Requirement: Header-Based Requirement Identification
+
+Requirement headers SHALL serve as unique identifiers for programmatic matching between current specs and proposed changes.
+
+#### Scenario: Matching requirements programmatically
+
+- **WHEN** processing delta changes
+- **THEN** use the `### Requirement: [Name]` header as the unique identifier
+- **AND** match using normalized headers: `normalize(header) = trim(header)`
+- **AND** compare headers with case-sensitive equality after normalization
+
+#### Scenario: Handling requirement renames
+
+- **WHEN** renaming a requirement
+- **THEN** use a special `## RENAMED Requirements` section
+- **AND** specify both old and new names explicitly:
+  ```markdown
+  ## RENAMED Requirements
+  - FROM: `### Requirement: Old Name`
+  - TO: `### Requirement: New Name`
+  ```
+- **AND** if content also changes, include under MODIFIED using the NEW header
+
+#### Scenario: Validating header uniqueness
+
+- **WHEN** creating or modifying requirements
+- **THEN** ensure no duplicate headers exist within a spec
+- **AND** validation tools SHALL flag duplicate headers as errors
+
+## MODIFIED Requirements
+
+### Requirement: Change Storage Convention
+
+Change proposals SHALL store only the additions, modifications, and removals to specifications, not complete future states.
+
+#### Scenario: Creating change proposals with additions
+
+- **WHEN** creating a change proposal that adds new requirements
+- **THEN** include only the new requirements under `## ADDED Requirements`
+- **AND** each requirement SHALL include its complete content
+- **AND** use the standard structured format for requirements and scenarios
+
+#### Scenario: Creating change proposals with modifications  
+
+- **WHEN** creating a change proposal that modifies existing requirements
+- **THEN** include the modified requirements under `## MODIFIED Requirements`
+- **AND** use the same header text as in the current spec (normalized)
+- **AND** include the complete modified requirement (not a diff)
+- **AND** optionally annotate what changed with inline comments like `← (was X)`
+
+#### Scenario: Creating change proposals with removals
+
+- **WHEN** creating a change proposal that removes requirements
+- **THEN** list them under `## REMOVED Requirements`
+- **AND** use the normalized header text for identification
+- **AND** include reason for removal
+- **AND** document any migration path if applicable
+
+
+The `changes/[name]/specs/` directory SHALL contain:
+- Delta files showing only what changes
+- Sections for ADDED, MODIFIED, REMOVED, and RENAMED requirements
+- Normalized header matching for requirement identification
+- Complete requirements using the structured format
+- Clear indication of change type for each requirement
+
+#### Scenario: Using standard output symbols
+
+- **WHEN** displaying delta operations in CLI output
+- **THEN** use these standard symbols:
+  - `+` for ADDED (green)
+  - `~` for MODIFIED (yellow)
+  - `-` for REMOVED (red)
+  - `→` for RENAMED (cyan)
+
+### Requirement: Archive Process Enhancement
+
+The archive process SHALL programmatically apply delta changes to current specifications using header-based matching.
+
+#### Scenario: Archiving changes with deltas
+
+- **WHEN** archiving a completed change
+- **THEN** the archive command SHALL:
+  1. Parse RENAMED sections first and apply renames
+  2. Parse REMOVED sections and remove by normalized header match
+  3. Parse MODIFIED sections and replace by normalized header match (using new names if renamed)
+  4. Parse ADDED sections and append new requirements
+- **AND** validate that all MODIFIED/REMOVED headers exist in current spec
+- **AND** validate that ADDED headers don't already exist
+- **AND** generate the updated spec in the main specs/ directory
+
+#### Scenario: Handling conflicts during archive
+
+- **WHEN** delta changes conflict with current spec state
+- **THEN** the archive command SHALL report specific conflicts
+- **AND** require manual resolution before proceeding
+- **AND** provide clear guidance on resolving conflicts
+
+## REMOVED Requirements
+
+### Requirement: Future State Storage
+
+The system SHALL no longer store complete future-state specifications in change proposals.
+
+**Reason for removal**: Replaced by delta-based change storage which provides better review experience and clearer change tracking.
+
+**Migration path**: All new changes must use delta format.
+
+#### Scenario: Deprecate future state storage
+
+- **WHEN** creating a new change proposal
+- **THEN** do not include full future-state specs
+- **AND** include only ADDED/MODIFIED/REMOVED/RENAMED requirements under the change's `specs/` directory

openspec/changes/adopt-delta-based-changes/tasks.md

@@ -0,0 +1,55 @@
+# Implementation Tasks
+
+## 1. Update Conventions
+- [x] 1.1 Update openspec-conventions spec with delta-based approach
+- [x] 1.2 Add Header-Based Requirement Identification
+- [x] 1.3 Define ADDED/MODIFIED/REMOVED/RENAMED sections
+- [x] 1.4 Document standard output symbols (+ ~ - →)
+- [x] 1.5 Update openspec/README.md with delta-based conventions
+- [x] 1.6 Update examples to use delta format
+
+## 2. Update Diff Command
+- [ ] 2.1 Update cli-diff spec with requirement-level comparison
+- [ ] 2.2 Parse specs into requirement-level structures
+- [ ] 2.3 Apply deltas to generate future state
+- [ ] 2.4 Implement side-by-side comparison view (changes only)
+- [ ] 2.5 Add tests for requirement-level comparison
+- [ ] 2.6 Add tests for side-by-side view formatting
+
+## 3. Update Archive Command
+- [x] 3.1 Update cli-archive spec with delta processing behavior
+- [x] 3.2 Implement requirement-block extractor that preserves exact headers (`### Requirement: [Name]`) and captures full content (including scenarios)
+- [x] 3.3 Implement normalized header matching (trim-only, case-sensitive)
+- [x] 3.4 Parse delta sections (ADDED/MODIFIED/REMOVED/RENAMED)
+- [x] 3.5 New spec creation when target spec does not exist
+  - [x] 3.5.1 Auto-generate minimal skeleton: `# [Spec Name] Specification`, `## Purpose` placeholder, `## Requirements`
+  - [x] 3.5.2 Allow only ADDED operations for non-existent specs; abort if MODIFIED/REMOVED/RENAMED present
+- [x] 3.6 Apply changes in order: RENAMED → REMOVED → MODIFIED → ADDED
+- [x] 3.7 Validation and conflict checks
+  - [x] 3.7.1 MODIFIED/REMOVED requirements exist (after applying rename mappings)
+  - [x] 3.7.2 ADDED requirements don't already exist (consider post-rename state)
+  - [x] 3.7.3 RENAMED FROM headers exist; TO headers don't (including collisions with ADDED)
+  - [x] 3.7.4 No duplicate headers within specs after all operations
+  - [x] 3.7.5 Detect cross-section conflicts (e.g., same requirement in MODIFIED and REMOVED)
+  - [x] 3.7.6 When a rename exists, require MODIFIED to reference the NEW header
+- [x] 3.8 Atomic updates
+  - [x] 3.8.1 Validate all deltas first; stage updates in-memory per spec
+  - [x] 3.8.2 Single write per spec; abort entire archive on any validation failure (no partial writes)
+- [x] 3.9 Output and error messaging
+  - [x] 3.9.1 Display per-spec operation counts with symbols: `+` added, `~` modified, `-` removed, `→` renamed
+  - [x] 3.9.2 Optionally display an aggregated totals line across all specs
+  - [x] 3.9.3 Standardize error message format: `[spec] [operation] failed for header "### Requirement: X" — reason`; end with `Aborted. No files were changed.` on failure
+- [x] 3.10 Idempotency behavior (v1): abort on precondition failures (e.g., ADDED already exists); do not implement no-op detection
+- [x] 3.11 Tests
+  - [x] 3.11.1 Header normalization (trim-only) matching
+  - [x] 3.11.2 Apply in correct order (RENAMED → REMOVED → MODIFIED → ADDED)
+  - [x] 3.11.3 Validation edge cases (missing headers, duplicates, rename collisions, conflicting sections)
+  - [x] 3.11.4 Rename + modify interplay (MODIFIED uses new header)
+  - [x] 3.11.5 New spec creation via skeleton
+  - [x] 3.11.6 Multi-spec mixed operations with independent validation and write
+
+## Notes
+- Archive command is critical path - must work reliably
+- All new changes must use delta format
+- Header normalization: normalize(header) = trim(header)
+- Diff command shows only changed requirements in side-by-side comparison

openspec/changes/archive/2025-01-13-add-list-command/proposal.md

@@ -0,0 +1,20 @@
+# Add List Command to OpenSpec CLI
+
+## Why
+
+Developers need visibility into available changes and their status to understand the project's evolution and pending work.
+
+## What Changes
+
+- Add `openspec list` command that displays all changes in the changes/ directory
+- Show each change name with task completion count (e.g., "add-auth: 3/5 tasks")
+- Display completion status indicator (✓ for fully complete, progress for partial)
+- Skip the archive/ subdirectory to focus on active changes
+- Simple table output for easy scanning
+
+## Impact
+
+- Affected specs: New capability `cli-list` will be added
+- Affected code:
+  - `src/cli/index.ts` - Add list command
+  - `src/core/list.ts` - New file with directory scanning and task parsing (~60 lines)

openspec/changes/archive/2025-01-13-add-list-command/specs/cli-list/spec.md

@@ -0,0 +1,69 @@
+# List Command Specification
+
+## Purpose
+
+The `openspec list` command SHALL provide developers with a quick overview of all active changes in the project, showing their names and task completion status.
+
+## Behavior
+
+### Command Execution
+
+WHEN `openspec list` is executed
+THEN scan the `openspec/changes/` directory for change directories
+AND exclude the `archive/` subdirectory from results
+AND parse each change's `tasks.md` file to count task completion
+
+### Task Counting
+
+WHEN parsing a `tasks.md` file
+THEN count tasks matching these patterns:
+- Completed: Lines containing `- [x]`
+- Incomplete: Lines containing `- [ ]`
+AND calculate total tasks as the sum of completed and incomplete
+
+### Output Format
+
+WHEN displaying the list
+THEN show a table with columns:
+- Change name (directory name)
+- Task progress (e.g., "3/5 tasks" or "✓ Complete")
+- Status indicator:
+  - `✓` for fully completed changes (all tasks done)
+  - Progress fraction for partial completion
+
+Example output:
+```
+Changes:
+  add-auth-feature     3/5 tasks
+  update-api-docs      ✓ Complete
+  fix-validation       0/2 tasks
+  add-list-command     1/4 tasks
+```
+
+### Empty State
+
+WHEN no active changes exist (only archive/ or empty changes/)
+THEN display: "No active changes found."
+
+### Error Handling
+
+IF a change directory has no `tasks.md` file
+THEN display the change with "No tasks" status
+
+IF `openspec/changes/` directory doesn't exist
+THEN display error: "No OpenSpec changes directory found. Run 'openspec init' first."
+AND exit with code 1
+
+### Sorting
+
+Changes SHALL be displayed in alphabetical order by change name for consistency.
+
+## Why
+
+Developers need a quick way to:
+- See what changes are in progress
+- Identify which changes are ready to archive
+- Understand the overall project evolution status
+- Get a bird's-eye view without opening multiple files
+
+This command provides that visibility with minimal effort, following OpenSpec's philosophy of simplicity and clarity.

openspec/changes/archive/2025-01-13-add-list-command/tasks.md

@@ -0,0 +1,26 @@
+# Implementation Tasks
+
+## 1. Core Implementation
+- [x] 1.1 Create `src/core/list.ts` with list logic
+  - [x] 1.1.1 Implement directory scanning (exclude archive/)
+  - [x] 1.1.2 Implement task counting from tasks.md files
+  - [x] 1.1.3 Format output as simple table
+- [x] 1.2 Add list command to CLI in `src/cli/index.ts`
+  - [x] 1.2.1 Register `openspec list` command
+  - [x] 1.2.2 Connect to list.ts implementation
+
+## 2. Error Handling
+- [x] 2.1 Handle missing openspec/changes/ directory
+- [x] 2.2 Handle changes without tasks.md files
+- [x] 2.3 Handle empty changes directory
+
+## 3. Testing
+- [x] 3.1 Add tests for list functionality
+  - [x] 3.1.1 Test with multiple changes
+  - [x] 3.1.2 Test with completed changes
+  - [x] 3.1.3 Test with no changes
+  - [x] 3.1.4 Test error conditions
+
+## 4. Documentation
+- [x] 4.1 Update CLI help text with list command
+- [x] 4.2 Add list command to README if applicable

openspec/changes/archive/2025-08-13-add-archive-command/proposal.md

@@ -0,0 +1,15 @@
+## Why
+Need a command to archive completed changes to the archive folder with proper date prefixing, following OpenSpec conventions. Currently changes must be manually moved and renamed.
+
+## What Changes
+- Add new `archive` command to CLI that moves changes to `changes/archive/YYYY-MM-DD-[change-name]/`
+- Check for incomplete tasks before archiving and warn user
+- Allow interactive selection of change to archive
+- Prevent archiving if target directory already exists
+- Update main specs from the change's future state specs (copy from `changes/[name]/specs/` to `openspec/specs/`)
+- Show confirmation prompt before updating specs, displaying which specs will be created/updated
+- Support `--yes` flag to skip confirmations for automation
+
+## Impact
+- Affected specs: cli-archive (new)
+- Affected code: src/cli/index.ts, src/core/archive.ts (new)

openspec/changes/archive/2025-08-13-add-archive-command/specs/cli-archive/spec.md

@@ -0,0 +1,111 @@
+# CLI Archive Command Specification
+
+## Purpose
+The archive command moves completed changes from the active changes directory to the archive folder with date-based naming, following OpenSpec conventions.
+
+## Command Syntax
+```bash
+openspec archive [change-name] [--yes|-y]
+```
+
+Options:
+- `--yes`, `-y`: Skip confirmation prompts (for automation)
+
+## Behavior
+
+### Change Selection
+WHEN no change-name is provided
+THEN display interactive list of available changes (excluding archive/)
+AND allow user to select one
+
+WHEN change-name is provided
+THEN use that change directly
+AND validate it exists
+
+### Task Completion Check
+The command SHALL scan the change's tasks.md file for incomplete tasks (marked with `- [ ]`)
+
+WHEN incomplete tasks are found
+THEN display all incomplete tasks to the user
+AND prompt for confirmation to continue
+AND default to "No" for safety
+
+WHEN all tasks are complete OR no tasks.md exists
+THEN proceed with archiving without prompting
+
+### Archive Process
+The archive operation SHALL:
+1. Create archive/ directory if it doesn't exist
+2. Generate target name as `YYYY-MM-DD-[change-name]` using current date
+3. Check if target directory already exists
+4. Update main specs from the change's future state specs (see Spec Update Process below)
+5. Move the entire change directory to the archive location
+
+WHEN target archive already exists
+THEN fail with error message
+AND do not overwrite existing archive
+
+WHEN move succeeds
+THEN display success message with archived name and list of updated specs
+
+### Spec Update Process
+Before moving the change to archive, the command SHALL update main specs to reflect the deployed reality:
+
+WHEN the change contains specs in `changes/[name]/specs/`
+THEN:
+1. Analyze which specs will be affected by comparing with existing specs
+2. Display a summary of spec updates to the user (see Confirmation Behavior below)
+3. Prompt for confirmation unless `--yes` flag is provided
+4. If confirmed, for each capability spec in the change directory:
+   - Copy the spec from `changes/[name]/specs/[capability]/spec.md` to `openspec/specs/[capability]/spec.md`
+   - Create the target directory structure if it doesn't exist
+   - Overwrite existing spec files (specs represent current reality, change specs are the new reality)
+   - Track which specs were updated for the success message
+
+WHEN no specs exist in the change
+THEN skip the spec update step
+AND proceed with archiving
+
+### Confirmation Behavior
+The spec update confirmation SHALL:
+- Display a clear summary showing:
+  - Which specs will be created (new capabilities)
+  - Which specs will be updated (existing capabilities)
+  - The source path for each spec
+- Format the confirmation prompt as:
+  ```
+  The following specs will be updated:
+  
+  NEW specs to be created:
+    - cli-archive (from changes/add-archive-command/specs/cli-archive/spec.md)
+  
+  EXISTING specs to be updated:
+    - cli-init (from changes/update-init-command/specs/cli-init/spec.md)
+  
+  Update 2 specs and archive 'add-archive-command'? [y/N]:
+  ```
+- Default to "No" for safety (require explicit "y" or "yes")
+- Skip confirmation when `--yes` or `-y` flag is provided
+
+WHEN user declines the confirmation
+THEN abort the entire archive operation
+AND display message: "Archive cancelled. No changes were made."
+AND exit with non-zero status code
+
+## Error Handling
+
+SHALL handle the following error conditions:
+- Missing openspec/changes/ directory
+- Change not found
+- Archive target already exists
+- File system permissions issues
+
+## Why These Decisions
+
+**Interactive selection**: Reduces typing and helps users see available changes
+**Task checking**: Prevents accidental archiving of incomplete work
+**Date prefixing**: Maintains chronological order and prevents naming conflicts
+**No overwrite**: Preserves historical archives and prevents data loss
+**Spec updates before archiving**: Specs in the main directory represent current reality; when a change is deployed and archived, its future state specs become the new reality and must replace the main specs
+**Confirmation for spec updates**: Provides visibility into what will change, prevents accidental overwrites, and ensures users understand the impact before specs are modified
+**--yes flag for automation**: Allows CI/CD pipelines to archive without interactive prompts while maintaining safety by default for manual use

openspec/changes/archive/2025-08-13-add-archive-command/tasks.md

@@ -0,0 +1,44 @@
+# Implementation Tasks
+
+## 1. Core Implementation
+- [ ] 1.1 Create `src/core/archive.ts` with ArchiveCommand class
+  - [ ] 1.1.1 Implement change selection (interactive if not provided)
+  - [ ] 1.1.2 Implement incomplete task checking from tasks.md
+  - [ ] 1.1.3 Implement confirmation prompt for incomplete tasks
+  - [ ] 1.1.4 Implement spec update functionality
+    - [ ] 1.1.4.1 Detect specs in change directory
+    - [ ] 1.1.4.2 Compare with existing main specs
+    - [ ] 1.1.4.3 Display summary of new vs updated specs
+    - [ ] 1.1.4.4 Show confirmation prompt for spec updates
+    - [ ] 1.1.4.5 Copy specs to main spec directory
+  - [ ] 1.1.5 Implement archive move with date prefixing
+  - [ ] 1.1.6 Support --yes flag to skip confirmations
+
+## 2. CLI Integration
+- [ ] 2.1 Add archive command to `src/cli/index.ts`
+  - [ ] 2.1.1 Import ArchiveCommand
+  - [ ] 2.1.2 Register command with commander
+  - [ ] 2.1.3 Add --yes/-y flag option
+  - [ ] 2.1.4 Add proper error handling
+
+## 3. Error Handling
+- [ ] 3.1 Handle missing openspec/changes/ directory
+- [ ] 3.2 Handle change not found
+- [ ] 3.3 Handle archive target already exists
+- [ ] 3.4 Handle user cancellation
+
+## 4. Testing
+- [ ] 4.1 Test with fully completed change
+- [ ] 4.2 Test with incomplete tasks (warning shown)
+- [ ] 4.3 Test interactive selection mode
+- [ ] 4.4 Test duplicate archive prevention
+- [ ] 4.5 Test spec update functionality
+  - [ ] 4.5.1 Test creating new specs
+  - [ ] 4.5.2 Test updating existing specs
+  - [ ] 4.5.3 Test confirmation prompt display
+  - [ ] 4.5.4 Test declining confirmation (no changes made)
+  - [ ] 4.5.5 Test --yes flag skips confirmation
+
+## 5. Build and Validation
+- [ ] 5.1 Ensure TypeScript compilation succeeds
+- [ ] 5.2 Test command execution

openspec/changes/bulk-validation-interactive-selection/proposal.md

@@ -0,0 +1,20 @@
+## Why
+
+Currently, users must validate changes and specs individually by specifying each ID. This creates friction when:
+- Teams want to validate all changes/specs before a release
+- Developers need to ensure consistency across multiple related changes  
+- Users run validation commands without arguments and receive errors instead of helpful guidance
+- The subcommand structure requires users to know in advance whether they're validating a change or spec
+
+## What Changes
+
+- Add new top-level `validate` command with intuitive flags (--all, --changes, --specs)
+- Enhance existing `change validate` and `spec validate` to support interactive selection (backwards compatibility)
+- Interactive selection by default when no arguments provided
+- Support direct item validation: `openspec validate <item>` with automatic type detection
+
+## Impact
+
+- New specs to create: cli-validate
+- Specs to enhance: cli-change, cli-spec (for backwards compatibility)
+- Affected code: src/cli/index.ts, src/commands/validate.ts (new), src/commands/spec.ts, src/commands/change.ts

openspec/changes/bulk-validation-interactive-selection/specs/cli-change/spec.md

@@ -0,0 +1,22 @@
+# CLI Change Command Spec
+
+## ADDED Requirements
+
+### Requirement: Interactive validation selection
+
+The change validate command SHALL support interactive selection when no change name is provided.
+
+#### Scenario: Interactive change selection for validation
+
+- **WHEN** executing `openspec change validate` without arguments
+- **THEN** display an interactive list of available changes
+- **AND** allow the user to select a change to validate
+- **AND** validate the selected change
+
+#### Scenario: Non-interactive fallback keeps current behavior
+
+- **GIVEN** stdin is not a TTY or `--no-interactive` is provided or environment variable `OPEN_SPEC_INTERACTIVE=0`
+- **WHEN** executing `openspec change validate` without a change name
+- **THEN** do not prompt interactively
+- **AND** print the existing hint including available change IDs
+- **AND** set `process.exitCode = 1`

openspec/changes/bulk-validation-interactive-selection/specs/cli-spec/spec.md

@@ -0,0 +1,23 @@
+# CLI Spec Command Spec
+
+## ADDED Requirements
+
+### Requirement: Interactive spec validation
+
+The spec validate command SHALL support interactive selection when no spec-id is provided.
+
+#### Scenario: Interactive spec selection for validation
+
+- **WHEN** executing `openspec spec validate` without arguments
+- **THEN** display an interactive list of available specs
+- **AND** allow the user to select a spec to validate
+- **AND** validate the selected spec
+- **AND** maintain all existing validation options (--strict, --json)
+
+#### Scenario: Non-interactive fallback keeps current behavior
+
+- **GIVEN** stdin is not a TTY or `--no-interactive` is provided or environment variable `OPEN_SPEC_INTERACTIVE=0`
+- **WHEN** executing `openspec spec validate` without a spec-id
+- **THEN** do not prompt interactively
+- **AND** print the existing error message for missing spec-id
+- **AND** set non-zero exit code

openspec/changes/bulk-validation-interactive-selection/specs/cli-validate/spec.md

@@ -0,0 +1,141 @@
+# CLI Validate Command Spec
+
+## ADDED Requirements
+
+### Requirement: Top-level validate command
+
+The CLI SHALL provide a top-level `validate` command for validating changes and specs with flexible selection options.
+
+#### Scenario: Interactive validation selection
+
+- **WHEN** executing `openspec validate` without arguments
+- **THEN** prompt user to select what to validate (all, changes, specs, or specific item)
+- **AND** perform validation based on selection
+- **AND** display results with appropriate formatting
+
+#### Scenario: Non-interactive environments do not prompt
+
+- **GIVEN** stdin is not a TTY or `--no-interactive` is provided or environment variable `OPEN_SPEC_INTERACTIVE=0`
+- **WHEN** executing `openspec validate` without arguments
+- **THEN** do not prompt interactively
+- **AND** print a helpful hint listing available commands/flags and exit with code 1
+
+#### Scenario: Direct item validation
+
+- **WHEN** executing `openspec validate <item-name>`
+- **THEN** automatically detect if item is a change or spec
+- **AND** validate the specified item
+- **AND** display validation results
+
+### Requirement: Bulk and filtered validation
+
+The validate command SHALL support flags for bulk validation (--all) and filtered validation by type (--changes, --specs).
+
+#### Scenario: Validate everything
+
+- **WHEN** executing `openspec validate --all`
+- **THEN** validate all changes in openspec/changes/ (excluding archive)
+- **AND** validate all specs in openspec/specs/
+- **AND** display a summary showing passed/failed items
+- **AND** exit with code 1 if any validation fails
+
+#### Scenario: Scope of bulk validation
+
+- **WHEN** validating with `--all` or `--changes`
+- **THEN** include all change proposals under `openspec/changes/`
+- **AND** exclude the `openspec/changes/archive/` directory
+
+- **WHEN** validating with `--specs`
+- **THEN** include all specs that have a `spec.md` under `openspec/specs/<id>/spec.md`
+
+#### Scenario: Validate all changes
+
+- **WHEN** executing `openspec validate --changes`
+- **THEN** validate all changes in openspec/changes/ (excluding archive)
+- **AND** display results for each change
+- **AND** show summary statistics
+
+#### Scenario: Validate all specs
+
+- **WHEN** executing `openspec validate --specs`
+- **THEN** validate all specs in openspec/specs/
+- **AND** display results for each spec
+- **AND** show summary statistics
+
+### Requirement: Validation options and progress indication
+
+The validate command SHALL support standard validation options (--strict, --json) and display progress during bulk operations.
+
+#### Scenario: Strict validation
+
+- **WHEN** executing `openspec validate --all --strict`
+- **THEN** apply strict validation to all items
+- **AND** treat warnings as errors
+- **AND** fail if any item has warnings or errors
+
+#### Scenario: JSON output
+
+- **WHEN** executing `openspec validate --all --json`
+- **THEN** output validation results as JSON
+- **AND** include detailed issues for each item
+- **AND** include summary statistics
+
+#### Scenario: JSON output schema for bulk validation
+
+- **WHEN** executing `openspec validate --all --json` (or `--changes` / `--specs`)
+- **THEN** output a JSON object with the following shape:
+  - `items`: Array of objects with fields `{ id: string, type: "change"|"spec", valid: boolean, issues: Issue[], durationMs: number }`
+  - `summary`: Object `{ totals: { items: number, passed: number, failed: number }, byType: { change?: { items: number, passed: number, failed: number }, spec?: { items: number, passed: number, failed: number } } }`
+  - `version`: String identifier for the schema (e.g., `"1.0"`)
+- **AND** exit with code 1 if any `items[].valid === false`
+
+Where `Issue` follows the existing per-item validation report shape `{ level: "ERROR"|"WARNING"|"INFO", path: string, message: string }`.
+
+#### Scenario: Show validation progress
+
+- **WHEN** validating multiple items (--all, --changes, or --specs)
+- **THEN** show progress indicator or status updates
+- **AND** indicate which item is currently being validated
+- **AND** display running count of passed/failed items
+
+#### Scenario: Concurrency limits for performance
+
+- **WHEN** validating multiple items
+- **THEN** run validations with a bounded concurrency (e.g., 4–8 in parallel)
+- **AND** ensure progress indicators remain responsive
+
+### Requirement: Item type detection and ambiguity handling
+
+#### Scenario: Direct item validation with automatic type detection
+
+- **WHEN** executing `openspec validate <item-name>`
+- **THEN** if `<item-name>` uniquely matches a change or a spec, validate that item
+
+#### Scenario: Ambiguity between change and spec names
+
+- **GIVEN** `<item-name>` exists both as a change and as a spec
+- **WHEN** executing `openspec validate <item-name>`
+- **THEN** print an ambiguity error explaining both matches
+- **AND** suggest passing `--type change` or `--type spec`, or using `openspec change validate` / `openspec spec validate`
+- **AND** exit with code 1 without performing validation
+
+#### Scenario: Unknown item name
+
+- **WHEN** the `<item-name>` matches neither a change nor a spec
+- **THEN** print a not-found error
+- **AND** show nearest-match suggestions when available
+- **AND** exit with code 1
+
+#### Scenario: Explicit type override
+
+- **WHEN** executing `openspec validate --type change <item>`
+- **THEN** treat `<item>` as a change ID and validate it (skipping auto-detection)
+
+- **WHEN** executing `openspec validate --type spec <item>`
+- **THEN** treat `<item>` as a spec ID and validate it (skipping auto-detection)
+
+### Requirement: Interactivity controls
+
+- The CLI SHALL respect `--no-interactive` to disable prompts.
+- The CLI SHALL respect `OPEN_SPEC_INTERACTIVE=0` to disable prompts globally.
+- Interactive prompts SHALL only be shown when stdin is a TTY and interactivity is not disabled.

openspec/changes/bulk-validation-interactive-selection/tasks.md

@@ -0,0 +1,81 @@
+# Implementation Tasks
+
+## 1. Change Command: Interactive Validation Selection
+- [x] 1.1 Add `--no-interactive` flag to `change validate` in `src/cli/index.ts`
+- [x] 1.2 Implement interactivity gate respecting TTY and `OPEN_SPEC_INTERACTIVE=0` in `src/commands/change.ts`
+- [x] 1.3 When no `[change-name]` is provided and interactivity is allowed, prompt with a list of active changes (exclude `archive/`) and validate the selected one
+- [x] 1.4 Preserve current non-interactive fallback: print available change IDs and hint, set `process.exitCode = 1`
+- [x] 1.5 Tests: add coverage for interactive and non-interactive flows
+  - Added `test/commands/change.interactive-validate.test.ts`
+
+## 2. Spec Command: Interactive Validation Selection
+- [x] 2.1 Make `spec validate` accept optional `[spec-id]` in `src/commands/spec.ts` registration
+- [x] 2.2 Add `--no-interactive` flag to `spec validate`
+- [x] 2.3 Implement interactivity gate respecting TTY and `OPEN_SPEC_INTERACTIVE=0`
+- [x] 2.4 When no `[spec-id]` provided and interactivity allowed, prompt to select from `openspec/specs/*/spec.md` and validate the selected spec
+- [x] 2.5 Preserve current non-interactive fallback when no spec-id and no interactivity: print existing error and exit code non-zero
+- [x] 2.6 Tests: add coverage for interactive and non-interactive flows
+  - Added `test/commands/spec.interactive-validate.test.ts`
+
+## 3. New Top-level `validate` Command
+- [x] 3.1 Add `validate` command in `src/cli/index.ts`
+  - Options: `--all`, `--changes`, `--specs`, `--type <change|spec>`, `--strict`, `--json`, `--no-interactive`
+  - Usage: `openspec validate [item-name]`
+- [x] 3.2 Create `src/commands/validate.ts` implementing:
+  - [x] 3.2.1 Interactive selector when no args (choices: All, Changes, Specs, Specific item)
+  - [x] 3.2.2 Non-interactive fallback with helpful hint and exit code 1
+  - [x] 3.2.3 Direct item validation with automatic type detection
+  - [x] 3.2.4 Ambiguity error when name exists as both change and spec; suggest `--type` or subcommands
+  - [x] 3.2.5 Unknown item handling with nearest-match suggestions
+  - [x] 3.2.6 Bulk validation for `--all`, `--changes`, `--specs` (exclude `openspec/changes/archive/`)
+  - [x] 3.2.7 Respect `--strict` and `--json` options; JSON shape per spec
+  - [x] 3.2.8 Exit with code 1 if any validation fails
+  - [x] 3.2.9 Bounded concurrency (default 4–8) for bulk validation
+  - [x] 3.2.10 Progress indication during bulk runs (current item, running counts)
+
+## 4. Utilities and Shared Helpers
+- [x] 4.1 Add `src/utils/interactive.ts` with `isInteractive(stdin: NodeJS.ReadStream, noInteractiveFlag?: boolean): boolean`
+  - Considers: `process.stdin.isTTY`, `--no-interactive`, `OPEN_SPEC_INTERACTIVE=0`
+- [x] 4.2 Add `src/utils/item-discovery.ts` with:
+  - `getActiveChangeIds(root = process.cwd()): Promise<string[]>` (exclude `archive/`)
+  - `getSpecIds(root = process.cwd()): Promise<string[]>` (folders with `spec.md`)
+- [ ] 4.3 Optional: `src/utils/concurrency.ts` helper for bounded parallelism
+- [x] 4.4 Reuse `src/core/validation/validator.ts` for item validation
+
+## 5. JSON Output (Bulk Validation)
+- [x] 5.1 Implement JSON schema:
+  - `items: Array<{ id: string, type: "change"|"spec", valid: boolean, issues: Issue[], durationMs: number }>`
+  - `summary: { totals: { items: number, passed: number, failed: number }, byType: { change?: { items: number, passed: number, failed: number }, spec?: { items: number, passed: number, failed: number } } }`
+  - `version: "1.0"`
+- [x] 5.2 Ensure process exit code is 1 if any `items[].valid === false`
+- [x] 5.3 Tests for JSON shape (keys, types, counts) and exit code behavior
+  - Added `test/commands/validate.test.ts`
+
+## 6. Progress and UX
+- [x] 6.1 Use `ora` or minimal console progress to show current item and running counts
+- [x] 6.2 Keep output stable in `--json` mode (no extra logs to stdout; use stderr for progress if needed)
+- [x] 6.3 Ensure responsiveness with concurrency limits
+
+## 7. Tests
+- [x] 7.1 Add top-level validate tests: `test/commands/validate.test.ts`
+  - Includes non-interactive hint, --all JSON, --specs with concurrency, ambiguity error
+- [ ] 7.2 Add unit tests for `isInteractive` and item discovery helpers
+- [x] 7.3 Extend existing change/spec command tests to cover interactive `validate`
+  - Added `test/commands/change.interactive-validate.test.ts`, `test/commands/spec.interactive-validate.test.ts`
+
+## 8. CLI Help and Docs
+- [x] 8.1 Update command descriptions/options in `src/cli/index.ts`
+- [x] 8.2 Verify help output includes `validate` command and flags
+- [x] 8.3 Ensure existing specs under `openspec/changes/bulk-validation-interactive-selection/specs/*` remain satisfied
+
+## 9. Non-functional
+- [x] 9.1 Code style and types: explicit types for exported APIs; avoid `any`
+- [x] 9.2 No linter errors; stable formatting; avoid unrelated refactors
+- [x] 9.3 Maintain existing behavior for unaffected commands
+
+## 10. Acceptance Criteria Mapping
+- [x] AC-1: `openspec change validate` interactive selection when no arg (TTY only; respects `--no-interactive`/env) — matches cli-change spec
+- [x] AC-2: `openspec spec validate` interactive selection when no arg (TTY only; respects `--no-interactive`/env) — matches cli-spec spec
+- [x] AC-3: New `openspec validate` supports interactive selection, bulk/filtered validation, JSON schema, progress, concurrency, exit codes — matches cli-validate spec
+
+

openspec/changes/fix-update-tool-selection/proposal.md

@@ -0,0 +1,40 @@
+# Fix Update Command Tool Selection
+
+## Problem
+
+The `openspec update` command currently forces the creation/update of CLAUDE.md regardless of which AI tool was selected during initialization. This violates the tool-agnostic design principle and creates confusion for users who selected different AI assistants.
+
+Additionally, different team members may use different AI tools, so we cannot rely on a shared configuration file.
+
+## Solution
+
+Modify the update command to:
+1. Only update AI tool configuration files that already exist
+2. Never create new AI tool configuration files
+3. Always update the core OpenSpec files (README.md, etc.)
+
+## Implementation
+
+- Remove hardcoded CLAUDE.md update from update command
+- Implement file existence check before updating any AI tool config
+- Update each existing AI tool config file with its appropriate markers
+- No configuration file needed (avoids team conflicts)
+
+## Success Criteria
+
+- Update command only modifies existing AI tool configuration files
+- No new AI tool files created during update
+- Team members can use different AI tools without conflicts
+- Existing projects continue to work (backward compatibility)
+
+## Why
+
+Users need predictable, tool-agnostic behavior from `openspec update`. Creating or forcing updates for AI tool files that a project does not use causes confusion and merge conflicts. Restricting updates to existing files and always updating core OpenSpec files keeps the workflow consistent for mixed-tool teams.
+
+## What Changes
+
+- **cli-update:** Modify update behavior to update only existing AI tool configuration files and never create new ones; always update core OpenSpec files and display an ASCII-safe success message.
+
+## ADDED Requirements
+
+Removed from proposal to follow conventions. See `specs/cli-update/spec.md` for the delta requirements content.

openspec/changes/fix-update-tool-selection/specs/cli-update/spec.md

@@ -0,0 +1,23 @@
+## ADDED Requirements
+
+### Requirement: Tool-Agnostic Updates
+
+The update command SHALL update only existing AI tool configuration files and SHALL NOT create new ones.
+
+#### Scenario: Updating existing tool files
+
+- **WHEN** a user runs `openspec update`
+- **THEN** update each AI tool configuration file that exists (e.g., CLAUDE.md, COPILOT.md)
+- **AND** do not create missing tool configuration files
+- **AND** preserve user content outside OpenSpec markers
+
+### Requirement: Core Files Always Updated
+
+The update command SHALL always update the core OpenSpec files and display an ASCII-safe success message.
+
+#### Scenario: Successful update
+
+- **WHEN** the update completes successfully
+- **THEN** replace `openspec/README.md` with the latest template
+- **AND** update existing AI tool configuration files within markers
+- **AND** display the message: "Updated OpenSpec instructions"

openspec/changes/fix-update-tool-selection/tasks.md

@@ -0,0 +1,21 @@
+# Implementation Tasks
+
+## 1. Update Update Command
+- [x] Remove hardcoded CLAUDE.md update from `src/core/update.ts`
+- [x] Add logic to check for existing AI tool configuration files
+- [x] Update only existing files using their appropriate configurators
+- [x] Iterate through all registered configurators to check for existing files
+
+## 2. Update Configurator Registry
+- [x] Add method to get all configurators for update command
+- [x] Ensure each configurator can check if its file exists
+
+## 3. Add Tests
+- [x] Test update command with only CLAUDE.md present
+- [x] Test update command with no AI tool files present
+- [x] Test update command with multiple AI tool files present
+- [x] Test that update never creates new AI tool files
+
+## 4. Update Documentation
+- [x] Update README to clarify team-friendly behavior
+- [x] Document that update only modifies existing files

openspec/changes/structured-spec-format/proposal.md

@@ -0,0 +1,36 @@
+## Why
+
+OpenSpec specifications lack a consistent structure that makes sections visually identifiable and programmatically parseable across different specs. This makes it harder to maintain consistency and build tooling.
+
+## What Changes
+
+**Specification Format Section**
+- From: No formal structure requirements for specifications
+- To: Structured format with `### Requirement:` and `#### Scenario:` headers
+- Reason: Visual consistency and parseability across all specs
+- Impact: Non-breaking - existing specs can migrate gradually
+
+**Keyword Formatting**
+- From: Inconsistent use of WHEN/THEN/AND keywords
+- To: Bold keywords (**WHEN**, **THEN**, **AND**) in scenario bullets
+- Reason: Improved readability and consistent visual hierarchy
+- Impact: Non-breaking - formatting enhancement only
+
+**Format Flexibility**
+- From: Implicit understanding that different content needs different formats
+- To: Explicit allowance for alternative formats (OpenAPI, JSON Schema, etc.)
+- Reason: Address concern that not all specs fit requirement/scenario pattern
+- Impact: Non-breaking - clarifies existing practice
+
+**Migration Guidelines**
+- From: No migration guidance
+- To: Documented gradual migration approach
+- Reason: Allows incremental adoption without disrupting existing specs
+- Impact: Non-breaking - opt-in migration as specs are modified
+
+## Impact
+
+- Affected specs: openspec-conventions (enhancement to existing capability)
+- Affected code: None initially - this is a documentation standard enhancement
+- Migration: Gradual - existing specs migrate as they're modified
+- Tooling: Enables future parsing tools but doesn't require them

openspec/changes/structured-spec-format/specs/openspec-conventions/spec.md

@@ -0,0 +1,192 @@
+# OpenSpec Conventions Specification
+
+## ADDED Requirements
+
+### Requirement: Structured Format Adoption
+
+Behavioral specifications SHALL adopt the structured format with `### Requirement:` and `#### Scenario:` headers as the default.
+
+#### Scenario: Use structured headings for behavior
+
+- **WHEN** documenting behavioral requirements
+- **THEN** use `### Requirement:` for requirements
+- **AND** use `#### Scenario:` for scenarios with bold WHEN/THEN/AND keywords
+
+## Purpose
+
+OpenSpec conventions SHALL define how system capabilities are documented, how changes are proposed and tracked, and how specifications evolve over time. This meta-specification serves as the source of truth for OpenSpec's own conventions.
+
+## Core Principles
+
+The system SHALL follow these principles:
+- Specs reflect what IS currently built and deployed
+- Changes contain proposals for what SHOULD be changed
+- AI drives the documentation process
+- Specs are living documentation kept in sync with deployed code
+
+## Directory Structure
+
+WHEN an OpenSpec project is initialized
+THEN it SHALL have this structure:
+```
+openspec/
+├── project.md              # Project-specific context
+├── README.md               # AI assistant instructions
+├── specs/                  # Current deployed capabilities
+│   └── [capability]/       # Single, focused capability
+│       ├── spec.md         # WHAT and WHY
+│       └── design.md       # HOW (optional, for established patterns)
+└── changes/                # Proposed changes
+    ├── [change-name]/      # Descriptive change identifier
+    │   ├── proposal.md     # Why, what, and impact
+    │   ├── tasks.md        # Implementation checklist
+    │   ├── design.md       # Technical decisions (optional)
+    │   └── specs/          # Complete future state
+    │       └── [capability]/
+    │           └── spec.md # Clean markdown (no diff syntax)
+    └── archive/            # Completed changes
+        └── YYYY-MM-DD-[name]/
+```
+
+## Specification Format
+
+### Requirement: Structured Format for Behavioral Specs
+
+Behavioral specifications SHALL use a structured format with consistent section headers and keywords to ensure visual consistency and parseability.
+
+#### Scenario: Writing requirement sections
+
+- **WHEN** documenting a requirement in a behavioral specification
+- **THEN** use a level-3 heading with format `### Requirement: [Name]`
+- **AND** immediately follow with a SHALL statement describing core behavior
+- **AND** keep requirement names descriptive and under 50 characters
+
+#### Scenario: Documenting scenarios
+
+- **WHEN** documenting specific behaviors or use cases
+- **THEN** use level-4 headings with format `#### Scenario: [Description]`
+- **AND** use bullet points with bold keywords for steps:
+  - **GIVEN** for initial state (optional)
+  - **WHEN** for conditions or triggers
+  - **THEN** for expected outcomes
+  - **AND** for additional outcomes or conditions
+
+#### Scenario: Adding implementation details
+
+- **WHEN** a step requires additional detail
+- **THEN** use sub-bullets under the main step
+- **AND** maintain consistent indentation
+  - Sub-bullets provide examples or specifics
+  - Keep sub-bullets concise
+
+### Requirement: Format Flexibility
+
+The structured format SHALL be the default for behavioral specifications, but alternative formats MAY be used when more appropriate for the content type.
+
+#### Scenario: Documenting API specifications
+
+- **WHEN** documenting REST API endpoints or GraphQL schemas
+- **THEN** OpenAPI, GraphQL SDL, or similar formats MAY be used
+- **AND** the spec SHALL clearly indicate the format being used
+- **AND** behavioral aspects SHALL still follow the structured format
+
+#### Scenario: Documenting data schemas
+
+- **WHEN** documenting data structures, database schemas, or configurations
+- **THEN** JSON Schema, SQL DDL, or similar formats MAY be used
+- **AND** include the structured format for behavioral rules and constraints
+
+#### Scenario: Using simplified format
+
+- **WHEN** documenting simple capabilities without complex scenarios
+- **THEN** a simplified WHEN/THEN format without full structure MAY be used
+- **AND** this should be consistent within the capability
+
+## Change Storage Convention
+
+### Future State Storage
+
+WHEN creating a change proposal
+THEN store the complete future state of affected specs
+AND use clean markdown without diff syntax
+
+The `changes/[name]/specs/` directory SHALL contain:
+- Complete spec files as they will exist after the change
+- Clean markdown without `+` or `-` prefixes
+- All formatting and structure of the final intended state
+
+### Proposal Format
+
+WHEN documenting what changes
+THEN the proposal SHALL explicitly describe each change:
+
+```markdown
+**[Section or Behavior Name]**
+- From: [current state/requirement]
+- To: [future state/requirement]
+- Reason: [why this change is needed]
+- Impact: [breaking/non-breaking, who's affected]
+```
+
+This explicit format compensates for not having inline diffs and ensures reviewers understand exactly what will change.
+
+## Change Lifecycle
+
+The change process SHALL follow these states:
+
+1. **Propose**: AI creates change with future state specs and explicit proposal
+2. **Review**: Humans review proposal and future state
+3. **Approve**: Change is approved for implementation
+4. **Implement**: Follow tasks.md checklist (can span multiple PRs)
+5. **Deploy**: Changes are deployed to production
+6. **Update**: Specs in `specs/` are updated to match deployed reality
+7. **Archive**: Change is moved to `archive/YYYY-MM-DD-[name]/`
+
+## Viewing Changes
+
+WHEN reviewing proposed changes
+THEN reviewers can compare using:
+- GitHub PR diff view when changes are committed
+- Command line: `diff -u specs/[capability]/spec.md changes/[name]/specs/[capability]/spec.md`
+- Any visual diff tool comparing current vs future state
+
+The system relies on tools to generate diffs rather than storing them.
+
+## Capability Naming
+
+Capabilities SHALL use:
+- Verb-noun patterns (e.g., `user-auth`, `payment-capture`)
+- Hyphenated lowercase names
+- Singular focus (one responsibility per capability)
+- No nesting (flat structure under `specs/`)
+
+## When Changes Require Proposals
+
+A proposal SHALL be created for:
+- New features or capabilities
+- Breaking changes to existing behavior
+- Architecture or pattern changes
+- Performance optimizations that change behavior
+- Security updates affecting access patterns
+
+A proposal is NOT required for:
+- Bug fixes restoring intended behavior
+- Typos or formatting fixes
+- Non-breaking dependency updates
+- Adding tests for existing behavior
+- Documentation clarifications
+
+## Why This Approach
+
+Clean future state storage provides:
+- **Readability**: No diff syntax pollution
+- **AI-compatibility**: Standard markdown that AI tools understand
+- **Simplicity**: No special parsing or processing needed
+- **Tool-agnostic**: Any diff tool can show changes
+- **Clear intent**: Explicit proposals document reasoning
+
+The structured format adds:
+- **Visual Consistency**: Requirement and Scenario prefixes make sections instantly recognizable
+- **Parseability**: Consistent structure enables tooling and automation
+- **Flexibility**: Alternative formats supported where appropriate
+- **Gradual Adoption**: Existing specs can migrate incrementally

openspec/changes/structured-spec-format/tasks.md

@@ -0,0 +1,19 @@
+## 1. Update OpenSpec Conventions Spec
+
+- [x] 1.1 Add "Specification Format" section to openspec-conventions
+- [x] 1.2 Document structured format with Requirement/Scenario headers
+- [x] 1.3 Define bold keyword usage (WHEN/THEN/AND) for scenarios
+- [x] 1.4 Include examples demonstrating the format within the spec itself
+
+## 2. Update Documentation
+
+- [x] 2.1 Update the "Why This Approach" section with structured format benefits
+- [x] 2.2 Ensure spec follows its own format as a demonstration
+
+## 3. Update Existing Specs
+
+- [x] 3.1 Update cli-init spec to use structured format in Behavior section
+- [x] 3.2 Update cli-list spec to use structured format in Behavior section
+- [x] 3.3 Update cli-update spec to use structured format in Behavior section
+- [x] 3.4 Update cli-diff spec to use structured format in Behavior section
+- [x] 3.5 Update cli-archive spec to use structured format in Behavior section

openspec/specs/cli-archive/spec.md

@@ -0,0 +1,155 @@
+# CLI Archive Command Specification
+
+## Purpose
+The archive command moves completed changes from the active changes directory to the archive folder with date-based naming, following OpenSpec conventions.
+
+## Command Syntax
+```bash
+openspec archive [change-name] [--yes|-y]
+```
+
+Options:
+- `--yes`, `-y`: Skip confirmation prompts (for automation)
+
+## Requirements
+
+### Requirement: Change Selection
+
+The command SHALL support both interactive and direct change selection methods.
+
+#### Scenario: Interactive selection
+
+- **WHEN** no change-name is provided
+- **THEN** display interactive list of available changes (excluding archive/)
+- **AND** allow user to select one
+
+#### Scenario: Direct selection
+
+- **WHEN** change-name is provided
+- **THEN** use that change directly
+- **AND** validate it exists
+
+### Requirement: Task Completion Check
+
+The command SHALL verify task completion status before archiving to prevent premature archival.
+
+#### Scenario: Incomplete tasks found
+
+- **WHEN** incomplete tasks are found (marked with `- [ ]`)
+- **THEN** display all incomplete tasks to the user
+- **AND** prompt for confirmation to continue
+- **AND** default to "No" for safety
+
+#### Scenario: All tasks complete
+
+- **WHEN** all tasks are complete OR no tasks.md exists
+- **THEN** proceed with archiving without prompting
+
+### Requirement: Archive Process
+
+The archive operation SHALL follow a structured process to safely move changes to the archive.
+
+#### Scenario: Performing archive
+
+- **WHEN** archiving a change
+- **THEN** execute these steps:
+  1. Create archive/ directory if it doesn't exist
+  2. Generate target name as `YYYY-MM-DD-[change-name]` using current date
+  3. Check if target directory already exists
+  4. Update main specs from the change's future state specs (see Spec Update Process below)
+  5. Move the entire change directory to the archive location
+
+#### Scenario: Archive already exists
+
+- **WHEN** target archive already exists
+- **THEN** fail with error message
+- **AND** do not overwrite existing archive
+
+#### Scenario: Successful archive
+
+- **WHEN** move succeeds
+- **THEN** display success message with archived name and list of updated specs
+
+### Requirement: Spec Update Process
+
+Before moving the change to archive, the command SHALL update main specs to reflect the deployed reality.
+
+#### Scenario: Updating specs from change
+
+- **WHEN** the change contains specs in `changes/[name]/specs/`
+- **THEN** execute these steps:
+  1. Analyze which specs will be affected by comparing with existing specs
+  2. Display a summary of spec updates to the user (see Confirmation Behavior below)
+  3. Prompt for confirmation unless `--yes` flag is provided
+  4. If confirmed, for each capability spec in the change directory:
+     - Copy the spec from `changes/[name]/specs/[capability]/spec.md` to `openspec/specs/[capability]/spec.md`
+     - Create the target directory structure if it doesn't exist
+     - Overwrite existing spec files (specs represent current reality, change specs are the new reality)
+     - Track which specs were updated for the success message
+
+#### Scenario: No specs in change
+
+- **WHEN** no specs exist in the change
+- **THEN** skip the spec update step
+- **AND** proceed with archiving
+
+### Requirement: Confirmation Behavior
+
+The spec update confirmation SHALL provide clear visibility into changes before they are applied.
+
+#### Scenario: Displaying confirmation
+
+- **WHEN** prompting for confirmation
+- **THEN** display a clear summary showing:
+  - Which specs will be created (new capabilities)
+  - Which specs will be updated (existing capabilities)
+  - The source path for each spec
+- **AND** format the confirmation prompt as:
+  ```
+  The following specs will be updated:
+  
+  NEW specs to be created:
+    - cli-archive (from changes/add-archive-command/specs/cli-archive/spec.md)
+  
+  EXISTING specs to be updated:
+    - cli-init (from changes/update-init-command/specs/cli-init/spec.md)
+  
+  Update 2 specs and archive 'add-archive-command'? [y/N]:
+  ```
+#### Scenario: Handling confirmation response
+
+- **WHEN** waiting for user confirmation
+- **THEN** default to "No" for safety (require explicit "y" or "yes")
+- **AND** skip confirmation when `--yes` or `-y` flag is provided
+
+#### Scenario: User declines confirmation
+
+- **WHEN** user declines the confirmation
+- **THEN** abort the entire archive operation
+- **AND** display message: "Archive cancelled. No changes were made."
+- **AND** exit with non-zero status code
+
+## Error Handling
+
+### Requirement: Error Conditions
+
+The command SHALL handle various error conditions gracefully.
+
+#### Scenario: Handling errors
+
+- **WHEN** errors occur
+- **THEN** handle the following conditions:
+  - Missing openspec/changes/ directory
+  - Change not found
+  - Archive target already exists
+  - File system permissions issues
+
+## Why These Decisions
+
+**Interactive selection**: Reduces typing and helps users see available changes
+**Task checking**: Prevents accidental archiving of incomplete work
+**Date prefixing**: Maintains chronological order and prevents naming conflicts
+**No overwrite**: Preserves historical archives and prevents data loss
+**Spec updates before archiving**: Specs in the main directory represent current reality; when a change is deployed and archived, its future state specs become the new reality and must replace the main specs
+**Confirmation for spec updates**: Provides visibility into what will change, prevents accidental overwrites, and ensures users understand the impact before specs are modified
+**--yes flag for automation**: Allows CI/CD pipelines to archive without interactive prompts while maintaining safety by default for manual use

openspec/specs/cli-diff/spec.md

@@ -0,0 +1,120 @@
+# CLI Diff Command Specification
+
+## Purpose
+
+The `openspec diff` command provides developers with a visual comparison between proposed spec changes and the current deployed specs.
+
+## Command Syntax
+
+```bash
+openspec diff [change-name]
+```
+
+## Requirements
+
+### Requirement: Without Arguments
+
+The command SHALL provide an interactive selection when no change is specified.
+
+#### Scenario: Running without arguments
+
+- **WHEN** running `openspec diff` without arguments
+- **THEN** list all available changes in the `changes/` directory (excluding archive)
+- **AND** prompt user to select a change
+
+### Requirement: With Change Name
+
+The command SHALL compare specs when a specific change is provided.
+
+#### Scenario: Running with change name
+
+- **WHEN** running `openspec diff <change-name>`
+- **THEN** compare all spec files in `changes/<change-name>/specs/` with corresponding files in `specs/`
+
+### Requirement: Diff Output
+
+The command SHALL generate appropriate diff output for all spec changes.
+
+#### Scenario: Comparing existing files
+
+- **WHEN** file exists in both locations
+- **THEN** show unified diff
+
+#### Scenario: New files
+
+- **WHEN** file only exists in change
+- **THEN** show as new file (all lines with +)
+
+#### Scenario: Deleted files
+
+- **WHEN** file only exists in current specs
+- **THEN** show as deleted (all lines with -)
+
+### Requirement: Display Format
+
+The command SHALL use standard unified diff format for consistency with existing tools.
+
+#### Scenario: Formatting diff output
+
+- **WHEN** displaying diff output
+- **THEN** use standard unified diff format:
+  - Lines prefixed with `-` for removed content
+  - Lines prefixed with `+` for added content
+  - Lines without prefix for unchanged context
+  - File headers showing the paths being compared
+
+### Requirement: Color Support
+
+The command SHALL enhance readability with colors when supported.
+
+#### Scenario: Terminal with color support
+
+- **WHEN** terminal supports colors
+- **THEN** display:
+  - Removed lines in red
+  - Added lines in green
+  - File headers in bold
+  - Context lines in default color
+
+### Requirement: Error Handling
+
+The command SHALL provide clear error messages for various failure conditions.
+
+#### Scenario: Change not found
+
+- **WHEN** specified change doesn't exist
+- **THEN** display error "Change '<name>' not found"
+
+#### Scenario: No specs in change
+
+- **WHEN** no specs directory in change
+- **THEN** display "No spec changes found for '<name>'"
+
+#### Scenario: Missing changes directory
+
+- **WHEN** changes directory doesn't exist
+- **THEN** display "No OpenSpec changes directory found"
+
+## Examples
+
+```bash
+# View diff for specific change
+$ openspec diff add-auth-feature
+
+--- specs/user-auth/spec.md
++++ changes/add-auth-feature/specs/user-auth/spec.md
+@@ -10,6 +10,8 @@
+ Users SHALL authenticate with email and password.
+ 
++Users MAY authenticate with OAuth providers.
++
+ WHEN credentials are valid THEN issue JWT token.
+
+# List all changes and select
+$ openspec diff
+Available changes:
+  1. add-auth-feature
+  2. update-payment-flow
+  3. add-status-command
+Select a change (1-3): 
+```

openspec/specs/cli-init/spec.md

@@ -4,22 +4,30 @@
 
 The `openspec init` command SHALL create a complete OpenSpec directory structure in any project, enabling immediate adoption of OpenSpec conventions with support for multiple AI coding assistants.
 
-## Behavior
+## Requirements
 
-### Progress Indicators
+### Requirement: Progress Indicators
 
-WHEN executing initialization steps
-THEN validate environment silently in background (no output unless error)
-AND display progress with ora spinners:
-- Show spinner: "⠋ Creating OpenSpec structure..."
-- Then success: "✔ OpenSpec structure created"
-- Show spinner: "⠋ Configuring AI tools..."
-- Then success: "✔ AI tools configured"
+The command SHALL display progress indicators during initialization to provide clear feedback about each step.
 
-### Directory Creation
+#### Scenario: Displaying initialization progress
 
-WHEN `openspec init` is executed
-THEN create the following directory structure:
+- **WHEN** executing initialization steps
+- **THEN** validate environment silently in background (no output unless error)
+- **AND** display progress with ora spinners:
+  - Show spinner: "⠋ Creating OpenSpec structure..."
+  - Then success: "✔ OpenSpec structure created"
+  - Show spinner: "⠋ Configuring AI tools..."
+  - Then success: "✔ AI tools configured"
+
+### Requirement: Directory Creation
+
+The command SHALL create the complete OpenSpec directory structure with all required directories and files.
+
+#### Scenario: Creating OpenSpec structure
+
+- **WHEN** `openspec init` is executed
+- **THEN** create the following directory structure:
 ```
 openspec/
 ├── project.md
@@ -29,27 +37,41 @@ openspec/
     └── archive/
 ```
 
-### File Generation
+### Requirement: File Generation
 
-The command SHALL generate:
-- `README.md` containing complete OpenSpec instructions for AI assistants
-- `project.md` with project context template
+The command SHALL generate required template files with appropriate content for immediate use.
 
-### AI Tool Configuration
+#### Scenario: Generating template files
 
-WHEN run interactively
-THEN prompt user to select AI tools to configure:
-- Claude Code (updates/creates CLAUDE.md with OpenSpec markers)
-- Cursor (future)
-- Aider (future)
+- **WHEN** initializing OpenSpec
+- **THEN** generate `README.md` containing complete OpenSpec instructions for AI assistants
+- **AND** generate `project.md` with project context template
 
-### AI Tool Configuration Details
+### Requirement: AI Tool Configuration
 
-WHEN Claude Code is selected
-THEN create or update `CLAUDE.md` in the project root directory (not inside openspec/)
+The command SHALL configure AI coding assistants with OpenSpec instructions based on user selection.
 
-WHEN CLAUDE.md does not exist
-THEN create new file with OpenSpec content wrapped in markers:
+#### Scenario: Prompting for AI tool selection
+
+- **WHEN** run interactively
+- **THEN** prompt user to select AI tools to configure:
+  - Claude Code (updates/creates CLAUDE.md with OpenSpec markers)
+  - Cursor (future)
+  - Aider (future)
+
+### Requirement: AI Tool Configuration Details
+
+The command SHALL properly configure selected AI tools with OpenSpec-specific instructions using a marker system.
+
+#### Scenario: Configuring Claude Code
+
+- **WHEN** Claude Code is selected
+- **THEN** create or update `CLAUDE.md` in the project root directory (not inside openspec/)
+
+#### Scenario: Creating new CLAUDE.md
+
+- **WHEN** CLAUDE.md does not exist
+- **THEN** create new file with OpenSpec content wrapped in markers:
 ```markdown
 <!-- OPENSPEC:START -->
 # OpenSpec Project
@@ -62,51 +84,71 @@ See @openspec/README.md for detailed conventions and guidelines.
 <!-- OPENSPEC:END -->
 ```
 
-WHEN CLAUDE.md already exists
-THEN preserve all existing content
-AND insert OpenSpec content at the beginning of the file using markers
-AND ensure markers don't duplicate if they already exist
+#### Scenario: Updating existing CLAUDE.md
 
-The marker system SHALL:
-- Use `<!-- OPENSPEC:START -->` to mark the beginning of managed content
-- Use `<!-- OPENSPEC:END -->` to mark the end of managed content
-- Allow OpenSpec to update its content without affecting user customizations
-- Preserve all content outside the markers intact
+- **WHEN** CLAUDE.md already exists
+- **THEN** preserve all existing content
+- **AND** insert OpenSpec content at the beginning of the file using markers
+- **AND** ensure markers don't duplicate if they already exist
+
+#### Scenario: Managing content with markers
+
+- **WHEN** using the marker system
+- **THEN** use `<!-- OPENSPEC:START -->` to mark the beginning of managed content
+- **AND** use `<!-- OPENSPEC:END -->` to mark the end of managed content
+- **AND** allow OpenSpec to update its content without affecting user customizations
+- **AND** preserve all content outside the markers intact
 
 WHY use markers:
 - Users may have existing CLAUDE.md instructions they want to keep
 - OpenSpec can update its instructions in future versions
 - Clear boundary between OpenSpec-managed and user-managed content
 
-### Interactive Mode
+### Requirement: Interactive Mode
 
-WHEN run
-THEN prompt user with: "Which AI tool do you use?"
-AND show single-select menu with available tools:
-- Claude Code
-AND show disabled options as "coming soon" (not selectable):
-- Cursor (coming soon)
-- Aider (coming soon)  
-- Continue (coming soon)
+The command SHALL provide an interactive menu for AI tool selection with clear navigation instructions.
 
-User navigation:
-- Use arrow keys to move between options
-- Press Enter to select the highlighted option
+#### Scenario: Displaying interactive menu
 
-### Safety Checks
+- **WHEN** run
+- **THEN** prompt user with: "Which AI tool do you use?"
+- **AND** show single-select menu with available tools:
+  - Claude Code
+- **AND** show disabled options as "coming soon" (not selectable):
+  - Cursor (coming soon)
+  - Aider (coming soon)  
+  - Continue (coming soon)
 
-WHEN `openspec/` directory already exists
-THEN display error with ora fail indicator:
-"✖ Error: OpenSpec seems to already be initialized. Use 'openspec update' to update the structure."
+#### Scenario: Navigating the menu
 
-WHEN checking initialization feasibility
-THEN verify write permissions in the target directory silently
-AND only display error if permissions are insufficient
+- **WHEN** user is in the menu
+- **THEN** allow arrow keys to move between options
+- **AND** allow Enter key to select the highlighted option
 
-### Success Output
+### Requirement: Safety Checks
 
-WHEN initialization completes successfully
-THEN display actionable prompts for AI-driven workflow:
+The command SHALL perform safety checks to prevent overwriting existing structures and ensure proper permissions.
+
+#### Scenario: Detecting existing initialization
+
+- **WHEN** `openspec/` directory already exists
+- **THEN** display error with ora fail indicator:
+  - "✖ Error: OpenSpec seems to already be initialized. Use 'openspec update' to update the structure."
+
+#### Scenario: Checking write permissions
+
+- **WHEN** checking initialization feasibility
+- **THEN** verify write permissions in the target directory silently
+- **AND** only display error if permissions are insufficient
+
+### Requirement: Success Output
+
+The command SHALL provide clear, actionable next steps upon successful initialization.
+
+#### Scenario: Displaying success message
+
+- **WHEN** initialization completes successfully
+- **THEN** display actionable prompts for AI-driven workflow:
 ```
 ✔ OpenSpec initialized successfully!
 
@@ -132,12 +174,18 @@ The prompts SHALL:
 - Guide users through the AI-driven workflow
 - Replace placeholder text ([YOUR FEATURE HERE]) with actual features
 
-### Exit Codes
+### Requirement: Exit Codes
 
-- 0: Success
-- 1: General error (including when OpenSpec directory already exists)
-- 2: Insufficient permissions (reserved for future use)
-- 3: User cancelled operation (reserved for future use)
+The command SHALL use consistent exit codes to indicate different failure modes.
+
+#### Scenario: Returning exit codes
+
+- **WHEN** the command completes
+- **THEN** return appropriate exit code:
+  - 0: Success
+  - 1: General error (including when OpenSpec directory already exists)
+  - 2: Insufficient permissions (reserved for future use)
+  - 3: User cancelled operation (reserved for future use)
 
 ## Why
 

openspec/specs/cli-list/spec.md

@@ -0,0 +1,96 @@
+# List Command Specification
+
+## Purpose
+
+The `openspec list` command SHALL provide developers with a quick overview of all active changes in the project, showing their names and task completion status.
+
+## Requirements
+
+### Requirement: Command Execution
+
+The command SHALL scan and analyze all active changes to provide a comprehensive overview.
+
+#### Scenario: Scanning for changes
+
+- **WHEN** `openspec list` is executed
+- **THEN** scan the `openspec/changes/` directory for change directories
+- **AND** exclude the `archive/` subdirectory from results
+- **AND** parse each change's `tasks.md` file to count task completion
+
+### Requirement: Task Counting
+
+The command SHALL accurately count task completion status using standard markdown checkbox patterns.
+
+#### Scenario: Counting tasks in tasks.md
+
+- **WHEN** parsing a `tasks.md` file
+- **THEN** count tasks matching these patterns:
+  - Completed: Lines containing `- [x]`
+  - Incomplete: Lines containing `- [ ]`
+- **AND** calculate total tasks as the sum of completed and incomplete
+
+### Requirement: Output Format
+
+The command SHALL display changes in a clear, readable table format with progress indicators.
+
+#### Scenario: Displaying change list
+
+- **WHEN** displaying the list
+- **THEN** show a table with columns:
+  - Change name (directory name)
+  - Task progress (e.g., "3/5 tasks" or "✓ Complete")
+- **AND** use status indicators:
+  - `✓` for fully completed changes (all tasks done)
+  - Progress fraction for partial completion
+
+Example output:
+```
+Changes:
+  add-auth-feature     3/5 tasks
+  update-api-docs      ✓ Complete
+  fix-validation       0/2 tasks
+  add-list-command     1/4 tasks
+```
+
+### Requirement: Empty State
+
+The command SHALL provide clear feedback when no active changes are present.
+
+#### Scenario: Handling empty state
+
+- **WHEN** no active changes exist (only archive/ or empty changes/)
+- **THEN** display: "No active changes found."
+
+### Requirement: Error Handling
+
+The command SHALL gracefully handle missing files and directories with appropriate messages.
+
+#### Scenario: Missing tasks.md file
+
+- **WHEN** a change directory has no `tasks.md` file
+- **THEN** display the change with "No tasks" status
+
+#### Scenario: Missing changes directory
+
+- **WHEN** `openspec/changes/` directory doesn't exist
+- **THEN** display error: "No OpenSpec changes directory found. Run 'openspec init' first."
+- **AND** exit with code 1
+
+### Requirement: Sorting
+
+The command SHALL maintain consistent ordering of changes for predictable output.
+
+#### Scenario: Ordering changes
+
+- **WHEN** displaying multiple changes
+- **THEN** sort them in alphabetical order by change name
+
+## Why
+
+Developers need a quick way to:
+- See what changes are in progress
+- Identify which changes are ready to archive
+- Understand the overall project evolution status
+- Get a bird's-eye view without opening multiple files
+
+This command provides that visibility with minimal effort, following OpenSpec's philosophy of simplicity and clarity.

openspec/specs/cli-update/spec.md

@@ -6,45 +6,70 @@ As a developer using OpenSpec, I want to update the OpenSpec instructions in my
 
 ## Core Requirements
 
-### Update Behavior
+### Requirement: Update Behavior
 
-The update command SHALL update OpenSpec instruction files to the latest templates.
+The update command SHALL update OpenSpec instruction files to the latest templates in a team-friendly manner.
 
-WHEN a user runs `openspec update` THEN the command SHALL:
-- Check if the `openspec` directory exists
-- Replace `openspec/README.md` with the latest template (complete replacement)
-- Update the OpenSpec-managed block in `CLAUDE.md` using markers
-  - Preserve user content outside markers
-  - Create `CLAUDE.md` if missing
-- Display ASCII-safe success message: "Updated OpenSpec instructions"
+#### Scenario: Running update command
 
-### Prerequisites
+- **WHEN** a user runs `openspec update`
+- **THEN** the command SHALL:
+  - Check if the `openspec` directory exists
+  - Replace `openspec/README.md` with the latest template (complete replacement)
+  - Update **only existing** AI tool configuration files (e.g., CLAUDE.md)
+    - Check each registered AI tool configurator
+    - For each configurator, check if its file exists
+    - Update only files that already exist using their markers
+    - Preserve user content outside markers
+    - **Never create new AI tool configuration files**
+  - Display success message listing updated files
 
-The command SHALL require:
-- An existing `openspec` directory (created by `openspec init`)
+### Requirement: Prerequisites
 
-IF the `openspec` directory does not exist THEN:
-- Display error: "No OpenSpec directory found. Run 'openspec init' first."
-- Exit with code 1
+The command SHALL require an existing OpenSpec structure before allowing updates.
 
-### File Handling
+#### Scenario: Checking prerequisites
 
-The update command SHALL:
-- Completely replace `openspec/README.md` with the latest template
-- Update only the OpenSpec-managed block in `CLAUDE.md` using markers
-- Use the default directory name `openspec`
-- Be idempotent (repeated runs have no additional effect)
+- **GIVEN** the command requires an existing `openspec` directory (created by `openspec init`)
+- **WHEN** the `openspec` directory does not exist
+- **THEN** display error: "No OpenSpec directory found. Run 'openspec init' first."
+- **AND** exit with code 1
+
+### Requirement: File Handling
+
+The update command SHALL handle file updates in a predictable and safe manner.
+
+#### Scenario: Updating files
+
+- **WHEN** updating files
+- **THEN** completely replace `openspec/README.md` with the latest template
+- **AND** update only the OpenSpec-managed blocks in **existing** AI tool files using markers
+- **AND** use the default directory name `openspec`
+- **AND** be idempotent (repeated runs have no additional effect)
+- **AND** respect team members' AI tool choices by not creating unwanted files
 
 ## Edge Cases
 
-### File Permissions
-IF file write fails THEN let the error bubble up naturally with file path.
+### Requirement: Error Handling
 
-### Missing CLAUDE.md
-IF CLAUDE.md doesn't exist THEN create it with the template content.
+The command SHALL handle edge cases gracefully.
 
-### Custom Directory Name
-Not supported in this change. The default directory name `openspec` SHALL be used.
+#### Scenario: File permission errors
+
+- **WHEN** file write fails
+- **THEN** let the error bubble up naturally with file path
+
+#### Scenario: Missing AI tool files
+
+- **WHEN** an AI tool configuration file doesn't exist
+- **THEN** skip updating that file
+- **AND** do not create it
+
+#### Scenario: Custom directory names
+
+- **WHEN** considering custom directory names
+- **THEN** not supported in this change
+- **AND** the default directory name `openspec` SHALL be used
 
 ## Success Criteria
 

openspec/specs/openspec-conventions/spec.md

@@ -14,8 +14,14 @@ The system SHALL follow these principles:
 
 ## Directory Structure
 
-WHEN an OpenSpec project is initialized
-THEN it SHALL have this structure:
+### Requirement: Project Structure
+
+An OpenSpec project SHALL maintain a consistent directory structure for specifications and changes.
+
+#### Scenario: Initializing project structure
+
+- **WHEN** an OpenSpec project is initialized
+- **THEN** it SHALL have this structure:
 ```
 openspec/
 ├── project.md              # Project-specific context
@@ -36,23 +42,144 @@ openspec/
         └── YYYY-MM-DD-[name]/
 ```
 
+## Specification Format
+
+### Requirement: Structured Format for Behavioral Specs
+
+Behavioral specifications SHALL use a structured format with consistent section headers and keywords to ensure visual consistency and parseability.
+
+#### Scenario: Writing requirement sections
+
+- **WHEN** documenting a requirement in a behavioral specification
+- **THEN** use a level-3 heading with format `### Requirement: [Name]`
+- **AND** immediately follow with a SHALL statement describing core behavior
+- **AND** keep requirement names descriptive and under 50 characters
+
+#### Scenario: Documenting scenarios
+
+- **WHEN** documenting specific behaviors or use cases
+- **THEN** use level-4 headings with format `#### Scenario: [Description]`
+- **AND** use bullet points with bold keywords for steps:
+  - **GIVEN** for initial state (optional)
+  - **WHEN** for conditions or triggers
+  - **THEN** for expected outcomes
+  - **AND** for additional outcomes or conditions
+
+#### Scenario: Adding implementation details
+
+- **WHEN** a step requires additional detail
+- **THEN** use sub-bullets under the main step
+- **AND** maintain consistent indentation
+  - Sub-bullets provide examples or specifics
+  - Keep sub-bullets concise
+
+
 ## Change Storage Convention
 
-### Future State Storage
+### Requirement: Header-Based Requirement Identification
+
+Requirement headers SHALL serve as unique identifiers for programmatic matching between current specs and proposed changes.
+
+#### Scenario: Matching requirements programmatically
+
+- **WHEN** processing delta changes
+- **THEN** use the `### Requirement: [Name]` header as the unique identifier
+- **AND** match using normalized headers: `normalize(header) = trim(header)`
+- **AND** compare headers with case-sensitive equality after normalization
+
+#### Scenario: Handling requirement renames
+
+- **WHEN** renaming a requirement
+- **THEN** use a special `## RENAMED Requirements` section
+- **AND** specify both old and new names explicitly:
+  ```markdown
+  ## RENAMED Requirements
+  - FROM: `### Requirement: Old Name`
+  - TO: `### Requirement: New Name`
+  ```
+- **AND** if content also changes, include under MODIFIED using the NEW header
+
+#### Scenario: Validating header uniqueness
+
+- **WHEN** creating or modifying requirements
+- **THEN** ensure no duplicate headers exist within a spec
+- **AND** validation tools SHALL flag duplicate headers as errors
+
+### Requirement: Change Storage Convention
+
+Change proposals SHALL store only the additions, modifications, and removals to specifications, not complete future states.
+
+#### Scenario: Creating change proposals with additions
+
+- **WHEN** creating a change proposal that adds new requirements
+- **THEN** include only the new requirements under `## ADDED Requirements`
+- **AND** each requirement SHALL include its complete content
+- **AND** use the standard structured format for requirements and scenarios
+
+#### Scenario: Creating change proposals with modifications  
+
+- **WHEN** creating a change proposal that modifies existing requirements
+- **THEN** include the modified requirements under `## MODIFIED Requirements`
+- **AND** use the same header text as in the current spec (normalized)
+- **AND** include the complete modified requirement (not a diff)
+- **AND** optionally annotate what changed with inline comments like `← (was X)`
+
+#### Scenario: Creating change proposals with removals
+
+- **WHEN** creating a change proposal that removes requirements
+- **THEN** list them under `## REMOVED Requirements`
+- **AND** use the normalized header text for identification
+- **AND** include reason for removal
+- **AND** document any migration path if applicable
 
-WHEN creating a change proposal
-THEN store the complete future state of affected specs
-AND use clean markdown without diff syntax
 
 The `changes/[name]/specs/` directory SHALL contain:
-- Complete spec files as they will exist after the change
-- Clean markdown without `+` or `-` prefixes
-- All formatting and structure of the final intended state
+- Delta files showing only what changes
+- Sections for ADDED, MODIFIED, REMOVED, and RENAMED requirements
+- Normalized header matching for requirement identification
+- Complete requirements using the structured format
+- Clear indication of change type for each requirement
 
-### Proposal Format
+#### Scenario: Using standard output symbols
 
-WHEN documenting what changes
-THEN the proposal SHALL explicitly describe each change:
+- **WHEN** displaying delta operations in CLI output
+- **THEN** use these standard symbols:
+  - `+` for ADDED (green)
+  - `~` for MODIFIED (yellow)
+  - `-` for REMOVED (red)
+  - `→` for RENAMED (cyan)
+
+### Requirement: Archive Process Enhancement
+
+The archive process SHALL programmatically apply delta changes to current specifications using header-based matching.
+
+#### Scenario: Archiving changes with deltas
+
+- **WHEN** archiving a completed change
+- **THEN** the archive command SHALL:
+  1. Parse RENAMED sections first and apply renames
+  2. Parse REMOVED sections and remove by normalized header match
+  3. Parse MODIFIED sections and replace by normalized header match (using new names if renamed)
+  4. Parse ADDED sections and append new requirements
+- **AND** validate that all MODIFIED/REMOVED headers exist in current spec
+- **AND** validate that ADDED headers don't already exist
+- **AND** generate the updated spec in the main specs/ directory
+
+#### Scenario: Handling conflicts during archive
+
+- **WHEN** delta changes conflict with current spec state
+- **THEN** the archive command SHALL report specific conflicts
+- **AND** require manual resolution before proceeding
+- **AND** provide clear guidance on resolving conflicts
+
+### Requirement: Proposal Format
+
+Proposals SHALL explicitly document all changes with clear from/to comparisons.
+
+#### Scenario: Documenting changes
+
+- **WHEN** documenting what changes
+- **THEN** the proposal SHALL explicitly describe each change:
 
 ```markdown
 **[Section or Behavior Name]**
@@ -78,8 +205,14 @@ The change process SHALL follow these states:
 
 ## Viewing Changes
 
-WHEN reviewing proposed changes
-THEN reviewers can compare using:
+### Requirement: Change Review
+
+The system SHALL support multiple methods for reviewing proposed changes.
+
+#### Scenario: Reviewing changes
+
+- **WHEN** reviewing proposed changes
+- **THEN** reviewers can compare using:
 - GitHub PR diff view when changes are committed
 - Command line: `diff -u specs/[capability]/spec.md changes/[name]/specs/[capability]/spec.md`
 - Any visual diff tool comparing current vs future state
@@ -117,4 +250,9 @@ Clean future state storage provides:
 - **AI-compatibility**: Standard markdown that AI tools understand
 - **Simplicity**: No special parsing or processing needed
 - **Tool-agnostic**: Any diff tool can show changes
-- **Clear intent**: Explicit proposals document reasoning
+- **Clear intent**: Explicit proposals document reasoning
+
+The structured format adds:
+- **Visual Consistency**: Requirement and Scenario prefixes make sections instantly recognizable
+- **Parseability**: Consistent structure enables tooling and automation
+- **Gradual Adoption**: Existing specs can migrate incrementally

package.json

@@ -37,7 +37,8 @@
     "build": "node build.js",
     "dev": "tsc --watch",
     "dev:cli": "pnpm build && node bin/openspec.js",
-    "test": "vitest",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "test:ui": "vitest --ui",
     "test:coverage": "vitest --coverage",
     "prepare": "npm run build"
@@ -56,6 +57,7 @@
     "chalk": "^5.5.0",
     "commander": "^14.0.0",
     "jest-diff": "^30.0.5",
-    "ora": "^8.2.0"
+    "ora": "^8.2.0",
+    "zod": "^4.0.17"
   }
 }

pnpm-lock.yaml

@@ -23,6 +23,9 @@ importers:
       ora:
         specifier: ^8.2.0
         version: 8.2.0
+      zod:
+        specifier: ^4.0.17
+        version: 4.0.17
     devDependencies:
       '@types/node':
         specifier: ^24.2.0
@@ -900,6 +903,9 @@ packages:
     resolution: {integrity: sha512-cYVsTjKl8b+FrnidjibDWskAv7UKOfcwaVZdp/it9n1s9fU3IkgDbhdIRKCW4JDsAlECJY0ytoVPT3sK6kideA==}
     engines: {node: '>=18'}
 
+  zod@4.0.17:
+    resolution: {integrity: sha512-1PHjlYRevNxxdy2JZ8JcNAw7rX8V9P1AKkP+x/xZfxB0K5FYfuV+Ug6P/6NVSR2jHQ+FzDDoDHS04nYUsOIyLQ==}
+
 snapshots:
 
   '@esbuild/aix-ppc64@0.25.8':
@@ -1631,3 +1637,5 @@ snapshots:
       strip-ansi: 6.0.1
 
   yoctocolors-cjs@2.1.2: {}
+
+  zod@4.0.17: {}

src/cli/index.ts

@@ -5,6 +5,11 @@ import { promises as fs } from 'fs';
 import { InitCommand } from '../core/init.js';
 import { UpdateCommand } from '../core/update.js';
 import { DiffCommand } from '../core/diff.js';
+import { ListCommand } from '../core/list.js';
+import { ArchiveCommand } from '../core/archive.js';
+import { registerSpecCommand } from '../commands/spec.js';
+import { ChangeCommand } from '../commands/change.js';
+import { ValidateCommand } from '../commands/validate.js';
 
 const program = new Command();
 
@@ -13,6 +18,17 @@ program
   .description('AI-native system for spec-driven development')
   .version('0.0.1');
 
+// Global options
+program.option('--no-color', 'Disable color output');
+
+// Apply global flags before any command runs
+program.hook('preAction', (thisCommand) => {
+  const opts = thisCommand.opts();
+  if (opts.noColor) {
+    process.env.NO_COLOR = '1';
+  }
+});
+
 program
   .command('init [path]')
   .description('Initialize OpenSpec in your project')
@@ -63,7 +79,7 @@ program
 
 program
   .command('diff [change-name]')
-  .description('Show differences between proposed spec changes and current specs')
+  .description('Show differences between proposed spec changes and current specs (includes validation warnings)')
   .action(async (changeName?: string) => {
     try {
       const diffCommand = new DiffCommand();
@@ -75,4 +91,113 @@ program
     }
   });
 
+program
+  .command('list')
+  .description('List all active changes with their task status (DEPRECATED: use "openspec change list" instead)')
+  .action(async () => {
+    try {
+      console.log('\x1b[33m%s\x1b[0m', 'Warning: The "openspec list" command is deprecated. Please use "openspec change list" instead.\n');
+      const listCommand = new ListCommand();
+      await listCommand.execute();
+    } catch (error) {
+      console.log(); // Empty line for spacing
+      ora().fail(`Error: ${(error as Error).message}`);
+      process.exit(1);
+    }
+  });
+
+// Change command with subcommands
+const changeCmd = program
+  .command('change')
+  .description('Manage OpenSpec change proposals');
+
+changeCmd
+  .command('show [change-name]')
+  .description('Show a change proposal in JSON or markdown format')
+  .option('--json', 'Output as JSON')
+  .option('--deltas-only', 'Show only deltas (JSON only)')
+  .option('--requirements-only', 'Alias for --deltas-only (deprecated)')
+  .action(async (changeName?: string, options?: { json?: boolean; requirementsOnly?: boolean; deltasOnly?: boolean }) => {
+    try {
+      const changeCommand = new ChangeCommand();
+      await changeCommand.show(changeName, options);
+    } catch (error) {
+      console.error(`Error: ${(error as Error).message}`);
+      process.exitCode = 1;
+    }
+  });
+
+changeCmd
+  .command('list')
+  .description('List all active changes')
+  .option('--json', 'Output as JSON')
+  .option('--long', 'Show id and title with counts')
+  .action(async (options?: { json?: boolean; long?: boolean }) => {
+    try {
+      const changeCommand = new ChangeCommand();
+      await changeCommand.list(options);
+    } catch (error) {
+      console.error(`Error: ${(error as Error).message}`);
+      process.exitCode = 1;
+    }
+  });
+
+changeCmd
+  .command('validate [change-name]')
+  .description('Validate a change proposal')
+  .option('--strict', 'Enable strict validation mode')
+  .option('--json', 'Output validation report as JSON')
+  .option('--no-interactive', 'Disable interactive prompts')
+  .action(async (changeName?: string, options?: { strict?: boolean; json?: boolean; noInteractive?: boolean }) => {
+    try {
+      const changeCommand = new ChangeCommand();
+      await changeCommand.validate(changeName, options);
+    } catch (error) {
+      console.error(`Error: ${(error as Error).message}`);
+      process.exitCode = 1;
+    }
+  });
+
+program
+  .command('archive [change-name]')
+  .description('Archive a completed change and update main specs')
+  .option('-y, --yes', 'Skip confirmation prompts')
+  .option('--skip-specs', 'Skip spec update operations (useful for infrastructure, tooling, or doc-only changes)')
+  .option('--no-validate', 'Skip validation (not recommended, requires confirmation)')
+  .action(async (changeName?: string, options?: { yes?: boolean; skipSpecs?: boolean; noValidate?: boolean }) => {
+    try {
+      const archiveCommand = new ArchiveCommand();
+      await archiveCommand.execute(changeName, options);
+    } catch (error) {
+      console.log(); // Empty line for spacing
+      ora().fail(`Error: ${(error as Error).message}`);
+      process.exit(1);
+    }
+  });
+
+registerSpecCommand(program);
+
+// Top-level validate command
+program
+  .command('validate [item-name]')
+  .description('Validate changes and specs')
+  .option('--all', 'Validate all changes and specs')
+  .option('--changes', 'Validate all changes')
+  .option('--specs', 'Validate all specs')
+  .option('--type <type>', 'Specify item type when ambiguous: change|spec')
+  .option('--strict', 'Enable strict validation mode')
+  .option('--json', 'Output validation results as JSON')
+  .option('--concurrency <n>', 'Max concurrent validations (defaults to env OPENSPEC_CONCURRENCY or 6)')
+  .option('--no-interactive', 'Disable interactive prompts')
+  .action(async (itemName?: string, options?: { all?: boolean; changes?: boolean; specs?: boolean; type?: string; strict?: boolean; json?: boolean; noInteractive?: boolean; concurrency?: string }) => {
+    try {
+      const validateCommand = new ValidateCommand();
+      await validateCommand.execute(itemName, options);
+    } catch (error) {
+      console.log();
+      ora().fail(`Error: ${(error as Error).message}`);
+      process.exit(1);
+    }
+  });
+
 program.parse();

src/commands/change.ts

@@ -0,0 +1,260 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import { select } from '@inquirer/prompts';
+import { JsonConverter } from '../core/converters/json-converter.js';
+import { Validator } from '../core/validation/validator.js';
+import { ChangeParser } from '../core/parsers/change-parser.js';
+import { Change } from '../core/schemas/index.js';
+import { isInteractive } from '../utils/interactive.js';
+import { getActiveChangeIds } from '../utils/item-discovery.js';
+
+// Constants for better maintainability
+const ARCHIVE_DIR = 'archive';
+const TASK_PATTERN = /^[-*]\s+\[[\sx]\]/i;
+const COMPLETED_TASK_PATTERN = /^[-*]\s+\[x\]/i;
+
+export class ChangeCommand {
+  private converter: JsonConverter;
+
+  constructor() {
+    this.converter = new JsonConverter();
+  }
+
+  /**
+   * Show a change proposal.
+   * - Text mode: raw markdown passthrough (no filters)
+   * - JSON mode: minimal object with deltas; --deltas-only returns same object with filtered deltas
+   *   Note: --requirements-only is deprecated alias for --deltas-only
+   */
+  async show(changeName?: string, options?: { json?: boolean; requirementsOnly?: boolean; deltasOnly?: boolean }): Promise<void> {
+    const changesPath = path.join(process.cwd(), 'openspec', 'changes');
+    
+    if (!changeName) {
+      const changes = await this.getActiveChanges(changesPath);
+      if (changes.length === 0) {
+        console.error('No change specified. No active changes found.');
+      } else {
+        console.error(`No change specified. Available IDs: ${changes.join(', ')}`);
+      }
+      console.error('Hint: use "openspec change list" to view available changes.');
+      process.exitCode = 1;
+      return;
+    }
+    
+    const proposalPath = path.join(changesPath, changeName, 'proposal.md');
+    
+    try {
+      await fs.access(proposalPath);
+    } catch {
+      throw new Error(`Change "${changeName}" not found at ${proposalPath}`);
+    }
+    
+    if (options?.json) {
+      const jsonOutput = await this.converter.convertChangeToJson(proposalPath);
+      
+      if (options.requirementsOnly) {
+        console.error('Flag --requirements-only is deprecated; use --deltas-only instead.');
+      }
+
+      const parsed: Change = JSON.parse(jsonOutput);
+      const contentForTitle = await fs.readFile(proposalPath, 'utf-8');
+      const title = this.extractTitle(contentForTitle);
+      const id = parsed.name;
+      const deltas = parsed.deltas || [];
+
+      if (options.requirementsOnly || options.deltasOnly) {
+        const output = { id, title, deltaCount: deltas.length, deltas };
+        console.log(JSON.stringify(output, null, 2));
+      } else {
+        const output = {
+          id,
+          title,
+          deltaCount: deltas.length,
+          deltas,
+        };
+        console.log(JSON.stringify(output, null, 2));
+      }
+    } else {
+      const content = await fs.readFile(proposalPath, 'utf-8');
+      console.log(content);
+    }
+  }
+
+  /**
+   * List active changes.
+   * - Text default: IDs only; --long prints minimal details (title, counts)
+   * - JSON: array of { id, title, deltaCount, taskStatus }, sorted by id
+   */
+  async list(options?: { json?: boolean; long?: boolean }): Promise<void> {
+    const changesPath = path.join(process.cwd(), 'openspec', 'changes');
+    
+    const changes = await this.getActiveChanges(changesPath);
+    
+    if (options?.json) {
+      const changeDetails = await Promise.all(
+        changes.map(async (changeName) => {
+          const proposalPath = path.join(changesPath, changeName, 'proposal.md');
+          const tasksPath = path.join(changesPath, changeName, 'tasks.md');
+          
+          try {
+            const content = await fs.readFile(proposalPath, 'utf-8');
+            const changeDir = path.join(changesPath, changeName);
+            const parser = new ChangeParser(content, changeDir);
+            const change = await parser.parseChangeWithDeltas(changeName);
+            
+            let taskStatus = { total: 0, completed: 0 };
+            try {
+              const tasksContent = await fs.readFile(tasksPath, 'utf-8');
+              taskStatus = this.countTasks(tasksContent);
+            } catch (error) {
+              // Tasks file may not exist, which is okay
+              if (process.env.DEBUG) {
+                console.error(`Failed to read tasks file at ${tasksPath}:`, error);
+              }
+            }
+            
+            return {
+              id: changeName,
+              title: this.extractTitle(content),
+              deltaCount: change.deltas.length,
+              taskStatus,
+            };
+          } catch (error) {
+            return {
+              id: changeName,
+              title: 'Unknown',
+              deltaCount: 0,
+              taskStatus: { total: 0, completed: 0 },
+            };
+          }
+        })
+      );
+      
+      const sorted = changeDetails.sort((a, b) => a.id.localeCompare(b.id));
+      console.log(JSON.stringify(sorted, null, 2));
+    } else {
+      if (changes.length === 0) {
+        console.log('No items found');
+        return;
+      }
+      const sorted = [...changes].sort();
+      if (!options?.long) {
+        // IDs only
+        sorted.forEach(id => console.log(id));
+        return;
+      }
+
+      // Long format: id: title and minimal counts
+      for (const changeName of sorted) {
+        const proposalPath = path.join(changesPath, changeName, 'proposal.md');
+        const tasksPath = path.join(changesPath, changeName, 'tasks.md');
+        try {
+          const content = await fs.readFile(proposalPath, 'utf-8');
+          const title = this.extractTitle(content);
+          let taskStatusText = '';
+          try {
+            const tasksContent = await fs.readFile(tasksPath, 'utf-8');
+            const { total, completed } = this.countTasks(tasksContent);
+            taskStatusText = ` [tasks ${completed}/${total}]`;
+          } catch (error) {
+            if (process.env.DEBUG) {
+              console.error(`Failed to read tasks file at ${tasksPath}:`, error);
+            }
+          }
+          const changeDir = path.join(changesPath, changeName);
+          const parser = new ChangeParser(await fs.readFile(proposalPath, 'utf-8'), changeDir);
+          const change = await parser.parseChangeWithDeltas(changeName);
+          const deltaCountText = ` [deltas ${change.deltas.length}]`;
+          console.log(`${changeName}: ${title}${deltaCountText}${taskStatusText}`);
+        } catch {
+          console.log(`${changeName}: (unable to read)`);
+        }
+      }
+    }
+  }
+
+  async validate(changeName?: string, options?: { strict?: boolean; json?: boolean; noInteractive?: boolean }): Promise<void> {
+    const changesPath = path.join(process.cwd(), 'openspec', 'changes');
+    
+    if (!changeName) {
+      const canPrompt = isInteractive(options?.noInteractive);
+      const changes = await getActiveChangeIds();
+      if (canPrompt && changes.length > 0) {
+        const selected = await select({
+          message: 'Select a change to validate',
+          choices: changes.map(id => ({ name: id, value: id })),
+        });
+        changeName = selected;
+      } else {
+        if (changes.length === 0) {
+          console.error('No change specified. No active changes found.');
+        } else {
+          console.error(`No change specified. Available IDs: ${changes.join(', ')}`);
+        }
+        console.error('Hint: use "openspec change list" to view available changes.');
+        process.exitCode = 1;
+        return;
+      }
+    }
+    
+    const proposalPath = path.join(changesPath, changeName, 'proposal.md');
+    
+    try {
+      await fs.access(proposalPath);
+    } catch {
+      throw new Error(`Change "${changeName}" not found at ${proposalPath}`);
+    }
+    
+    const validator = new Validator(options?.strict || false);
+    const report = await validator.validateChange(proposalPath);
+    
+    if (options?.json) {
+      console.log(JSON.stringify(report, null, 2));
+    } else {
+      if (report.valid) {
+        console.log(`Change "${changeName}" is valid`);
+      } else {
+        console.error(`Change "${changeName}" has validation issues`);
+        report.issues.forEach(issue => {
+          const label = issue.level === 'ERROR' ? 'ERROR' : 'WARNING';
+          const prefix = issue.level === 'ERROR' ? '✗' : '⚠';
+          console.error(`${prefix} [${label}] ${issue.path}: ${issue.message}`);
+        });
+      }
+    }
+  }
+
+  private async getActiveChanges(changesPath: string): Promise<string[]> {
+    try {
+      const entries = await fs.readdir(changesPath, { withFileTypes: true });
+      return entries
+        .filter(entry => entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== ARCHIVE_DIR)
+        .map(entry => entry.name)
+        .sort();
+    } catch {
+      return [];
+    }
+  }
+
+  private extractTitle(content: string): string {
+    const match = content.match(/^#\s+(?:Change:\s+)?(.+)$/m);
+    return match ? match[1].trim() : 'Untitled Change';
+  }
+
+  private countTasks(content: string): { total: number; completed: number } {
+    const lines = content.split('\n');
+    let total = 0;
+    let completed = 0;
+    
+    for (const line of lines) {
+      if (line.match(TASK_PATTERN)) {
+        total++;
+        if (line.match(COMPLETED_TASK_PATTERN)) {
+          completed++;
+        }
+      }
+    }
+    
+    return { total, completed };
+  }
+}

src/commands/spec.ts

@@ -0,0 +1,223 @@
+import { program } from 'commander';
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { MarkdownParser } from '../core/parsers/markdown-parser.js';
+import { Validator } from '../core/validation/validator.js';
+import type { Spec } from '../core/schemas/index.js';
+import { select } from '@inquirer/prompts';
+import { isInteractive } from '../utils/interactive.js';
+import { getSpecIds } from '../utils/item-discovery.js';
+
+const SPECS_DIR = 'openspec/specs';
+
+export function registerSpecCommand(rootProgram: typeof program) {
+  const specCommand = rootProgram
+    .command('spec')
+    .description('Manage and view OpenSpec specifications');
+
+  interface ShowOptions {
+    json?: boolean;
+    // JSON-only filters (raw-first text has no filters)
+    requirements?: boolean;
+    scenarios?: boolean; // --no-scenarios sets this to false (JSON only)
+    requirement?: string; // JSON only
+  }
+
+  function parseSpecFromFile(specPath: string, specId: string): Spec {
+    const content = readFileSync(specPath, 'utf-8');
+    const parser = new MarkdownParser(content);
+    return parser.parseSpec(specId);
+  }
+
+  function validateRequirementIndex(spec: Spec, requirementOpt?: string): number | undefined {
+    if (!requirementOpt) return undefined;
+    const index = Number.parseInt(requirementOpt, 10);
+    if (!Number.isInteger(index) || index < 1 || index > spec.requirements.length) {
+      throw new Error(`Requirement ${requirementOpt} not found`);
+    }
+    return index - 1; // convert to 0-based
+  }
+
+  function filterSpec(spec: Spec, options: ShowOptions): Spec {
+    const requirementIndex = validateRequirementIndex(spec, options.requirement);
+    const includeScenarios = options.scenarios !== false && !options.requirements;
+
+    const filteredRequirements = (requirementIndex !== undefined
+      ? [spec.requirements[requirementIndex]]
+      : spec.requirements
+    ).map(req => ({
+      text: req.text,
+      scenarios: includeScenarios ? req.scenarios : [],
+    }));
+
+    const metadata = spec.metadata ?? { version: '1.0.0', format: 'openspec' as const };
+
+    return {
+      name: spec.name,
+      overview: spec.overview,
+      requirements: filteredRequirements,
+      metadata,
+    };
+  }
+
+  /**
+   * Print the raw markdown content for a spec file without any formatting.
+   * Raw-first behavior ensures text mode is a passthrough for deterministic output.
+   */
+  function printSpecTextRaw(specPath: string): void {
+    const content = readFileSync(specPath, 'utf-8');
+    console.log(content);
+  }
+
+  specCommand
+    .command('show <spec-id>')
+    .description('Display a specific specification')
+    .option('--json', 'Output as JSON')
+    .option('--requirements', 'JSON only: Show only requirements (exclude scenarios)')
+    .option('--no-scenarios', 'JSON only: Exclude scenario content')
+    .option('-r, --requirement <id>', 'JSON only: Show specific requirement by ID (1-based)')
+    .action((specId: string, options: ShowOptions) => {
+      try {
+        const specPath = join(SPECS_DIR, specId, 'spec.md');
+        
+        if (!existsSync(specPath)) {
+          throw new Error(`Spec '${specId}' not found at openspec/specs/${specId}/spec.md`);
+        }
+
+        if (options.json) {
+          if (options.requirements && options.requirement) {
+            throw new Error('Options --requirements and --requirement cannot be used together');
+          }
+          const parsed = parseSpecFromFile(specPath, specId);
+          const filtered = filterSpec(parsed, options);
+          const output = {
+            id: specId,
+            title: parsed.name,
+            overview: parsed.overview,
+            requirementCount: filtered.requirements.length,
+            requirements: filtered.requirements,
+            metadata: parsed.metadata ?? { version: '1.0.0', format: 'openspec' as const },
+          };
+          console.log(JSON.stringify(output, null, 2));
+        } else {
+          // raw-first text: print raw file
+          printSpecTextRaw(specPath);
+        }
+      } catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        process.exitCode = 1;
+      }
+    });
+
+  specCommand
+    .command('list')
+    .description('List all available specifications')
+    .option('--json', 'Output as JSON')
+    .option('--long', 'Show id and title with counts')
+    .action((options: { json?: boolean; long?: boolean }) => {
+      try {
+        if (!existsSync(SPECS_DIR)) {
+          console.log('No items found');
+          return;
+        }
+
+        const specs = readdirSync(SPECS_DIR, { withFileTypes: true })
+          .filter(dirent => dirent.isDirectory())
+          .map(dirent => {
+            const specPath = join(SPECS_DIR, dirent.name, 'spec.md');
+            if (existsSync(specPath)) {
+              try {
+                const spec = parseSpecFromFile(specPath, dirent.name);
+                
+                return {
+                  id: dirent.name,
+                  title: spec.name,
+                  requirementCount: spec.requirements.length
+                };
+              } catch {
+                return {
+                  id: dirent.name,
+                  title: dirent.name,
+                  requirementCount: 0
+                };
+              }
+            }
+            return null;
+          })
+          .filter((spec): spec is { id: string; title: string; requirementCount: number } => spec !== null)
+          .sort((a, b) => a.id.localeCompare(b.id));
+
+        if (options.json) {
+          console.log(JSON.stringify(specs, null, 2));
+        } else {
+          if (specs.length === 0) {
+            console.log('No items found');
+            return;
+          }
+          if (!options.long) {
+            specs.forEach(spec => console.log(spec.id));
+            return;
+          }
+          specs.forEach(spec => {
+            console.log(`${spec.id}: ${spec.title} [requirements ${spec.requirementCount}]`);
+          });
+        }
+      } catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        process.exitCode = 1;
+      }
+    });
+
+  specCommand
+    .command('validate [spec-id]')
+    .description('Validate a specification structure')
+    .option('--strict', 'Enable strict validation mode')
+    .option('--json', 'Output validation report as JSON')
+    .option('--no-interactive', 'Disable interactive prompts')
+    .action(async (specId: string | undefined, options: { strict?: boolean; json?: boolean; noInteractive?: boolean }) => {
+      try {
+        if (!specId) {
+          const canPrompt = isInteractive(options?.noInteractive);
+          const specIds = await getSpecIds();
+          if (canPrompt && specIds.length > 0) {
+            specId = await select({
+              message: 'Select a spec to validate',
+              choices: specIds.map(id => ({ name: id, value: id })),
+            });
+          } else {
+            throw new Error('Missing required argument <spec-id>');
+          }
+        }
+
+        const specPath = join(SPECS_DIR, specId, 'spec.md');
+        
+        if (!existsSync(specPath)) {
+          throw new Error(`Spec '${specId}' not found at openspec/specs/${specId}/spec.md`);
+        }
+
+        const validator = new Validator(options.strict);
+        const report = await validator.validateSpec(specPath);
+
+        if (options.json) {
+          console.log(JSON.stringify(report, null, 2));
+        } else {
+          if (report.valid) {
+            console.log(`Specification '${specId}' is valid`);
+          } else {
+            console.error(`Specification '${specId}' has issues`);
+            report.issues.forEach(issue => {
+              const label = issue.level === 'ERROR' ? 'ERROR' : issue.level;
+              const prefix = issue.level === 'ERROR' ? '✗' : issue.level === 'WARNING' ? '⚠' : 'ℹ';
+              console.error(`${prefix} [${label}] ${issue.path}: ${issue.message}`);
+            });
+          }
+        }
+        process.exitCode = report.valid ? 0 : 1;
+      } catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        process.exitCode = 1;
+      }
+    });
+
+  return specCommand;
+}

src/commands/validate.ts

@@ -0,0 +1,312 @@
+import { select } from '@inquirer/prompts';
+import ora from 'ora';
+import path from 'path';
+import { Validator } from '../core/validation/validator.js';
+import { isInteractive } from '../utils/interactive.js';
+import { getActiveChangeIds, getSpecIds } from '../utils/item-discovery.js';
+
+type ItemType = 'change' | 'spec';
+
+interface ExecuteOptions {
+  all?: boolean;
+  changes?: boolean;
+  specs?: boolean;
+  type?: string;
+  strict?: boolean;
+  json?: boolean;
+  noInteractive?: boolean;
+  concurrency?: string;
+}
+
+interface BulkItemResult {
+  id: string;
+  type: ItemType;
+  valid: boolean;
+  issues: { level: 'ERROR' | 'WARNING' | 'INFO'; path: string; message: string }[];
+  durationMs: number;
+}
+
+export class ValidateCommand {
+  async execute(itemName: string | undefined, options: ExecuteOptions = {}): Promise<void> {
+    const interactive = isInteractive(options.noInteractive);
+
+    // Handle bulk flags first
+    if (options.all || options.changes || options.specs) {
+      await this.runBulkValidation({
+        changes: !!options.all || !!options.changes,
+        specs: !!options.all || !!options.specs,
+      }, { strict: !!options.strict, json: !!options.json, concurrency: options.concurrency });
+      return;
+    }
+
+    // No item and no flags
+    if (!itemName) {
+      if (interactive) {
+        await this.runInteractiveSelector({ strict: !!options.strict, json: !!options.json, concurrency: options.concurrency });
+        return;
+      }
+      this.printNonInteractiveHint();
+      process.exitCode = 1;
+      return;
+    }
+
+    // Direct item validation with type detection or override
+    const typeOverride = this.normalizeType(options.type);
+    await this.validateDirectItem(itemName, { typeOverride, strict: !!options.strict, json: !!options.json });
+  }
+
+  private normalizeType(value?: string): ItemType | undefined {
+    if (!value) return undefined;
+    const v = value.toLowerCase();
+    if (v === 'change' || v === 'spec') return v;
+    return undefined;
+  }
+
+  private async runInteractiveSelector(opts: { strict: boolean; json: boolean; concurrency?: string }): Promise<void> {
+    const choice = await select({
+      message: 'What would you like to validate?',
+      choices: [
+        { name: 'All (changes + specs)', value: 'all' },
+        { name: 'All changes', value: 'changes' },
+        { name: 'All specs', value: 'specs' },
+        { name: 'Pick a specific change or spec', value: 'one' },
+      ],
+    });
+
+    if (choice === 'all') return this.runBulkValidation({ changes: true, specs: true }, opts);
+    if (choice === 'changes') return this.runBulkValidation({ changes: true, specs: false }, opts);
+    if (choice === 'specs') return this.runBulkValidation({ changes: false, specs: true }, opts);
+
+    // one
+    const [changes, specs] = await Promise.all([getActiveChangeIds(), getSpecIds()]);
+    const items: { name: string; value: { type: ItemType; id: string } }[] = [];
+    items.push(...changes.map(id => ({ name: `change/${id}`, value: { type: 'change' as const, id } })));
+    items.push(...specs.map(id => ({ name: `spec/${id}`, value: { type: 'spec' as const, id } })));
+    if (items.length === 0) {
+      console.error('No items found to validate.');
+      process.exitCode = 1;
+      return;
+    }
+    const picked = await select<{ type: ItemType; id: string }>({ message: 'Pick an item', choices: items });
+    await this.validateByType(picked.type, picked.id, opts);
+  }
+
+  private printNonInteractiveHint(): void {
+    console.error('Nothing to validate. Try one of:');
+    console.error('  openspec validate --all');
+    console.error('  openspec validate --changes');
+    console.error('  openspec validate --specs');
+    console.error('  openspec validate <item-name>');
+    console.error('Or run in an interactive terminal.');
+  }
+
+  private async validateDirectItem(itemName: string, opts: { typeOverride?: ItemType; strict: boolean; json: boolean }): Promise<void> {
+    const [changes, specs] = await Promise.all([getActiveChangeIds(), getSpecIds()]);
+    const isChange = changes.includes(itemName);
+    const isSpec = specs.includes(itemName);
+
+    const type = opts.typeOverride ?? (isChange ? 'change' : isSpec ? 'spec' : undefined);
+
+    if (!type) {
+      console.error(`Unknown item '${itemName}'`);
+      const suggestions = nearestMatches(itemName, [...changes, ...specs]);
+      if (suggestions.length) console.error(`Did you mean: ${suggestions.join(', ')}?`);
+      process.exitCode = 1;
+      return;
+    }
+
+    if (!opts.typeOverride && isChange && isSpec) {
+      console.error(`Ambiguous item '${itemName}' matches both a change and a spec.`);
+      console.error('Pass --type change|spec, or use: openspec change validate / openspec spec validate');
+      process.exitCode = 1;
+      return;
+    }
+
+    await this.validateByType(type, itemName, opts);
+  }
+
+  private async validateByType(type: ItemType, id: string, opts: { strict: boolean; json: boolean }): Promise<void> {
+    const validator = new Validator(opts.strict);
+    if (type === 'change') {
+      const file = path.join(process.cwd(), 'openspec', 'changes', id, 'proposal.md');
+      const start = Date.now();
+      const report = await validator.validateChange(file);
+      const durationMs = Date.now() - start;
+      this.printReport('change', id, report, durationMs, opts.json);
+      process.exitCode = report.valid ? 0 : 1;
+      return;
+    }
+    const file = path.join(process.cwd(), 'openspec', 'specs', id, 'spec.md');
+    const start = Date.now();
+    const report = await validator.validateSpec(file);
+    const durationMs = Date.now() - start;
+    this.printReport('spec', id, report, durationMs, opts.json);
+    process.exitCode = report.valid ? 0 : 1;
+  }
+
+  private printReport(type: ItemType, id: string, report: { valid: boolean; issues: any[] }, durationMs: number, json: boolean): void {
+    if (json) {
+      const out = { items: [{ id, type, valid: report.valid, issues: report.issues, durationMs }], summary: { totals: { items: 1, passed: report.valid ? 1 : 0, failed: report.valid ? 0 : 1 }, byType: { [type]: { items: 1, passed: report.valid ? 1 : 0, failed: report.valid ? 0 : 1 } } }, version: '1.0' };
+      console.log(JSON.stringify(out, null, 2));
+      return;
+    }
+    if (report.valid) {
+      console.log(`${type === 'change' ? 'Change' : 'Specification'} '${id}' is valid`);
+    } else {
+      console.error(`${type === 'change' ? 'Change' : 'Specification'} '${id}' has issues`);
+      for (const issue of report.issues) {
+        const label = issue.level === 'ERROR' ? 'ERROR' : issue.level;
+        const prefix = issue.level === 'ERROR' ? '✗' : issue.level === 'WARNING' ? '⚠' : 'ℹ';
+        console.error(`${prefix} [${label}] ${issue.path}: ${issue.message}`);
+      }
+    }
+  }
+
+  private async runBulkValidation(scope: { changes: boolean; specs: boolean }, opts: { strict: boolean; json: boolean; concurrency?: string }): Promise<void> {
+    const spinner = !opts.json ? ora('Validating...').start() : undefined;
+    const [changeIds, specIds] = await Promise.all([
+      scope.changes ? getActiveChangeIds() : Promise.resolve<string[]>([]),
+      scope.specs ? getSpecIds() : Promise.resolve<string[]>([]),
+    ]);
+
+    const DEFAULT_CONCURRENCY = 6;
+    const maxSuggestions = 5; // used by nearestMatches
+    const concurrency = normalizeConcurrency(opts.concurrency) ?? normalizeConcurrency(process.env.OPENSPEC_CONCURRENCY) ?? DEFAULT_CONCURRENCY;
+    const validator = new Validator(opts.strict);
+    const queue: Array<() => Promise<BulkItemResult>> = [];
+
+    for (const id of changeIds) {
+      queue.push(async () => {
+        const start = Date.now();
+        const file = path.join(process.cwd(), 'openspec', 'changes', id, 'proposal.md');
+        const report = await validator.validateChange(file);
+        const durationMs = Date.now() - start;
+        return { id, type: 'change' as const, valid: report.valid, issues: report.issues, durationMs };
+      });
+    }
+    for (const id of specIds) {
+      queue.push(async () => {
+        const start = Date.now();
+        const file = path.join(process.cwd(), 'openspec', 'specs', id, 'spec.md');
+        const report = await validator.validateSpec(file);
+        const durationMs = Date.now() - start;
+        return { id, type: 'spec' as const, valid: report.valid, issues: report.issues, durationMs };
+      });
+    }
+
+    const results: BulkItemResult[] = [];
+    let index = 0;
+    let running = 0;
+    let passed = 0;
+    let failed = 0;
+
+    await new Promise<void>((resolve) => {
+      const next = () => {
+        while (running < concurrency && index < queue.length) {
+          const currentIndex = index++;
+          const task = queue[currentIndex];
+          running++;
+          if (spinner) spinner.text = `Validating (${currentIndex + 1}/${queue.length})...`;
+          task()
+            .then(res => {
+              results.push(res);
+              if (res.valid) passed++; else failed++;
+            })
+            .catch((error: any) => {
+              const message = error?.message || 'Unknown error';
+              const res: BulkItemResult = { id: getPlannedId(currentIndex, changeIds, specIds) ?? 'unknown', type: getPlannedType(currentIndex, changeIds, specIds) ?? 'change', valid: false, issues: [{ level: 'ERROR', path: 'file', message }], durationMs: 0 };
+              results.push(res);
+              failed++;
+            })
+            .finally(() => {
+              running--;
+              if (index >= queue.length && running === 0) resolve();
+              else next();
+            });
+        }
+      };
+      next();
+    });
+
+    spinner?.stop();
+
+    results.sort((a, b) => a.id.localeCompare(b.id));
+    const summary = {
+      totals: { items: results.length, passed, failed },
+      byType: {
+        ...(scope.changes ? { change: summarizeType(results, 'change') } : {}),
+        ...(scope.specs ? { spec: summarizeType(results, 'spec') } : {}),
+      },
+    } as const;
+
+    if (opts.json) {
+      const out = { items: results, summary, version: '1.0' };
+      console.log(JSON.stringify(out, null, 2));
+    } else {
+      for (const res of results) {
+        if (res.valid) console.log(`✓ ${res.type}/${res.id}`);
+        else console.error(`✗ ${res.type}/${res.id}`);
+      }
+      console.log(`Totals: ${summary.totals.passed} passed, ${summary.totals.failed} failed (${summary.totals.items} items)`);
+    }
+
+    process.exitCode = failed > 0 ? 1 : 0;
+  }
+}
+
+function summarizeType(results: BulkItemResult[], type: ItemType) {
+  const filtered = results.filter(r => r.type === type);
+  const items = filtered.length;
+  const passed = filtered.filter(r => r.valid).length;
+  const failed = items - passed;
+  return { items, passed, failed };
+}
+
+function nearestMatches(input: string, candidates: string[], max: number = 5): string[] {
+  const scored = candidates.map(c => ({ c, d: levenshtein(input, c) }));
+  scored.sort((a, b) => a.d - b.d);
+  return scored.slice(0, max).map(s => s.c);
+}
+
+function levenshtein(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+  const dp: number[][] = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      dp[i][j] = Math.min(
+        dp[i - 1][j] + 1,
+        dp[i][j - 1] + 1,
+        dp[i - 1][j - 1] + cost
+      );
+    }
+  }
+  return dp[m][n];
+}
+
+function normalizeConcurrency(value?: string): number | undefined {
+  if (!value) return undefined;
+  const n = parseInt(value, 10);
+  if (Number.isNaN(n) || n <= 0) return undefined;
+  return n;
+}
+
+function getPlannedId(index: number, changeIds: string[], specIds: string[]): string | undefined {
+  const totalChanges = changeIds.length;
+  if (index < totalChanges) return changeIds[index];
+  const specIndex = index - totalChanges;
+  return specIds[specIndex];
+}
+
+function getPlannedType(index: number, changeIds: string[], specIds: string[]): ItemType | undefined {
+  const totalChanges = changeIds.length;
+  if (index < totalChanges) return 'change';
+  const specIndex = index - totalChanges;
+  if (specIndex >= 0 && specIndex < specIds.length) return 'spec';
+  return undefined;
+}
+
+

src/core/archive.ts

@@ -0,0 +1,591 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import { select, confirm } from '@inquirer/prompts';
+import { FileSystemUtils } from '../utils/file-system.js';
+import { getTaskProgressForChange, formatTaskStatus } from '../utils/task-progress.js';
+import { Validator } from './validation/validator.js';
+import chalk from 'chalk';
+import {
+  extractRequirementsSection,
+  parseDeltaSpec,
+  normalizeRequirementName,
+  type RequirementBlock,
+} from './parsers/requirement-blocks.js';
+
+interface SpecUpdate {
+  source: string;
+  target: string;
+  exists: boolean;
+}
+
+export class ArchiveCommand {
+  async execute(changeName?: string, options: { yes?: boolean; skipSpecs?: boolean; noValidate?: boolean } = {}): Promise<void> {
+    const targetPath = '.';
+    const changesDir = path.join(targetPath, 'openspec', 'changes');
+    const archiveDir = path.join(changesDir, 'archive');
+    const mainSpecsDir = path.join(targetPath, 'openspec', 'specs');
+
+    // Check if changes directory exists
+    try {
+      await fs.access(changesDir);
+    } catch {
+      throw new Error("No OpenSpec changes directory found. Run 'openspec init' first.");
+    }
+
+    // Get change name interactively if not provided
+    if (!changeName) {
+      const selectedChange = await this.selectChange(changesDir);
+      if (!selectedChange) {
+        console.log('No change selected. Aborting.');
+        return;
+      }
+      changeName = selectedChange;
+    }
+
+    const changeDir = path.join(changesDir, changeName);
+
+    // Verify change exists
+    try {
+      const stat = await fs.stat(changeDir);
+      if (!stat.isDirectory()) {
+        throw new Error(`Change '${changeName}' not found.`);
+      }
+    } catch {
+      throw new Error(`Change '${changeName}' not found.`);
+    }
+
+    // Validate specs and change before archiving
+    if (!options.noValidate) {
+      const validator = new Validator();
+      let hasValidationErrors = false;
+
+      // Validate change.md file
+      const changeFile = path.join(changeDir, 'change.md');
+      try {
+        await fs.access(changeFile);
+        const changeReport = await validator.validateChange(changeFile);
+        
+        if (!changeReport.valid) {
+          hasValidationErrors = true;
+          console.log(chalk.red(`\nValidation errors in change.md:`));
+          for (const issue of changeReport.issues) {
+            if (issue.level === 'ERROR') {
+              console.log(chalk.red(`  ✗ ${issue.message}`));
+            } else if (issue.level === 'WARNING') {
+              console.log(chalk.yellow(`  ⚠ ${issue.message}`));
+            }
+          }
+        }
+      } catch {
+        // Change file doesn't exist, skip validation
+      }
+
+      // Validate spec files
+      const changeSpecsDir = path.join(changeDir, 'specs');
+      try {
+        const entries = await fs.readdir(changeSpecsDir, { withFileTypes: true });
+        
+        for (const entry of entries) {
+          if (entry.isDirectory()) {
+            const specFile = path.join(changeSpecsDir, entry.name, 'spec.md');
+            
+            try {
+              await fs.access(specFile);
+              const report = await validator.validateSpec(specFile);
+              
+              if (!report.valid) {
+                hasValidationErrors = true;
+                console.log(chalk.red(`\nValidation errors in ${entry.name}/spec.md:`));
+                for (const issue of report.issues) {
+                  if (issue.level === 'ERROR') {
+                    console.log(chalk.red(`  ✗ ${issue.message}`));
+                  } else if (issue.level === 'WARNING') {
+                    console.log(chalk.yellow(`  ⚠ ${issue.message}`));
+                  }
+                }
+              }
+            } catch {
+              // Spec file doesn't exist, skip validation
+            }
+          }
+        }
+      } catch {
+        // No specs directory, skip validation
+      }
+
+      if (hasValidationErrors) {
+        console.log(chalk.red('\nValidation failed. Please fix the errors before archiving.'));
+        console.log(chalk.yellow('To skip validation (not recommended), use --no-validate flag.'));
+        return;
+      }
+    } else {
+      // Log warning when validation is skipped
+      const timestamp = new Date().toISOString();
+      
+      if (!options.yes) {
+        const proceed = await confirm({
+          message: chalk.yellow('⚠️  WARNING: Skipping validation may archive invalid specs. Continue? (y/N)'),
+          default: false
+        });
+        if (!proceed) {
+          console.log('Archive cancelled.');
+          return;
+        }
+      } else {
+        console.log(chalk.yellow(`\n⚠️  WARNING: Skipping validation may archive invalid specs.`));
+      }
+      
+      console.log(chalk.yellow(`[${timestamp}] Validation skipped for change: ${changeName}`));
+      console.log(chalk.yellow(`Affected files: ${changeDir}`));
+    }
+
+    // Show progress and check for incomplete tasks
+    const progress = await getTaskProgressForChange(changesDir, changeName);
+    const status = formatTaskStatus(progress);
+    console.log(`Task status: ${status}`);
+
+    const incompleteTasks = Math.max(progress.total - progress.completed, 0);
+    if (incompleteTasks > 0) {
+      if (!options.yes) {
+        const proceed = await confirm({
+          message: `Warning: ${incompleteTasks} incomplete task(s) found. Continue?`,
+          default: false
+        });
+        if (!proceed) {
+          console.log('Archive cancelled.');
+          return;
+        }
+      } else {
+        console.log(`Warning: ${incompleteTasks} incomplete task(s) found. Continuing due to --yes flag.`);
+      }
+    }
+
+    // Handle spec updates unless skipSpecs flag is set
+    if (options.skipSpecs) {
+      console.log('Skipping spec updates (--skip-specs flag provided).');
+    } else {
+      // Find specs to update
+      const specUpdates = await this.findSpecUpdates(changeDir, mainSpecsDir);
+      
+      if (specUpdates.length > 0) {
+        console.log('\nSpecs to update:');
+        for (const update of specUpdates) {
+          const status = update.exists ? 'update' : 'create';
+          const capability = path.basename(path.dirname(update.target));
+          console.log(`  ${capability}: ${status}`);
+        }
+
+        let shouldUpdateSpecs = true;
+        if (!options.yes) {
+          shouldUpdateSpecs = await confirm({
+            message: 'Proceed with spec updates?',
+            default: true
+          });
+          if (!shouldUpdateSpecs) {
+            console.log('Skipping spec updates. Proceeding with archive.');
+          }
+        }
+
+        if (shouldUpdateSpecs) {
+          // Prepare all updates first (validation pass, no writes)
+          const prepared: Array<{ update: SpecUpdate; rebuilt: string; counts: { added: number; modified: number; removed: number; renamed: number } }> = [];
+          try {
+            for (const update of specUpdates) {
+              const built = await this.buildUpdatedSpec(update, changeName!);
+              prepared.push({ update, rebuilt: built.rebuilt, counts: built.counts });
+            }
+          } catch (err: any) {
+            console.log(String(err.message || err));
+            console.log('Aborted. No files were changed.');
+            return;
+          }
+
+          // All validations passed; write files and display counts
+          let totals = { added: 0, modified: 0, removed: 0, renamed: 0 };
+          for (const p of prepared) {
+            await this.writeUpdatedSpec(p.update, p.rebuilt, p.counts);
+            totals.added += p.counts.added;
+            totals.modified += p.counts.modified;
+            totals.removed += p.counts.removed;
+            totals.renamed += p.counts.renamed;
+          }
+          console.log(
+            `Totals: + ${totals.added}, ~ ${totals.modified}, - ${totals.removed}, → ${totals.renamed}`
+          );
+          console.log('Specs updated successfully.');
+        }
+      }
+    }
+
+    // Create archive directory with date prefix
+    const archiveName = `${this.getArchiveDate()}-${changeName}`;
+    const archivePath = path.join(archiveDir, archiveName);
+
+    // Check if archive already exists
+    try {
+      await fs.access(archivePath);
+      throw new Error(`Archive '${archiveName}' already exists.`);
+    } catch (error: any) {
+      if (error.code !== 'ENOENT') {
+        throw error;
+      }
+    }
+
+    // Create archive directory if needed
+    await fs.mkdir(archiveDir, { recursive: true });
+
+    // Move change to archive
+    await fs.rename(changeDir, archivePath);
+    
+    console.log(`Change '${changeName}' archived as '${archiveName}'.`);
+  }
+
+  private async selectChange(changesDir: string): Promise<string | null> {
+    // Get all directories in changes (excluding archive)
+    const entries = await fs.readdir(changesDir, { withFileTypes: true });
+    const changeDirs = entries
+      .filter(entry => entry.isDirectory() && entry.name !== 'archive')
+      .map(entry => entry.name)
+      .sort();
+
+    if (changeDirs.length === 0) {
+      console.log('No active changes found.');
+      return null;
+    }
+
+    // Build choices with progress inline to avoid duplicate lists
+    let choices: Array<{ name: string; value: string }> = changeDirs.map(name => ({ name, value: name }));
+    try {
+      const progressList: Array<{ id: string; status: string }> = [];
+      for (const id of changeDirs) {
+        const progress = await getTaskProgressForChange(changesDir, id);
+        const status = formatTaskStatus(progress);
+        progressList.push({ id, status });
+      }
+      const nameWidth = Math.max(...progressList.map(p => p.id.length));
+      choices = progressList.map(p => ({
+        name: `${p.id.padEnd(nameWidth)}     ${p.status}`,
+        value: p.id
+      }));
+    } catch {
+      // If anything fails, fall back to simple names
+      choices = changeDirs.map(name => ({ name, value: name }));
+    }
+
+    try {
+      const answer = await select({
+        message: 'Select a change to archive',
+        choices
+      });
+      return answer;
+    } catch (error) {
+      // User cancelled (Ctrl+C)
+      return null;
+    }
+  }
+
+  // Deprecated: replaced by shared task-progress utilities
+  private async checkIncompleteTasks(_tasksPath: string): Promise<number> {
+    return 0;
+  }
+
+  private async findSpecUpdates(changeDir: string, mainSpecsDir: string): Promise<SpecUpdate[]> {
+    const updates: SpecUpdate[] = [];
+    const changeSpecsDir = path.join(changeDir, 'specs');
+
+    try {
+      const entries = await fs.readdir(changeSpecsDir, { withFileTypes: true });
+      
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          const specFile = path.join(changeSpecsDir, entry.name, 'spec.md');
+          const targetFile = path.join(mainSpecsDir, entry.name, 'spec.md');
+          
+          try {
+            await fs.access(specFile);
+            
+            // Check if target exists
+            let exists = false;
+            try {
+              await fs.access(targetFile);
+              exists = true;
+            } catch {
+              exists = false;
+            }
+
+            updates.push({
+              source: specFile,
+              target: targetFile,
+              exists
+            });
+          } catch {
+            // Source spec doesn't exist, skip
+          }
+        }
+      }
+    } catch {
+      // No specs directory in change
+    }
+
+    return updates;
+  }
+
+  private async buildUpdatedSpec(update: SpecUpdate, changeName: string): Promise<{ rebuilt: string; counts: { added: number; modified: number; removed: number; renamed: number } }> {
+    // Read change spec content (delta-format expected)
+    const changeContent = await fs.readFile(update.source, 'utf-8');
+
+    // Parse deltas from the change spec file
+    const plan = parseDeltaSpec(changeContent);
+    const specName = path.basename(path.dirname(update.target));
+
+    // Pre-validate duplicates within sections
+    const addedNames = new Set<string>();
+    for (const add of plan.added) {
+      const name = normalizeRequirementName(add.name);
+      if (addedNames.has(name)) {
+        throw new Error(
+          `${specName} validation failed - duplicate requirement in ADDED for header "### Requirement: ${add.name}"`
+        );
+      }
+      addedNames.add(name);
+    }
+    const modifiedNames = new Set<string>();
+    for (const mod of plan.modified) {
+      const name = normalizeRequirementName(mod.name);
+      if (modifiedNames.has(name)) {
+        throw new Error(
+          `${specName} validation failed - duplicate requirement in MODIFIED for header "### Requirement: ${mod.name}"`
+        );
+      }
+      modifiedNames.add(name);
+    }
+    const removedNamesSet = new Set<string>();
+    for (const rem of plan.removed) {
+      const name = normalizeRequirementName(rem);
+      if (removedNamesSet.has(name)) {
+        throw new Error(
+          `${specName} validation failed - duplicate requirement in REMOVED for header "### Requirement: ${rem}"`
+        );
+      }
+      removedNamesSet.add(name);
+    }
+    const renamedFromSet = new Set<string>();
+    const renamedToSet = new Set<string>();
+    for (const { from, to } of plan.renamed) {
+      const fromNorm = normalizeRequirementName(from);
+      const toNorm = normalizeRequirementName(to);
+      if (renamedFromSet.has(fromNorm)) {
+        throw new Error(
+          `${specName} validation failed - duplicate FROM in RENAMED for header "### Requirement: ${from}"`
+        );
+      }
+      if (renamedToSet.has(toNorm)) {
+        throw new Error(
+          `${specName} validation failed - duplicate TO in RENAMED for header "### Requirement: ${to}"`
+        );
+      }
+      renamedFromSet.add(fromNorm);
+      renamedToSet.add(toNorm);
+    }
+
+    // Pre-validate cross-section conflicts
+    const conflicts: Array<{ name: string; a: string; b: string }> = [];
+    for (const n of modifiedNames) {
+      if (removedNamesSet.has(n)) conflicts.push({ name: n, a: 'MODIFIED', b: 'REMOVED' });
+      if (addedNames.has(n)) conflicts.push({ name: n, a: 'MODIFIED', b: 'ADDED' });
+    }
+    for (const n of addedNames) {
+      if (removedNamesSet.has(n)) conflicts.push({ name: n, a: 'ADDED', b: 'REMOVED' });
+    }
+    // Renamed interplay: MODIFIED must reference the NEW header, not FROM
+    for (const { from, to } of plan.renamed) {
+      const fromNorm = normalizeRequirementName(from);
+      const toNorm = normalizeRequirementName(to);
+      if (modifiedNames.has(fromNorm)) {
+        throw new Error(
+          `${specName} validation failed - when a rename exists, MODIFIED must reference the NEW header "### Requirement: ${to}"`
+        );
+      }
+      // Detect ADDED colliding with a RENAMED TO
+      if (addedNames.has(toNorm)) {
+        throw new Error(
+          `${specName} validation failed - RENAMED TO header collides with ADDED for "### Requirement: ${to}"`
+        );
+      }
+    }
+    if (conflicts.length > 0) {
+      const c = conflicts[0];
+      throw new Error(
+        `${specName} validation failed - requirement present in multiple sections (${c.a} and ${c.b}) for header "### Requirement: ${c.name}"`
+      );
+    }
+    const hasAnyDelta = (plan.added.length + plan.modified.length + plan.removed.length + plan.renamed.length) > 0;
+    if (!hasAnyDelta) {
+      throw new Error(
+        `Delta parsing found no operations for ${path.basename(path.dirname(update.source))}. ` +
+        `Provide ADDED/MODIFIED/REMOVED/RENAMED sections in change spec.`
+      );
+    }
+
+    // Load or create base target content
+    let targetContent: string;
+    try {
+      targetContent = await fs.readFile(update.target, 'utf-8');
+    } catch {
+      // Target spec does not exist; only ADDED operations are permitted
+      if (plan.modified.length > 0 || plan.removed.length > 0 || plan.renamed.length > 0) {
+        throw new Error(
+          `${specName}: target spec does not exist; only ADDED requirements are allowed for new specs.`
+        );
+      }
+      targetContent = this.buildSpecSkeleton(specName, changeName);
+    }
+
+    // Extract requirements section and build name->block map
+    const parts = extractRequirementsSection(targetContent);
+    const nameToBlock = new Map<string, RequirementBlock>();
+    for (const block of parts.bodyBlocks) {
+      nameToBlock.set(normalizeRequirementName(block.name), block);
+    }
+
+    // Apply operations in order: RENAMED → REMOVED → MODIFIED → ADDED
+    // RENAMED
+    for (const r of plan.renamed) {
+      const from = normalizeRequirementName(r.from);
+      const to = normalizeRequirementName(r.to);
+      if (!nameToBlock.has(from)) {
+        throw new Error(
+          `${specName} RENAMED failed for header "### Requirement: ${r.from}" - source not found`
+        );
+      }
+      if (nameToBlock.has(to)) {
+        throw new Error(
+          `${specName} RENAMED failed for header "### Requirement: ${r.to}" - target already exists`
+        );
+      }
+      const block = nameToBlock.get(from)!;
+      const newHeader = `### Requirement: ${to}`;
+      const rawLines = block.raw.split('\n');
+      rawLines[0] = newHeader;
+      const renamedBlock: RequirementBlock = {
+        headerLine: newHeader,
+        name: to,
+        raw: rawLines.join('\n'),
+      };
+      nameToBlock.delete(from);
+      nameToBlock.set(to, renamedBlock);
+    }
+
+    // REMOVED
+    for (const name of plan.removed) {
+      const key = normalizeRequirementName(name);
+      if (!nameToBlock.has(key)) {
+        throw new Error(
+          `${specName} REMOVED failed for header "### Requirement: ${name}" - not found`
+        );
+      }
+      nameToBlock.delete(key);
+    }
+
+    // MODIFIED
+    for (const mod of plan.modified) {
+      const key = normalizeRequirementName(mod.name);
+      if (!nameToBlock.has(key)) {
+        throw new Error(
+          `${specName} MODIFIED failed for header "### Requirement: ${mod.name}" - not found`
+        );
+      }
+      // Replace block with provided raw (ensure header line matches key)
+      const modHeaderMatch = mod.raw.split('\n')[0].match(/^###\s*Requirement:\s*(.+)\s*$/);
+      if (!modHeaderMatch || normalizeRequirementName(modHeaderMatch[1]) !== key) {
+        throw new Error(
+          `${specName} MODIFIED failed for header "### Requirement: ${mod.name}" - header mismatch in content`
+        );
+      }
+      nameToBlock.set(key, mod);
+    }
+
+    // ADDED
+    for (const add of plan.added) {
+      const key = normalizeRequirementName(add.name);
+      if (nameToBlock.has(key)) {
+        throw new Error(
+          `${specName} ADDED failed for header "### Requirement: ${add.name}" - already exists`
+        );
+      }
+      nameToBlock.set(key, add);
+    }
+
+    // Duplicates within resulting map are implicitly prevented by key uniqueness.
+
+    // Recompose requirements section preserving original ordering where possible
+    const keptOrder: RequirementBlock[] = [];
+    const seen = new Set<string>();
+    for (const block of parts.bodyBlocks) {
+      const key = normalizeRequirementName(block.name);
+      const replacement = nameToBlock.get(key);
+      if (replacement) {
+        keptOrder.push(replacement);
+        seen.add(key);
+      }
+    }
+    // Append any newly added that were not in original order
+    for (const [key, block] of nameToBlock.entries()) {
+      if (!seen.has(key)) {
+        keptOrder.push(block);
+      }
+    }
+
+    const reqBody = [
+      parts.preamble && parts.preamble.trim() ? parts.preamble.trimEnd() : ''
+    ]
+      .filter(Boolean)
+      .concat(keptOrder.map(b => b.raw))
+      .join('\n\n')
+      .trimEnd();
+
+    const rebuilt = [
+      parts.before.trimEnd(),
+      parts.headerLine,
+      reqBody,
+      parts.after
+    ]
+      .filter((s, idx) => !(idx === 0 && s === ''))
+      .join('\n')
+      .replace(/\n{3,}/g, '\n\n');
+
+    return {
+      rebuilt,
+      counts: {
+        added: plan.added.length,
+        modified: plan.modified.length,
+        removed: plan.removed.length,
+        renamed: plan.renamed.length,
+      }
+    };
+  }
+
+  private async writeUpdatedSpec(update: SpecUpdate, rebuilt: string, counts: { added: number; modified: number; removed: number; renamed: number }): Promise<void> {
+    // Create target directory if needed
+    const targetDir = path.dirname(update.target);
+    await fs.mkdir(targetDir, { recursive: true });
+    await fs.writeFile(update.target, rebuilt);
+
+    const specName = path.basename(path.dirname(update.target));
+    console.log(`Applying changes to openspec/specs/${specName}/spec.md:`);
+    if (counts.added) console.log(`  + ${counts.added} added`);
+    if (counts.modified) console.log(`  ~ ${counts.modified} modified`);
+    if (counts.removed) console.log(`  - ${counts.removed} removed`);
+    if (counts.renamed) console.log(`  → ${counts.renamed} renamed`);
+  }
+
+  private buildSpecSkeleton(specFolderName: string, changeName: string): string {
+    const titleBase = specFolderName;
+    return `# ${titleBase} Specification\n\n## Purpose\nTBD - created by archiving change ${changeName}. Update Purpose after archive.\n\n## Requirements\n`;
+  }
+
+  private getArchiveDate(): string {
+    // Returns date in YYYY-MM-DD format
+    return new Date().toISOString().split('T')[0];
+  }
+}

src/core/converters/json-converter.ts

@@ -0,0 +1,59 @@
+import { readFileSync } from 'fs';
+import path from 'path';
+import { MarkdownParser } from '../parsers/markdown-parser.js';
+import { ChangeParser } from '../parsers/change-parser.js';
+import { Spec, Change } from '../schemas/index.js';
+
+export class JsonConverter {
+  convertSpecToJson(filePath: string): string {
+    const content = readFileSync(filePath, 'utf-8');
+    const parser = new MarkdownParser(content);
+    const specName = this.extractNameFromPath(filePath);
+    
+    const spec = parser.parseSpec(specName);
+    
+    const jsonSpec = {
+      ...spec,
+      metadata: {
+        ...spec.metadata,
+        sourcePath: filePath,
+      },
+    };
+    
+    return JSON.stringify(jsonSpec, null, 2);
+  }
+
+  async convertChangeToJson(filePath: string): Promise<string> {
+    const content = readFileSync(filePath, 'utf-8');
+    const changeName = this.extractNameFromPath(filePath);
+    const changeDir = path.dirname(filePath);
+    const parser = new ChangeParser(content, changeDir);
+    
+    const change = await parser.parseChangeWithDeltas(changeName);
+    
+    const jsonChange = {
+      ...change,
+      metadata: {
+        ...change.metadata,
+        sourcePath: filePath,
+      },
+    };
+    
+    return JSON.stringify(jsonChange, null, 2);
+  }
+
+  private extractNameFromPath(filePath: string): string {
+    const parts = filePath.split('/');
+    
+    for (let i = parts.length - 1; i >= 0; i--) {
+      if (parts[i] === 'specs' || parts[i] === 'changes') {
+        if (i < parts.length - 1) {
+          return parts[i + 1];
+        }
+      }
+    }
+    
+    const fileName = parts[parts.length - 1];
+    return fileName.replace('.md', '');
+  }
+}

src/core/diff.ts

@@ -3,6 +3,7 @@ import path from 'path';
 import chalk from 'chalk';
 import { diffStringsUnified } from 'jest-diff';
 import { select } from '@inquirer/prompts';
+import { Validator } from './validation/validator.js';
 
 // Constants
 const ARCHIVE_DIR = 'archive';
@@ -47,6 +48,53 @@ export class DiffCommand {
       return;
     }
 
+    // Validate specs and show warnings (non-blocking)
+    const validator = new Validator();
+    let hasWarnings = false;
+    
+    try {
+      const entries = await fs.readdir(changeSpecsDir, { withFileTypes: true });
+      
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          const specFile = path.join(changeSpecsDir, entry.name, 'spec.md');
+          
+          try {
+            await fs.access(specFile);
+            const report = await validator.validateSpec(specFile);
+            
+            if (report.issues.length > 0) {
+              const warnings = report.issues.filter(i => i.level === 'WARNING');
+              const errors = report.issues.filter(i => i.level === 'ERROR');
+              
+              if (errors.length > 0 || warnings.length > 0) {
+                if (!hasWarnings) {
+                  console.log(chalk.yellow('\n⚠️  Validation warnings found:'));
+                  hasWarnings = true;
+                }
+                
+                console.log(chalk.yellow(`\n  ${entry.name}/spec.md:`));
+                for (const issue of errors) {
+                  console.log(chalk.red(`    ✗ ${issue.message}`));
+                }
+                for (const issue of warnings) {
+                  console.log(chalk.yellow(`    ⚠ ${issue.message}`));
+                }
+              }
+            }
+          } catch {
+            // Spec file doesn't exist, skip validation
+          }
+        }
+      }
+      
+      if (hasWarnings) {
+        console.log(chalk.yellow('\nConsider fixing these issues before archiving.\n'));
+      }
+    } catch {
+      // No specs directory, skip validation
+    }
+
     // Reset counters
     this.filesChanged = 0;
     this.linesAdded = 0;
@@ -82,7 +130,7 @@ export class DiffCommand {
       choices
     });
 
-    return answer;
+    return answer as string;
   }
 
   private async showDiffs(changeSpecsDir: string): Promise<void> {

src/core/init.ts

@@ -64,7 +64,7 @@ export class InitCommand {
       }))
     });
     
-    config.aiTools = [selectedTool];
+    config.aiTools = [selectedTool as string];
 
     return config;
   }

src/core/list.ts

@@ -0,0 +1,60 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import { getTaskProgressForChange, formatTaskStatus } from '../utils/task-progress.js';
+
+interface ChangeInfo {
+  name: string;
+  completedTasks: number;
+  totalTasks: number;
+}
+
+export class ListCommand {
+  async execute(targetPath: string = '.'): Promise<void> {
+    const changesDir = path.join(targetPath, 'openspec', 'changes');
+    
+    // Check if changes directory exists
+    try {
+      await fs.access(changesDir);
+    } catch {
+      throw new Error("No OpenSpec changes directory found. Run 'openspec init' first.");
+    }
+
+    // Get all directories in changes (excluding archive)
+    const entries = await fs.readdir(changesDir, { withFileTypes: true });
+    const changeDirs = entries
+      .filter(entry => entry.isDirectory() && entry.name !== 'archive')
+      .map(entry => entry.name);
+
+    if (changeDirs.length === 0) {
+      console.log('No active changes found.');
+      return;
+    }
+
+    // Collect information about each change
+    const changes: ChangeInfo[] = [];
+    
+    for (const changeDir of changeDirs) {
+      const progress = await getTaskProgressForChange(changesDir, changeDir);
+      changes.push({
+        name: changeDir,
+        completedTasks: progress.completed,
+        totalTasks: progress.total
+      });
+    }
+
+    // Sort alphabetically by name
+    changes.sort((a, b) => a.name.localeCompare(b.name));
+
+    // Display results
+    console.log('Changes:');
+    for (const change of changes) {
+      const padding = '  ';
+      const nameWidth = Math.max(...changes.map(c => c.name.length));
+      const paddedName = change.name.padEnd(nameWidth);
+      
+      const status = formatTaskStatus({ total: change.totalTasks, completed: change.completedTasks });
+      
+      console.log(`${padding}${paddedName}     ${status}`);
+    }
+  }
+}

src/core/parsers/change-parser.ts

@@ -0,0 +1,233 @@
+import { MarkdownParser, Section } from './markdown-parser.js';
+import { Change, Delta, DeltaOperation, Requirement } from '../schemas/index.js';
+import path from 'path';
+import { promises as fs } from 'fs';
+
+interface DeltaSection {
+  operation: DeltaOperation;
+  requirements: Requirement[];
+  renames?: Array<{ from: string; to: string }>;
+}
+
+export class ChangeParser extends MarkdownParser {
+  private changeDir: string;
+
+  constructor(content: string, changeDir: string) {
+    super(content);
+    this.changeDir = changeDir;
+  }
+
+  async parseChangeWithDeltas(name: string): Promise<Change> {
+    const sections = this.parseSections();
+    const why = this.findSection(sections, 'Why')?.content || '';
+    const whatChanges = this.findSection(sections, 'What Changes')?.content || '';
+    
+    if (!why) {
+      throw new Error('Change must have a Why section');
+    }
+    
+    if (!whatChanges) {
+      throw new Error('Change must have a What Changes section');
+    }
+
+    // Parse deltas from the What Changes section (simple format)
+    const simpleDeltas = this.parseDeltas(whatChanges);
+    
+    // Check if there are spec files with delta format
+    const specsDir = path.join(this.changeDir, 'specs');
+    const deltaDeltas = await this.parseDeltaSpecs(specsDir);
+    
+    // Combine both types of deltas, preferring delta format if available
+    const deltas = deltaDeltas.length > 0 ? deltaDeltas : simpleDeltas;
+
+    return {
+      name,
+      why: why.trim(),
+      whatChanges: whatChanges.trim(),
+      deltas,
+      metadata: {
+        version: '1.0.0',
+        format: 'openspec-change',
+      },
+    };
+  }
+
+  private async parseDeltaSpecs(specsDir: string): Promise<Delta[]> {
+    const deltas: Delta[] = [];
+    
+    try {
+      const specDirs = await fs.readdir(specsDir, { withFileTypes: true });
+      
+      for (const dir of specDirs) {
+        if (!dir.isDirectory()) continue;
+        
+        const specName = dir.name;
+        const specFile = path.join(specsDir, specName, 'spec.md');
+        
+        try {
+          const content = await fs.readFile(specFile, 'utf-8');
+          const specDeltas = this.parseSpecDeltas(specName, content);
+          deltas.push(...specDeltas);
+        } catch (error) {
+          // Spec file might not exist, which is okay
+          continue;
+        }
+      }
+    } catch (error) {
+      // Specs directory might not exist, which is okay
+      return [];
+    }
+    
+    return deltas;
+  }
+
+  private parseSpecDeltas(specName: string, content: string): Delta[] {
+    const deltas: Delta[] = [];
+    const sections = this.parseSectionsFromContent(content);
+    
+    // Parse ADDED requirements
+    const addedSection = this.findSection(sections, 'ADDED Requirements');
+    if (addedSection) {
+      const requirements = this.parseRequirements(addedSection);
+      requirements.forEach(req => {
+        deltas.push({
+          spec: specName,
+          operation: 'ADDED' as DeltaOperation,
+          description: `Add requirement: ${req.text}`,
+          // Provide both single and plural forms for compatibility
+          requirement: req,
+          requirements: [req],
+        });
+      });
+    }
+    
+    // Parse MODIFIED requirements
+    const modifiedSection = this.findSection(sections, 'MODIFIED Requirements');
+    if (modifiedSection) {
+      const requirements = this.parseRequirements(modifiedSection);
+      requirements.forEach(req => {
+        deltas.push({
+          spec: specName,
+          operation: 'MODIFIED' as DeltaOperation,
+          description: `Modify requirement: ${req.text}`,
+          requirement: req,
+          requirements: [req],
+        });
+      });
+    }
+    
+    // Parse REMOVED requirements
+    const removedSection = this.findSection(sections, 'REMOVED Requirements');
+    if (removedSection) {
+      const requirements = this.parseRequirements(removedSection);
+      requirements.forEach(req => {
+        deltas.push({
+          spec: specName,
+          operation: 'REMOVED' as DeltaOperation,
+          description: `Remove requirement: ${req.text}`,
+          requirement: req,
+          requirements: [req],
+        });
+      });
+    }
+    
+    // Parse RENAMED requirements
+    const renamedSection = this.findSection(sections, 'RENAMED Requirements');
+    if (renamedSection) {
+      const renames = this.parseRenames(renamedSection.content);
+      renames.forEach(rename => {
+        deltas.push({
+          spec: specName,
+          operation: 'RENAMED' as DeltaOperation,
+          description: `Rename requirement from "${rename.from}" to "${rename.to}"`,
+          rename,
+        });
+      });
+    }
+    
+    return deltas;
+  }
+
+  private parseRenames(content: string): Array<{ from: string; to: string }> {
+    const renames: Array<{ from: string; to: string }> = [];
+    const lines = content.split('\n');
+    
+    let currentRename: { from?: string; to?: string } = {};
+    
+    for (const line of lines) {
+      const fromMatch = line.match(/^\s*-?\s*FROM:\s*`?###\s*Requirement:\s*(.+?)`?\s*$/);
+      const toMatch = line.match(/^\s*-?\s*TO:\s*`?###\s*Requirement:\s*(.+?)`?\s*$/);
+      
+      if (fromMatch) {
+        currentRename.from = fromMatch[1].trim();
+      } else if (toMatch) {
+        currentRename.to = toMatch[1].trim();
+        
+        if (currentRename.from && currentRename.to) {
+          renames.push({
+            from: currentRename.from,
+            to: currentRename.to,
+          });
+          currentRename = {};
+        }
+      }
+    }
+    
+    return renames;
+  }
+
+  private parseSectionsFromContent(content: string): Section[] {
+    const lines = content.split('\n');
+    const sections: Section[] = [];
+    const stack: Section[] = [];
+    
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const headerMatch = line.match(/^(#{1,6})\s+(.+)$/);
+      
+      if (headerMatch) {
+        const level = headerMatch[1].length;
+        const title = headerMatch[2].trim();
+        const contentLines = this.getContentUntilNextHeaderFromLines(lines, i + 1, level);
+        
+        const section = {
+          level,
+          title,
+          content: contentLines.join('\n').trim(),
+          children: [],
+        };
+
+        while (stack.length > 0 && stack[stack.length - 1].level >= level) {
+          stack.pop();
+        }
+
+        if (stack.length === 0) {
+          sections.push(section);
+        } else {
+          stack[stack.length - 1].children.push(section);
+        }
+        
+        stack.push(section);
+      }
+    }
+    
+    return sections;
+  }
+
+  private getContentUntilNextHeaderFromLines(lines: string[], startLine: number, currentLevel: number): string[] {
+    const contentLines: string[] = [];
+    
+    for (let i = startLine; i < lines.length; i++) {
+      const line = lines[i];
+      const headerMatch = line.match(/^(#{1,6})\s+/);
+      
+      if (headerMatch && headerMatch[1].length <= currentLevel) {
+        break;
+      }
+      
+      contentLines.push(line);
+    }
+    
+    return contentLines;
+  }
+}

src/core/parsers/markdown-parser.ts

@@ -0,0 +1,232 @@
+import { Spec, Change, Requirement, Scenario, Delta, DeltaOperation } from '../schemas/index.js';
+
+export interface Section {
+  level: number;
+  title: string;
+  content: string;
+  children: Section[];
+}
+
+export class MarkdownParser {
+  private lines: string[];
+  private currentLine: number;
+
+  constructor(content: string) {
+    this.lines = content.split('\n');
+    this.currentLine = 0;
+  }
+
+  parseSpec(name: string): Spec {
+    const sections = this.parseSections();
+    const purpose = this.findSection(sections, 'Purpose')?.content || '';
+    
+    const requirementsSection = this.findSection(sections, 'Requirements');
+    
+    if (!purpose) {
+      throw new Error('Spec must have a Purpose section');
+    }
+    
+    if (!requirementsSection) {
+      throw new Error('Spec must have a Requirements section');
+    }
+
+    const requirements = this.parseRequirements(requirementsSection);
+
+    return {
+      name,
+      overview: purpose.trim(),
+      requirements,
+      metadata: {
+        version: '1.0.0',
+        format: 'openspec',
+      },
+    };
+  }
+
+  parseChange(name: string): Change {
+    const sections = this.parseSections();
+    const why = this.findSection(sections, 'Why')?.content || '';
+    const whatChanges = this.findSection(sections, 'What Changes')?.content || '';
+    
+    if (!why) {
+      throw new Error('Change must have a Why section');
+    }
+    
+    if (!whatChanges) {
+      throw new Error('Change must have a What Changes section');
+    }
+
+    const deltas = this.parseDeltas(whatChanges);
+
+    return {
+      name,
+      why: why.trim(),
+      whatChanges: whatChanges.trim(),
+      deltas,
+      metadata: {
+        version: '1.0.0',
+        format: 'openspec-change',
+      },
+    };
+  }
+
+  protected parseSections(): Section[] {
+    const sections: Section[] = [];
+    const stack: Section[] = [];
+    
+    for (let i = 0; i < this.lines.length; i++) {
+      const line = this.lines[i];
+      const headerMatch = line.match(/^(#{1,6})\s+(.+)$/);
+      
+      if (headerMatch) {
+        const level = headerMatch[1].length;
+        const title = headerMatch[2].trim();
+        const content = this.getContentUntilNextHeader(i + 1, level);
+        
+        const section: Section = {
+          level,
+          title,
+          content,
+          children: [],
+        };
+
+        while (stack.length > 0 && stack[stack.length - 1].level >= level) {
+          stack.pop();
+        }
+
+        if (stack.length === 0) {
+          sections.push(section);
+        } else {
+          stack[stack.length - 1].children.push(section);
+        }
+        
+        stack.push(section);
+      }
+    }
+    
+    return sections;
+  }
+
+  protected getContentUntilNextHeader(startLine: number, currentLevel: number): string {
+    const contentLines: string[] = [];
+    
+    for (let i = startLine; i < this.lines.length; i++) {
+      const line = this.lines[i];
+      const headerMatch = line.match(/^(#{1,6})\s+/);
+      
+      if (headerMatch && headerMatch[1].length <= currentLevel) {
+        break;
+      }
+      
+      contentLines.push(line);
+    }
+    
+    return contentLines.join('\n').trim();
+  }
+
+  protected findSection(sections: Section[], title: string): Section | undefined {
+    for (const section of sections) {
+      if (section.title.toLowerCase() === title.toLowerCase()) {
+        return section;
+      }
+      const child = this.findSection(section.children, title);
+      if (child) {
+        return child;
+      }
+    }
+    return undefined;
+  }
+
+  protected parseRequirements(section: Section): Requirement[] {
+    const requirements: Requirement[] = [];
+    
+    for (const child of section.children) {
+      // Extract requirement text from first non-empty content line, fall back to heading
+      let text = child.title;
+      
+      // Get content before any child sections (scenarios)
+      if (child.content.trim()) {
+        // Split content into lines and find content before any child headers
+        const lines = child.content.split('\n');
+        const contentBeforeChildren: string[] = [];
+        
+        for (const line of lines) {
+          // Stop at child headers (scenarios start with ####)
+          if (line.trim().startsWith('#')) {
+            break;
+          }
+          contentBeforeChildren.push(line);
+        }
+        
+        // Find first non-empty line
+        const directContent = contentBeforeChildren.join('\n').trim();
+        if (directContent) {
+          const firstLine = directContent.split('\n').find(l => l.trim());
+          if (firstLine) {
+            text = firstLine.trim();
+          }
+        }
+      }
+      
+      const scenarios = this.parseScenarios(child);
+      
+      requirements.push({
+        text,
+        scenarios,
+      });
+    }
+    
+    return requirements;
+  }
+
+  protected parseScenarios(requirementSection: Section): Scenario[] {
+    const scenarios: Scenario[] = [];
+    
+    for (const scenarioSection of requirementSection.children) {
+      // Store the raw text content of the scenario section
+      if (scenarioSection.content.trim()) {
+        scenarios.push({
+          rawText: scenarioSection.content
+        });
+      }
+    }
+    
+    return scenarios;
+  }
+
+
+  protected parseDeltas(content: string): Delta[] {
+    const deltas: Delta[] = [];
+    const lines = content.split('\n');
+    
+    for (const line of lines) {
+      // Match both formats: **spec:** and **spec**:
+      const deltaMatch = line.match(/^\s*-\s*\*\*([^*:]+)(?::\*\*|\*\*:)\s*(.+)$/);
+      if (deltaMatch) {
+        const specName = deltaMatch[1].trim();
+        const description = deltaMatch[2].trim();
+        
+        let operation: DeltaOperation = 'MODIFIED';
+        const lowerDesc = description.toLowerCase();
+        
+        // Use word boundaries to avoid false matches (e.g., "address" matching "add")
+        // Check RENAMED first since it's more specific than patterns containing "new"
+        if (/\brename(s|d|ing)?\b/.test(lowerDesc) || /\brenamed\s+(to|from)\b/.test(lowerDesc)) {
+          operation = 'RENAMED';
+        } else if (/\badd(s|ed|ing)?\b/.test(lowerDesc) || /\bcreate(s|d|ing)?\b/.test(lowerDesc) || /\bnew\b/.test(lowerDesc)) {
+          operation = 'ADDED';
+        } else if (/\bremove(s|d|ing)?\b/.test(lowerDesc) || /\bdelete(s|d|ing)?\b/.test(lowerDesc)) {
+          operation = 'REMOVED';
+        }
+        
+        deltas.push({
+          spec: specName,
+          operation,
+          description,
+        });
+      }
+    }
+    
+    return deltas;
+  }
+}

src/core/parsers/requirement-blocks.ts

@@ -0,0 +1,201 @@
+export interface RequirementBlock {
+  headerLine: string; // e.g., '### Requirement: Something'
+  name: string; // e.g., 'Something'
+  raw: string; // full block including headerLine and following content
+}
+
+export interface RequirementsSectionParts {
+  before: string;
+  headerLine: string; // the '## Requirements' line
+  preamble: string; // content between headerLine and first requirement block
+  bodyBlocks: RequirementBlock[]; // parsed requirement blocks in order
+  after: string;
+}
+
+export function normalizeRequirementName(name: string): string {
+  return name.trim();
+}
+
+const REQUIREMENT_HEADER_REGEX = /^###\s*Requirement:\s*(.+)\s*$/;
+
+/**
+ * Extracts the Requirements section from a spec file and parses requirement blocks.
+ */
+export function extractRequirementsSection(content: string): RequirementsSectionParts {
+  const lines = content.split('\n');
+  const reqHeaderIndex = lines.findIndex(l => /^##\s+Requirements\s*$/i.test(l));
+
+  if (reqHeaderIndex === -1) {
+    // No requirements section; create an empty one at the end
+    const before = content.trimEnd();
+    const headerLine = '## Requirements';
+    return {
+      before: before ? before + '\n\n' : '',
+      headerLine,
+      preamble: '',
+      bodyBlocks: [],
+      after: '\n',
+    };
+  }
+
+  // Find end of this section: next line that starts with '## ' at same or higher level
+  let endIndex = lines.length;
+  for (let i = reqHeaderIndex + 1; i < lines.length; i++) {
+    if (/^##\s+/.test(lines[i])) {
+      endIndex = i;
+      break;
+    }
+  }
+
+  const before = lines.slice(0, reqHeaderIndex).join('\n');
+  const headerLine = lines[reqHeaderIndex];
+  const sectionBodyLines = lines.slice(reqHeaderIndex + 1, endIndex);
+
+  // Parse requirement blocks within section body
+  const blocks: RequirementBlock[] = [];
+  let cursor = 0;
+  let preambleLines: string[] = [];
+
+  // Collect preamble lines until first requirement header
+  while (cursor < sectionBodyLines.length && !/^###\s+Requirement:/.test(sectionBodyLines[cursor])) {
+    preambleLines.push(sectionBodyLines[cursor]);
+    cursor++;
+  }
+
+  while (cursor < sectionBodyLines.length) {
+    const headerStart = cursor;
+    const headerLineCandidate = sectionBodyLines[cursor];
+    const headerMatch = headerLineCandidate.match(REQUIREMENT_HEADER_REGEX);
+    if (!headerMatch) {
+      // Not a requirement header; skip line defensively
+      cursor++;
+      continue;
+    }
+    const name = normalizeRequirementName(headerMatch[1]);
+    cursor++;
+    // Gather lines until next requirement header or end of section
+    const bodyLines: string[] = [headerLineCandidate];
+    while (cursor < sectionBodyLines.length && !/^###\s+Requirement:/.test(sectionBodyLines[cursor]) && !/^##\s+/.test(sectionBodyLines[cursor])) {
+      bodyLines.push(sectionBodyLines[cursor]);
+      cursor++;
+    }
+    const raw = bodyLines.join('\n').trimEnd();
+    blocks.push({ headerLine: headerLineCandidate, name, raw });
+  }
+
+  const after = lines.slice(endIndex).join('\n');
+  const preamble = preambleLines.join('\n').trimEnd();
+
+  return {
+    before: before.trimEnd() ? before + '\n' : before,
+    headerLine,
+    preamble,
+    bodyBlocks: blocks,
+    after: after.startsWith('\n') ? after : '\n' + after,
+  };
+}
+
+export interface DeltaPlan {
+  added: RequirementBlock[];
+  modified: RequirementBlock[];
+  removed: string[]; // requirement names
+  renamed: Array<{ from: string; to: string }>;
+}
+
+/**
+ * Parse a delta-formatted spec change file content into a DeltaPlan with raw blocks.
+ */
+export function parseDeltaSpec(content: string): DeltaPlan {
+  const sections = splitTopLevelSections(content);
+  const added = parseRequirementBlocksFromSection(sections['ADDED Requirements'] || '');
+  const modified = parseRequirementBlocksFromSection(sections['MODIFIED Requirements'] || '');
+  const removedNames = parseRemovedNames(sections['REMOVED Requirements'] || '');
+  const renamedPairs = parseRenamedPairs(sections['RENAMED Requirements'] || '');
+  return { added, modified, removed: removedNames, renamed: renamedPairs };
+}
+
+function splitTopLevelSections(content: string): Record<string, string> {
+  const lines = content.split('\n');
+  const result: Record<string, string> = {};
+  const indices: Array<{ title: string; index: number; level: number }> = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^(##)\s+(.+)$/);
+    if (m) {
+      const level = m[1].length; // only care for '##'
+      indices.push({ title: m[2].trim(), index: i, level });
+    }
+  }
+  for (let i = 0; i < indices.length; i++) {
+    const current = indices[i];
+    const next = indices[i + 1];
+    const body = lines.slice(current.index + 1, next ? next.index : lines.length).join('\n');
+    result[current.title] = body;
+  }
+  return result;
+}
+
+function parseRequirementBlocksFromSection(sectionBody: string): RequirementBlock[] {
+  if (!sectionBody) return [];
+  const lines = sectionBody.split('\n');
+  const blocks: RequirementBlock[] = [];
+  let i = 0;
+  while (i < lines.length) {
+    // Seek next requirement header
+    while (i < lines.length && !/^###\s+Requirement:/.test(lines[i])) i++;
+    if (i >= lines.length) break;
+    const headerLine = lines[i];
+    const m = headerLine.match(REQUIREMENT_HEADER_REGEX);
+    if (!m) { i++; continue; }
+    const name = normalizeRequirementName(m[1]);
+    const buf: string[] = [headerLine];
+    i++;
+    while (i < lines.length && !/^###\s+Requirement:/.test(lines[i]) && !/^##\s+/.test(lines[i])) {
+      buf.push(lines[i]);
+      i++;
+    }
+    blocks.push({ headerLine, name, raw: buf.join('\n').trimEnd() });
+  }
+  return blocks;
+}
+
+function parseRemovedNames(sectionBody: string): string[] {
+  if (!sectionBody) return [];
+  const names: string[] = [];
+  const lines = sectionBody.split('\n');
+  for (const line of lines) {
+    const m = line.match(REQUIREMENT_HEADER_REGEX);
+    if (m) {
+      names.push(normalizeRequirementName(m[1]));
+      continue;
+    }
+    // Also support bullet list of headers
+    const bullet = line.match(/^\s*-\s*`?###\s*Requirement:\s*(.+?)`?\s*$/);
+    if (bullet) {
+      names.push(normalizeRequirementName(bullet[1]));
+    }
+  }
+  return names;
+}
+
+function parseRenamedPairs(sectionBody: string): Array<{ from: string; to: string }> {
+  if (!sectionBody) return [];
+  const pairs: Array<{ from: string; to: string }> = [];
+  const lines = sectionBody.split('\n');
+  let current: { from?: string; to?: string } = {};
+  for (const line of lines) {
+    const fromMatch = line.match(/^\s*-?\s*FROM:\s*`?###\s*Requirement:\s*(.+?)`?\s*$/);
+    const toMatch = line.match(/^\s*-?\s*TO:\s*`?###\s*Requirement:\s*(.+?)`?\s*$/);
+    if (fromMatch) {
+      current.from = normalizeRequirementName(fromMatch[1]);
+    } else if (toMatch) {
+      current.to = normalizeRequirementName(toMatch[1]);
+      if (current.from && current.to) {
+        pairs.push({ from: current.from, to: current.to });
+        current = {};
+      }
+    }
+  }
+  return pairs;
+}
+
+

src/core/schemas/base.schema.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { VALIDATION_MESSAGES } from '../validation/constants.js';
+
+export const ScenarioSchema = z.object({
+  rawText: z.string().min(1, VALIDATION_MESSAGES.SCENARIO_EMPTY),
+});
+
+export const RequirementSchema = z.object({
+  text: z.string()
+    .min(1, VALIDATION_MESSAGES.REQUIREMENT_EMPTY)
+    .refine(
+      (text) => text.includes('SHALL') || text.includes('MUST'),
+      VALIDATION_MESSAGES.REQUIREMENT_NO_SHALL
+    ),
+  scenarios: z.array(ScenarioSchema)
+    .min(1, VALIDATION_MESSAGES.REQUIREMENT_NO_SCENARIOS),
+});
+
+export type Scenario = z.infer<typeof ScenarioSchema>;
+export type Requirement = z.infer<typeof RequirementSchema>;

src/core/schemas/change.schema.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+import { RequirementSchema } from './base.schema.js';
+import { 
+  MIN_WHY_SECTION_LENGTH,
+  MAX_WHY_SECTION_LENGTH,
+  MAX_DELTAS_PER_CHANGE,
+  VALIDATION_MESSAGES 
+} from '../validation/constants.js';
+
+export const DeltaOperationType = z.enum(['ADDED', 'MODIFIED', 'REMOVED', 'RENAMED']);
+
+export const DeltaSchema = z.object({
+  spec: z.string().min(1, VALIDATION_MESSAGES.DELTA_SPEC_EMPTY),
+  operation: DeltaOperationType,
+  description: z.string().min(1, VALIDATION_MESSAGES.DELTA_DESCRIPTION_EMPTY),
+  requirement: RequirementSchema.optional(),
+  requirements: z.array(RequirementSchema).optional(),
+  rename: z.object({
+    from: z.string(),
+    to: z.string(),
+  }).optional(),
+});
+
+export const ChangeSchema = z.object({
+  name: z.string().min(1, VALIDATION_MESSAGES.CHANGE_NAME_EMPTY),
+  why: z.string()
+    .min(MIN_WHY_SECTION_LENGTH, VALIDATION_MESSAGES.CHANGE_WHY_TOO_SHORT)
+    .max(MAX_WHY_SECTION_LENGTH, VALIDATION_MESSAGES.CHANGE_WHY_TOO_LONG),
+  whatChanges: z.string().min(1, VALIDATION_MESSAGES.CHANGE_WHAT_EMPTY),
+  deltas: z.array(DeltaSchema)
+    .min(1, VALIDATION_MESSAGES.CHANGE_NO_DELTAS)
+    .max(MAX_DELTAS_PER_CHANGE, VALIDATION_MESSAGES.CHANGE_TOO_MANY_DELTAS),
+  metadata: z.object({
+    version: z.string().default('1.0.0'),
+    format: z.literal('openspec-change'),
+    sourcePath: z.string().optional(),
+  }).optional(),
+});
+
+export type DeltaOperation = z.infer<typeof DeltaOperationType>;
+export type Delta = z.infer<typeof DeltaSchema>;
+export type Change = z.infer<typeof ChangeSchema>;

src/core/schemas/index.ts

@@ -0,0 +1,20 @@
+export {
+  ScenarioSchema,
+  RequirementSchema,
+  type Scenario,
+  type Requirement,
+} from './base.schema.js';
+
+export {
+  SpecSchema,
+  type Spec,
+} from './spec.schema.js';
+
+export {
+  DeltaOperationType,
+  DeltaSchema,
+  ChangeSchema,
+  type DeltaOperation,
+  type Delta,
+  type Change,
+} from './change.schema.js';

src/core/schemas/spec.schema.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import { RequirementSchema } from './base.schema.js';
+import { VALIDATION_MESSAGES } from '../validation/constants.js';
+
+export const SpecSchema = z.object({
+  name: z.string().min(1, VALIDATION_MESSAGES.SPEC_NAME_EMPTY),
+  overview: z.string().min(1, VALIDATION_MESSAGES.SPEC_PURPOSE_EMPTY),
+  requirements: z.array(RequirementSchema)
+    .min(1, VALIDATION_MESSAGES.SPEC_NO_REQUIREMENTS),
+  metadata: z.object({
+    version: z.string().default('1.0.0'),
+    format: z.literal('openspec'),
+    sourcePath: z.string().optional(),
+  }).optional(),
+});
+
+export type Spec = z.infer<typeof SpecSchema>;

src/core/templates/project-template.ts

@@ -7,7 +7,7 @@ export interface ProjectContext {
 
 export const projectTemplate = (context: ProjectContext = {}) => `# ${context.projectName || 'Project'} Context
 
-## Overview
+## Purpose
 ${context.description || '[Describe your project\'s purpose and goals]'}
 
 ## Tech Stack

src/core/templates/readme-template.ts

@@ -43,9 +43,9 @@ openspec/
 │   │   ├── proposal.md     # Why, what, impact (consolidated)
 │   │   ├── tasks.md        # Implementation checklist
 │   │   ├── design.md       # Technical decisions (optional, for complex changes)
-│   │   └── specs/          # Future state of affected specs
+│   │   └── specs/          # Delta changes to specs
 │   │       └── [capability]/
-│   │           └── spec.md # Clean markdown (no diff syntax)
+│   │           └── spec.md # Delta format (ADDED/MODIFIED/REMOVED/RENAMED)
 │   └── archive/            # Completed changes (dated)
 \`\`\`
 
@@ -94,7 +94,35 @@ Before any task:
 - If adding dependencies, frameworks, or architectural patterns, document why simpler alternatives won't work
 - Default to single-file implementations until proven insufficient
 
-### 3. Creating a Change Proposal
+### 3. Delta-Based Change Format
+
+Changes use a delta format with clear sections:
+
+\`\`\`markdown
+## ADDED Requirements
+### Requirement: New Feature
+[Complete requirement content in structured format]
+
+## MODIFIED Requirements  
+### Requirement: Existing Feature
+[Complete modified requirement (header must match current spec)]
+
+## REMOVED Requirements
+### Requirement: Old Feature
+**Reason for removal**: [Why removing]
+**Migration path**: [How to handle existing usage]
+
+## RENAMED Requirements
+- FROM: \`### Requirement: Old Name\`
+- TO: \`### Requirement: New Name\`
+\`\`\`
+
+Key rules:
+- Headers are matched using \`normalize(header) = trim(header)\`
+- Include complete requirements (not diffs)
+- Use standard symbols in CLI output: + (added), ~ (modified), - (removed), → (renamed)
+
+### 4. Creating a Change Proposal
 
 When a user requests a significant change:
 
@@ -113,13 +141,21 @@ openspec/changes/[descriptive-name]/
 - Affected specs: [list capabilities that will change]
 - Affected code: [list key files/systems]
 
-# 3. Create future state specs for ALL affected capabilities
-# - Store complete spec files as they will exist after the change
-# - Use clean markdown without diff syntax (+/- prefixes)
-# - Include all formatting and structure of the final intended state
+# 3. Create delta specs for ALL affected capabilities
+# - Store only the changes (not complete future state)
+# - Use sections: ## ADDED, ## MODIFIED, ## REMOVED, ## RENAMED
+# - Include complete requirements in their final form
+# Example spec.md content:
+#   ## ADDED Requirements
+#   ### Requirement: Password Reset
+#   Users SHALL be able to reset passwords via email...
+#   
+#   ## MODIFIED Requirements
+#   ### Requirement: User Authentication
+#   [Complete modified requirement with new password reset hook]
 specs/
 └── [capability]/
-    └── spec.md
+    └── spec.md  # Contains delta sections
 
 # 4. Create tasks.md with implementation steps
 ## 1. [Task Group]
@@ -130,16 +166,16 @@ specs/
 [Technical decisions and trade-offs]
 \`\`\`
 
-### 4. The Change Lifecycle
+### 5. The Change Lifecycle
 
-1. **Propose** → Create change directory with all documentation
+1. **Propose** → Create change directory with delta-based documentation
 2. **Review** → User reviews and approves the proposal
 3. **Implement** → Follow the approved tasks.md (can be multiple PRs)
 4. **Deploy** → User confirms deployment
-5. **Update Specs** → Sync specs/ with new reality (IF the change affects system capabilities)
+5. **Update Specs** → Apply deltas to sync specs/ with new reality (IF the change affects system capabilities)
 6. **Archive** → Move to \`changes/archive/YYYY-MM-DD-[name]/\`
 
-### 5. Implementing Changes
+### 6. Implementing Changes
 
 When implementing an approved change:
 1. Follow the tasks.md checklist exactly
@@ -154,7 +190,7 @@ When implementing an approved change:
 - Different developers can work on different task groups
 - Example: PR #1 completes tasks 1.1-1.3, PR #2 completes tasks 2.1-2.4
 
-### 6. Updating Specs and Archiving After Deployment
+### 7. Updating Specs and Archiving After Deployment
 
 **Create a separate PR after deployment** that:
 1. Moves change to \`changes/archive/YYYY-MM-DD-[name]/\`
@@ -163,7 +199,7 @@ When implementing an approved change:
 
 This ensures changes are only archived when truly complete and deployed.
 
-### 7. Types of Changes That Don't Require Specs
+### 8. Types of Changes That Don't Require Specs
 
 Some changes only affect development infrastructure and don't need specs:
 - Initial project setup (package.json, tsconfig.json, etc.)
@@ -216,7 +252,16 @@ User: "Add password reset functionality"
 You should:
 1. Read specs/user-auth/spec.md
 2. Check changes/ for pending auth changes
-3. Create changes/add-password-reset/ with proposal
+3. Create changes/add-password-reset/ with:
+   - proposal.md describing the change
+   - specs/user-auth/spec.md with:
+     ## ADDED Requirements
+     ### Requirement: Password Reset
+     [Complete requirement for password reset]
+     
+     ## MODIFIED Requirements
+     ### Requirement: User Authentication
+     [Updated to integrate with password reset]
 4. Wait for approval before implementing
 \`\`\`
 

src/core/update.ts

@@ -1,8 +1,8 @@
 import path from 'path';
 import { FileSystemUtils } from '../utils/file-system.js';
-import { TemplateManager } from './templates/index.js';
-import { OPENSPEC_DIR_NAME, OPENSPEC_MARKERS } from './config.js';
+import { OPENSPEC_DIR_NAME } from './config.js';
 import { readmeTemplate } from './templates/readme-template.js';
+import { ToolRegistry } from './configurators/registry.js';
 
 export class UpdateCommand {
   async execute(projectPath: string): Promise<void> {
@@ -19,17 +19,37 @@ export class UpdateCommand {
     const readmePath = path.join(openspecPath, 'README.md');
     await FileSystemUtils.writeFile(readmePath, readmeTemplate);
 
-    // 3. Update CLAUDE.md (marker-based)
-    const claudePath = path.join(resolvedProjectPath, 'CLAUDE.md');
-    const claudeContent = TemplateManager.getClaudeTemplate();
-    await FileSystemUtils.updateFileWithMarkers(
-      claudePath,
-      claudeContent,
-      OPENSPEC_MARKERS.start,
-      OPENSPEC_MARKERS.end
-    );
+    // 3. Update existing AI tool configuration files only
+    const configurators = ToolRegistry.getAll();
+    let updatedFiles: string[] = [];
+    let failedFiles: string[] = [];
+    
+    for (const configurator of configurators) {
+      const configFilePath = path.join(resolvedProjectPath, configurator.configFileName);
+      
+      // Only update if the file already exists
+      if (await FileSystemUtils.fileExists(configFilePath)) {
+        try {
+          await configurator.configure(resolvedProjectPath, openspecPath);
+          updatedFiles.push(configurator.configFileName);
+        } catch (error) {
+          failedFiles.push(configurator.configFileName);
+          console.error(`Failed to update ${configurator.configFileName}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+      }
+    }
 
     // 4. Success message (ASCII-safe)
-    console.log('Updated OpenSpec instructions');
+    const messages: string[] = ['Updated OpenSpec instructions (README.md)'];
+    
+    if (updatedFiles.length > 0) {
+      messages.push(`Updated AI tool files: ${updatedFiles.join(', ')}`);
+    }
+    
+    if (failedFiles.length > 0) {
+      messages.push(`Failed to update: ${failedFiles.join(', ')}`);
+    }
+    
+    console.log(messages.join('\n'));
   }
 }

src/core/validation/constants.ts

@@ -0,0 +1,38 @@
+/**
+ * Validation threshold constants
+ */
+
+// Minimum character lengths
+export const MIN_WHY_SECTION_LENGTH = 50;
+export const MIN_PURPOSE_LENGTH = 50;
+
+// Maximum character/item limits
+export const MAX_WHY_SECTION_LENGTH = 1000;
+export const MAX_REQUIREMENT_TEXT_LENGTH = 500;
+export const MAX_DELTAS_PER_CHANGE = 10;
+
+// Validation messages
+export const VALIDATION_MESSAGES = {
+  // Required content
+  SCENARIO_EMPTY: 'Scenario text cannot be empty',
+  REQUIREMENT_EMPTY: 'Requirement text cannot be empty',
+  REQUIREMENT_NO_SHALL: 'Requirement must contain SHALL or MUST keyword',
+  REQUIREMENT_NO_SCENARIOS: 'Requirement must have at least one scenario',
+  SPEC_NAME_EMPTY: 'Spec name cannot be empty',
+  SPEC_PURPOSE_EMPTY: 'Purpose section cannot be empty',
+  SPEC_NO_REQUIREMENTS: 'Spec must have at least one requirement',
+  CHANGE_NAME_EMPTY: 'Change name cannot be empty',
+  CHANGE_WHY_TOO_SHORT: `Why section must be at least ${MIN_WHY_SECTION_LENGTH} characters`,
+  CHANGE_WHY_TOO_LONG: `Why section should not exceed ${MAX_WHY_SECTION_LENGTH} characters`,
+  CHANGE_WHAT_EMPTY: 'What Changes section cannot be empty',
+  CHANGE_NO_DELTAS: 'Change must have at least one delta',
+  CHANGE_TOO_MANY_DELTAS: `Consider splitting changes with more than ${MAX_DELTAS_PER_CHANGE} deltas`,
+  DELTA_SPEC_EMPTY: 'Spec name cannot be empty',
+  DELTA_DESCRIPTION_EMPTY: 'Delta description cannot be empty',
+  
+  // Warnings
+  PURPOSE_TOO_BRIEF: `Purpose section is too brief (less than ${MIN_PURPOSE_LENGTH} characters)`,
+  REQUIREMENT_TOO_LONG: `Requirement text is very long (>${MAX_REQUIREMENT_TEXT_LENGTH} characters). Consider breaking it down.`,
+  DELTA_DESCRIPTION_TOO_BRIEF: 'Delta description is too brief',
+  DELTA_MISSING_REQUIREMENTS: 'Delta should include requirements',
+} as const;

src/core/validation/types.ts

@@ -0,0 +1,19 @@
+export type ValidationLevel = 'ERROR' | 'WARNING' | 'INFO';
+
+export interface ValidationIssue {
+  level: ValidationLevel;
+  path: string;
+  message: string;
+  line?: number;
+  column?: number;
+}
+
+export interface ValidationReport {
+  valid: boolean;
+  issues: ValidationIssue[];
+  summary: {
+    errors: number;
+    warnings: number;
+    info: number;
+  };
+}

src/core/validation/validator.ts

@@ -0,0 +1,187 @@
+import { z, ZodError } from 'zod';
+import { readFileSync } from 'fs';
+import path from 'path';
+import { SpecSchema, ChangeSchema, Spec, Change } from '../schemas/index.js';
+import { MarkdownParser } from '../parsers/markdown-parser.js';
+import { ChangeParser } from '../parsers/change-parser.js';
+import { ValidationReport, ValidationIssue, ValidationLevel } from './types.js';
+import { 
+  MIN_PURPOSE_LENGTH,
+  MAX_REQUIREMENT_TEXT_LENGTH,
+  VALIDATION_MESSAGES 
+} from './constants.js';
+
+export class Validator {
+  private strictMode: boolean;
+
+  constructor(strictMode: boolean = false) {
+    this.strictMode = strictMode;
+  }
+
+  async validateSpec(filePath: string): Promise<ValidationReport> {
+    const issues: ValidationIssue[] = [];
+    
+    try {
+      const content = readFileSync(filePath, 'utf-8');
+      const parser = new MarkdownParser(content);
+      const specName = this.extractNameFromPath(filePath);
+      
+      const spec = parser.parseSpec(specName);
+      
+      const result = SpecSchema.safeParse(spec);
+      
+      if (!result.success) {
+        issues.push(...this.convertZodErrors(result.error));
+      }
+      
+      issues.push(...this.applySpecRules(spec, content));
+      
+    } catch (error) {
+      issues.push({
+        level: 'ERROR',
+        path: 'file',
+        message: error instanceof Error ? error.message : 'Unknown error',
+      });
+    }
+    
+    return this.createReport(issues);
+  }
+
+  async validateChange(filePath: string): Promise<ValidationReport> {
+    const issues: ValidationIssue[] = [];
+    
+    try {
+      const content = readFileSync(filePath, 'utf-8');
+      const changeName = this.extractNameFromPath(filePath);
+      const changeDir = path.dirname(filePath);
+      const parser = new ChangeParser(content, changeDir);
+      
+      const change = await parser.parseChangeWithDeltas(changeName);
+      
+      const result = ChangeSchema.safeParse(change);
+      
+      if (!result.success) {
+        issues.push(...this.convertZodErrors(result.error));
+      }
+      
+      issues.push(...this.applyChangeRules(change, content));
+      
+    } catch (error) {
+      issues.push({
+        level: 'ERROR',
+        path: 'file',
+        message: error instanceof Error ? error.message : 'Unknown error',
+      });
+    }
+    
+    return this.createReport(issues);
+  }
+
+  private convertZodErrors(error: ZodError): ValidationIssue[] {
+    return error.issues.map(err => ({
+      level: 'ERROR' as ValidationLevel,
+      path: err.path.join('.'),
+      message: err.message,
+    }));
+  }
+
+  private applySpecRules(spec: Spec, content: string): ValidationIssue[] {
+    const issues: ValidationIssue[] = [];
+    
+    if (spec.overview.length < MIN_PURPOSE_LENGTH) {
+      issues.push({
+        level: 'WARNING',
+        path: 'overview',
+        message: VALIDATION_MESSAGES.PURPOSE_TOO_BRIEF,
+      });
+    }
+    
+    spec.requirements.forEach((req, index) => {
+      if (req.text.length > MAX_REQUIREMENT_TEXT_LENGTH) {
+        issues.push({
+          level: 'INFO',
+          path: `requirements[${index}]`,
+          message: VALIDATION_MESSAGES.REQUIREMENT_TOO_LONG,
+        });
+      }
+      
+      if (req.scenarios.length === 0) {
+        issues.push({
+          level: 'WARNING',
+          path: `requirements[${index}].scenarios`,
+          message: 'Requirement has no scenarios',
+        });
+      }
+    });
+    
+    return issues;
+  }
+
+  private applyChangeRules(change: Change, content: string): ValidationIssue[] {
+    const issues: ValidationIssue[] = [];
+    
+    const MIN_DELTA_DESCRIPTION_LENGTH = 10;
+    
+    change.deltas.forEach((delta, index) => {
+      if (!delta.description || delta.description.length < MIN_DELTA_DESCRIPTION_LENGTH) {
+        issues.push({
+          level: 'WARNING',
+          path: `deltas[${index}].description`,
+          message: VALIDATION_MESSAGES.DELTA_DESCRIPTION_TOO_BRIEF,
+        });
+      }
+      
+      if ((delta.operation === 'ADDED' || delta.operation === 'MODIFIED') && 
+          (!delta.requirements || delta.requirements.length === 0)) {
+        issues.push({
+          level: 'WARNING',
+          path: `deltas[${index}].requirements`,
+          message: `${delta.operation} ${VALIDATION_MESSAGES.DELTA_MISSING_REQUIREMENTS}`,
+        });
+      }
+    });
+    
+    return issues;
+  }
+
+  private extractNameFromPath(filePath: string): string {
+    const parts = filePath.split('/');
+    
+    // Look for the directory name after 'specs' or 'changes'
+    for (let i = parts.length - 1; i >= 0; i--) {
+      if (parts[i] === 'specs' || parts[i] === 'changes') {
+        if (i < parts.length - 1) {
+          return parts[i + 1];
+        }
+      }
+    }
+    
+    // Fallback to filename without extension if not in expected structure
+    const fileName = parts[parts.length - 1];
+    return fileName.replace('.md', '');
+  }
+
+  private createReport(issues: ValidationIssue[]): ValidationReport {
+    const errors = issues.filter(i => i.level === 'ERROR').length;
+    const warnings = issues.filter(i => i.level === 'WARNING').length;
+    const info = issues.filter(i => i.level === 'INFO').length;
+    
+    const valid = this.strictMode 
+      ? errors === 0 && warnings === 0
+      : errors === 0;
+    
+    return {
+      valid,
+      issues,
+      summary: {
+        errors,
+        warnings,
+        info,
+      },
+    };
+  }
+
+  isValid(report: ValidationReport): boolean {
+    return report.valid;
+  }
+}

src/utils/interactive.ts

@@ -0,0 +1,7 @@
+export function isInteractive(noInteractiveFlag?: boolean): boolean {
+  if (noInteractiveFlag) return false;
+  if (process.env.OPEN_SPEC_INTERACTIVE === '0') return false;
+  return !!process.stdin.isTTY;
+}
+
+

src/utils/item-discovery.ts

@@ -0,0 +1,38 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+
+export async function getActiveChangeIds(root: string = process.cwd()): Promise<string[]> {
+  const changesPath = path.join(root, 'openspec', 'changes');
+  try {
+    const entries = await fs.readdir(changesPath, { withFileTypes: true });
+    return entries
+      .filter(entry => entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'archive')
+      .map(entry => entry.name)
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+export async function getSpecIds(root: string = process.cwd()): Promise<string[]> {
+  const specsPath = path.join(root, 'openspec', 'specs');
+  const result: string[] = [];
+  try {
+    const entries = await fs.readdir(specsPath, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+      const specFile = path.join(specsPath, entry.name, 'spec.md');
+      try {
+        await fs.access(specFile);
+        result.push(entry.name);
+      } catch {
+        // ignore
+      }
+    }
+  } catch {
+    // ignore
+  }
+  return result.sort();
+}
+
+

src/utils/task-progress.ts

@@ -0,0 +1,43 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+
+const TASK_PATTERN = /^[-*]\s+\[[\sx]\]/i;
+const COMPLETED_TASK_PATTERN = /^[-*]\s+\[x\]/i;
+
+export interface TaskProgress {
+  total: number;
+  completed: number;
+}
+
+export function countTasksFromContent(content: string): TaskProgress {
+  const lines = content.split('\n');
+  let total = 0;
+  let completed = 0;
+  for (const line of lines) {
+    if (line.match(TASK_PATTERN)) {
+      total++;
+      if (line.match(COMPLETED_TASK_PATTERN)) {
+        completed++;
+      }
+    }
+  }
+  return { total, completed };
+}
+
+export async function getTaskProgressForChange(changesDir: string, changeName: string): Promise<TaskProgress> {
+  const tasksPath = path.join(changesDir, changeName, 'tasks.md');
+  try {
+    const content = await fs.readFile(tasksPath, 'utf-8');
+    return countTasksFromContent(content);
+  } catch {
+    return { total: 0, completed: 0 };
+  }
+}
+
+export function formatTaskStatus(progress: TaskProgress): string {
+  if (progress.total === 0) return 'No tasks';
+  if (progress.completed === progress.total) return '✓ Complete';
+  return `${progress.completed}/${progress.total} tasks`;
+}
+
+

test/commands/change.interactive-validate.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect, beforeAll, beforeEach, afterEach } from 'vitest';
+import { promises as fs } from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+
+// Note: We cannot truly simulate TTY prompts in this test runner easily.
+// Instead, we verify non-interactive fallback behavior and basic invocation.
+
+describe('change validate (interactive behavior)', () => {
+  const projectRoot = process.cwd();
+  const testDir = path.join(projectRoot, 'test-change-validate-tmp');
+  const changesDir = path.join(testDir, 'openspec', 'changes');
+  const bin = path.join(projectRoot, 'bin', 'openspec.js');
+
+  beforeAll(() => {
+    execSync('pnpm -s build', { stdio: 'pipe' });
+  });
+
+  beforeEach(async () => {
+    await fs.mkdir(changesDir, { recursive: true });
+    const content = `# Change: Demo\n\n## Why\nBecause reasons that are sufficiently long.\n\n## What Changes\n- **spec-x:** Add something`;
+    await fs.mkdir(path.join(changesDir, 'demo'), { recursive: true });
+    await fs.writeFile(path.join(changesDir, 'demo', 'proposal.md'), content, 'utf-8');
+  });
+
+  afterEach(async () => {
+    await fs.rm(testDir, { recursive: true, force: true });
+  });
+
+  it('prints list hint and exits non-zero when no arg and non-interactive', () => {
+    const originalCwd = process.cwd();
+    const originalEnv = { ...process.env };
+    try {
+      process.chdir(testDir);
+      process.env.OPEN_SPEC_INTERACTIVE = '0';
+      let err: any;
+      try {
+        execSync(`node ${bin} change validate`, { encoding: 'utf-8' });
+      } catch (e) { err = e; }
+      expect(err).toBeDefined();
+      expect(err.status).not.toBe(0);
+      expect(err.stderr.toString()).toContain('Available IDs:');
+      expect(err.stderr.toString()).toContain('openspec change list');
+    } finally {
+      process.chdir(originalCwd);
+      process.env = originalEnv;
+    }
+  });
+});
+
+

test/commands/spec.interactive-validate.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect, beforeAll, beforeEach, afterEach } from 'vitest';
+import { promises as fs } from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+
+describe('spec validate (interactive behavior)', () => {
+  const projectRoot = process.cwd();
+  const testDir = path.join(projectRoot, 'test-spec-validate-tmp');
+  const specsDir = path.join(testDir, 'openspec', 'specs');
+  const bin = path.join(projectRoot, 'bin', 'openspec.js');
+
+  beforeAll(() => {
+    execSync('pnpm -s build', { stdio: 'pipe' });
+  });
+
+  beforeEach(async () => {
+    await fs.mkdir(specsDir, { recursive: true });
+    const content = `## Purpose\nValid spec for interactive test.\n\n## Requirements\n\n### Requirement: X\nText`;
+    await fs.mkdir(path.join(specsDir, 's1'), { recursive: true });
+    await fs.writeFile(path.join(specsDir, 's1', 'spec.md'), content, 'utf-8');
+  });
+
+  afterEach(async () => {
+    await fs.rm(testDir, { recursive: true, force: true });
+  });
+
+  it('errors when no arg and non-interactive', () => {
+    const originalCwd = process.cwd();
+    const originalEnv = { ...process.env };
+    try {
+      process.chdir(testDir);
+      process.env.OPEN_SPEC_INTERACTIVE = '0';
+      let err: any;
+      try {
+        execSync(`node ${bin} spec validate`, { encoding: 'utf-8' });
+      } catch (e) { err = e; }
+      expect(err).toBeDefined();
+      expect(err.status).not.toBe(0);
+      expect(err.stderr.toString()).toContain('Missing required argument <spec-id>');
+    } finally {
+      process.chdir(originalCwd);
+      process.env = originalEnv;
+    }
+  });
+});
+
+

test/commands/spec.test.ts

@@ -0,0 +1,328 @@
+import { describe, it, expect, beforeEach, afterEach, beforeAll } from 'vitest';
+import { promises as fs } from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+
+describe('spec command', () => {
+  const projectRoot = process.cwd();
+  const testDir = path.join(projectRoot, 'test-spec-command-tmp');
+  const specsDir = path.join(testDir, 'openspec', 'specs');
+  const openspecBin = path.join(projectRoot, 'bin', 'openspec.js');
+  
+  beforeAll(() => {
+    // Ensure CLI is built so bin/openspec.js loads latest logic from dist/
+    execSync('pnpm -s build', { stdio: 'pipe' });
+  });
+  
+  beforeEach(async () => {
+    await fs.mkdir(specsDir, { recursive: true });
+    
+    // Create test spec files
+    const testSpec = `## Purpose
+This is a test specification for the authentication system.
+
+## Requirements
+
+### Requirement: User Authentication
+The system SHALL provide secure user authentication
+
+#### Scenario: Successful login
+- **GIVEN** a user with valid credentials
+- **WHEN** they submit the login form  
+- **THEN** they are authenticated
+
+### Requirement: Password Reset
+The system SHALL allow users to reset their password
+
+#### Scenario: Reset via email
+- **GIVEN** a user with a registered email
+- **WHEN** they request a password reset
+- **THEN** they receive a reset link`;
+
+    await fs.mkdir(path.join(specsDir, 'auth'), { recursive: true });
+    await fs.writeFile(path.join(specsDir, 'auth', 'spec.md'), testSpec);
+    
+    const testSpec2 = `## Purpose
+This specification defines the payment processing system.
+
+## Requirements
+
+### Requirement: Process Payments
+The system SHALL process credit card payments securely`;
+
+    await fs.mkdir(path.join(specsDir, 'payment'), { recursive: true });
+    await fs.writeFile(path.join(specsDir, 'payment', 'spec.md'), testSpec2);
+  });
+
+  afterEach(async () => {
+    await fs.rm(testDir, { recursive: true, force: true });
+  });
+
+  describe('spec show', () => {
+    it('should display spec in text format', () => {
+      const originalCwd = process.cwd();
+      try {
+        process.chdir(testDir);
+        const output = execSync(`node ${openspecBin} spec show auth`, {
+          encoding: 'utf-8'
+        });
+        
+        // Raw passthrough should match spec.md content
+        const raw = execSync(`cat ${path.join(specsDir, 'auth', 'spec.md')}`, { encoding: 'utf-8' });
+        expect(output.trim()).toBe(raw.trim());
+      } finally {
+        process.chdir(originalCwd);
+      }
+    });
+
+    it('should output spec as JSON with --json flag', () => {
+      const originalCwd = process.cwd();
+      try {
+        process.chdir(testDir);
+        const output = execSync(`node ${openspecBin} spec show auth --json`, {
+          encoding: 'utf-8'
+        });
+        
+        const json = JSON.parse(output);
+        expect(json.id).toBe('auth');
+        expect(json.title).toBe('auth');
+        expect(json.overview).toContain('test specification');
+        expect(json.requirements).toHaveLength(2);
+        expect(json.metadata.format).toBe('openspec');
+      } finally {
+        process.chdir(originalCwd);
+      }
+    });
+
+    it('should filter to show only requirements with --requirements flag (JSON only)', () => {
+      const originalCwd = process.cwd();
+      try {
+        process.chdir(testDir);
+        const output = execSync(`node ${openspecBin} spec show auth --json --requirements`, {
+          encoding: 'utf-8'
+        });
+        
+        const json = JSON.parse(output);
+        expect(json.requirements).toHaveLength(2);
+        // Scenarios should be excluded when --requirements is used
+        expect(json.requirements.every((r: any) => Array.isArray(r.scenarios) && r.scenarios.length === 0)).toBe(true);
+      } finally {
+        process.chdir(originalCwd);
+      }
+    });
+
+    it('should exclude scenarios with --no-scenarios flag (JSON only)', () => {
+      const originalCwd = process.cwd();
+      try {
+        process.chdir(testDir);
+        const output = execSync(`node ${openspecBin} spec show auth --json --no-scenarios`, {
+          encoding: 'utf-8'
+        });
+        
+        const json = JSON.parse(output);
+        expect(json.requirements).toHaveLength(2);
+        expect(json.requirements.every((r: any) => Array.isArray(r.scenarios) && r.scenarios.length === 0)).toBe(true);
+      } finally {
+        process.chdir(originalCwd);
+      }
+    });
+
+    it('should show specific requirement with -r flag (JSON only)', () => {
+      const originalCwd = process.cwd();
+      try {
+        process.chdir(testDir);
+        const output = execSync(`node ${openspecBin} spec show auth --json -r 1`, {
+          encoding: 'utf-8'
+        });
+        
+        const json = JSON.parse(output);
+        expect(json.requirements).toHaveLength(1);
+        expect(json.requirements[0].text).toContain('The system SHALL provide secure user authentication');
+      } finally {
+        process.chdir(originalCwd);
+      }
+    });
+
+    it('should return JSON with filtered requirements', () => {
+      const originalCwd = process.cwd();
+      try {
+        process.chdir(testDir);
+        const output = execSync(`node ${openspecBin} spec show auth --json --no-scenarios`, {
+          encoding: 'utf-8'
+        });
+        
+        const json = JSON.parse(output);
+        expect(json.requirements).toHaveLength(2);
+        expect(json.requirements[0].scenarios).toHaveLength(0);
+      } finally {
+        process.chdir(originalCwd);
+      }
+    });
+  });
+
+  describe('spec list', () => {
+    it('should list all available specs (IDs only by default)', () => {
+      const originalCwd = process.cwd();
+      try {
+        process.chdir(testDir);
+        const output = execSync(`node ${openspecBin} spec list`, {
+          encoding: 'utf-8'
+        });
+        
+        expect(output).toContain('auth');
+        expect(output).toContain('payment');
+        // Default should not include counts or teasers
+        expect(output).not.toMatch(/Requirements:\s*\d+/);
+      } finally {
+        process.chdir(originalCwd);
+      }
+    });
+
+    it('should output spec list as JSON with --json flag', () => {
+      const originalCwd = process.cwd();
+      try {
+        process.chdir(testDir);
+        const output = execSync(`node ${openspecBin} spec list --json`, {
+          encoding: 'utf-8'
+        });
+        
+        const json = JSON.parse(output);
+        expect(json).toHaveLength(2);
+        expect(json.find((s: any) => s.id === 'auth')).toBeDefined();
+        expect(json.find((s: any) => s.id === 'payment')).toBeDefined();
+        expect(json[0].requirementCount).toBeDefined();
+      } finally {
+        process.chdir(originalCwd);
+      }
+    });
+  });
+
+  describe('spec validate', () => {
+    it('should validate a valid spec', () => {
+      const originalCwd = process.cwd();
+      try {
+        process.chdir(testDir);
+        const output = execSync(`node ${openspecBin} spec validate auth`, {
+          encoding: 'utf-8'
+        });
+        
+        expect(output).toContain("Specification 'auth' is valid");
+      } finally {
+        process.chdir(originalCwd);
+      }
+    });
+
+    it('should output validation report as JSON with --json flag', () => {
+      const originalCwd = process.cwd();
+      try {
+        process.chdir(testDir);
+        const output = execSync(`node ${openspecBin} spec validate auth --json`, {
+          encoding: 'utf-8'
+        });
+        
+        const json = JSON.parse(output);
+        expect(json.valid).toBeDefined();
+        expect(json.issues).toBeDefined();
+        expect(json.summary).toBeDefined();
+        expect(json.summary.errors).toBeDefined();
+        expect(json.summary.warnings).toBeDefined();
+      } finally {
+        process.chdir(originalCwd);
+      }
+    });
+
+    it('should validate with strict mode', () => {
+      const originalCwd = process.cwd();
+      try {
+        process.chdir(testDir);
+        const output = execSync(`node ${openspecBin} spec validate auth --strict --json`, {
+          encoding: 'utf-8'
+        });
+        
+        const json = JSON.parse(output);
+        expect(json.valid).toBeDefined();
+        // In strict mode, warnings also affect validity
+      } finally {
+        process.chdir(originalCwd);
+      }
+    });
+
+    it('should detect invalid spec structure', async () => {
+      const invalidSpec = `## Purpose
+
+## Requirements
+This section has no actual requirements`;
+
+      await fs.mkdir(path.join(specsDir, 'invalid'), { recursive: true });
+      await fs.writeFile(path.join(specsDir, 'invalid', 'spec.md'), invalidSpec);
+
+      const originalCwd = process.cwd();
+      try {
+        process.chdir(testDir);
+        
+        // This should exit with non-zero code
+        let exitCode = 0;
+        try {
+          execSync(`node ${openspecBin} spec validate invalid`, {
+            encoding: 'utf-8'
+          });
+        } catch (error: any) {
+          exitCode = error.status;
+        }
+        
+        expect(exitCode).not.toBe(0);
+      } finally {
+        process.chdir(originalCwd);
+      }
+    });
+  });
+
+  describe('error handling', () => {
+    it('should handle non-existent spec gracefully', () => {
+      const originalCwd = process.cwd();
+      try {
+        process.chdir(testDir);
+        
+        let error: any;
+        try {
+          execSync(`node ${openspecBin} spec show nonexistent`, {
+            encoding: 'utf-8'
+          });
+        } catch (e) {
+          error = e;
+        }
+        
+        expect(error).toBeDefined();
+        expect(error.status).not.toBe(0);
+        expect(error.stderr.toString()).toContain('not found');
+      } finally {
+        process.chdir(originalCwd);
+      }
+    });
+
+    it('should handle missing specs directory gracefully', async () => {
+      await fs.rm(specsDir, { recursive: true, force: true });
+      const originalCwd = process.cwd();
+      try {
+        process.chdir(testDir);
+        const output = execSync(`node ${openspecBin} spec list`, { encoding: 'utf-8' });
+        expect(output.trim()).toBe('No items found');
+      } finally {
+        process.chdir(originalCwd);
+      }
+    });
+
+    it('should honor --no-color (no ANSI escapes)', () => {
+      const originalCwd = process.cwd();
+      try {
+        process.chdir(testDir);
+        const output = execSync(`node ${openspecBin} --no-color spec list --long`, { encoding: 'utf-8' });
+        // Basic ANSI escape pattern
+        const hasAnsi = /\u001b\[[0-9;]*m/.test(output);
+        expect(hasAnsi).toBe(false);
+      } finally {
+        process.chdir(originalCwd);
+      }
+    });
+  });
+});

test/commands/validate.test.ts

@@ -0,0 +1,125 @@
+import { describe, it, expect, beforeAll, beforeEach, afterEach } from 'vitest';
+import { promises as fs } from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+
+describe('top-level validate command', () => {
+  const projectRoot = process.cwd();
+  const testDir = path.join(projectRoot, 'test-validate-command-tmp');
+  const changesDir = path.join(testDir, 'openspec', 'changes');
+  const specsDir = path.join(testDir, 'openspec', 'specs');
+  const bin = path.join(projectRoot, 'bin', 'openspec.js');
+
+  beforeAll(() => {
+    execSync('pnpm -s build', { stdio: 'pipe' });
+  });
+
+  beforeEach(async () => {
+    await fs.mkdir(changesDir, { recursive: true });
+    await fs.mkdir(specsDir, { recursive: true });
+
+    // Create a valid spec
+    const specContent = `## Purpose
+Valid spec for testing.
+
+## Requirements
+
+### Requirement: Foo
+Text
+
+#### Scenario: Bar
+Given A\nWhen B\nThen C`;
+    await fs.mkdir(path.join(specsDir, 'alpha'), { recursive: true });
+    await fs.writeFile(path.join(specsDir, 'alpha', 'spec.md'), specContent, 'utf-8');
+
+    // Create a simple change with bullets (parser supports this)
+    const changeContent = `# Test Change\n\n## Why\nBecause reasons that are sufficiently long for validation.\n\n## What Changes\n- **alpha:** Add something`;
+    await fs.mkdir(path.join(changesDir, 'c1'), { recursive: true });
+    await fs.writeFile(path.join(changesDir, 'c1', 'proposal.md'), changeContent, 'utf-8');
+
+    // Duplicate name for ambiguity test
+    await fs.mkdir(path.join(changesDir, 'dup'), { recursive: true });
+    await fs.writeFile(path.join(changesDir, 'dup', 'proposal.md'), changeContent, 'utf-8');
+    await fs.mkdir(path.join(specsDir, 'dup'), { recursive: true });
+    await fs.writeFile(path.join(specsDir, 'dup', 'spec.md'), specContent, 'utf-8');
+  });
+
+  afterEach(async () => {
+    await fs.rm(testDir, { recursive: true, force: true });
+  });
+
+  it('prints a helpful hint when no args in non-interactive mode', () => {
+    const originalCwd = process.cwd();
+    const originalEnv = { ...process.env };
+    try {
+      process.chdir(testDir);
+      process.env.OPEN_SPEC_INTERACTIVE = '0';
+      let err: any;
+      try {
+        execSync(`node ${bin} validate`, { encoding: 'utf-8' });
+      } catch (e) { err = e; }
+      expect(err).toBeDefined();
+      expect(err.status).not.toBe(0);
+      expect(err.stderr.toString()).toContain('Nothing to validate. Try one of:');
+    } finally {
+      process.chdir(originalCwd);
+      process.env = originalEnv;
+    }
+  });
+
+  it('validates all with --all and outputs JSON summary', () => {
+    const originalCwd = process.cwd();
+    try {
+      process.chdir(testDir);
+      let outStr = '';
+      try {
+        outStr = execSync(`node ${bin} validate --all --json`, { encoding: 'utf-8' });
+      } catch (e: any) {
+        // If exit code is non-zero (e.g., on failures), still parse stdout JSON
+        outStr = e.stdout?.toString?.() ?? '';
+      }
+      const json = JSON.parse(outStr);
+      expect(Array.isArray(json.items)).toBe(true);
+      expect(json.summary?.totals?.items).toBeDefined();
+      expect(json.version).toBe('1.0');
+    } finally {
+      process.chdir(originalCwd);
+    }
+  });
+
+  it('validates only specs with --specs and respects --concurrency', () => {
+    const originalCwd = process.cwd();
+    try {
+      process.chdir(testDir);
+      let outStr = '';
+      try {
+        outStr = execSync(`node ${bin} validate --specs --json --concurrency 1`, { encoding: 'utf-8' });
+      } catch (e: any) {
+        outStr = e.stdout?.toString?.() ?? '';
+      }
+      const json = JSON.parse(outStr);
+      // All items should be specs
+      expect(json.items.every((i: any) => i.type === 'spec')).toBe(true);
+    } finally {
+      process.chdir(originalCwd);
+    }
+  });
+
+  it('errors on ambiguous item names and suggests type override', () => {
+    const originalCwd = process.cwd();
+    try {
+      process.chdir(testDir);
+      let err: any;
+      try {
+        execSync(`node ${bin} validate dup`, { encoding: 'utf-8' });
+      } catch (e) { err = e; }
+      expect(err).toBeDefined();
+      expect(err.stderr.toString()).toContain('Ambiguous item');
+      expect(err.status).not.toBe(0);
+    } finally {
+      process.chdir(originalCwd);
+    }
+  });
+});
+
+

test/core/archive.test.ts

@@ -0,0 +1,639 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { ArchiveCommand } from '../../src/core/archive.js';
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+
+// Mock @inquirer/prompts
+vi.mock('@inquirer/prompts', () => ({
+  select: vi.fn(),
+  confirm: vi.fn()
+}));
+
+describe('ArchiveCommand', () => {
+  let tempDir: string;
+  let archiveCommand: ArchiveCommand;
+  const originalConsoleLog = console.log;
+
+  beforeEach(async () => {
+    // Create temp directory
+    tempDir = path.join(os.tmpdir(), `openspec-archive-test-${Date.now()}`);
+    await fs.mkdir(tempDir, { recursive: true });
+    
+    // Change to temp directory
+    process.chdir(tempDir);
+    
+    // Create OpenSpec structure
+    const openspecDir = path.join(tempDir, 'openspec');
+    await fs.mkdir(path.join(openspecDir, 'changes'), { recursive: true });
+    await fs.mkdir(path.join(openspecDir, 'specs'), { recursive: true });
+    await fs.mkdir(path.join(openspecDir, 'changes', 'archive'), { recursive: true });
+    
+    // Suppress console.log during tests
+    console.log = vi.fn();
+    
+    archiveCommand = new ArchiveCommand();
+  });
+
+  afterEach(async () => {
+    // Restore console.log
+    console.log = originalConsoleLog;
+    
+    // Clear mocks
+    vi.clearAllMocks();
+    
+    // Clean up temp directory
+    try {
+      await fs.rm(tempDir, { recursive: true, force: true });
+    } catch (error) {
+      // Ignore cleanup errors
+    }
+  });
+
+  describe('execute', () => {
+    it('should archive a change successfully', async () => {
+      // Create a test change
+      const changeName = 'test-feature';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      await fs.mkdir(changeDir, { recursive: true });
+      
+      // Create tasks.md with completed tasks
+      const tasksContent = '- [x] Task 1\n- [x] Task 2';
+      await fs.writeFile(path.join(changeDir, 'tasks.md'), tasksContent);
+      
+      // Execute archive with --yes flag
+      await archiveCommand.execute(changeName, { yes: true });
+      
+      // Check that change was moved to archive
+      const archiveDir = path.join(tempDir, 'openspec', 'changes', 'archive');
+      const archives = await fs.readdir(archiveDir);
+      
+      expect(archives.length).toBe(1);
+      expect(archives[0]).toMatch(new RegExp(`\\d{4}-\\d{2}-\\d{2}-${changeName}`));
+      
+      // Verify original change directory no longer exists
+      await expect(fs.access(changeDir)).rejects.toThrow();
+    });
+
+    it('should warn about incomplete tasks', async () => {
+      const changeName = 'incomplete-feature';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      await fs.mkdir(changeDir, { recursive: true });
+      
+      // Create tasks.md with incomplete tasks
+      const tasksContent = '- [x] Task 1\n- [ ] Task 2\n- [ ] Task 3';
+      await fs.writeFile(path.join(changeDir, 'tasks.md'), tasksContent);
+      
+      // Execute archive with --yes flag
+      await archiveCommand.execute(changeName, { yes: true });
+      
+      // Verify warning was logged
+      expect(console.log).toHaveBeenCalledWith(
+        expect.stringContaining('Warning: 2 incomplete task(s) found')
+      );
+    });
+
+    it('should update specs when archiving (delta-based ADDED) and include change name in skeleton', async () => {
+      const changeName = 'spec-feature';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      const changeSpecDir = path.join(changeDir, 'specs', 'test-capability');
+      await fs.mkdir(changeSpecDir, { recursive: true });
+      
+      // Create delta-based change spec (ADDED requirement)
+      const specContent = `# Test Capability Spec - Changes
+
+## ADDED Requirements
+
+### Requirement: The system SHALL provide test capability
+
+#### Scenario: Basic test
+Given a test condition
+When an action occurs
+Then expected result happens`;
+      await fs.writeFile(path.join(changeSpecDir, 'spec.md'), specContent);
+      
+      // Execute archive with --yes flag and skip validation for speed
+      await archiveCommand.execute(changeName, { yes: true, noValidate: true });
+      
+      // Verify spec was created from skeleton and ADDED requirement applied
+      const mainSpecPath = path.join(tempDir, 'openspec', 'specs', 'test-capability', 'spec.md');
+      const updatedContent = await fs.readFile(mainSpecPath, 'utf-8');
+      expect(updatedContent).toContain('# test-capability Specification');
+      expect(updatedContent).toContain('## Purpose');
+      expect(updatedContent).toContain(`created by archiving change ${changeName}`);
+      expect(updatedContent).toContain('## Requirements');
+      expect(updatedContent).toContain('### Requirement: The system SHALL provide test capability');
+      expect(updatedContent).toContain('#### Scenario: Basic test');
+    });
+
+    it('should throw error if change does not exist', async () => {
+      await expect(
+        archiveCommand.execute('non-existent-change', { yes: true })
+      ).rejects.toThrow("Change 'non-existent-change' not found.");
+    });
+
+    it('should throw error if archive already exists', async () => {
+      const changeName = 'duplicate-feature';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      await fs.mkdir(changeDir, { recursive: true });
+      
+      // Create existing archive with same date
+      const date = new Date().toISOString().split('T')[0];
+      const archivePath = path.join(tempDir, 'openspec', 'changes', 'archive', `${date}-${changeName}`);
+      await fs.mkdir(archivePath, { recursive: true });
+      
+      // Try to archive
+      await expect(
+        archiveCommand.execute(changeName, { yes: true })
+      ).rejects.toThrow(`Archive '${date}-${changeName}' already exists.`);
+    });
+
+    it('should handle changes without tasks.md', async () => {
+      const changeName = 'no-tasks-feature';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      await fs.mkdir(changeDir, { recursive: true });
+      
+      // Execute archive without tasks.md
+      await archiveCommand.execute(changeName, { yes: true });
+      
+      // Should complete without warnings
+      expect(console.log).not.toHaveBeenCalledWith(
+        expect.stringContaining('incomplete task(s)')
+      );
+      
+      // Verify change was archived
+      const archiveDir = path.join(tempDir, 'openspec', 'changes', 'archive');
+      const archives = await fs.readdir(archiveDir);
+      expect(archives.length).toBe(1);
+    });
+
+    it('should handle changes without specs', async () => {
+      const changeName = 'no-specs-feature';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      await fs.mkdir(changeDir, { recursive: true });
+      
+      // Execute archive without specs
+      await archiveCommand.execute(changeName, { yes: true });
+      
+      // Should complete without spec updates
+      expect(console.log).not.toHaveBeenCalledWith(
+        expect.stringContaining('Specs to update')
+      );
+      
+      // Verify change was archived
+      const archiveDir = path.join(tempDir, 'openspec', 'changes', 'archive');
+      const archives = await fs.readdir(archiveDir);
+      expect(archives.length).toBe(1);
+    });
+
+    it('should skip spec updates when --skip-specs flag is used', async () => {
+      const changeName = 'skip-specs-feature';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      const changeSpecDir = path.join(changeDir, 'specs', 'test-capability');
+      await fs.mkdir(changeSpecDir, { recursive: true });
+      
+      // Create spec in change
+      const specContent = '# Test Capability Spec\n\nTest content';
+      await fs.writeFile(path.join(changeSpecDir, 'spec.md'), specContent);
+      
+      // Execute archive with --skip-specs flag and noValidate to skip validation
+      await archiveCommand.execute(changeName, { yes: true, skipSpecs: true, noValidate: true });
+      
+      // Verify skip message was logged
+      expect(console.log).toHaveBeenCalledWith(
+        'Skipping spec updates (--skip-specs flag provided).'
+      );
+      
+      // Verify spec was NOT copied to main specs
+      const mainSpecPath = path.join(tempDir, 'openspec', 'specs', 'test-capability', 'spec.md');
+      await expect(fs.access(mainSpecPath)).rejects.toThrow();
+      
+      // Verify change was still archived
+      const archiveDir = path.join(tempDir, 'openspec', 'changes', 'archive');
+      const archives = await fs.readdir(archiveDir);
+      expect(archives.length).toBe(1);
+      expect(archives[0]).toMatch(new RegExp(`\\d{4}-\\d{2}-\\d{2}-${changeName}`));
+    });
+
+    it('should proceed with archive when user declines spec updates', async () => {
+      const { confirm } = await import('@inquirer/prompts');
+      const mockConfirm = confirm as unknown as ReturnType<typeof vi.fn>;
+      
+      const changeName = 'decline-specs-feature';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      const changeSpecDir = path.join(changeDir, 'specs', 'test-capability');
+      await fs.mkdir(changeSpecDir, { recursive: true });
+      
+      // Create valid spec in change
+      const specContent = `# Test Capability Spec
+
+## Purpose
+This is a test capability specification.
+
+## Requirements
+
+### The system SHALL provide test capability
+
+#### Scenario: Basic test
+Given a test condition
+When an action occurs
+Then expected result happens`;
+      await fs.writeFile(path.join(changeSpecDir, 'spec.md'), specContent);
+      
+      // Mock confirm to return false (decline spec updates)
+      mockConfirm.mockResolvedValueOnce(false);
+      
+      // Execute archive without --yes flag
+      await archiveCommand.execute(changeName);
+      
+      // Verify user was prompted about specs
+      expect(mockConfirm).toHaveBeenCalledWith({
+        message: 'Proceed with spec updates?',
+        default: true
+      });
+      
+      // Verify skip message was logged
+      expect(console.log).toHaveBeenCalledWith(
+        'Skipping spec updates. Proceeding with archive.'
+      );
+      
+      // Verify spec was NOT copied to main specs
+      const mainSpecPath = path.join(tempDir, 'openspec', 'specs', 'test-capability', 'spec.md');
+      await expect(fs.access(mainSpecPath)).rejects.toThrow();
+      
+      // Verify change was still archived
+      const archiveDir = path.join(tempDir, 'openspec', 'changes', 'archive');
+      const archives = await fs.readdir(archiveDir);
+      expect(archives.length).toBe(1);
+      expect(archives[0]).toMatch(new RegExp(`\\d{4}-\\d{2}-\\d{2}-${changeName}`));
+    });
+
+    it('should support header trim-only normalization for matching', async () => {
+      const changeName = 'normalize-headers';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      const changeSpecDir = path.join(changeDir, 'specs', 'alpha');
+      await fs.mkdir(changeSpecDir, { recursive: true });
+
+      // Create existing main spec with a requirement (no extra trailing spaces)
+      const mainSpecDir = path.join(tempDir, 'openspec', 'specs', 'alpha');
+      await fs.mkdir(mainSpecDir, { recursive: true });
+      const mainContent = `# alpha Specification
+
+## Purpose
+Alpha purpose.
+
+## Requirements
+
+### Requirement: Important Rule
+Some details.`;
+      await fs.writeFile(path.join(mainSpecDir, 'spec.md'), mainContent);
+
+      // Change attempts to modify the same requirement but with trailing spaces after the name
+      const deltaContent = `# Alpha - Changes
+
+## MODIFIED Requirements
+
+### Requirement: Important Rule   
+Updated details.`;
+      await fs.writeFile(path.join(changeSpecDir, 'spec.md'), deltaContent);
+
+      await archiveCommand.execute(changeName, { yes: true, noValidate: true });
+
+      const updated = await fs.readFile(path.join(mainSpecDir, 'spec.md'), 'utf-8');
+      expect(updated).toContain('### Requirement: Important Rule');
+      expect(updated).toContain('Updated details.');
+    });
+
+    it('should apply operations in order: RENAMED → REMOVED → MODIFIED → ADDED', async () => {
+      const changeName = 'apply-order';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      const changeSpecDir = path.join(changeDir, 'specs', 'beta');
+      await fs.mkdir(changeSpecDir, { recursive: true });
+
+      // Main spec with two requirements A and B
+      const mainSpecDir = path.join(tempDir, 'openspec', 'specs', 'beta');
+      await fs.mkdir(mainSpecDir, { recursive: true });
+      const mainContent = `# beta Specification
+
+## Purpose
+Beta purpose.
+
+## Requirements
+
+### Requirement: A
+content A
+
+### Requirement: B
+content B`;
+      await fs.writeFile(path.join(mainSpecDir, 'spec.md'), mainContent);
+
+      // Rename A->C, Remove B, Modify C, Add D
+      const deltaContent = `# Beta - Changes
+
+## RENAMED Requirements
+- FROM: \`### Requirement: A\`
+- TO: \`### Requirement: C\`
+
+## REMOVED Requirements
+### Requirement: B
+
+## MODIFIED Requirements
+### Requirement: C
+updated C
+
+## ADDED Requirements
+### Requirement: D
+content D`;
+      await fs.writeFile(path.join(changeSpecDir, 'spec.md'), deltaContent);
+
+      await archiveCommand.execute(changeName, { yes: true, noValidate: true });
+
+      const updated = await fs.readFile(path.join(mainSpecDir, 'spec.md'), 'utf-8');
+      expect(updated).toContain('### Requirement: C');
+      expect(updated).toContain('updated C');
+      expect(updated).toContain('### Requirement: D');
+      expect(updated).not.toContain('### Requirement: A');
+      expect(updated).not.toContain('### Requirement: B');
+    });
+
+    it('should abort with error when MODIFIED/REMOVED reference non-existent requirements', async () => {
+      const changeName = 'validate-missing';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      const changeSpecDir = path.join(changeDir, 'specs', 'gamma');
+      await fs.mkdir(changeSpecDir, { recursive: true });
+
+      // Main spec with no requirements
+      const mainSpecDir = path.join(tempDir, 'openspec', 'specs', 'gamma');
+      await fs.mkdir(mainSpecDir, { recursive: true });
+      const mainContent = `# gamma Specification
+
+## Purpose
+Gamma purpose.
+
+## Requirements`;
+      await fs.writeFile(path.join(mainSpecDir, 'spec.md'), mainContent);
+
+      // Delta tries to modify and remove non-existent requirement
+      const deltaContent = `# Gamma - Changes
+
+## MODIFIED Requirements
+### Requirement: Missing
+new text
+
+## REMOVED Requirements
+### Requirement: Another Missing`;
+      await fs.writeFile(path.join(changeSpecDir, 'spec.md'), deltaContent);
+
+      await archiveCommand.execute(changeName, { yes: true, noValidate: true });
+
+      // Should not change the main spec and should not archive the change dir
+      const still = await fs.readFile(path.join(mainSpecDir, 'spec.md'), 'utf-8');
+      expect(still).toBe(mainContent);
+      // Change dir should still exist since operation aborted
+      await expect(fs.access(changeDir)).resolves.not.toThrow();
+    });
+
+    it('should require MODIFIED to reference the NEW header when a rename exists (error format)', async () => {
+      const changeName = 'rename-modify-new-header';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      const changeSpecDir = path.join(changeDir, 'specs', 'delta');
+      await fs.mkdir(changeSpecDir, { recursive: true });
+
+      // Main spec with Old
+      const mainSpecDir = path.join(tempDir, 'openspec', 'specs', 'delta');
+      await fs.mkdir(mainSpecDir, { recursive: true });
+      const mainContent = `# delta Specification
+
+## Purpose
+Delta purpose.
+
+## Requirements
+
+### Requirement: Old
+old body`;
+      await fs.writeFile(path.join(mainSpecDir, 'spec.md'), mainContent);
+
+      // Delta: rename Old->New, but MODIFIED references Old (should abort)
+      const badDelta = `# Delta - Changes
+
+## RENAMED Requirements
+- FROM: \`### Requirement: Old\`
+- TO: \`### Requirement: New\`
+
+## MODIFIED Requirements
+### Requirement: Old
+new body`;
+      await fs.writeFile(path.join(changeSpecDir, 'spec.md'), badDelta);
+
+      await archiveCommand.execute(changeName, { yes: true, noValidate: true });
+      const unchanged = await fs.readFile(path.join(mainSpecDir, 'spec.md'), 'utf-8');
+      expect(unchanged).toBe(mainContent);
+      // Assert error message format and abort notice
+      expect(console.log).toHaveBeenCalledWith(
+        expect.stringContaining('delta validation failed')
+      );
+      expect(console.log).toHaveBeenCalledWith(
+        expect.stringContaining('Aborted. No files were changed.')
+      );
+
+      // Fix MODIFIED to reference New (should succeed)
+      const goodDelta = `# Delta - Changes
+
+## RENAMED Requirements
+- FROM: \`### Requirement: Old\`
+- TO: \`### Requirement: New\`
+
+## MODIFIED Requirements
+### Requirement: New
+new body`;
+      await fs.writeFile(path.join(changeSpecDir, 'spec.md'), goodDelta);
+
+      await archiveCommand.execute(changeName, { yes: true, noValidate: true });
+      const updated = await fs.readFile(path.join(mainSpecDir, 'spec.md'), 'utf-8');
+      expect(updated).toContain('### Requirement: New');
+      expect(updated).toContain('new body');
+      expect(updated).not.toContain('### Requirement: Old');
+    });
+
+    it('should process multiple specs atomically (any failure aborts all)', async () => {
+      const changeName = 'multi-spec-atomic';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      const spec1Dir = path.join(changeDir, 'specs', 'epsilon');
+      const spec2Dir = path.join(changeDir, 'specs', 'zeta');
+      await fs.mkdir(spec1Dir, { recursive: true });
+      await fs.mkdir(spec2Dir, { recursive: true });
+
+      // Existing main specs
+      const epsilonMain = path.join(tempDir, 'openspec', 'specs', 'epsilon', 'spec.md');
+      await fs.mkdir(path.dirname(epsilonMain), { recursive: true });
+      await fs.writeFile(epsilonMain, `# epsilon Specification
+
+## Purpose
+Epsilon purpose.
+
+## Requirements
+
+### Requirement: E1
+e1`);
+
+      const zetaMain = path.join(tempDir, 'openspec', 'specs', 'zeta', 'spec.md');
+      await fs.mkdir(path.dirname(zetaMain), { recursive: true });
+      await fs.writeFile(zetaMain, `# zeta Specification
+
+## Purpose
+Zeta purpose.
+
+## Requirements
+
+### Requirement: Z1
+z1`);
+
+      // Delta: epsilon is valid modification; zeta tries to remove non-existent -> should abort both
+      await fs.writeFile(path.join(spec1Dir, 'spec.md'), `# Epsilon - Changes
+
+## MODIFIED Requirements
+### Requirement: E1
+E1 updated`);
+
+      await fs.writeFile(path.join(spec2Dir, 'spec.md'), `# Zeta - Changes
+
+## REMOVED Requirements
+### Requirement: Missing`);
+
+      await archiveCommand.execute(changeName, { yes: true, noValidate: true });
+
+      const e1 = await fs.readFile(epsilonMain, 'utf-8');
+      const z1 = await fs.readFile(zetaMain, 'utf-8');
+      expect(e1).toContain('### Requirement: E1');
+      expect(e1).not.toContain('E1 updated');
+      expect(z1).toContain('### Requirement: Z1');
+      // changeDir should still exist
+      await expect(fs.access(changeDir)).resolves.not.toThrow();
+    });
+
+    it('should display aggregated totals across multiple specs', async () => {
+      const changeName = 'multi-spec-totals';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      const spec1Dir = path.join(changeDir, 'specs', 'omega');
+      const spec2Dir = path.join(changeDir, 'specs', 'psi');
+      await fs.mkdir(spec1Dir, { recursive: true });
+      await fs.mkdir(spec2Dir, { recursive: true });
+
+      // Existing main specs
+      const omegaMain = path.join(tempDir, 'openspec', 'specs', 'omega', 'spec.md');
+      await fs.mkdir(path.dirname(omegaMain), { recursive: true });
+      await fs.writeFile(omegaMain, `# omega Specification\n\n## Purpose\nOmega purpose.\n\n## Requirements\n\n### Requirement: O1\no1`);
+
+      const psiMain = path.join(tempDir, 'openspec', 'specs', 'psi', 'spec.md');
+      await fs.mkdir(path.dirname(psiMain), { recursive: true });
+      await fs.writeFile(psiMain, `# psi Specification\n\n## Purpose\nPsi purpose.\n\n## Requirements\n\n### Requirement: P1\np1`);
+
+      // Deltas: omega add one, psi rename and modify -> totals: +1, ~1, -0, →1
+      await fs.writeFile(path.join(spec1Dir, 'spec.md'), `# Omega - Changes\n\n## ADDED Requirements\n\n### Requirement: O2\nnew`);
+      await fs.writeFile(path.join(spec2Dir, 'spec.md'), `# Psi - Changes\n\n## RENAMED Requirements\n- FROM: \`### Requirement: P1\`\n- TO: \`### Requirement: P2\`\n\n## MODIFIED Requirements\n### Requirement: P2\nupdated`);
+
+      await archiveCommand.execute(changeName, { yes: true, noValidate: true });
+
+      // Verify aggregated totals line was printed
+      expect(console.log).toHaveBeenCalledWith(
+        expect.stringContaining('Totals: + 1, ~ 1, - 0, → 1')
+      );
+    });
+  });
+
+  describe('error handling', () => {
+    it('should throw error when openspec directory does not exist', async () => {
+      // Remove openspec directory
+      await fs.rm(path.join(tempDir, 'openspec'), { recursive: true });
+      
+      await expect(
+        archiveCommand.execute('any-change', { yes: true })
+      ).rejects.toThrow("No OpenSpec changes directory found. Run 'openspec init' first.");
+    });
+  });
+
+  describe('interactive mode', () => {
+    it('should use select prompt for change selection', async () => {
+      const { select } = await import('@inquirer/prompts');
+      const mockSelect = select as unknown as ReturnType<typeof vi.fn>;
+      
+      // Create test changes
+      const change1 = 'feature-a';
+      const change2 = 'feature-b';
+      await fs.mkdir(path.join(tempDir, 'openspec', 'changes', change1), { recursive: true });
+      await fs.mkdir(path.join(tempDir, 'openspec', 'changes', change2), { recursive: true });
+      
+      // Mock select to return first change
+      mockSelect.mockResolvedValueOnce(change1);
+      
+      // Execute without change name
+      await archiveCommand.execute(undefined, { yes: true });
+      
+      // Verify select was called with correct options (values matter, names may include progress)
+      expect(mockSelect).toHaveBeenCalledWith(expect.objectContaining({
+        message: 'Select a change to archive',
+        choices: expect.arrayContaining([
+          expect.objectContaining({ value: change1 }),
+          expect.objectContaining({ value: change2 })
+        ])
+      }));
+      
+      // Verify the selected change was archived
+      const archiveDir = path.join(tempDir, 'openspec', 'changes', 'archive');
+      const archives = await fs.readdir(archiveDir);
+      expect(archives[0]).toContain(change1);
+    });
+
+    it('should use confirm prompt for task warnings', async () => {
+      const { confirm } = await import('@inquirer/prompts');
+      const mockConfirm = confirm as unknown as ReturnType<typeof vi.fn>;
+      
+      const changeName = 'incomplete-interactive';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      await fs.mkdir(changeDir, { recursive: true });
+      
+      // Create tasks.md with incomplete tasks
+      const tasksContent = '- [ ] Task 1';
+      await fs.writeFile(path.join(changeDir, 'tasks.md'), tasksContent);
+      
+      // Mock confirm to return true (proceed)
+      mockConfirm.mockResolvedValueOnce(true);
+      
+      // Execute without --yes flag
+      await archiveCommand.execute(changeName);
+      
+      // Verify confirm was called
+      expect(mockConfirm).toHaveBeenCalledWith({
+        message: 'Warning: 1 incomplete task(s) found. Continue?',
+        default: false
+      });
+    });
+
+    it('should cancel when user declines task warning', async () => {
+      const { confirm } = await import('@inquirer/prompts');
+      const mockConfirm = confirm as unknown as ReturnType<typeof vi.fn>;
+      
+      const changeName = 'cancel-test';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      await fs.mkdir(changeDir, { recursive: true });
+      
+      // Create tasks.md with incomplete tasks
+      const tasksContent = '- [ ] Task 1';
+      await fs.writeFile(path.join(changeDir, 'tasks.md'), tasksContent);
+      
+      // Mock confirm to return false (cancel) for validation skip
+      mockConfirm.mockResolvedValueOnce(false);
+      // Mock another false for task warning
+      mockConfirm.mockResolvedValueOnce(false);
+      
+      // Execute without --yes flag but skip validation to test task warning
+      await archiveCommand.execute(changeName, { noValidate: true });
+      
+      // Verify archive was cancelled
+      expect(console.log).toHaveBeenCalledWith('Archive cancelled.');
+      
+      // Verify change was not archived
+      await expect(fs.access(changeDir)).resolves.not.toThrow();
+    });
+  });
+});

test/core/commands/change-command.list.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import { ChangeCommand } from '../../../src/commands/change.js';
+
+// These tests assume the repository's own openspec/changes directory exists
+// and contains at least one active change (e.g., add-change-commands)
+
+describe('ChangeCommand.list', () => {
+  let cmd: ChangeCommand;
+
+  beforeAll(() => {
+    cmd = new ChangeCommand();
+  });
+
+  it('returns JSON with expected shape', async () => {
+    // Capture console output
+    const logs: string[] = [];
+    const origLog = console.log;
+    try {
+      console.log = (msg?: any, ...args: any[]) => {
+        logs.push([msg, ...args].filter(Boolean).join(' '));
+      };
+
+      await cmd.list({ json: true });
+
+      const output = logs.join('\n');
+      const parsed = JSON.parse(output);
+      expect(Array.isArray(parsed)).toBe(true);
+      if (parsed.length > 0) {
+        const item = parsed[0];
+        expect(item).toHaveProperty('id');
+        expect(item).toHaveProperty('title');
+        expect(item).toHaveProperty('deltaCount');
+        expect(item).toHaveProperty('taskStatus');
+        expect(item.taskStatus).toHaveProperty('total');
+        expect(item.taskStatus).toHaveProperty('completed');
+      }
+    } finally {
+      console.log = origLog;
+    }
+  });
+
+  it('prints IDs by default and details with --long', async () => {
+    const logs: string[] = [];
+    const origLog = console.log;
+    try {
+      console.log = (msg?: any, ...args: any[]) => {
+        logs.push([msg, ...args].filter(Boolean).join(' '));
+      };
+      await cmd.list({});
+      const idsOnly = logs.join('\n');
+      expect(idsOnly).toMatch(/\w+/);
+      logs.length = 0;
+      await cmd.list({ long: true });
+      const longOut = logs.join('\n');
+      expect(longOut).toMatch(/:\s/);
+      expect(longOut).toMatch(/\[deltas\s\d+\]/);
+    } finally {
+      console.log = origLog;
+    }
+  });
+});

test/core/commands/change-command.show-validate.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import { ChangeCommand } from '../../../src/commands/change.js';
+import path from 'path';
+import { promises as fs } from 'fs';
+
+async function findSingleActiveChange(root: string): Promise<string | undefined> {
+  const changesDir = path.join(root, 'openspec', 'changes');
+  try {
+    const entries = await fs.readdir(changesDir, { withFileTypes: true });
+    const names = entries
+      .filter((e) => e.isDirectory() && e.name !== 'archive')
+      .map((e) => e.name);
+    if (names.length === 1) return names[0];
+    return names.includes('add-change-commands') ? 'add-change-commands' : names[0];
+  } catch {
+    return undefined;
+  }
+}
+
+describe('ChangeCommand.show/validate', () => {
+  let cmd: ChangeCommand;
+  let changeName: string | undefined;
+
+  beforeAll(async () => {
+    cmd = new ChangeCommand();
+    changeName = await findSingleActiveChange(process.cwd());
+  });
+
+  it('show --json prints JSON including deltas', async () => {
+    if (!changeName) return; // skip if no changes present
+
+    const logs: string[] = [];
+    const origLog = console.log;
+    try {
+      console.log = (msg?: any, ...args: any[]) => {
+        logs.push([msg, ...args].filter(Boolean).join(' '));
+      };
+
+      await cmd.show(changeName, { json: true });
+
+      const output = logs.join('\n');
+      const parsed = JSON.parse(output);
+      expect(parsed).toHaveProperty('deltas');
+      expect(Array.isArray(parsed.deltas)).toBe(true);
+    } finally {
+      console.log = origLog;
+    }
+  });
+
+  it('error when no change specified: prints available IDs', async () => {
+    const logsErr: string[] = [];
+    const origErr = console.error;
+    try {
+      console.error = (msg?: any, ...args: any[]) => {
+        logsErr.push([msg, ...args].filter(Boolean).join(' '));
+      };
+      await cmd.show(undefined as unknown as string, { json: false } as any);
+      // Should have set exit code and printed hint
+      expect(process.exitCode).toBe(1);
+      const errOut = logsErr.join('\n');
+      expect(errOut).toMatch(/No change specified/);
+      expect(errOut).toMatch(/Available IDs/);
+    } finally {
+      console.error = origErr;
+      process.exitCode = 0;
+    }
+  });
+
+  it('show --json --requirements-only returns minimal object with deltas (deprecated alias)', async () => {
+    if (!changeName) return; // skip if no changes present
+
+    const logs: string[] = [];
+    const origLog = console.log;
+    try {
+      console.log = (msg?: any, ...args: any[]) => {
+        logs.push([msg, ...args].filter(Boolean).join(' '));
+      };
+
+      await cmd.show(changeName, { json: true, requirementsOnly: true });
+
+      const output = logs.join('\n');
+      const parsed = JSON.parse(output);
+      expect(parsed).toHaveProperty('deltas');
+      expect(Array.isArray(parsed.deltas)).toBe(true);
+      if (parsed.deltas.length > 0) {
+        expect(parsed.deltas[0]).toHaveProperty('spec');
+        expect(parsed.deltas[0]).toHaveProperty('operation');
+        expect(parsed.deltas[0]).toHaveProperty('description');
+      }
+    } finally {
+      console.log = origLog;
+    }
+  });
+
+  it('validate --strict --json returns a report with valid boolean', async () => {
+    if (!changeName) return; // skip if no changes present
+
+    const logs: string[] = [];
+    const origLog = console.log;
+    try {
+      console.log = (msg?: any, ...args: any[]) => {
+        logs.push([msg, ...args].filter(Boolean).join(' '));
+      };
+
+      await cmd.validate(changeName, { strict: true, json: true });
+
+      const output = logs.join('\n');
+      const parsed = JSON.parse(output);
+      expect(parsed).toHaveProperty('valid');
+      expect(parsed).toHaveProperty('issues');
+      expect(Array.isArray(parsed.issues)).toBe(true);
+    } finally {
+      console.log = origLog;
+    }
+  });
+});

test/core/converters/json-converter.test.ts

@@ -0,0 +1,184 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { promises as fs } from 'fs';
+import path from 'path';
+import { JsonConverter } from '../../../src/core/converters/json-converter.js';
+
+describe('JsonConverter', () => {
+  const testDir = path.join(process.cwd(), 'test-json-converter-tmp');
+  const converter = new JsonConverter();
+  
+  beforeEach(async () => {
+    await fs.mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await fs.rm(testDir, { recursive: true, force: true });
+  });
+
+  describe('convertSpecToJson', () => {
+    it('should convert a spec to JSON format', async () => {
+      const specContent = `# User Authentication Spec
+
+## Purpose
+This specification defines the requirements for user authentication.
+
+## Requirements
+
+### The system SHALL provide secure user authentication
+Users need to be able to log in securely.
+
+#### Scenario: Successful login
+Given a user with valid credentials
+When they submit the login form
+Then they are authenticated`;
+
+      const specPath = path.join(testDir, 'spec.md');
+      await fs.writeFile(specPath, specContent);
+      
+      const json = converter.convertSpecToJson(specPath);
+      const parsed = JSON.parse(json);
+      
+      expect(parsed.name).toBe('spec');
+      expect(parsed.overview).toContain('user authentication');
+      expect(parsed.requirements).toHaveLength(1);
+      expect(parsed.requirements[0].scenarios).toHaveLength(1);
+      expect(parsed.metadata).toBeDefined();
+      expect(parsed.metadata.format).toBe('openspec');
+      expect(parsed.metadata.sourcePath).toBe(specPath);
+    });
+
+    it('should extract spec name from directory structure', async () => {
+      const specsDir = path.join(testDir, 'specs', 'user-auth');
+      await fs.mkdir(specsDir, { recursive: true });
+      
+      const specContent = `# User Auth
+
+## Purpose
+Auth spec overview
+
+## Requirements
+
+### The system SHALL authenticate users
+
+#### Scenario: Login
+Given a user
+When they login
+Then authenticated`;
+
+      const specPath = path.join(specsDir, 'spec.md');
+      await fs.writeFile(specPath, specContent);
+      
+      const json = converter.convertSpecToJson(specPath);
+      const parsed = JSON.parse(json);
+      
+      expect(parsed.name).toBe('user-auth');
+    });
+  });
+
+  describe('convertChangeToJson', () => {
+    it('should convert a change to JSON format', async () => {
+      const changeContent = `# Add User Authentication
+
+## Why
+We need to implement user authentication to secure the application and protect user data from unauthorized access.
+
+## What Changes
+- **user-auth:** Add new user authentication specification
+- **api-endpoints:** Modify to include authentication endpoints`;
+
+      const changePath = path.join(testDir, 'change.md');
+      await fs.writeFile(changePath, changeContent);
+      
+      const json = await converter.convertChangeToJson(changePath);
+      const parsed = JSON.parse(json);
+      
+      expect(parsed.name).toBe('change');
+      expect(parsed.why).toContain('secure the application');
+      expect(parsed.deltas).toHaveLength(2);
+      expect(parsed.deltas[0].spec).toBe('user-auth');
+      expect(parsed.deltas[0].operation).toBe('ADDED');
+      expect(parsed.metadata).toBeDefined();
+      expect(parsed.metadata.format).toBe('openspec-change');
+      expect(parsed.metadata.sourcePath).toBe(changePath);
+    });
+
+    it('should extract change name from directory structure', async () => {
+      const changesDir = path.join(testDir, 'changes', 'add-auth');
+      await fs.mkdir(changesDir, { recursive: true });
+      
+      const changeContent = `# Add Auth
+
+## Why
+We need authentication for security reasons and to protect user data properly.
+
+## What Changes
+- **auth:** Add authentication`;
+
+      const changePath = path.join(changesDir, 'proposal.md');
+      await fs.writeFile(changePath, changeContent);
+      
+      const json = await converter.convertChangeToJson(changePath);
+      const parsed = JSON.parse(json);
+      
+      expect(parsed.name).toBe('add-auth');
+    });
+  });
+
+  describe('JSON formatting', () => {
+    it('should produce properly formatted JSON with indentation', async () => {
+      const specContent = `# Test
+
+## Purpose
+Test overview
+
+## Requirements
+
+### The system SHALL test
+
+#### Scenario: Test
+Given test
+When action
+Then result`;
+
+      const specPath = path.join(testDir, 'spec.md');
+      await fs.writeFile(specPath, specContent);
+      
+      const json = converter.convertSpecToJson(specPath);
+      
+      // Check for proper indentation (2 spaces)
+      expect(json).toContain('  "name"');
+      expect(json).toContain('  "overview"');
+      expect(json).toContain('  "requirements"');
+      
+      // Check it's valid JSON
+      expect(() => JSON.parse(json)).not.toThrow();
+    });
+
+    it('should handle special characters in content', async () => {
+      const specContent = `# Test
+
+## Purpose
+This has "quotes" and \\ backslashes and
+newlines
+
+## Requirements
+
+### The system SHALL handle "special" characters
+
+#### Scenario: Special chars
+Given a string with "quotes"
+When processing \\ backslash
+Then handle correctly`;
+
+      const specPath = path.join(testDir, 'spec.md');
+      await fs.writeFile(specPath, specContent);
+      
+      const json = converter.convertSpecToJson(specPath);
+      const parsed = JSON.parse(json);
+      
+      expect(parsed.overview).toContain('"quotes"');
+      expect(parsed.overview).toContain('\\');
+      expect(parsed.requirements[0].text).toContain('"special"');
+    });
+  });
+});

test/core/list.test.ts

@@ -0,0 +1,165 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+import { ListCommand } from '../../src/core/list.js';
+
+describe('ListCommand', () => {
+  let tempDir: string;
+  let originalLog: typeof console.log;
+  let logOutput: string[] = [];
+
+  beforeEach(async () => {
+    // Create temp directory
+    tempDir = path.join(os.tmpdir(), `openspec-list-test-${Date.now()}`);
+    await fs.mkdir(tempDir, { recursive: true });
+
+    // Mock console.log to capture output
+    originalLog = console.log;
+    console.log = (...args: any[]) => {
+      logOutput.push(args.join(' '));
+    };
+    logOutput = [];
+  });
+
+  afterEach(async () => {
+    // Restore console.log
+    console.log = originalLog;
+
+    // Clean up temp directory
+    await fs.rm(tempDir, { recursive: true, force: true });
+  });
+
+  describe('execute', () => {
+    it('should handle missing openspec/changes directory', async () => {
+      const listCommand = new ListCommand();
+      
+      await expect(listCommand.execute(tempDir)).rejects.toThrow(
+        "No OpenSpec changes directory found. Run 'openspec init' first."
+      );
+    });
+
+    it('should handle empty changes directory', async () => {
+      const changesDir = path.join(tempDir, 'openspec', 'changes');
+      await fs.mkdir(changesDir, { recursive: true });
+
+      const listCommand = new ListCommand();
+      await listCommand.execute(tempDir);
+
+      expect(logOutput).toEqual(['No active changes found.']);
+    });
+
+    it('should exclude archive directory', async () => {
+      const changesDir = path.join(tempDir, 'openspec', 'changes');
+      await fs.mkdir(path.join(changesDir, 'archive'), { recursive: true });
+      await fs.mkdir(path.join(changesDir, 'my-change'), { recursive: true });
+      
+      // Create tasks.md with some tasks
+      await fs.writeFile(
+        path.join(changesDir, 'my-change', 'tasks.md'),
+        '- [x] Task 1\n- [ ] Task 2\n'
+      );
+
+      const listCommand = new ListCommand();
+      await listCommand.execute(tempDir);
+
+      expect(logOutput).toContain('Changes:');
+      expect(logOutput.some(line => line.includes('my-change'))).toBe(true);
+      expect(logOutput.some(line => line.includes('archive'))).toBe(false);
+    });
+
+    it('should count tasks correctly', async () => {
+      const changesDir = path.join(tempDir, 'openspec', 'changes');
+      await fs.mkdir(path.join(changesDir, 'test-change'), { recursive: true });
+      
+      await fs.writeFile(
+        path.join(changesDir, 'test-change', 'tasks.md'),
+        `# Tasks
+- [x] Completed task 1
+- [x] Completed task 2
+- [ ] Incomplete task 1
+- [ ] Incomplete task 2
+- [ ] Incomplete task 3
+Regular text that should be ignored
+`
+      );
+
+      const listCommand = new ListCommand();
+      await listCommand.execute(tempDir);
+
+      expect(logOutput.some(line => line.includes('2/5 tasks'))).toBe(true);
+    });
+
+    it('should show complete status for fully completed changes', async () => {
+      const changesDir = path.join(tempDir, 'openspec', 'changes');
+      await fs.mkdir(path.join(changesDir, 'completed-change'), { recursive: true });
+      
+      await fs.writeFile(
+        path.join(changesDir, 'completed-change', 'tasks.md'),
+        '- [x] Task 1\n- [x] Task 2\n- [x] Task 3\n'
+      );
+
+      const listCommand = new ListCommand();
+      await listCommand.execute(tempDir);
+
+      expect(logOutput.some(line => line.includes('✓ Complete'))).toBe(true);
+    });
+
+    it('should handle changes without tasks.md', async () => {
+      const changesDir = path.join(tempDir, 'openspec', 'changes');
+      await fs.mkdir(path.join(changesDir, 'no-tasks'), { recursive: true });
+
+      const listCommand = new ListCommand();
+      await listCommand.execute(tempDir);
+
+      expect(logOutput.some(line => line.includes('no-tasks') && line.includes('No tasks'))).toBe(true);
+    });
+
+    it('should sort changes alphabetically', async () => {
+      const changesDir = path.join(tempDir, 'openspec', 'changes');
+      await fs.mkdir(path.join(changesDir, 'zebra'), { recursive: true });
+      await fs.mkdir(path.join(changesDir, 'alpha'), { recursive: true });
+      await fs.mkdir(path.join(changesDir, 'middle'), { recursive: true });
+
+      const listCommand = new ListCommand();
+      await listCommand.execute(tempDir);
+
+      const changeLines = logOutput.filter(line => 
+        line.includes('alpha') || line.includes('middle') || line.includes('zebra')
+      );
+      
+      expect(changeLines[0]).toContain('alpha');
+      expect(changeLines[1]).toContain('middle');
+      expect(changeLines[2]).toContain('zebra');
+    });
+
+    it('should handle multiple changes with various states', async () => {
+      const changesDir = path.join(tempDir, 'openspec', 'changes');
+      
+      // Complete change
+      await fs.mkdir(path.join(changesDir, 'completed'), { recursive: true });
+      await fs.writeFile(
+        path.join(changesDir, 'completed', 'tasks.md'),
+        '- [x] Task 1\n- [x] Task 2\n'
+      );
+
+      // Partial change
+      await fs.mkdir(path.join(changesDir, 'partial'), { recursive: true });
+      await fs.writeFile(
+        path.join(changesDir, 'partial', 'tasks.md'),
+        '- [x] Done\n- [ ] Not done\n- [ ] Also not done\n'
+      );
+
+      // No tasks
+      await fs.mkdir(path.join(changesDir, 'no-tasks'), { recursive: true });
+
+      const listCommand = new ListCommand();
+      await listCommand.execute(tempDir);
+
+      expect(logOutput).toContain('Changes:');
+      expect(logOutput.some(line => line.includes('completed') && line.includes('✓ Complete'))).toBe(true);
+      expect(logOutput.some(line => line.includes('partial') && line.includes('1/3 tasks'))).toBe(true);
+      expect(logOutput.some(line => line.includes('no-tasks') && line.includes('No tasks'))).toBe(true);
+    });
+  });
+});

test/core/parsers/change-parser.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from 'vitest';
+import path from 'path';
+import { promises as fs } from 'fs';
+import os from 'os';
+import { ChangeParser } from '../../../src/core/parsers/change-parser.js';
+
+async function withTempDir(run: (dir: string) => Promise<void>) {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'openspec-change-parser-'));
+  try {
+    await run(dir);
+  } finally {
+    // Best-effort cleanup
+    try { await fs.rm(dir, { recursive: true, force: true }); } catch {}
+  }
+}
+
+describe('ChangeParser', () => {
+  it('parses simple What Changes bullet list', async () => {
+    const content = `# Test Change\n\n## Why\nWe need it because reasons that are sufficiently long.\n\n## What Changes\n- **spec-a:** Add a new requirement to A\n- **spec-b:** Rename requirement X to Y\n- **spec-c:** Remove obsolete requirement`;
+
+    const parser = new ChangeParser(content, process.cwd());
+    const change = await parser.parseChangeWithDeltas('test-change');
+
+    expect(change.name).toBe('test-change');
+    expect(change.deltas.length).toBe(3);
+    expect(change.deltas[0].spec).toBe('spec-a');
+    expect(['ADDED', 'MODIFIED', 'REMOVED', 'RENAMED']).toContain(change.deltas[1].operation);
+  });
+
+  it('prefers delta-format specs over simple bullets when both exist', async () => {
+    await withTempDir(async (dir) => {
+      const changeDir = dir;
+      const specsDir = path.join(changeDir, 'specs', 'foo');
+      await fs.mkdir(specsDir, { recursive: true });
+
+      const content = `# Test Change\n\n## Why\nWe need it because reasons that are sufficiently long.\n\n## What Changes\n- **foo:** Add something via bullets (should be overridden)`;
+      const deltaSpec = `# Delta for Foo\n\n## ADDED Requirements\n\n### Requirement: New thing\n\n#### Scenario: basic\nGiven X\nWhen Y\nThen Z`;
+
+      await fs.writeFile(path.join(specsDir, 'spec.md'), deltaSpec, 'utf8');
+
+      const parser = new ChangeParser(content, changeDir);
+      const change = await parser.parseChangeWithDeltas('test-change');
+
+      expect(change.deltas.length).toBeGreaterThan(0);
+      // Since delta spec exists, the description should reflect delta-derived entries
+      expect(change.deltas[0].spec).toBe('foo');
+      expect(change.deltas[0].description).toContain('Add requirement:');
+      expect(change.deltas[0].operation).toBe('ADDED');
+      expect(change.deltas[0].requirement).toBeDefined();
+    });
+  });
+});

test/core/parsers/markdown-parser.test.ts

@@ -0,0 +1,272 @@
+import { describe, it, expect } from 'vitest';
+import { MarkdownParser } from '../../../src/core/parsers/markdown-parser.js';
+
+describe('MarkdownParser', () => {
+  describe('parseSpec', () => {
+    it('should parse a valid spec', () => {
+      const content = `# User Authentication Spec
+
+## Purpose
+This specification defines the requirements for user authentication.
+
+## Requirements
+
+### The system SHALL provide secure user authentication
+Users need to be able to log in securely.
+
+#### Scenario: Successful login
+Given a user with valid credentials
+When they submit the login form
+Then they are authenticated
+
+### The system SHALL handle invalid login attempts
+The system must handle incorrect credentials.
+
+#### Scenario: Invalid credentials
+Given a user with invalid credentials
+When they submit the login form
+Then they see an error message`;
+
+      const parser = new MarkdownParser(content);
+      const spec = parser.parseSpec('user-auth');
+      
+      expect(spec.name).toBe('user-auth');
+      expect(spec.overview).toContain('requirements for user authentication');
+      expect(spec.requirements).toHaveLength(2);
+      
+      const firstReq = spec.requirements[0];
+      expect(firstReq.text).toBe('Users need to be able to log in securely.');
+      expect(firstReq.scenarios).toHaveLength(1);
+      
+      const scenario = firstReq.scenarios[0];
+      expect(scenario.rawText).toContain('Given a user with valid credentials');
+      expect(scenario.rawText).toContain('When they submit the login form');
+      expect(scenario.rawText).toContain('Then they are authenticated');
+    });
+
+    it('should handle multi-line scenarios', () => {
+      const content = `# Test Spec
+
+## Purpose
+Test overview
+
+## Requirements
+
+### The system SHALL handle complex scenarios
+This requirement has content.
+
+#### Scenario: Multi-line scenario
+Given a user with valid credentials
+  and the user has admin privileges
+  and the system is in maintenance mode
+When they attempt to login
+  and provide their MFA token
+Then they are authenticated
+  and redirected to admin dashboard
+  and see a maintenance warning`;
+
+      const parser = new MarkdownParser(content);
+      const spec = parser.parseSpec('test');
+      
+      const scenario = spec.requirements[0].scenarios[0];
+      expect(scenario.rawText).toContain('Given a user with valid credentials');
+      expect(scenario.rawText).toContain('and the user has admin privileges');
+      expect(scenario.rawText).toContain('When they attempt to login');
+      expect(scenario.rawText).toContain('and provide their MFA token');
+      expect(scenario.rawText).toContain('Then they are authenticated');
+      expect(scenario.rawText).toContain('and see a maintenance warning');
+    });
+
+    it('should throw error for missing overview', () => {
+      const content = `# Test Spec
+
+## Requirements
+
+### The system SHALL do something
+
+#### Scenario: Test
+Given test
+When action
+Then result`;
+
+      const parser = new MarkdownParser(content);
+      expect(() => parser.parseSpec('test')).toThrow('must have a Purpose section');
+    });
+
+    it('should throw error for missing requirements', () => {
+      const content = `# Test Spec
+
+## Purpose
+This is a test spec`;
+
+      const parser = new MarkdownParser(content);
+      expect(() => parser.parseSpec('test')).toThrow('must have a Requirements section');
+    });
+  });
+
+  describe('parseChange', () => {
+    it('should parse a valid change', () => {
+      const content = `# Add User Authentication
+
+## Why
+We need to implement user authentication to secure the application and protect user data from unauthorized access.
+
+## What Changes
+- **user-auth:** Add new user authentication specification
+- **api-endpoints:** Modify to include authentication endpoints
+- **database:** Remove old session management tables`;
+
+      const parser = new MarkdownParser(content);
+      const change = parser.parseChange('add-user-auth');
+      
+      expect(change.name).toBe('add-user-auth');
+      expect(change.why).toContain('secure the application');
+      expect(change.whatChanges).toContain('user-auth');
+      expect(change.deltas).toHaveLength(3);
+      
+      expect(change.deltas[0].spec).toBe('user-auth');
+      expect(change.deltas[0].operation).toBe('ADDED');
+      expect(change.deltas[0].description).toContain('Add new user authentication');
+      
+      expect(change.deltas[1].spec).toBe('api-endpoints');
+      expect(change.deltas[1].operation).toBe('MODIFIED');
+      
+      expect(change.deltas[2].spec).toBe('database');
+      expect(change.deltas[2].operation).toBe('REMOVED');
+    });
+
+    it('should throw error for missing why section', () => {
+      const content = `# Test Change
+
+## What Changes
+- **test:** Add test`;
+
+      const parser = new MarkdownParser(content);
+      expect(() => parser.parseChange('test')).toThrow('must have a Why section');
+    });
+
+    it('should throw error for missing what changes section', () => {
+      const content = `# Test Change
+
+## Why
+Because we need it`;
+
+      const parser = new MarkdownParser(content);
+      expect(() => parser.parseChange('test')).toThrow('must have a What Changes section');
+    });
+
+    it('should handle changes without deltas', () => {
+      const content = `# Test Change
+
+## Why
+We need to make some changes for important reasons that justify this work.
+
+## What Changes
+Some general description of changes without specific deltas`;
+
+      const parser = new MarkdownParser(content);
+      const change = parser.parseChange('test');
+      
+      expect(change.deltas).toHaveLength(0);
+    });
+  });
+
+  describe('section parsing', () => {
+    it('should handle nested sections correctly', () => {
+      const content = `# Test Spec
+
+## Purpose
+This is the overview section for testing nested sections.
+
+## Requirements
+
+### The system SHALL handle nested sections
+
+#### Scenario: Test nested
+Given a nested structure
+When parsing sections
+Then handle correctly
+
+### Another requirement SHALL work
+
+#### Scenario: Another test
+Given another test
+When running
+Then success`;
+
+      const parser = new MarkdownParser(content);
+      const spec = parser.parseSpec('test');
+      
+      // Should find the correct sections at different levels
+      expect(spec).toBeDefined();
+      expect(spec.overview).toContain('testing nested sections');
+      expect(spec.requirements).toHaveLength(2);
+    });
+
+    it('should preserve content between headers', () => {
+      const content = `# Test
+
+## Purpose
+This is the overview.
+It has multiple lines.
+
+Some more content here.
+
+## Requirements
+
+### Requirement 1
+Content for requirement 1`;
+
+      const parser = new MarkdownParser(content);
+      const spec = parser.parseSpec('test');
+      
+      expect(spec.overview).toContain('multiple lines');
+      expect(spec.overview).toContain('more content');
+    });
+
+    it('should use requirement heading as fallback when no content is provided', () => {
+      const content = `# Test Spec
+
+## Purpose
+Test overview
+
+## Requirements
+
+### The system SHALL use heading text when no content
+
+#### Scenario: Test
+Given test
+When action
+Then result`;
+
+      const parser = new MarkdownParser(content);
+      const spec = parser.parseSpec('test');
+      
+      expect(spec.requirements[0].text).toBe('The system SHALL use heading text when no content');
+    });
+
+    it('should extract requirement text from first non-empty content line', () => {
+      const content = `# Test Spec
+
+## Purpose
+Test overview
+
+## Requirements
+
+### Requirement heading
+
+This is the actual requirement text.
+This is additional description.
+
+#### Scenario: Test
+Given test
+When action
+Then result`;
+
+      const parser = new MarkdownParser(content);
+      const spec = parser.parseSpec('test');
+      
+      expect(spec.requirements[0].text).toBe('This is the actual requirement text.');
+    });
+  });
+});

test/core/update.test.ts

@@ -0,0 +1,165 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { UpdateCommand } from '../../src/core/update.js';
+import { FileSystemUtils } from '../../src/utils/file-system.js';
+import { ToolRegistry } from '../../src/core/configurators/registry.js';
+import path from 'path';
+import fs from 'fs/promises';
+import os from 'os';
+
+describe('UpdateCommand', () => {
+  let testDir: string;
+  let updateCommand: UpdateCommand;
+
+  beforeEach(async () => {
+    // Create a temporary test directory
+    testDir = path.join(os.tmpdir(), `openspec-test-${Date.now()}`);
+    await fs.mkdir(testDir, { recursive: true });
+    
+    // Create openspec directory
+    const openspecDir = path.join(testDir, 'openspec');
+    await fs.mkdir(openspecDir, { recursive: true });
+    
+    updateCommand = new UpdateCommand();
+  });
+
+  afterEach(async () => {
+    // Clean up test directory
+    await fs.rm(testDir, { recursive: true, force: true });
+  });
+
+  it('should update only existing CLAUDE.md file', async () => {
+    // Create CLAUDE.md file with initial content
+    const claudePath = path.join(testDir, 'CLAUDE.md');
+    const initialContent = `# Project Instructions
+
+Some existing content here.
+
+<!-- OPENSPEC:START -->
+Old OpenSpec content
+<!-- OPENSPEC:END -->
+
+More content after.`;
+    await fs.writeFile(claudePath, initialContent);
+
+    const consoleSpy = vi.spyOn(console, 'log');
+    
+    // Execute update command
+    await updateCommand.execute(testDir);
+
+    // Check that CLAUDE.md was updated
+    const updatedContent = await fs.readFile(claudePath, 'utf-8');
+    expect(updatedContent).toContain('<!-- OPENSPEC:START -->');
+    expect(updatedContent).toContain('<!-- OPENSPEC:END -->');
+    expect(updatedContent).toContain('This project uses OpenSpec');
+    expect(updatedContent).toContain('Some existing content here');
+    expect(updatedContent).toContain('More content after');
+    
+    // Check console output
+    expect(consoleSpy).toHaveBeenCalledWith(
+      'Updated OpenSpec instructions (README.md)\nUpdated AI tool files: CLAUDE.md'
+    );
+    consoleSpy.mockRestore();
+  });
+
+  it('should not create CLAUDE.md if it does not exist', async () => {
+    // Ensure CLAUDE.md does not exist
+    const claudePath = path.join(testDir, 'CLAUDE.md');
+    
+    // Execute update command
+    await updateCommand.execute(testDir);
+
+    // Check that CLAUDE.md was not created
+    const fileExists = await FileSystemUtils.fileExists(claudePath);
+    expect(fileExists).toBe(false);
+  });
+
+  it('should handle no AI tool files present', async () => {
+    // Execute update command with no AI tool files
+    const consoleSpy = vi.spyOn(console, 'log');
+    await updateCommand.execute(testDir);
+
+    // Should only update OpenSpec instructions
+    expect(consoleSpy).toHaveBeenCalledWith('Updated OpenSpec instructions (README.md)');
+    consoleSpy.mockRestore();
+  });
+
+  it('should update multiple AI tool files if present', async () => {
+    // TODO: When additional configurators are added (Cursor, Aider, etc.),
+    // enhance this test to create multiple AI tool files and verify
+    // that all existing files are updated in a single operation.
+    // For now, we test with just CLAUDE.md.
+    const claudePath = path.join(testDir, 'CLAUDE.md');
+    await fs.writeFile(claudePath, '<!-- OPENSPEC:START -->\nOld\n<!-- OPENSPEC:END -->');
+
+    const consoleSpy = vi.spyOn(console, 'log');
+    await updateCommand.execute(testDir);
+
+    // Should report updating with new format
+    expect(consoleSpy).toHaveBeenCalledWith(
+      'Updated OpenSpec instructions (README.md)\nUpdated AI tool files: CLAUDE.md'
+    );
+    consoleSpy.mockRestore();
+  });
+
+  it('should never create new AI tool files', async () => {
+    // Get all configurators
+    const configurators = ToolRegistry.getAll();
+    
+    // Execute update command
+    await updateCommand.execute(testDir);
+
+    // Check that no new AI tool files were created
+    for (const configurator of configurators) {
+      const configPath = path.join(testDir, configurator.configFileName);
+      const fileExists = await FileSystemUtils.fileExists(configPath);
+      expect(fileExists).toBe(false);
+    }
+  });
+
+  it('should update README.md in openspec directory', async () => {
+    // Execute update command
+    await updateCommand.execute(testDir);
+
+    // Check that README.md was created/updated
+    const readmePath = path.join(testDir, 'openspec', 'README.md');
+    const fileExists = await FileSystemUtils.fileExists(readmePath);
+    expect(fileExists).toBe(true);
+
+    const content = await fs.readFile(readmePath, 'utf-8');
+    expect(content).toContain('# OpenSpec Instructions');
+  });
+
+  it('should throw error if openspec directory does not exist', async () => {
+    // Remove openspec directory
+    await fs.rm(path.join(testDir, 'openspec'), { recursive: true, force: true });
+
+    // Execute update command and expect error
+    await expect(updateCommand.execute(testDir)).rejects.toThrow(
+      "No OpenSpec directory found. Run 'openspec init' first."
+    );
+  });
+
+  it('should handle configurator errors gracefully', async () => {
+    // Create CLAUDE.md file but make it read-only to cause an error
+    const claudePath = path.join(testDir, 'CLAUDE.md');
+    await fs.writeFile(claudePath, '<!-- OPENSPEC:START -->\nOld\n<!-- OPENSPEC:END -->');
+    await fs.chmod(claudePath, 0o444); // Read-only
+    
+    const consoleSpy = vi.spyOn(console, 'log');
+    const errorSpy = vi.spyOn(console, 'error');
+    
+    // Execute update command - should not throw
+    await updateCommand.execute(testDir);
+    
+    // Should report the failure
+    expect(errorSpy).toHaveBeenCalled();
+    expect(consoleSpy).toHaveBeenCalledWith(
+      'Updated OpenSpec instructions (README.md)\nFailed to update: CLAUDE.md'
+    );
+    
+    // Restore permissions for cleanup
+    await fs.chmod(claudePath, 0o644);
+    consoleSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+});

test/core/validation.test.ts

@@ -0,0 +1,341 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { promises as fs } from 'fs';
+import path from 'path';
+import { Validator } from '../../src/core/validation/validator.js';
+import { 
+  ScenarioSchema, 
+  RequirementSchema, 
+  SpecSchema, 
+  ChangeSchema,
+  DeltaSchema 
+} from '../../src/core/schemas/index.js';
+
+describe('Validation Schemas', () => {
+  describe('ScenarioSchema', () => {
+    it('should validate a valid scenario', () => {
+      const scenario = {
+        rawText: 'Given a user is logged in\nWhen they click logout\nThen they are redirected to login page',
+      };
+      
+      const result = ScenarioSchema.safeParse(scenario);
+      expect(result.success).toBe(true);
+    });
+
+    it('should reject scenario with empty text', () => {
+      const scenario = {
+        rawText: '',
+      };
+      
+      const result = ScenarioSchema.safeParse(scenario);
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error.issues[0].message).toBe('Scenario text cannot be empty');
+      }
+    });
+  });
+
+  describe('RequirementSchema', () => {
+    it('should validate a valid requirement', () => {
+      const requirement = {
+        text: 'The system SHALL provide user authentication',
+        scenarios: [
+          {
+            rawText: 'Given a user with valid credentials\nWhen they submit the login form\nThen they are authenticated',
+          },
+        ],
+      };
+      
+      const result = RequirementSchema.safeParse(requirement);
+      expect(result.success).toBe(true);
+    });
+
+    it('should reject requirement without SHALL or MUST', () => {
+      const requirement = {
+        text: 'The system provides user authentication',
+        scenarios: [
+          {
+            rawText: 'Given a user\nWhen they login\nThen authenticated',
+          },
+        ],
+      };
+      
+      const result = RequirementSchema.safeParse(requirement);
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error.issues[0].message).toBe('Requirement must contain SHALL or MUST keyword');
+      }
+    });
+
+    it('should reject requirement without scenarios', () => {
+      const requirement = {
+        text: 'The system SHALL provide user authentication',
+        scenarios: [],
+      };
+      
+      const result = RequirementSchema.safeParse(requirement);
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error.issues[0].message).toBe('Requirement must have at least one scenario');
+      }
+    });
+  });
+
+  describe('SpecSchema', () => {
+    it('should validate a valid spec', () => {
+      const spec = {
+        name: 'user-auth',
+        overview: 'This spec defines user authentication requirements',
+        requirements: [
+          {
+            text: 'The system SHALL provide user authentication',
+            scenarios: [
+              {
+                rawText: 'Given a user with valid credentials\nWhen they submit the login form\nThen they are authenticated',
+              },
+            ],
+          },
+        ],
+      };
+      
+      const result = SpecSchema.safeParse(spec);
+      expect(result.success).toBe(true);
+    });
+
+    it('should reject spec without requirements', () => {
+      const spec = {
+        name: 'user-auth',
+        overview: 'This spec defines user authentication requirements',
+        requirements: [],
+      };
+      
+      const result = SpecSchema.safeParse(spec);
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error.issues[0].message).toBe('Spec must have at least one requirement');
+      }
+    });
+  });
+
+  describe('ChangeSchema', () => {
+    it('should validate a valid change', () => {
+      const change = {
+        name: 'add-user-auth',
+        why: 'We need user authentication to secure the application and protect user data',
+        whatChanges: 'Add authentication module with login and logout capabilities',
+        deltas: [
+          {
+            spec: 'user-auth',
+            operation: 'ADDED',
+            description: 'Add new user authentication spec',
+          },
+        ],
+      };
+      
+      const result = ChangeSchema.safeParse(change);
+      expect(result.success).toBe(true);
+    });
+
+    it('should reject change with short why section', () => {
+      const change = {
+        name: 'add-user-auth',
+        why: 'Need auth',
+        whatChanges: 'Add authentication',
+        deltas: [
+          {
+            spec: 'user-auth',
+            operation: 'ADDED',
+            description: 'Add auth',
+          },
+        ],
+      };
+      
+      const result = ChangeSchema.safeParse(change);
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error.issues[0].message).toBe('Why section must be at least 50 characters');
+      }
+    });
+
+    it('should warn about too many deltas', () => {
+      const deltas = Array.from({ length: 11 }, (_, i) => ({
+        spec: `spec-${i}`,
+        operation: 'ADDED' as const,
+        description: `Add spec ${i}`,
+      }));
+      
+      const change = {
+        name: 'massive-change',
+        why: 'This is a massive change that affects many parts of the system',
+        whatChanges: 'Update everything',
+        deltas,
+      };
+      
+      const result = ChangeSchema.safeParse(change);
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error.issues[0].message).toBe('Consider splitting changes with more than 10 deltas');
+      }
+    });
+  });
+});
+
+describe('Validator', () => {
+  const testDir = path.join(process.cwd(), 'test-validation-tmp');
+  
+  beforeEach(async () => {
+    await fs.mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await fs.rm(testDir, { recursive: true, force: true });
+  });
+
+  describe('validateSpec', () => {
+    it('should validate a valid spec file', async () => {
+      const specContent = `# User Authentication Spec
+
+## Purpose
+This specification defines the requirements for user authentication in the system.
+
+## Requirements
+
+### The system SHALL provide secure user authentication
+The system SHALL provide secure user authentication mechanisms.
+
+#### Scenario: Successful login
+Given a user with valid credentials
+When they submit the login form
+Then they are authenticated and redirected to the dashboard
+
+### The system SHALL handle invalid login attempts
+The system SHALL gracefully handle incorrect credentials.
+
+#### Scenario: Invalid credentials
+Given a user with invalid credentials
+When they submit the login form
+Then they see an error message`;
+
+      const specPath = path.join(testDir, 'spec.md');
+      await fs.writeFile(specPath, specContent);
+      
+      const validator = new Validator();
+      const report = await validator.validateSpec(specPath);
+      
+      expect(report.valid).toBe(true);
+      expect(report.summary.errors).toBe(0);
+    });
+
+    it('should detect missing overview section', async () => {
+      const specContent = `# User Authentication Spec
+
+## Requirements
+
+### The system SHALL provide secure user authentication
+
+#### Scenario: Login
+Given a user
+When they login
+Then authenticated`;
+
+      const specPath = path.join(testDir, 'spec.md');
+      await fs.writeFile(specPath, specContent);
+      
+      const validator = new Validator();
+      const report = await validator.validateSpec(specPath);
+      
+      expect(report.valid).toBe(false);
+      expect(report.summary.errors).toBeGreaterThan(0);
+      expect(report.issues.some(i => i.message.includes('Purpose'))).toBe(true);
+    });
+  });
+
+  describe('validateChange', () => {
+    it('should validate a valid change file', async () => {
+      const changeContent = `# Add User Authentication
+
+## Why
+We need to implement user authentication to secure the application and protect user data from unauthorized access.
+
+## What Changes
+- **user-auth:** Add new user authentication specification
+- **api-endpoints:** Modify to include auth endpoints`;
+
+      const changePath = path.join(testDir, 'change.md');
+      await fs.writeFile(changePath, changeContent);
+      
+      const validator = new Validator();
+      const report = await validator.validateChange(changePath);
+      
+      expect(report.valid).toBe(true);
+      expect(report.summary.errors).toBe(0);
+    });
+
+    it('should detect missing why section', async () => {
+      const changeContent = `# Add User Authentication
+
+## What Changes
+- **user-auth:** Add new user authentication specification`;
+
+      const changePath = path.join(testDir, 'change.md');
+      await fs.writeFile(changePath, changeContent);
+      
+      const validator = new Validator();
+      const report = await validator.validateChange(changePath);
+      
+      expect(report.valid).toBe(false);
+      expect(report.summary.errors).toBeGreaterThan(0);
+      expect(report.issues.some(i => i.message.includes('Why'))).toBe(true);
+    });
+  });
+
+  describe('strict mode', () => {
+    it('should fail on warnings in strict mode', async () => {
+      const specContent = `# Test Spec
+
+## Purpose
+Brief overview
+
+## Requirements
+
+### The system SHALL do something
+
+#### Scenario: Test
+Given test
+When action
+Then result`;
+
+      const specPath = path.join(testDir, 'spec.md');
+      await fs.writeFile(specPath, specContent);
+      
+      const validator = new Validator(true); // strict mode
+      const report = await validator.validateSpec(specPath);
+      
+      expect(report.valid).toBe(false); // Should fail due to brief overview warning
+    });
+
+    it('should pass warnings in non-strict mode', async () => {
+      const specContent = `# Test Spec
+
+## Purpose
+Brief overview
+
+## Requirements
+
+### The system SHALL do something
+
+#### Scenario: Test
+Given test
+When action
+Then result`;
+
+      const specPath = path.join(testDir, 'spec.md');
+      await fs.writeFile(specPath, specContent);
+      
+      const validator = new Validator(false); // non-strict mode
+      const report = await validator.validateSpec(specPath);
+      
+      expect(report.valid).toBe(true); // Should pass despite warnings
+      expect(report.summary.warnings).toBeGreaterThan(0);
+    });
+  });
+});