docs: update document to current state (#61)

- update document to current state
- fix any error handling standard violation

Author: wislertt

.amazonq/rules/cli-implementation.md

@@ -0,0 +1,135 @@
+# CLI Implementation Standards
+
+## Core Commands
+
+### `zerv version [OPTIONS]`
+
+Main version processing pipeline with composable operations.
+
+### `zerv check <version> [OPTIONS]`
+
+Validation-only command for version strings.
+
+## Pipeline Architecture
+
+```
+Input → Version Object → Zerv Object → Transform → Output Version Object → Display
+```
+
+## Key Implementation Patterns
+
+### Version Command Args Structure
+
+```rust
+#[derive(Parser)]
+struct VersionArgs {
+    version: Option<String>,
+    #[arg(long, default_value = "git")]
+    source: String,
+    #[arg(long, default_value = "zerv-default")]
+    schema: String,
+    #[arg(long)]
+    schema_ron: Option<String>,
+    #[arg(long)]
+    output_format: Option<String>,
+}
+```
+
+### Check Command Args Structure
+
+```rust
+#[derive(Parser)]
+struct CheckArgs {
+    version: String,
+    #[arg(long)]
+    format: Option<String>,  // pep440, semver, auto-detect (default)
+}
+```
+
+### Core Pipeline Function
+
+```rust
+pub fn run_version_pipeline(args: VersionArgs) -> Result<String> {
+    // 1. Get VCS data
+    let vcs_data = detect_vcs(current_dir())?.get_vcs_data()?;
+
+    // 2. Convert to ZervVars
+    let vars = vcs_data_to_zerv_vars(vcs_data)?;
+
+    // 3. Apply schema and output format
+    match args.output_format.as_deref() {
+        Some("pep440") => Ok(PEP440::from_zerv(&vars)?.to_string()),
+        Some("semver") => Ok(SemVer::from_zerv(&vars)?.to_string()),
+        _ => Ok(vars.to_string()),
+    }
+}
+```
+
+## State-Based Versioning Tiers
+
+**Tier 1** (Tagged, clean): `major.minor.patch`
+**Tier 2** (Distance, clean): `major.minor.patch.post<distance>+branch.<commit>`
+**Tier 3** (Dirty): `major.minor.patch.dev<timestamp>+branch.<commit>`
+
+## Format Flag Validation Pattern
+
+```rust
+// Error if conflicting format flags used
+if args.format.is_some() && (args.input_format.is_some() || args.output_format.is_some()) {
+    return Err(ZervError::ConflictingFlags(
+        "Cannot use --format with --input-format or --output-format".to_string()
+    ));
+}
+```
+
+## Check Command Auto-Detection Pattern
+
+```rust
+fn run_check_command(args: CheckArgs) -> Result<()> {
+    match args.format.as_deref() {
+        Some("pep440") => {
+            PEP440::parse(&args.version)?;
+            println!("✓ Valid PEP440 version");
+        }
+        Some("semver") => {
+            SemVer::parse(&args.version)?;
+            println!("✓ Valid SemVer version");
+        }
+        None => {
+            // Auto-detect format
+            let pep440_valid = PEP440::parse(&args.version).is_ok();
+            let semver_valid = SemVer::parse(&args.version).is_ok();
+
+            match (pep440_valid, semver_valid) {
+                (true, false) => println!("✓ Valid PEP440 version"),
+                (false, true) => println!("✓ Valid SemVer version"),
+                (true, true) => {
+                    println!("✓ Valid PEP440 version");
+                    println!("✓ Valid SemVer version");
+                }
+                (false, false) => return Err(ZervError::InvalidVersion(args.version)),
+            }
+        }
+        Some(format) => return Err(ZervError::UnknownFormat(format.to_string())),
+    }
+    Ok(())
+}
+```
+
+## Essential CLI Options
+
+### Input Sources
+
+- `--source git` (default) - Auto-detect Git
+- `--source string <version>` - Parse version string
+
+### Schema Control
+
+- `--schema zerv-default` (default) - Tier-aware schema
+- `--schema-ron <ron>` - Custom RON schema
+
+### Output Control
+
+- `--output-format <format>` - Target format: pep440, semver
+- `--output-template <template>` - Custom template string
+- `--output-prefix [prefix]` - Add prefix (defaults to "v")

.amazonq/rules/dev-workflow.md

@@ -4,6 +4,19 @@
 
 Before performing ANY coding task, **read `.dev/00-README.md`** for complete project context and workflow.
 
+## .dev Document Numbering
+
+**Rule**: All .dev documents use sequential numbering to indicate creation order:
+
+- `00-***.md`: Created at same point in time (current state)
+- `01-***.md`: Next development phase
+- `02-***.md`: Following phase
+- etc.
+
+**Higher numbers = more recent/updated plans**
+
+Always verify against actual codebase - higher numbered docs are more likely to be current.
+
 ## Essential Commands
 
 ✅ Use `make` commands (defined in `.dev/00-README.md`)
@@ -22,6 +35,20 @@ Before performing ANY coding task, **read `.dev/00-README.md`** for complete pro
 - Include context in error messages for debugging
 - Use `io::Error::other()` instead of `io::Error::new(io::ErrorKind::Other, ...)`
 
+## Performance Standards
+
+- Parse 1000+ versions in <100ms
+- Minimal VCS command calls (batch when possible)
+- Use compiled regex patterns for speed
+- Zero-copy string operations where possible
+
+## Architecture Patterns
+
+- **Universal Format**: Component-based system with variable references
+- **Multi-Format Support**: PEP440, SemVer, template-based custom formats
+- **State-Based Tiers**: Tagged/Distance/Dirty states determine version components
+- **Pipeline Architecture**: Input → Parse → Transform → Output
+
 **Error Standard Violations Check:**
 
 When user mentions:

.amazonq/rules/docker-git-testing.md

@@ -207,20 +207,63 @@ make test
 1. `src/test_utils/git/mod.rs` - GitOperations trait and exports
 2. `src/test_utils/git/docker.rs` - DockerGit implementation (local development)
 3. `src/test_utils/git/native.rs` - NativeGit implementation (CI testing)
-4. `src/config.rs` - Environment detection via `ZERV_CI` variable
-5. `src/test_utils/mod.rs` - `should_use_native_git()` helper function
+4. `src/config.rs` - Centralized environment variable loading via `ZERV_TEST_NATIVE_GIT` and `ZERV_TEST_DOCKER`
+5. `src/test_utils/mod.rs` - `should_use_native_git()` and `should_run_docker_tests()` helper functions
+
+## Environment Variable Matrix
+
+| Scenario         | `ZERV_TEST_NATIVE_GIT` | `ZERV_TEST_DOCKER` | Git Implementation | Docker Tests | Result             |
+| ---------------- | ---------------------- | ------------------ | ------------------ | ------------ | ------------------ |
+| Local Easy       | `false`                | `false`            | Docker Git         | Skipped      | Coverage with gaps |
+| Local Full       | `false`                | `true`             | Docker Git         | Run          | Full coverage      |
+| CI Linux         | `true`                 | `true`             | Native Git         | Run          | Platform coverage  |
+| CI macOS/Windows | `true`                 | `false`            | Native Git         | Skipped      | Platform coverage  |
+
+## Centralized Configuration
+
+**All environment variable loading centralized in `src/config.rs`:**
+
+```rust
+#[derive(Debug, Clone, Default)]
+pub struct ZervConfig {
+    pub test_native_git: bool,  // ZERV_TEST_NATIVE_GIT
+    pub test_docker: bool,      // ZERV_TEST_DOCKER
+}
+
+impl ZervConfig {
+    pub fn load() -> Result<Self, Box<dyn std::error::Error>> {
+        let test_native_git = Self::parse_bool_env("ZERV_TEST_NATIVE_GIT")?;
+        let test_docker = Self::parse_bool_env("ZERV_TEST_DOCKER")?;
+        Ok(ZervConfig { test_native_git, test_docker })
+    }
+
+    fn parse_bool_env(var_name: &str) -> Result<bool, Box<dyn std::error::Error>> {
+        match env::var(var_name) {
+            Ok(val) => Ok(val == "true" || val == "1"),
+            Err(_) => Ok(false),
+        }
+    }
+}
+```
+
+**Key Behavior Changes:**
+
+- Docker tests **fail** with clear error messages when `ZERV_TEST_DOCKER=true` but Docker unavailable
+- Policy enforcement: If Docker is available, tests must be enabled
+- Proper test separation between Docker-dependent and Docker-independent tests
 
 ## Current Testing Verification
 
 ```bash
 # Local test (uses DockerGit for isolation)
-make test
+make test_easy  # Docker tests skipped
+make test       # Docker tests enabled
 
 # Test validation works
 cargo test test_docker_validation --lib
 
-# Check specific git tests (Docker tests only run on Linux)
-cargo test git --include-ignored
+# Check specific git tests
+cargo test git
 
 # Verify multi-platform CI passes
 git push # Check GitHub Actions on Linux, macOS, Windows
@@ -237,7 +280,7 @@ git push # Check GitHub Actions on Linux, macOS, Windows
 **Local Safety Maintained**:
 
 - ✅ **Docker Isolation**: Protects personal git config during local development
-- ✅ **Environment Detection**: Automatic switching via `ZERV_CI=true`
+- ✅ **Environment Detection**: Automatic switching via `ZERV_TEST_NATIVE_GIT=true`
 - ✅ **Consistent API**: Same `GitOperations` trait for both implementations
 
 ## Architecture Evolution

.amazonq/rules/testing-standards.md

@@ -13,7 +13,7 @@
 **CI Environment:**
 
 - Use `NativeGit` for real platform testing (Windows/macOS/Linux)
-- Enabled automatically via `ZERV_CI=true` environment variable
+- Enabled automatically via `ZERV_TEST_NATIVE_GIT=true` environment variable
 - Tests actual platform-specific Git behavior, paths, line endings
 
 **Implementation Pattern:**
@@ -31,6 +31,41 @@ fn get_git_impl() -> Box<dyn GitOperations> {
 }
 ```
 
+## Docker Test Control
+
+**MANDATORY: Use `should_run_docker_tests()` for all Docker-dependent tests**
+
+**Environment Variables:**
+
+- `ZERV_TEST_DOCKER=true`: Enable Docker tests (requires Docker to be available)
+- `ZERV_TEST_DOCKER=false`: Skip Docker tests (default)
+
+**Policy Enforcement:**
+
+- If Docker is available on system, Docker tests MUST be enabled
+- Only skip Docker tests when Docker is genuinely unavailable
+- Tests will fail if `ZERV_TEST_DOCKER=true` but Docker is not available
+
+**Implementation Pattern:**
+
+```rust
+use crate::test_utils::should_run_docker_tests;
+
+#[test]
+fn test_docker_functionality() {
+    if !should_run_docker_tests() {
+        return; // Skip when Docker tests are disabled
+    }
+    // Docker-dependent test code
+}
+```
+
+**Make Commands:**
+
+- `make test_easy`: Docker Git + Docker tests skipped (fast, coverage gaps)
+- `make test`: Docker Git + Docker tests enabled (full coverage)
+- CI: Native Git + Docker tests on Linux only
+
 ## Race Condition Prevention
 
 **Atomic Operations Required:**

.dev/00-README.md

@@ -1,58 +1,40 @@
-# .dev/
+# Zerv Development Guide
 
-Development documentation for zerv - Dynamic Versioning CLI
+## Quick Start
 
-## Project Status
+1. **Check current state**: Read `00-current-state.md`
+2. **Key files**: Reference `00-key-files.md`
+3. **Run tests**: `make test_easy` (quick) or `make test` (full)
+4. **Check rules**: `.amazonq/rules/` for coding standards
 
-**Current State**: Version parsing system implemented
-**Next Step**: Building Git VCS integration
-**Target**: Alpha release with Git support
+## Current Priority
 
-## What's Implemented
+**CLI Implementation** - Core functionality exists, need CLI interface.
 
-✅ **Core Version System**
+## Architecture Overview
 
-- Universal `Zerv` format with component-based structure
-- PEP440 version parsing, display, and conversion
-- SemVer version parsing, display, and conversion
-- Comprehensive test coverage (91.40%)
-
-✅ **Development Infrastructure**
-
-- Docker-based testing for Git integration
-- Fast local tests without external dependencies
-- Makefile workflow with linting and formatting
-
-## Development Workflow
+```
+CLI → VCS Detection → Tag Parsing → Format Output
+```
 
-```bash
-# Fast development cycle (no Docker required)
-make lint         # Format and check code
-make run          # Test CLI binary
+**Key Components:**
 
-# Full validation (includes Docker tests)
-make test         # Run all tests including Docker integration
-make setup_dev    # Install development dependencies
-```
+- **VCS Layer**: Extract git metadata (`src/vcs/`)
+- **Version System**: Parse/convert formats (`src/version/`)
+- **Pipeline**: Transform data (`src/pipeline/`)
+- **CLI**: User interface (`src/cli/` - needs work)
 
-## Architecture
+## Testing Strategy
 
-```
-src/version/
-├── zerv/         # Universal version format
-├── pep440/       # PEP440 implementation
-├── semver/       # SemVer implementation
-└── mod.rs        # Public API
-```
+- **Local**: Docker Git for isolation
+- **CI**: Native Git for platform testing
+- **237 tests** with multi-platform coverage
 
-## Files
+## Environment Variables
 
-- `current-state.md` - Detailed implementation status
-- `new-cli-design.md` - Pipeline CLI architecture design
-- `roadmap.md` - Development roadmap to alpha release
-- `archived-insights.md` - Valuable concepts from old documentation
-- `.cache/` - Archived old documentation (preserved for reference)
+- `ZERV_TEST_NATIVE_GIT=true` - Use native Git (CI only)
+- `ZERV_TEST_DOCKER=true` - Enable Docker tests (Linux only)
 
-## Next Phase
+## Next Steps
 
-Git VCS integration + pipeline CLI (`zerv version` with `zerv-default` schema)
+Focus on `src/cli/app.rs` implementation to wire existing components together.