vibe-validate 0.17.1-rc.3 → 0.17.2

package/skill/resources/caching-internals.md

@@ -0,0 +1,366 @@
+# Caching Internals: Performance & How It Works
+
+## Overview
+
+vibe-validate achieves **dramatic speedup** through git-aware caching using content-based hashing. This document explains how the caching system works internally and how to leverage it for maximum performance.
+
+## Core Concept: Git Tree Hashing
+
+### What is a tree hash?
+
+A **tree hash** is git's way of creating a deterministic fingerprint of your working directory:
+- Content-based (same files = same hash)
+- No timestamps (purely about file contents)
+- Includes untracked files (not just committed code)
+- Deterministic (same state always produces same hash)
+
+### How vibe-validate uses tree hashes
+
+```bash
+# Behind the scenes on every validation:
+git add --intent-to-add .        # Stage untracked files
+git write-tree                    # Generate tree hash
+# Returns: abc123def456... (40-character SHA-1)
+```
+
+This tree hash becomes the **cache key** for validation results.
+
+## Performance Numbers
+
+Real-world measurements from vibe-validate development:
+
+| Scenario | Time | Speedup |
+|----------|------|---------|
+| **Cache miss** (first run) | ~90 seconds | 1x (baseline) |
+| **Cache hit** (no changes) | < 1 second | **Dramatically faster** |
+| **Partial cache** (1 file changed) | ~5-10 seconds | Faster re-validation |
+
+## Cache Key: What Invalidates Cache?
+
+### Cache invalidates when:
+- ✅ Any file content changes
+- ✅ New files added (even untracked)
+- ✅ Files deleted
+- ✅ File renamed
+- ✅ Working tree modifications
+
+### Cache persists when:
+- ✅ Switching branches (if same code state)
+- ✅ Git operations (commits, merges) that result in same tree
+- ✅ Time passing (content-based, not time-based)
+- ✅ .gitignore changes (ignored files not in tree hash)
+
+## How Caching Works: Step by Step
+
+### First Run (Cache Miss)
+
+```bash
+$ vv validate
+```
+
+1. **Calculate tree hash**: `git write-tree` → `abc123`
+2. **Check cache**: Look for `refs/notes/vibe-validate/validation/abc123`
+3. **Cache miss**: No notes found
+4. **Execute validation**: Run all phases (90 seconds)
+5. **Store result**: Save to `refs/notes/vibe-validate/validation/abc123`
+
+### Second Run (Cache Hit)
+
+```bash
+$ vv validate
+```
+
+1. **Calculate tree hash**: `git write-tree` → `abc123` (same!)
+2. **Check cache**: Look for `refs/notes/vibe-validate/validation/abc123`
+3. **Cache hit!**: Found notes with previous result
+4. **Return cached result**: No execution needed (288ms)
+
+### After Code Change (Partial Cache)
+
+```bash
+# Edit one file
+$ vv validate
+```
+
+1. **Calculate tree hash**: `git write-tree` → `def456` (different!)
+2. **Check cache**: Look for `refs/notes/vibe-validate/validation/def456`
+3. **Cache miss**: No notes found for new tree hash
+4. **Execute validation**: Run all phases again
+5. **Store result**: Save to `refs/notes/vibe-validate/validation/def456`
+
+## Cache Storage: Git Notes
+
+vibe-validate uses **git notes** for cache storage:
+
+```bash
+# View validation cache
+git notes --ref=refs/notes/vibe-validate/validation list
+
+# View specific cached result
+git notes --ref=refs/notes/vibe-validate/validation show <tree-hash>
+```
+
+### Why git notes?
+
+- ✅ Built into git (no external dependencies)
+- ✅ Survives branch switches
+- ✅ Works across clones (can be pushed/pulled)
+- ✅ Content-addressable (perfect for caching)
+- ✅ Garbage collected automatically by git
+
+## Run Command Caching (v0.15.0+)
+
+The `vv run` command has its own cache layer:
+
+```bash
+# First run - cache miss
+vv run "npm test"  # Executes (~30s)
+
+# Repeat run - cache hit
+vv run "npm test"  # Instant (<200ms)
+```
+
+### Cache key for run command
+
+Tree hash + command string:
+```
+cache_key = hash(tree_hash + "npm test")
+```
+
+Stored in: `refs/notes/vibe-validate/run/<tree-hash>/<command-hash>`
+
+## Leveraging Caching for Speed
+
+### Pattern 1: Incremental Fixes
+
+```bash
+# First run: Full validation (~90s)
+vv validate
+
+# Fix 1-2 errors in one file
+# Second run: New tree hash, re-validate
+vv validate  # (~90s again, but working toward green)
+
+# Fix is correct, no more changes
+# Third run: Cache hit!
+vv validate  # (288ms - instant!)
+```
+
+### Pattern 2: Fast Feedback Loop
+
+```bash
+# Use `run` for tight feedback during development
+vv run "npm test -- src/feature.test.ts"  # First run (~5s)
+
+# Make change
+vv run "npm test -- src/feature.test.ts"  # Re-runs (~5s)
+
+# No changes, verify still passes
+vv run "npm test -- src/feature.test.ts"  # Cache hit! (200ms)
+```
+
+### Pattern 3: Branch Switching
+
+```bash
+# On feature branch
+vv validate  # Cache result for feature code
+
+# Switch to main
+git checkout main
+vv validate  # Cache result for main code
+
+# Switch back to feature
+git checkout feature
+vv validate  # Cache hit! (same tree hash as before)
+```
+
+## Cache Control
+
+### Check cache without running
+
+```bash
+# Check if validation is cached
+vv validate --check
+# Exit 0: cached (green)
+# Exit 1: not cached (need to run)
+
+# Check if run command is cached
+vv run --check "npm test"
+```
+
+### Force cache refresh
+
+```bash
+# Force re-validation (ignore cache)
+vv validate --force
+
+# Force re-run (ignore cache)
+vv run --force "npm test"
+```
+
+### View cache state
+
+```bash
+# Show current validation state
+vv state
+
+# List all cached validations
+vv history list
+
+# List cached run commands
+vv history list --run
+```
+
+### Prune old cache
+
+```bash
+# Clear all validation history
+vv history prune --all
+
+# Clear only run cache
+vv history prune --run --all
+
+# Clear run cache for specific tree hash
+vv history prune --run --tree <tree-hash>
+```
+
+## Cache Misses: Common Causes
+
+### 1. Timestamp-based files
+
+**Problem**: Build artifacts with timestamps always change tree hash
+
+```bash
+# dist/bundle.js includes timestamp
+# Tree hash changes every build even if source unchanged
+```
+
+**Solution**: Add to .gitignore
+```bash
+echo "dist/" >> .gitignore
+```
+
+### 2. Lock file changes
+
+**Problem**: `package-lock.json` or `pnpm-lock.yaml` updates cause cache invalidation
+
+**Solution**: This is intentional! Dependencies changed = new validation needed.
+
+### 3. Untracked generated files
+
+**Problem**: Test coverage files, .tsbuildinfo, etc.
+
+**Solution**: Add to .gitignore
+```bash
+.tsbuildinfo
+coverage/
+.vitest/
+```
+
+## Debugging Cache Issues
+
+### Validation always runs (never cached)
+
+```bash
+# Check if in git repository
+git status
+
+# Check current tree hash
+git write-tree
+
+# Check if validation cached for current tree
+vv validate --check
+echo $?  # 0 = cached, 1 = not cached
+
+# See what's changing
+git status --short
+git diff
+```
+
+### Cache seems stale
+
+```bash
+# Check current tree hash
+current=$(git write-tree)
+
+# Check cached tree hash
+vv state | grep treeHash
+
+# Compare
+if [ "$current" != "$cached" ]; then
+  echo "Tree changed - cache correctly invalidated"
+fi
+
+# Force refresh if needed
+vv validate --force
+```
+
+### Performance slower than expected
+
+```bash
+# Run with timing
+time vv validate
+
+# If > 1 second on cache hit:
+# 1. Check git objects size: du -sh .git/objects
+# 2. Run git gc: git gc --aggressive
+# 3. Check disk I/O: iostat
+
+# If still slow, check:
+vv doctor
+```
+
+## Advanced: Cache Implementation Details
+
+### Tree hash calculation
+
+```typescript
+// Simplified implementation
+function getTreeHash(): string {
+  // Stage untracked files (intent-to-add, doesn't change index)
+  execSync('git add --intent-to-add .');
+
+  // Generate tree hash from current index
+  const treeHash = execSync('git write-tree').toString().trim();
+
+  // Unstage (cleanup)
+  execSync('git reset');
+
+  return treeHash;
+}
+```
+
+### Cache lookup
+
+```typescript
+function getCachedValidation(treeHash: string): ValidationResult | null {
+  const notesRef = `refs/notes/vibe-validate/validation`;
+
+  try {
+    const cached = execSync(
+      `git notes --ref=${notesRef} show ${treeHash}`
+    ).toString();
+
+    return JSON.parse(cached);
+  } catch {
+    return null; // Cache miss
+  }
+}
+```
+
+### Cache storage
+
+```typescript
+function cacheValidation(treeHash: string, result: ValidationResult): void {
+  const notesRef = `refs/notes/vibe-validate/validation`;
+  const data = JSON.stringify(result);
+
+  execSync(`git notes --ref=${notesRef} add -f -m '${data}' ${treeHash}`);
+}
+```
+
+## See Also
+
+- [Run Capability Guide](run-capability.md) - Deep dive on `vv run` caching
+- [CLI Reference](cli-reference.md) - Cache control flags
+- [Troubleshooting Guide](troubleshooting.md) - Cache issues

