Address review

Make change and spec commands consistent (raw-first)

CHANGE_VS_SPEC.md

@@ -0,0 +1,76 @@
+## openspec change vs spec: behavior differences and recommendations
+
+This document compares how `openspec change` and `openspec spec` behave today (focused on `show` and `list`) and recommends a raw-first, minimal standard to keep behavior simple and predictable before adding smarter formatting later.
+
+## Summary of key differences and recommendations
+
+| Area | Current: change | Current: spec | Recommendation |
+|---|---|---|---|
+| Invocation (show) | `openspec change show [change-name]` auto-picks when only one active change | `openspec spec show <spec-id>` requires id | Require explicit IDs for both. If `change-name` is omitted, print available IDs and a short hint (e.g., use `openspec change list`) and exit non-zero. No auto-pick. No interactive picker. |
+| Default text output (show) | Raw `proposal.md` content | Formatted summary | Default both to RAW: print the underlying Markdown file as-is. Provide a future `--pretty` flag (non-default) for formatted output. |
+| Filtering flags (show) | `--requirements-only` affects text and JSON | `--requirements`, `--no-scenarios`, `-r/--requirement` | Raw-first: in TEXT mode, no filtering. All filtering applies only to JSON output. Deprecate text-mode filters. Keep minimal JSON filters only. |
+| JSON shape (show) | Full change object; `--requirements-only` can return an array | Filtered object | Always return an OBJECT. Minimal, stable shape. Change: `{ id, title, deltaCount, deltas, taskStatus? }`. Spec: `{ id, title, overview, requirementCount, requirements, metadata }`. No top-level arrays. |
+| Text output (list) | "Active Changes" with progress | "Available Specifications" with teaser | Default both to RAW/minimal: print IDs only by default. Add `--long` to show `id + title` and minimal details (counts). No teasers. |
+| JSON shape (list) | `[{ name, title, deltas, taskStatus }]` | `[{ id, title, overview, requirementCount }]` | Unify minimal keys: `id`, `title`, counts only. Change: `deltaCount`, `taskStatus`. Spec: `requirementCount`. Drop `overview` from list JSON. Sort by `id`. |
+| Error/exit policy | Spinner + `process.exit(1)` in some paths | `exitCode` in others | Raw-first: no spinners in errors. Use `console.error` + `process.exitCode = 1` consistently. |
+| Empty states (list) | Graceful | Errors if specs missing | Raw-first: graceful empty state everywhere. Print "No items found" and exit 0. |
+| Multi-selection (change show) | Auto-pick single; error when multiple | N/A | Keep auto-pick single. If multiple, print IDs inline and exit non-zero. No interactive prompts. |
+| Colors/TTY | Mixed | Chalk only | Raw-first: minimal color; honor `NO_COLOR` and add `--no-color`. |
+
+## Detailed guidance
+
+### 1) Unify flags and semantics (raw-first)
+- Text mode: no filters; just raw file content.
+- JSON mode: allow minimal filters only.
+  - Specs: `--json` returns the structured spec. Optional: `-r/--requirement <n>` and `--requirements-only` apply to JSON only.
+  - Changes: `--json` returns the structured change. Optional: `--deltas-only` applies to JSON only.
+- Deprecate text-mode filtering flags across both commands.
+- Optional future: `--pretty` (text formatting) as a non-default enhancement.
+
+### 2) Normalize JSON contracts (minimal and stable)
+- Show (change): `{ id, title, deltaCount, deltas: [...], taskStatus?: { total, completed } }`
+- Show (spec): `{ id, title, overview, requirementCount, requirements: [...], metadata: { format, version } }`
+- List (change): `[{ id, title, deltaCount, taskStatus }]`
+- List (spec): `[{ id, title, requirementCount }]`
+- Notes:
+  - No top-level arrays for filtered show responses; always objects.
+  - Avoid derived/pretty fields (e.g., teasers, percentages). Counts only.
+
+### 3) Standardize text UI (minimal)
+- Show: print raw Markdown file contents.
+- List (default): print IDs only, one per line.
+- List (`--long`): print `id: title` plus minimal counts where relevant.
+- Keep colors minimal; support `--no-color` and respect `NO_COLOR`.
+
+### 4) Consistent error handling and empty states
+- Use `console.error` + `process.exitCode = 1`. Avoid `process.exit(1)`.
+- No spinners (`ora`) in raw-first mode.
+- Empty states print a simple message and exit 0.
+
+### 5) Discoverability and UX
+- No `change-name` provided: print IDs inline and a short hint; exit non-zero. No auto-pick. No interactive prompts.
+- Add `--no-color` for deterministic logs and pipelines.
+
+### 6) Backwards compatibility and deprecation
+- Keep legacy flags as aliases for one minor release.
+- Print a clear deprecation warning when a legacy flag is used.
+- Update CLI docs/README/specs to reflect raw-first behavior.
+
+### 7) Test coverage updates
+- Add tests asserting raw text outputs (file passthrough) for `show`.
+- Add tests for minimal list outputs (IDs by default, `--long` for details).
+- Add JSON contract tests asserting minimal, stable shapes and JSON-only filtering.
+
+### 8) Library alignment with existing commands
+- No new dependencies.
+- Do not use `@inquirer/prompts` in `change`/`spec` show/list (keep non-interactive). Interaction remains limited to `init`, `diff`, and `archive` where already in use.
+- Do not use `ora` in `change`/`spec` (including validate). Use `console.error` and `process.exitCode`.
+- Use `chalk` minimally; support `--no-color` and respect `NO_COLOR`.
+- Keep using the shared `Validator` where applicable.
+- Do not introduce `jest-diff` into `change`/`spec` (remains specific to `diff`).
+
+## Why this approach
+- Keeps the system raw and predictable; easy to compose in scripts.
+- Minimizes UI/formatting logic until real needs emerge.
+- Stabilizes JSON for tooling and avoids top-level arrays.
+- Simple to extend later with `--pretty` and richer filtering if needed.

