openspecui 0.0.0

package/references/openspec/openspec/changes/archive/2025-08-19-add-skip-specs-archive-option/specs/cli-archive/spec.md

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

package/references/openspec/openspec/changes/archive/2025-08-19-add-skip-specs-archive-option/tasks.md

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

package/references/openspec/openspec/changes/archive/2025-08-19-add-spec-commands/design.md

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

package/references/openspec/openspec/changes/archive/2025-08-19-add-spec-commands/proposal.md

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

package/references/openspec/openspec/changes/archive/2025-08-19-add-spec-commands/specs/cli-spec/spec.md

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

package/references/openspec/openspec/changes/archive/2025-08-19-add-spec-commands/tasks.md

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

package/references/openspec/openspec/changes/archive/2025-08-19-add-zod-validation/design.md

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

package/references/openspec/openspec/changes/archive/2025-08-19-add-zod-validation/proposal.md

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

package/references/openspec/openspec/changes/archive/2025-08-19-add-zod-validation/specs/cli-archive/spec.md

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

package/references/openspec/openspec/changes/archive/2025-08-19-add-zod-validation/specs/cli-diff/spec.md

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

package/references/openspec/openspec/changes/archive/2025-08-19-add-zod-validation/tasks.md

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