package/skill/resources/cli-reference.md

@@ -185,6 +185,16 @@ vibe-validate state --verbose # Show full error output
 
 ---
 
+### `snapshot`
+
+Show current worktree snapshot and recovery instructions
+
+**Options:**
+
+- `-v, --verbose` - Show detailed snapshot information
+
+---
+
 ### `sync-check`
 
 Check if branch is behind remote main branch

package/skill/resources/configure-project.md

@@ -4,7 +4,7 @@
 
 Configure your project to use vibe-validate for comprehensive validation with:
 - **Pre-commit validation** guardrails (prevent broken code from being committed)
-- **Git-aware caching** (312x speedup)
+- **Git-aware caching** (dramatic speedup)
 - **Team-wide consistency** (shared validation configuration)
 - **CI/CD integration** (same validation locally and in CI)
 

package/skill/resources/run-capability.md

@@ -3,7 +3,7 @@
 ## Overview
 
 The `vv run` capability provides **immediate benefits without any project configuration**. Just wrap any command to get:
-- **312x speedup** via git tree hash caching
+- **Dramatic speedup** via git tree hash caching
 - **95% token reduction** via smart error extraction
 - **Zero configuration** required
 
@@ -42,7 +42,7 @@ vv run ./gradlew build
 vv run npm test
 
 # Second run (no code changes): uses cache