README.md

@@ -17,8 +17,9 @@ openspec init
 # Update existing OpenSpec instructions (team-friendly)
 openspec update
 
-# List all specifications
-openspec list
+# 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]
@@ -47,12 +48,37 @@ Updates OpenSpec instructions to the latest version. This command is **team-frie
 
 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 list`
+### `openspec spec`
 
-Lists all specifications and pending changes in your project:
-- Shows current specifications in `openspec/specs/`
-- Shows pending changes in `openspec/changes/`
-- Shows archived changes in `openspec/changes/archive/`
+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]`
 
@@ -82,6 +108,12 @@ OpenSpec is designed for team collaboration:
 
 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/MIGRATION.md

@@ -1,263 +0,0 @@
-# Migration Guide: Integrating Validation into Future Commands
-
-## Overview
-
-This guide explains how to integrate the OpenSpec validation framework into new commands and features.
-
-## Adding Validation to New Commands
-
-### 1. Import Required Components
-
-```typescript
-import { Validator } from '../core/validation/validator.js';
-import { ValidationReport } from '../core/validation/types.js';
-import chalk from 'chalk';
-```
-
-### 2. Basic Validation Pattern
-
-```typescript
-export class NewCommand {
-  async execute(options: CommandOptions): Promise<void> {
-    // Create validator instance
-    const validator = new Validator(options.strict);
-    
-    // Validate the spec or change
-    const report = await validator.validateSpec(filePath);
-    // or
-    const report = await validator.validateChange(filePath);
-    
-    // Handle validation results
-    if (!report.valid && !options.skipValidation) {
-      this.displayValidationErrors(report);
-      throw new Error('Validation failed');
-    }
-    
-    // Continue with command logic...
-  }
-  
-  private displayValidationErrors(report: ValidationReport): void {
-    console.log(chalk.red('\nValidation errors:'));
-    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}`));
-      } else {
-        console.log(chalk.blue(`  ℹ ${issue.message}`));
-      }
-    }
-  }
-}
-```
-
-### 3. Adding Skip Validation Option
-
-```typescript
-// In CLI definition
-.option('--no-validate', 'Skip validation (not recommended)')
-
-// In command execution
-if (!options.noValidate) {
-  // Perform validation
-  const report = await validator.validateSpec(filePath);
-  
-  if (!report.valid) {
-    // Handle validation failure
-  }
-} else {
-  // Log warning about skipping validation
-  const timestamp = new Date().toISOString();
-  console.log(chalk.yellow(`⚠️  WARNING: Skipping validation`));
-  console.log(chalk.yellow(`[${timestamp}] Validation skipped for: ${filePath}`));
-  
-  // Optionally require confirmation
-  if (!options.yes) {
-    const proceed = await confirm({
-      message: 'Continue without validation? (y/N)',
-      default: false
-    });
-    if (!proceed) {
-      console.log('Operation cancelled.');
-      return;
-    }
-  }
-}
-```
-
-### 4. Non-Blocking Validation (Warnings Only)
-
-```typescript
-// For commands that should show warnings but continue
-const report = await validator.validateSpec(filePath);
-
-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) {
-    // Block on errors
-    this.displayValidationErrors(report);
-    throw new Error('Validation failed with errors');
-  } else if (warnings.length > 0) {
-    // Show warnings but continue
-    console.log(chalk.yellow('\n⚠️  Validation warnings:'));
-    this.displayValidationErrors(report);
-    console.log(chalk.yellow('\nConsider fixing these issues.\n'));
-  }
-}
-
-// Continue with command...
-```
-
-## Extending Validation Rules
-
-### 1. Add New Constants
-
-```typescript
-// In src/core/validation/constants.ts
-export const NEW_THRESHOLD = 100;
-export const VALIDATION_MESSAGES = {
-  // ... existing messages
-  NEW_RULE_MESSAGE: 'New validation rule message',
-};
-```
-
-### 2. Update Schema with New Rules
-
-```typescript
-// In appropriate schema file
-import { NEW_THRESHOLD, VALIDATION_MESSAGES } from '../validation/constants.js';
-
-export const ExtendedSchema = z.object({
-  // ... existing fields
-  newField: z.string()
-    .min(NEW_THRESHOLD, VALIDATION_MESSAGES.NEW_RULE_MESSAGE)
-});
-```
-
-### 3. Add Custom Validation Logic
-
-```typescript
-// In src/core/validation/validator.ts
-private applyCustomRules(data: CustomType): ValidationIssue[] {
-  const issues: ValidationIssue[] = [];
-  
-  // Add custom validation logic
-  if (data.someField.length > NEW_THRESHOLD) {
-    issues.push({
-      level: 'WARNING',
-      path: 'someField',
-      message: VALIDATION_MESSAGES.NEW_RULE_MESSAGE,
-    });
-  }
-  
-  return issues;
-}
-```
-
-## Testing Validation
-
-### 1. Unit Test Schema Validation
-
-```typescript
-import { describe, it, expect } from 'vitest';
-import { NewSchema } from '../../src/core/schemas/new.schema.js';
-
-describe('NewSchema', () => {
-  it('should validate valid data', () => {
-    const data = { /* valid data */ };
-    const result = NewSchema.safeParse(data);
-    expect(result.success).toBe(true);
-  });
-  
-  it('should reject invalid data', () => {
-    const data = { /* invalid data */ };
-    const result = NewSchema.safeParse(data);
-    expect(result.success).toBe(false);
-    if (!result.success) {
-      expect(result.error.issues[0].message).toBe('Expected error message');
-    }
-  });
-});
-```
-
-### 2. Integration Test Command Validation
-
-```typescript
-it('should validate before executing', async () => {
-  const command = new NewCommand();
-  
-  // Create invalid data
-  await fs.writeFile(testPath, invalidContent);
-  
-  // Execute should fail due to validation
-  await expect(command.execute({ filePath: testPath }))
-    .rejects.toThrow('Validation failed');
-});
-
-it('should skip validation with flag', async () => {
-  const command = new NewCommand();
-  const mockConfirm = vi.fn().mockResolvedValue(true);
-  
-  // Execute with skip validation
-  await command.execute({ 
-    filePath: testPath, 
-    noValidate: true,
-    yes: true 
-  });
-  
-  // Should succeed despite invalid data
-  expect(mockConfirm).not.toHaveBeenCalled();
-});
-```
-
-## Integration Checklist
-
-When adding validation to a new command:
-
-- [ ] Import Validator and related types
-- [ ] Add validation before critical operations
-- [ ] Handle validation errors appropriately
-- [ ] Add --no-validate flag if skipping should be allowed
-- [ ] Require confirmation for validation skips
-- [ ] Log validation skips with timestamp
-- [ ] Add tests for validation scenarios
-- [ ] Update command documentation
-- [ ] Document any new validation rules
-
-## Common Patterns
-
-### Pre-Operation Validation
-Use for destructive operations (archive, delete, modify):
-```typescript
-if (!options.noValidate) {
-  const report = await validator.validateSpec(filePath);
-  if (!report.valid) {
-    throw new Error('Cannot proceed with invalid spec');
-  }
-}
-```
-
-### Informational Validation
-Use for read-only operations (diff, list, show):
-```typescript
-const report = await validator.validateSpec(filePath);
-if (report.issues.length > 0) {
-  console.log(chalk.yellow('Note: This spec has validation issues'));
-}
-// Continue regardless
-```
-
-### Progressive Enhancement
-Start with warnings, gradually enforce:
-```typescript
-const report = await validator.validateSpec(filePath);
-const hasErrors = report.issues.some(i => i.level === 'ERROR');
-
-if (hasErrors && process.env.STRICT_VALIDATION) {
-  throw new Error('Strict validation enabled, errors found');
-} else if (hasErrors) {
-  console.log(chalk.yellow('Validation errors found (will be enforced in future)'));
-}
-```

openspec/VALIDATION.md

@@ -1,157 +0,0 @@
-# OpenSpec Validation Guide
-
-## Overview
-
-OpenSpec uses Zod for runtime validation of specifications and changes. The validation system ensures that all specs and changes conform to the required structure and quality standards.
-
-## Schema Structure
-
-### Spec Schema
-```typescript
-{
-  name: string,              // Spec identifier
-  overview: string,          // Description of the spec
-  requirements: [            // Array of requirements
-    {
-      text: string,          // Requirement text (must contain SHALL/MUST)
-      scenarios: [           // Array of test scenarios
-        {
-          given: string,     // Initial condition
-          when: string,      // Action taken
-          then: string       // Expected result
-        }
-      ]
-    }
-  ],
-  metadata?: {               // Optional metadata
-    version: string,
-    format: 'openspec',
-    sourcePath?: string
-  }
-}
-```
-
-### Change Schema
-```typescript
-{
-  name: string,              // Change identifier
-  why: string,               // Justification (50-1000 chars)
-  whatChanges: string,       // Description of changes
-  deltas: [                  // Array of spec changes
-    {
-      spec: string,          // Affected spec name
-      operation: 'ADDED' | 'MODIFIED' | 'REMOVED',
-      description: string,   // Delta description
-      requirements?: []      // New/modified requirements
-    }
-  ],
-  metadata?: {               // Optional metadata
-    version: string,
-    format: 'openspec-change',
-    sourcePath?: string
-  }
-}
-```
-
-## Validation Rules
-
-### Three-Tier Validation System
-
-#### ERROR Level (Blocking)
-- Missing required sections (Overview, Requirements, Why, What Changes)
-- Invalid heading hierarchy
-- Malformed requirement/scenario structure
-- Empty required fields
-
-#### WARNING Level (Should Fix)
-- Requirements without scenarios
-- Requirements missing SHALL/MUST keywords
-- Brief overview sections (<50 characters)
-- Brief why sections (<50 characters)
-- Missing requirements in ADDED/MODIFIED deltas
-- Delta descriptions too brief (<10 characters)
-
-#### INFO Level (Suggestions)
-- Very long requirement text (>500 characters)
-- Very long why sections (>1000 characters)
-- Scenarios without Given/When/Then structure
-- Too many deltas in single change (>10)
-
-## Validation Thresholds
-
-| Constant | Value | Description |
-|----------|-------|-------------|
-| MIN_WHY_SECTION_LENGTH | 50 | Minimum characters for change why section |
-| MIN_OVERVIEW_LENGTH | 50 | Minimum characters for spec overview |
-| MAX_WHY_SECTION_LENGTH | 1000 | Maximum characters for change why section |
-| MAX_REQUIREMENT_TEXT_LENGTH | 500 | Maximum characters per requirement |
-| MAX_DELTAS_PER_CHANGE | 10 | Maximum deltas in a single change |
-
-## Using Validation
-
-### Archive Command
-```bash
-# Validation runs by default
-openspec archive my-change
-
-# Skip validation (not recommended, requires confirmation)
-openspec archive my-change --no-validate
-```
-
-### Diff Command
-```bash
-# Shows validation warnings (non-blocking)
-openspec diff my-change
-```
-
-### Programmatic Usage
-```typescript
-import { Validator } from './src/core/validation/validator.js';
-
-const validator = new Validator();
-const report = await validator.validateSpec('path/to/spec.md');
-
-if (!report.valid) {
-  console.log('Validation failed:');
-  report.issues.forEach(issue => {
-    console.log(`[${issue.level}] ${issue.path}: ${issue.message}`);
-  });
-}
-```
-
-### Strict Mode
-```typescript
-// Fail on both errors and warnings
-const validator = new Validator(true);
-const report = await validator.validateSpec('path/to/spec.md');
-```
-
-## Validation Report Format
-
-```json
-{
-  "valid": false,
-  "issues": [
-    {
-      "level": "ERROR",
-      "path": "requirements[0].scenarios",
-      "message": "Requirement must have at least one scenario",
-      "line": 15,
-      "column": 0
-    }
-  ],
-  "summary": {
-    "errors": 1,
-    "warnings": 2,
-    "info": 1
-  }
-}
-```
-
-## Best Practices
-
-1. **Always validate before archiving** - The archive command validates by default to protect archive integrity
-2. **Fix errors immediately** - Errors indicate structural issues that prevent proper parsing
-3. **Address warnings before merging** - Warnings indicate quality issues that should be fixed
-4. **Consider info messages** - Info messages provide suggestions for improvement
-5. **Use strict mode in CI/CD** - Enforce both errors and warnings in automated pipelines

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

@@ -6,11 +6,8 @@ OpenSpec change proposals currently can only be viewed as markdown files, creati
 
 ## What Changes
 
-- Add new `openspec change` command with three subcommands: `show`, `list`, and `validate`
-- Implement JSON output capability for change proposals
-- Add Zod schemas for change structure validation
-- Maintain backward compatibility with existing `openspec list` command
-- Enable filtering options specific to changes (requirements-only view)
+- **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
 

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

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

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

@@ -63,4 +63,31 @@ 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.
+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/tasks.md

@@ -17,20 +17,36 @@
 - [ ] 2.6 Add tests for side-by-side view formatting
 
 ## 3. Update Archive Command
-- [ ] 3.1 Update cli-archive spec with delta processing behavior
-- [ ] 3.2 Implement normalized header matching (trim whitespace)
-- [ ] 3.3 Parse delta sections (ADDED/MODIFIED/REMOVED/RENAMED)
-- [ ] 3.4 Apply changes in order: RENAMED → REMOVED → MODIFIED → ADDED
-- [ ] 3.5 Validate delta operations:
-  - [ ] 3.5.1 MODIFIED/REMOVED requirements exist
-  - [ ] 3.5.2 ADDED requirements don't already exist
-  - [ ] 3.5.3 RENAMED FROM headers exist, TO headers don't
-  - [ ] 3.5.4 No duplicate headers within specs
-  - [ ] 3.5.5 Renamed requirements aren't also in ADDED
-- [ ] 3.6 Display operation counts (+ 2 added, ~ 3 modified, etc.)
-- [ ] 3.7 Add tests for header normalization
-- [ ] 3.8 Add tests for applying deltas in correct order
-- [ ] 3.9 Add tests for validation edge cases
+- [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

openspec/specs/cli-archive/spec.md

@@ -11,7 +11,7 @@ openspec archive [change-name] [--yes|-y]
 Options:
 - `--yes`, `-y`: Skip confirmation prompts (for automation)
 
-## Behavior
+## Requirements
 
 ### Requirement: Change Selection
 

openspec/specs/cli-diff/spec.md

@@ -10,7 +10,7 @@ The `openspec diff` command provides developers with a visual comparison between
 openspec diff [change-name]
 ```
 
