docs: update phase 2 plan

Author: wislertt

.dev/00-current-state.md

@@ -18,6 +18,10 @@ Main version processing pipeline with composable operations.
 
 Validation-only command for version strings.
 
+### `zerv compare <version1> <op> <version2> --format <format>`
+
+Version comparison command with format-specific ordering rules.
+
 ## Pipeline Stages
 
 ### 1. Input Sources (`--source`)
@@ -67,6 +71,10 @@ zerv version
 # Validate version
 zerv check 1.2.3
 
+# Compare versions (format required due to different ordering rules)
+zerv compare 1.2.3 gt 1.2.2 --format semver
+zerv compare 2.0.0a1 lt 2.0.0 --format pep440
+
 # Standard format output
 zerv version --output-format pep440
 
@@ -195,8 +203,62 @@ zerv version --output-format pep440 > VERSION.txt
 
 # Jenkins
 zerv version --output-template "{{major}}.{{minor}}.{{patch}}" > version.properties
+
+# Version comparison in CI
+CURRENT=$(git describe --tags --abbrev=0)
+NEW=$(zerv version --output-format semver)
+if zerv compare "$NEW" gt "$CURRENT" --format semver; then
+    echo "Deploying new version: $NEW"
+else
+    echo "Version $NEW is not newer than $CURRENT"
+    exit 1
+fi
+```
+
+## Version Comparison Command
+
+### `zerv compare <version1> <op> <version2> --format <format>`
+
+**Operators** (following `dpkg --compare-versions` pattern):
+
+- `gt` - greater than
+- `lt` - less than
+- `eq` - equal
+- `ge` - greater than or equal
+- `le` - less than or equal
+
+**Format Required**: Version ordering differs significantly between standards:
+
+- **PEP440**: `2.0.0a1 < 2.0.0b1 < 2.0.0rc1 < 2.0.0`
+- **SemVer**: `2.0.0-alpha.1 < 2.0.0-beta.1 < 2.0.0-rc.1 < 2.0.0`
+
+**Examples**:
+
+```bash
+# SemVer comparison
+zerv compare 1.2.3 gt 1.2.2 --format semver     # exit 0 (true)
+zerv compare 1.2.3 lt 1.2.2 --format semver     # exit 1 (false)
+zerv compare 2.0.0-alpha.1 lt 2.0.0 --format semver  # exit 0 (true)
+
+# PEP440 comparison
+zerv compare 1.2.3 eq 1.2.3 --format pep440     # exit 0 (true)
+zerv compare 2.0.0a1 lt 2.0.0 --format pep440   # exit 0 (true)
+zerv compare 1.2.3 ge 1.2.2 --format pep440     # exit 0 (true)
 ```
 
+**Use Cases**:
+
+- CI/CD pipeline version validation
+- Release automation scripts
+- Version constraint checking
+- Deployment safety checks
+
+**Exit Codes**:
+
+- `0` - Comparison is true
+- `1` - Comparison is false
+- `2` - Error (invalid version, unknown format, etc.)
+
 ## Benefits
 
 ### 1. **Unified Architecture**

.dev/00-new-cli-design.md

@@ -0,0 +1,138 @@
+# Current Implementation State
+
+## Phase 1 Complete ✅ - Git VCS Integration
+
+### 1. Universal Version System (`src/version/zerv/`)
+
+**Complete Implementation**:
+
+- `Zerv` - Universal version representation combining format template and data
+- `ZervFormat` - Component-based format definition (core, extra_core, build)
+- `ZervVars` - Variable storage for all version data
+- `Component` - Format components (String, Integer, VarField, VarTimestamp, VarCustom)
+
+**Key Features**:
+
+- Format-agnostic component system
+- Variable reference system for reusable data
+- Support for semantic versions, timestamps, VCS metadata
+- Extensible custom variables via HashMap
+
+### 2. PEP440 Implementation (`src/version/pep440/`)
+
+**Production-Ready**:
+
+- ✅ Parsing from strings with comprehensive regex
+- ✅ Display formatting with normalization
+- ✅ Conversion to/from Zerv format
+- ✅ Ordering and comparison
+- ✅ All PEP440 features: epoch, pre-release, post, dev, local versions
+
+### 3. SemVer Implementation (`src/version/semver/`)
+
+**Production-Ready**:
+
+- ✅ Core structure with major.minor.patch
+- ✅ Pre-release identifiers (string/integer)
+- ✅ Build metadata support
+- ✅ Conversion to/from Zerv format
+- ✅ Display formatting and parsing
+
+### 4. Git VCS Integration (`src/vcs/`)
+
+**Complete Implementation**:
+
+- ✅ VCS trait system with clean abstraction
+- ✅ Git repository detection and validation
+- ✅ Tag discovery and filtering (`get_latest_tag`)
+- ✅ Distance calculation from tag to HEAD
+- ✅ Commit hash extraction (short/full)
+- ✅ Dirty state detection
+- ✅ Branch name extraction
+- ✅ Timestamp handling (commit + tag)
+- ✅ Shallow clone detection with warnings
+- ✅ Docker-based testing for isolation
+- ✅ Comprehensive error handling
+
+### 5. Development Infrastructure
+
+**Production-Quality**:
+
+- ✅ 97.36% code coverage (2732/2806 lines)
+- ✅ Docker-based Git integration tests
+- ✅ Fast local tests (no external dependencies)
+- ✅ Makefile workflow for development
+- ✅ Automated formatting with rustfmt
+- ✅ Linting with clippy
+- ✅ Comprehensive error handling with `ZervError`
+
+## Phase 2 In Progress 🎯 - Pipeline CLI Interface
+
+### What's Built ✅
+
+**CLI Framework**:
+
+- ✅ Basic CLI structure (`src/cli/`) with clap integration
+- ✅ Command framework foundation
+- ✅ Error handling system ready
+
+### What's Missing ❌
+
+**Pipeline Implementation**:
+
+- ❌ `zerv version --source git` command
+- ❌ Integration between VCS data and version generation
+- ❌ RON schema parsing for custom schemas
+- ❌ `zerv-default` schema preset
+- ❌ VCS data to `ZervVars` mapping
+- ❌ Pattern matching for tag parsing
+
+## Phase 3 Not Started ⏳ - Output Templates
+
+**Missing Features**:
+
+- ❌ Template engine for `--output-template`
+- ❌ Variable substitution in templates
+- ❌ Template validation
+
+## Architecture Assessment
+
+### Strengths
+
+1. **Exceptional Foundation**: Universal Zerv format with complete format implementations
+2. **Production-Ready VCS**: Comprehensive Git integration with Docker testing
+3. **High Code Quality**: 97.36% test coverage, consistent error handling
+4. **Clean Architecture**: Excellent separation of concerns and abstractions
+5. **Type Safety**: Strong Rust typing prevents runtime errors
+
+### Current State
+
+- **Phase 1 (Git VCS)**: ✅ **COMPLETE** - Production-ready implementation
+- **Phase 2 (CLI)**: 🎯 **IN PROGRESS** - Framework ready, needs pipeline implementation
+- **Phase 3 (Templates)**: ⏳ **NOT STARTED**
+
+## Next Critical Steps
+
+### Immediate (Phase 2 Completion)
+
+1. **VCS-Version Integration**: Connect `VcsData` to `ZervVars`
+2. **CLI Pipeline**: Implement `zerv version --source git`
+3. **Schema System**: Add `zerv-default` preset and RON parsing
+4. **Tag Parsing**: Pattern matching for version extraction from tags
+
+### Success Criteria for Phase 2
+
+- `zerv version` generates versions from Git repository state
+- `--source git` explicitly uses Git VCS
+- Basic pipeline architecture functional
+- Integration tests pass for end-to-end workflow
+
+## Code Quality Metrics
+
+- **Test Coverage**: 97.36% (2732/2806 lines covered)
+- **Architecture**: Clean, modular, well-abstracted
+- **Error Handling**: Comprehensive with `ZervError`
+- **Performance**: Fast parsing, efficient memory usage
+- **Maintainability**: Excellent separation of concerns
+
+The project has a **exceptionally solid foundation** with Phase 1 complete. The VCS integration is more comprehensive than many production tools. Ready for rapid Phase 2 completion.