docs: update document to curret state

Author: wislertt

.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`)

.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.

.dev/00-architecture-insights.md

@@ -0,0 +1,63 @@
+# Architecture Insights - Key Decisions
+
+## Universal Version Format (Zerv)
+
+- **Component-based format system** with variable references
+- **Separation of format template from data values**
+- **Support for timestamp patterns** (YYYY, MM, DD, YYYYMMDD)
+- **Extensible custom variables** via HashMap
+- **Status**: ✅ Fully implemented in `src/version/zerv/`
+
+## State-Based Versioning Tiers
+
+**Three-tier system based on repository state:**
+
+- **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>`
+
+## Multi-Format Support Strategy
+
+- **PEP440** for Python ecosystem (`1.2.3.post7.dev0+g29045e8`)
+- **SemVer** for JavaScript/Node (`1.2.3-post.7+g29045e8`)
+- **Template-based** custom formats
+- **Status**: ✅ PEP440 and SemVer implemented
+
+## Error Handling Strategy
+
+- **Library layer**: Specific error types (`ZervError`)
+- **CLI layer**: User-friendly messages
+- **Use `io::Error::other()` instead of `io::Error::new(io::ErrorKind::Other, ...)`**
+- **Status**: ✅ Pattern established
+
+## Testing Strategy
+
+- **Local**: Docker Git for isolation
+- **CI**: Native Git for platform testing
+- **Atomic operations** using single Docker commands
+- **Status**: ✅ Successfully implemented
+
+## Performance Targets
+
+- **Parse 1000+ versions in <100ms**
+- **Minimal VCS command calls**
+- **Compiled regex patterns for speed**
+- **Zero-copy string operations where possible**
+
+## Configuration System Design (Future)
+
+```toml
+# Custom schemas: Different data structure + standard format output
+[schemas]
+calver-schema = '(core: [VarTimestamp("YYYY"), VarTimestamp("MM"), VarField("patch")], ...)'
+
+# Custom templates: Default schema + custom output format
+[templates]
+my-format = "v{{ major }}.{{ minor }}.{{ patch }}-{{ commit }}"
+```
+
+## Complementary Tool Strategy
+
+- **semantic-release**: Official release decisions and tagging
+- **zerv**: Continuous version identification for builds
+- **Perfect complementary workflow** for modern CI/CD