-## Behavior
+## Requirements
 
 ### Requirement: Without Arguments
 

openspec/specs/cli-init/spec.md

@@ -4,7 +4,7 @@
 
 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
 
 ### Requirement: Progress Indicators
 

openspec/specs/cli-list/spec.md

@@ -4,7 +4,7 @@
 
 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
+## Requirements
 
 ### Requirement: Command Execution
 

src/cli/index.ts

@@ -7,6 +7,8 @@ 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';
 
 const program = new Command();
 
@@ -15,6 +17,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')
@@ -79,9 +92,10 @@ program
 
 program
   .command('list')
-  .description('List all active changes with their task status')
+  .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) {
@@ -91,6 +105,57 @@ program
     }
   });
 
+// 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')
+  .action(async (changeName?: string, options?: { strict?: boolean; json?: 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')
@@ -108,4 +173,6 @@ program
     }
   });
 
+registerSpecCommand(program);
+
 program.parse();

src/commands/change.ts

@@ -0,0 +1,248 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+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';
+
+// 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 }): 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}`);
+    }
+    
+    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,206 @@
+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';
+
+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')
+    .action(async (specId: string, options: { strict?: boolean; json?: boolean }) => {
+      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`);
+        }
+
+        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/core/archive.ts

@@ -4,6 +4,12 @@ import { select, confirm } from '@inquirer/prompts';
 import { FileSystemUtils } from '../utils/file-system.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;
@@ -178,10 +184,31 @@ export class ArchiveCommand {
         }
 
         if (shouldUpdateSpecs) {
-          // Update specs
-          for (const update of specUpdates) {
-            await this.updateSpec(update);
+          // 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.');
         }
       }
@@ -301,14 +328,258 @@ export class ArchiveCommand {
     return updates;
   }
 
-  private async updateSpec(update: SpecUpdate): Promise<void> {
+  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);
 
-    // Copy spec file
-    const content = await fs.readFile(update.source, 'utf-8');
-    await fs.writeFile(update.target, content);
+    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 {

src/core/converters/json-converter.ts

@@ -1,5 +1,7 @@
 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 {
@@ -21,12 +23,13 @@ export class JsonConverter {
     return JSON.stringify(jsonSpec, null, 2);
   }
 
-  convertChangeToJson(filePath: string): string {
+  async convertChangeToJson(filePath: string): Promise<string> {
     const content = readFileSync(filePath, 'utf-8');
-    const parser = new MarkdownParser(content);
     const changeName = this.extractNameFromPath(filePath);
+    const changeDir = path.dirname(filePath);
+    const parser = new ChangeParser(content, changeDir);
     
-    const change = parser.parseChange(changeName);
+    const change = await parser.parseChangeWithDeltas(changeName);
     
     const jsonChange = {
       ...change,

src/core/parsers/change-parser.ts

@@ -0,0 +1,229 @@
+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}`,
+          requirement: 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,
+        });
+      });
+    }
+    
+    // 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,
+        });
+      });
+    }
+    
+    // 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