-vv run npm test  # Instant! (312x faster)
+vv run npm test  # Instant! (dramatically faster)
 
 # After code change: re-runs automatically
 vv run npm test  # Executes again

package/skill/resources/work-recovery.md

@@ -0,0 +1,233 @@
+# Work Recovery & Protection
+
+## Overview
+
+vibe-validate automatically creates **recoverable snapshots** of your work during validation. Every time you run `vv validate`, `vv pre-commit`, or `vv run`, a git tree hash is created that captures your complete working directory state - including untracked files.
+
+## What Gets Protected
+
+Automatic snapshots include:
+- ✅ **Staged changes** (in git index)
+- ✅ **Unstaged modifications** (tracked files)
+- ✅ **Untracked files** (new files, not in .gitignore)
+
+Not protected (by design):
+- ❌ Files in .gitignore (secrets, build artifacts)
+
+## When Snapshots Are Created
+
+Automatic snapshots happen during:
+- `vv validate` - Full validation pipeline
+- `vv pre-commit` - Pre-commit workflow
+- `vv run <command>` - Individual command execution (v0.15.0+)
+
+Each creates a tree hash in git objects that captures complete working directory state at that moment.
+
+## View Validation Snapshots
+
+```bash
+# List all validation points (timestamped tree hashes)
+vv history list
+
+# Show details of specific validation
+vv history show <tree-hash>
+
+# YAML output for programmatic access
+vv history list --yaml
+
+# Limit to recent validations
+vv history list --limit 10
+```
+
+## Recover Lost Work
+
+### Scenario: Accidentally deleted files or ran `git restore .`
+
+```bash
+# Step 1: Find recent validation point
+vv history list --limit 5
+
+# Step 2: View file content from that validation
+git cat-file -p <tree-hash>:path/to/file.ts
+
+# Step 3: Recover the file
+git cat-file -p <tree-hash>:path/to/file.ts > path/to/file.ts
+
+# Or recover entire directory
+git checkout <tree-hash> -- src/
+```
+
+### Important Notes
+
+- Tree hashes are permanent in git objects database
+- Even if you delete branches, tree hashes remain
+- Use `vv history list` to find the right snapshot
+- Recovery works even days/weeks later
+
+## Compare Code States
+
+### See what changed between two validation points
+
+```bash
+# Compare two tree hashes
+git diff <old-tree-hash> <new-tree-hash>
+
+# Compare specific file between validations
+git diff <old-tree-hash>:<file> <new-tree-hash>:<file>
+
+# Show what files changed
+git diff --name-status <old-tree-hash> <new-tree-hash>
+```
+
+## View Files in Snapshot
+
+```bash
+# List all files in a tree hash
+git ls-tree -r <tree-hash>
+
+# List specific directory
+git ls-tree -r <tree-hash> src/
+
+# View specific file
+git cat-file -p <tree-hash>:src/feature.ts
+```
+
+## Common Recovery Patterns
+
+### Pattern 1: Undo Recent Changes
+
+**Use case**: Made changes that broke everything, want to go back to last working state
+
+```bash
+# List recent validations
+vv history list --limit 10
+
+# Pick validation from before bad changes
+# Recover all affected files
+git checkout <good-tree-hash> -- src/
+```
+
+### Pattern 2: Cherry-pick Deleted File
+
+**Use case**: Accidentally deleted a file, need just that one file back
+
+```bash
+# Find validation when file existed
+vv history list
+
+# Look for validation timestamp before deletion
+# Recover just that file
+git cat-file -p <tree-hash>:path/to/deleted.ts > path/to/deleted.ts
+```
+
+### Pattern 3: Compare Before/After Refactoring
+
+**Use case**: Did major refactoring, want to see all changes or partially revert
+
+```bash
+# Before refactoring validation: abc123
+# After refactoring validation: def456
+
+# See all changes
+git diff abc123 def456
+
+# See just filenames that changed
+git diff --name-status abc123 def456
+
+# If refactoring went wrong, revert specific files
+git checkout abc123 -- src/refactored-file.ts
+```
+
+### Pattern 4: Recover After Branch Switch
+
+**Use case**: Switched branches and lost uncommitted work
+
+```bash
+# Find validation from before branch switch
+vv history list --limit 20
+
+# Look for validation on old branch
+# Recover entire working directory state
+git checkout <tree-hash> -- .
+
+# Or just specific directory
+git checkout <tree-hash> -- src/
+```
+
+## Troubleshooting Recovery
+
+### "I can't find my validation"
+
+**Check:**
+1. Did you run `vv validate`, `vv pre-commit`, or `vv run` before losing the work?
+2. Look further back: `vv history list --limit 50`
+3. Check if in different git repository
+
+**If validation wasn't run**: Work might not be recoverable via vibe-validate. Try:
+- `git reflog` - Shows git history including deleted commits
+- File recovery tools (OS-level)
+- IDE local history (VS Code, IntelliJ, etc.)
+
+### "Tree hash doesn't exist"
+
+**Error**: `fatal: Not a valid object name`
+
+**Solutions:**
+1. Verify tree hash is correct (copy-paste from `vv history list`)
+2. Check if in correct git repository
+3. Try `git fsck --full` to verify git objects database
+
+### "How long are snapshots kept?"
+
+**Answer**: Indefinitely in git objects database until you run `git gc` (garbage collection).
+
+**To manually prune old snapshots**:
+```bash
+# Clear all validation history (CAREFUL!)
+vv history prune --all
+
+# Clear only run cache
+vv history prune --run --all
+```
+
+## Best Practices
+
+1. **Run validation frequently** - More snapshots = more recovery points
+2. **Check history before panic** - `vv history list` shows what's recoverable
+3. **Recover incrementally** - Cherry-pick files rather than recovering everything
+4. **Test recovery on scratch branch** - Don't overwrite current work
+5. **Keep validation habit** - Treat validation as "save point" in your workflow
+
+## Advanced: Direct Git Object Access
+
+### Understanding tree hashes
+
+Tree hashes are git's way of storing directory snapshots. They're content-addressable - same content always produces same hash.
+
+```bash
+# View tree structure
+git cat-file -p <tree-hash>
+
+# Output shows:
+# 100644 blob abc123  README.md
+# 040000 tree def456  src
+# (permissions) (type) (hash) (name)
+```
+
+### Recovering from bare tree hash
+
+```bash
+# Create temporary index from tree
+GIT_INDEX_FILE=.git/index.tmp git read-tree <tree-hash>
+
+# Checkout files from temporary index
+GIT_INDEX_FILE=.git/index.tmp git checkout-index -a -f
+
+# Clean up
+rm .git/index.tmp
+```
+
+## See Also
+
+- [CLI Reference](cli-reference.md) - `history` command options
+- [Troubleshooting Guide](troubleshooting.md) - General recovery issues