@@ -1,6 +1,6 @@
 import { Spec, Change, Requirement, Scenario, Delta, DeltaOperation } from '../schemas/index.js';
 
-interface Section {
+export interface Section {
   level: number;
   title: string;
   content: string;
@@ -18,11 +18,12 @@ export class MarkdownParser {
 
   parseSpec(name: string): Spec {
     const sections = this.parseSections();
-    const overview = this.findSection(sections, 'Overview')?.content || '';
+    const purpose = this.findSection(sections, 'Purpose')?.content || '';
+    
     const requirementsSection = this.findSection(sections, 'Requirements');
     
-    if (!overview) {
-      throw new Error('Spec must have an Overview section');
+    if (!purpose) {
+      throw new Error('Spec must have a Purpose section');
     }
     
     if (!requirementsSection) {
@@ -33,7 +34,7 @@ export class MarkdownParser {
 
     return {
       name,
-      overview: overview.trim(),
+      overview: purpose.trim(),
       requirements,
       metadata: {
         version: '1.0.0',
@@ -69,7 +70,7 @@ export class MarkdownParser {
     };
   }
 
-  private parseSections(): Section[] {
+  protected parseSections(): Section[] {
     const sections: Section[] = [];
     const stack: Section[] = [];
     
@@ -106,7 +107,7 @@ export class MarkdownParser {
     return sections;
   }
 
-  private getContentUntilNextHeader(startLine: number, currentLevel: number): string {
+  protected getContentUntilNextHeader(startLine: number, currentLevel: number): string {
     const contentLines: string[] = [];
     
     for (let i = startLine; i < this.lines.length; i++) {
@@ -123,7 +124,7 @@ export class MarkdownParser {
     return contentLines.join('\n').trim();
   }
 
-  private findSection(sections: Section[], title: string): Section | undefined {
+  protected findSection(sections: Section[], title: string): Section | undefined {
     for (const section of sections) {
       if (section.title.toLowerCase() === title.toLowerCase()) {
         return section;
@@ -136,11 +137,37 @@ export class MarkdownParser {
     return undefined;
   }
 
-  private parseRequirements(section: Section): Requirement[] {
+  protected parseRequirements(section: Section): Requirement[] {
     const requirements: Requirement[] = [];
     
     for (const child of section.children) {
-      const text = child.title;
+      // 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({
@@ -152,7 +179,7 @@ export class MarkdownParser {
     return requirements;
   }
 
-  private parseScenarios(requirementSection: Section): Scenario[] {
+  protected parseScenarios(requirementSection: Section): Scenario[] {
     const scenarios: Scenario[] = [];
     
     for (const scenarioSection of requirementSection.children) {
@@ -168,12 +195,13 @@ export class MarkdownParser {
   }
 
 
-  private parseDeltas(content: string): Delta[] {
+  protected parseDeltas(content: string): Delta[] {
     const deltas: Delta[] = [];
     const lines = content.split('\n');
     
     for (const line of lines) {
-      const deltaMatch = line.match(/^\s*-\s*\*\*([^:]+):\*\*\s*(.+)$/);
+      // 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();
@@ -182,7 +210,10 @@ export class MarkdownParser {
         const lowerDesc = description.toLowerCase();
         
         // Use word boundaries to avoid false matches (e.g., "address" matching "add")
-        if (/\badd(s|ed|ing)?\b/.test(lowerDesc) || /\bcreate(s|d|ing)?\b/.test(lowerDesc) || /\bnew\b/.test(lowerDesc)) {
+        // 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';

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/change.schema.ts

@@ -7,13 +7,18 @@ import {
   VALIDATION_MESSAGES 
 } from '../validation/constants.js';
 
-export const DeltaOperationType = z.enum(['ADDED', 'MODIFIED', 'REMOVED']);
+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({

src/core/schemas/spec.schema.ts

@@ -4,7 +4,7 @@ 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_OVERVIEW_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({

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/validation/constants.ts

@@ -4,7 +4,7 @@
 
 // Minimum character lengths
 export const MIN_WHY_SECTION_LENGTH = 50;
-export const MIN_OVERVIEW_LENGTH = 50;
+export const MIN_PURPOSE_LENGTH = 50;
 
 // Maximum character/item limits
 export const MAX_WHY_SECTION_LENGTH = 1000;
@@ -19,7 +19,7 @@ export const VALIDATION_MESSAGES = {
   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_OVERVIEW_EMPTY: 'Overview section 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`,
@@ -31,7 +31,7 @@ export const VALIDATION_MESSAGES = {
   DELTA_DESCRIPTION_EMPTY: 'Delta description cannot be empty',
   
   // Warnings
-  OVERVIEW_TOO_BRIEF: `Overview section is too brief (less than ${MIN_OVERVIEW_LENGTH} characters)`,
+  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',

src/core/validation/validator.ts

@@ -1,10 +1,12 @@
 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_OVERVIEW_LENGTH,
+  MIN_PURPOSE_LENGTH,
   MAX_REQUIREMENT_TEXT_LENGTH,
   VALIDATION_MESSAGES 
 } from './constants.js';
@@ -50,10 +52,11 @@ export class Validator {
     
     try {
       const content = readFileSync(filePath, 'utf-8');
-      const parser = new MarkdownParser(content);
       const changeName = this.extractNameFromPath(filePath);
+      const changeDir = path.dirname(filePath);
+      const parser = new ChangeParser(content, changeDir);
       
-      const change = parser.parseChange(changeName);
+      const change = await parser.parseChangeWithDeltas(changeName);
       
       const result = ChangeSchema.safeParse(change);
       
@@ -85,11 +88,11 @@ export class Validator {
   private applySpecRules(spec: Spec, content: string): ValidationIssue[] {
     const issues: ValidationIssue[] = [];
     
-    if (spec.overview.length < MIN_OVERVIEW_LENGTH) {
+    if (spec.overview.length < MIN_PURPOSE_LENGTH) {
       issues.push({
         level: 'WARNING',
         path: 'overview',
-        message: VALIDATION_MESSAGES.OVERVIEW_TOO_BRIEF,
+        message: VALIDATION_MESSAGES.PURPOSE_TOO_BRIEF,
       });
     }
     

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/core/archive.test.ts

@@ -93,21 +93,18 @@ describe('ArchiveCommand', () => {
       );
     });
 
-    it('should update specs when archiving', async () => {
+    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 valid spec in change
-      const specContent = `# Test Capability Spec
+      // Create delta-based change spec (ADDED requirement)
+      const specContent = `# Test Capability Spec - Changes
 
-## Overview
-This is a test capability specification for testing purposes.
+## ADDED Requirements
 
-## Requirements
-
-### The system SHALL provide test capability
+### Requirement: The system SHALL provide test capability
 
 #### Scenario: Basic test
 Given a test condition
@@ -118,10 +115,15 @@ Then expected result happens`;
       // Execute archive with --yes flag and skip validation for speed
       await archiveCommand.execute(changeName, { yes: true, noValidate: true });
       
-      // Verify spec was copied to main specs
+      // Verify spec was created from skeleton and ADDED requirement applied
       const mainSpecPath = path.join(tempDir, 'openspec', 'specs', 'test-capability', 'spec.md');
-      const copiedContent = await fs.readFile(mainSpecPath, 'utf-8');
-      expect(copiedContent).toBe(specContent);
+      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 () => {
@@ -225,7 +227,7 @@ Then expected result happens`;
       // Create valid spec in change
       const specContent = `# Test Capability Spec
 
-## Overview
+## Purpose
 This is a test capability specification.
 
 ## Requirements
@@ -265,6 +267,278 @@ Then expected result happens`;
       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', () => {

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

@@ -19,7 +19,7 @@ describe('JsonConverter', () => {
     it('should convert a spec to JSON format', async () => {
       const specContent = `# User Authentication Spec
 
-## Overview
+## Purpose
 This specification defines the requirements for user authentication.
 
 ## Requirements
@@ -53,7 +53,7 @@ Then they are authenticated`;
       
       const specContent = `# User Auth
 
-## Overview
+## Purpose
 Auth spec overview
 
 ## Requirements
@@ -89,7 +89,7 @@ We need to implement user authentication to secure the application and protect u
       const changePath = path.join(testDir, 'change.md');
       await fs.writeFile(changePath, changeContent);
       
-      const json = converter.convertChangeToJson(changePath);
+      const json = await converter.convertChangeToJson(changePath);
       const parsed = JSON.parse(json);
       
       expect(parsed.name).toBe('change');
@@ -117,7 +117,7 @@ We need authentication for security reasons and to protect user data properly.
       const changePath = path.join(changesDir, 'proposal.md');
       await fs.writeFile(changePath, changeContent);
       
-      const json = converter.convertChangeToJson(changePath);
+      const json = await converter.convertChangeToJson(changePath);
       const parsed = JSON.parse(json);
       
       expect(parsed.name).toBe('add-auth');
@@ -128,7 +128,7 @@ We need authentication for security reasons and to protect user data properly.
     it('should produce properly formatted JSON with indentation', async () => {
       const specContent = `# Test
 
-## Overview
+## Purpose
 Test overview
 
 ## Requirements
@@ -157,7 +157,7 @@ Then result`;
     it('should handle special characters in content', async () => {
       const specContent = `# Test
 
-## Overview
+## Purpose
 This has "quotes" and \\ backslashes and
 newlines
 

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

@@ -6,7 +6,7 @@ describe('MarkdownParser', () => {
     it('should parse a valid spec', () => {
       const content = `# User Authentication Spec
 
-## Overview
+## Purpose
 This specification defines the requirements for user authentication.
 
 ## Requirements
@@ -35,7 +35,7 @@ Then they see an error message`;
       expect(spec.requirements).toHaveLength(2);
       
       const firstReq = spec.requirements[0];
-      expect(firstReq.text).toContain('SHALL provide secure user authentication');
+      expect(firstReq.text).toBe('Users need to be able to log in securely.');
       expect(firstReq.scenarios).toHaveLength(1);
       
       const scenario = firstReq.scenarios[0];
@@ -47,12 +47,13 @@ Then they see an error message`;
     it('should handle multi-line scenarios', () => {
       const content = `# Test Spec
 
-## Overview
+## Purpose
 Test overview
 
 ## Requirements
 
 ### The system SHALL handle complex scenarios
+This requirement has content.
 
 #### Scenario: Multi-line scenario
 Given a user with valid credentials
@@ -89,13 +90,13 @@ When action
 Then result`;
 
       const parser = new MarkdownParser(content);
-      expect(() => parser.parseSpec('test')).toThrow('must have an Overview section');
+      expect(() => parser.parseSpec('test')).toThrow('must have a Purpose section');
     });
 
     it('should throw error for missing requirements', () => {
       const content = `# Test Spec
 
-## Overview
+## Purpose
 This is a test spec`;
 
       const parser = new MarkdownParser(content);
@@ -174,7 +175,7 @@ Some general description of changes without specific deltas`;
     it('should handle nested sections correctly', () => {
       const content = `# Test Spec
 
-## Overview
+## Purpose
 This is the overview section for testing nested sections.
 
 ## Requirements
@@ -205,7 +206,7 @@ Then success`;
     it('should preserve content between headers', () => {
       const content = `# Test
 
-## Overview
+## Purpose
 This is the overview.
 It has multiple lines.
 
@@ -222,5 +223,50 @@ Content for requirement 1`;
       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/validation.test.ts

@@ -194,13 +194,13 @@ describe('Validator', () => {
     it('should validate a valid spec file', async () => {
       const specContent = `# User Authentication Spec
 
-## Overview
+## Purpose
 This specification defines the requirements for user authentication in the system.
 
 ## Requirements
 
 ### The system SHALL provide secure user authentication
-Users need to be able to log in and out of the system securely.
+The system SHALL provide secure user authentication mechanisms.
 
 #### Scenario: Successful login
 Given a user with valid credentials
@@ -208,7 +208,7 @@ When they submit the login form
 Then they are authenticated and redirected to the dashboard
 
 ### The system SHALL handle invalid login attempts
-The system must gracefully handle incorrect credentials.
+The system SHALL gracefully handle incorrect credentials.
 
 #### Scenario: Invalid credentials
 Given a user with invalid credentials
@@ -245,7 +245,7 @@ Then authenticated`;
       
       expect(report.valid).toBe(false);
       expect(report.summary.errors).toBeGreaterThan(0);
-      expect(report.issues.some(i => i.message.includes('Overview'))).toBe(true);
+      expect(report.issues.some(i => i.message.includes('Purpose'))).toBe(true);
     });
   });
 
@@ -292,7 +292,7 @@ We need to implement user authentication to secure the application and protect u
     it('should fail on warnings in strict mode', async () => {
       const specContent = `# Test Spec
 
-## Overview
+## Purpose
 Brief overview
 
 ## Requirements
@@ -316,7 +316,7 @@ Then result`;
     it('should pass warnings in non-strict mode', async () => {
       const specContent = `# Test Spec
 
-## Overview
+## Purpose
 Brief overview
 
 ## Requirements