@boshu2/vibe-check 1.0.2 → 1.2.0

package/.vibe-check/latest.json

@@ -0,0 +1,114 @@
+{
+  "period": {
+    "from": "2025-11-28T17:09:58.000Z",
+    "to": "2025-11-29T17:06:04.000Z",
+    "activeHours": 5.8
+  },
+  "commits": {
+    "total": 19,
+    "feat": 6,
+    "fix": 2,
+    "docs": 4,
+    "other": 7
+  },
+  "metrics": {
+    "iterationVelocity": {
+      "value": 3.3,
+      "unit": "commits/hour",
+      "rating": "high"
+    },
+    "reworkRatio": {
+      "value": 11,
+      "unit": "%",
+      "rating": "elite"
+    },
+    "trustPassRate": {
+      "value": 100,
+      "unit": "%",
+      "rating": "elite"
+    },
+    "debugSpiralDuration": {
+      "value": 0,
+      "unit": "min",
+      "rating": "elite"
+    },
+    "flowEfficiency": {
+      "value": 100,
+      "unit": "%",
+      "rating": "elite"
+    }
+  },
+  "fixChains": [],
+  "patterns": {
+    "categories": {},
+    "total": 0,
+    "tracerAvailable": 0
+  },
+  "overall": "ELITE",
+  "vibeScore": {
+    "value": 0.88,
+    "components": {
+      "fileChurn": 0.97,
+      "timeSpiral": 0.74,
+      "velocityAnomaly": 0.79,
+      "codeStability": 0.99
+    },
+    "weights": {
+      "fileChurn": 0.3,
+      "timeSpiral": 0.25,
+      "velocityAnomaly": 0.2,
+      "codeStability": 0.25
+    }
+  },
+  "recommendation": {
+    "level": 5,
+    "confidence": 0.3,
+    "probabilities": [
+      0.018853929395775577,
+      0.04111986761778373,
+      0.1148237967015614,
+      0.23809991674270975,
+      0.2872499181517066,
+      0.29985257139046295
+    ],
+    "ci": [
+      1.2053475326593759,
+      5
+    ]
+  },
+  "semanticFreeMetrics": {
+    "fileChurn": {
+      "value": 97,
+      "unit": "%",
+      "rating": "elite",
+      "description": "Elite: 2/63 files churned (<10%)",
+      "churnedFiles": 2,
+      "totalFiles": 63
+    },
+    "timeSpiral": {
+      "value": 74,
+      "unit": "%",
+      "rating": "high",
+      "description": "High: 5/19 rapid commits (15-30%)",
+      "spiralCommits": 5,
+      "totalCommits": 19
+    },
+    "velocityAnomaly": {
+      "value": 79,
+      "unit": "%",
+      "rating": "elite",
+      "description": "Elite: 3.3/hr (near baseline 3.0/hr)",
+      "currentVelocity": 3.3,
+      "baselineMean": 3,
+      "zScore": 0.17
+    },
+    "codeStability": {
+      "value": 99,
+      "unit": "%",
+      "rating": "elite",
+      "description": "Elite: 99% stability (+13230/-261)",
+      "linesAdded": 13230,
+      "linesSurviving": 13100
+    }
+  }
+}

package/CHANGELOG.md

@@ -5,6 +5,53 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2025-11-29
+
+### Added
+- **Git Hook** - `vibe-check init-hook` command to install pre-push hook
+  - Runs vibe-check automatically before every git push
+  - `--block-low` option to reject pushes with LOW rating
+  - Configurable via environment variables
+- Pre-push hook script in `hooks/pre-push` for manual installation
+
+## [1.1.0] - 2025-11-29
+
+### Added
+- **Gamification System** - XP, levels, streaks, and achievements to make vibe-checking more engaging
+  - 18 achievements across streak, score, sessions, and special categories
+  - XP rewards for sessions, streaks, scores, and achievements
+  - Level progression from "Newbie" (1) to "Legend" (10)
+  - Daily streaks with weekly goals
+  - 2 hidden achievements to discover
+- **Profile Command** - `vibe-check profile` to view your stats, achievements, and progress
+  - `--achievements` flag to see all achievements
+  - `--stats` flag for detailed statistics
+  - `--json` flag for machine-readable output
+- **GitHub Action** - Automated vibe-check on PRs with comment posting
+  - Configurable thresholds for pass/fail
+  - JSON artifact output option
+  - Full PR comment with metrics and recommendations
+- **JSON File Output** - `--output <file>` flag to save results to a JSON file
+- **Dashboard Shell** - Static HTML dashboard for viewing profile (in `dashboard/` directory)
+- **Simple Mode** - `--simple` flag for compact output showing only essential metrics
+- **UX Improvements**
+  - Summary section with top strength and focus area
+  - Opportunities section with actionable tips for low/medium metrics
+  - Date period context in output header
+  - Confidence display for level recommendations
+- **Anti-Gaming** - XP deduplication prevents multiple rewards for same time period
+- **Comprehensive Tests** - 108 tests covering gamification, metrics, and scoring
+
+### Changed
+- Requires Node.js 20+ (for Vitest 4.x compatibility)
+- Updated all dependencies to November 2025 stable versions
+- Improved CLI output clarity with better terminology
+- Renamed internal "FAAFO metrics" to "vibe metrics" (user-facing term unchanged)
+
+### Fixed
+- Grammar issues in CLI output
+- Level recommendation confidence display
+
 ## [1.0.2] - 2025-11-28
 
 ### Changed

package/CLAUDE.md

@@ -0,0 +1,178 @@
+# vibe-check Development Guide
+
+## npm Publishing Standards
+
+### When to Publish
+
+| Change Type | Version Bump | Publish? |
+|-------------|--------------|----------|
+| **Breaking changes** | MAJOR (1.0.0 → 2.0.0) | Yes |
+| **New features** (backward compatible) | MINOR (1.0.0 → 1.1.0) | Yes |
+| **Bug fixes** | PATCH (1.0.0 → 1.0.1) | Yes |
+| **Docs only (README, CHANGELOG)** | None | **No** |
+| **Tests only** | None | **No** |
+| **CI/tooling only** | None | **No** |
+
+### GitHub README vs npm README
+
+- **GitHub README**: Always shows latest from repo
+- **npm README**: Snapshot from last publish - only updates when you `npm publish`
+
+**Docs-only changes don't need a publish.** Just commit and push to GitHub.
+
+### Version Commands
+
+```bash
+# Check current version
+npm version
+
+# Bump and publish (creates git tag automatically)
+npm version patch   # 1.0.1 → 1.0.2 (bug fixes)
+npm version minor   # 1.0.1 → 1.1.0 (new features)
+npm version major   # 1.0.1 → 2.0.0 (breaking changes)
+
+# Then publish
+npm publish --access=public
+```
+
+### How Users Consume Versions
+
+```bash
+npm install @boshu2/vibe-check        # Gets "latest"
+npm install @boshu2/vibe-check@1.0.2  # Exact version
+npm install @boshu2/vibe-check@^1.0.0 # Any 1.x.x (common default)
+npm install @boshu2/vibe-check@~1.0.0 # Any 1.0.x only
+```
+
+Most users have `^` (caret) in their package.json, meaning they'll auto-update to latest minor/patch.
+
+## Development Workflow
+
+### Running Locally
+
+```bash
+npm run dev           # Run with ts-node
+npm run build         # Compile TypeScript
+npm test              # Run Vitest tests
+npm run test:coverage # Tests with coverage
+```
+
+### Testing the CLI
+
+```bash
+# Run against a repo
+node dist/cli.js --repo /path/to/repo --since "1 week ago"
+
+# Test different output formats
+node dist/cli.js --format json
+node dist/cli.js --format markdown
+```
+
+### Before Publishing
+
+1. Ensure tests pass: `npm test`
+2. Update CHANGELOG.md with changes
+3. Bump version appropriately (see table above)
+4. Commit version bump
+5. `npm publish --access=public`
+
+## Architecture
+
+```
+src/
+├── cli.ts              # CLI entry point (Commander.js)
+├── git.ts              # Git operations (simple-git)
+├── types.ts            # TypeScript interfaces
+├── commands/
+│   ├── index.ts        # Command exports
+│   ├── analyze.ts      # Main analyze command
+│   ├── level.ts        # Level recommendation command
+│   └── profile.ts      # Profile/stats command
+├── metrics/
+│   ├── index.ts        # Orchestrates all metrics
+│   ├── velocity.ts     # Iteration velocity
+│   ├── rework.ts       # Rework ratio
+│   ├── trust.ts        # Trust pass rate
+│   ├── spirals.ts      # Debug spiral detection
+│   ├── flow.ts         # Flow efficiency
+│   ├── file-churn.ts   # File churn patterns
+│   ├── time-spiral.ts  # Time-based spirals
+│   ├── velocity-anomaly.ts # Velocity anomaly detection
+│   └── code-stability.ts   # Code stability metrics
+├── gamification/
+│   ├── index.ts        # Gamification exports
+│   ├── types.ts        # XP, levels, achievements types
+│   ├── xp.ts           # XP calculation and levels
+│   ├── streaks.ts      # Daily/weekly streak tracking
+│   ├── achievements.ts # Achievement definitions and checks
+│   └── profile.ts      # Profile persistence (.vibe-check/)
+├── calibration/
+│   ├── index.ts        # Calibration orchestration
+│   ├── ece.ts          # Expected calibration error
+│   └── storage.ts      # Calibration data persistence
+├── recommend/
+│   ├── index.ts        # Recommendation orchestration
+│   ├── ordered-logistic.ts # Ordinal logistic regression
+│   └── questions.ts    # Assessment questions
+├── score/
+│   ├── index.ts        # VibeScore calculation
+│   └── weights.ts      # Metric weights
+└── output/
+    ├── index.ts        # Output format router
+    ├── terminal.ts     # Colored terminal output
+    ├── json.ts         # JSON output
+    └── markdown.ts     # Markdown output
+
+dashboard/              # Static HTML dashboard
+├── index.html          # Dashboard UI
+├── app.js              # Dashboard JavaScript
+└── styles.css          # Dashboard styles
+
+.vibe-check/            # Local profile data (per-repo)
+├── profile.json        # XP, streaks, achievements
+└── calibration.json    # Calibration samples
+```
+
+## Commands
+
+### Main Command (analyze)
+```bash
+vibe-check [options]           # Analyze git history
+vibe-check --since "1 week"    # Time-bounded analysis
+vibe-check --score --recommend # Full analysis with recommendations
+```
+
+### Profile Command
+```bash
+vibe-check profile             # View your profile
+vibe-check profile --achievements  # List all achievements
+vibe-check profile --stats     # Detailed statistics
+vibe-check profile --json      # Machine-readable output
+```
+
+### Level Command
+```bash
+vibe-check level               # Get level recommendation
+vibe-check level --calibrate 3 # Record calibration sample
+```
+
+## The 5 Metrics
+
+| Metric | Measures | Threshold |
+|--------|----------|-----------|
+| Iteration Velocity | Commits/hour | >5 = Elite |
+| Rework Ratio | % fix commits | <30% = Elite |
+| Trust Pass Rate | % commits without immediate fix | >95% = Elite |
+| Debug Spiral Duration | Avg time in fix chains | <15m = Elite |
+| Flow Efficiency | % time building vs debugging | >90% = Elite |
+
+## Debug Spiral Detection
+
+A "debug spiral" is detected when 3+ consecutive fix commits target the same component. Patterns are categorized:
+
+- `SECRETS_AUTH` - OAuth/credentials issues
+- `API_MISMATCH` - API version/schema problems
+- `VOLUME_CONFIG` - Mount/permission issues
+- `SSL_TLS` - Certificate problems
+- `IMAGE_REGISTRY` - Container pull issues
+- `GITOPS_DRIFT` - Sync/reconciliation issues

package/README.md

@@ -1,6 +1,8 @@
 # vibe-check
 
-**Stop guessing if AI coding is working. Start measuring.**
+> ⚠️ **Experimental** - Metrics correlations with actual productivity outcomes have not been independently validated. Use as a directional signal, not ground truth.
+
+**Track patterns in your AI-assisted coding workflow.**
 
 ## The Problem
 
@@ -90,12 +92,14 @@ vibe-check --repo /path/to/repo
 | **Debug Spiral Duration** | Avg time stuck in fix chains | <15m | 15-30m | >30m |
 | **Flow Efficiency** | % time building vs debugging | >90% | 75-90% | <75% |
 
-### What the ratings mean
+### What the ratings suggest
+
+- **ELITE**: Commit patterns suggest smooth workflow
+- **HIGH**: Generally healthy patterns, some areas to watch
+- **MEDIUM**: Mixed signals—review individual metrics
+- **LOW**: Commit patterns suggest friction—investigate causes
 
-- **ELITE**: Your AI collaboration is working excellently
-- **HIGH**: Good effectiveness, minor improvements possible
-- **MEDIUM**: Room for improvement—check which metrics are lagging
-- **LOW**: Process issues—you're debugging more than building
+*Note: These ratings reflect commit patterns, not actual code quality or productivity.*
 
 ## Debug Spiral Detection
 
@@ -124,16 +128,227 @@ When vibe-check detects 3+ consecutive fix commits on the same component, it fla
 --until <date>       End date (default: now)
 -f, --format <type>  Output: terminal, json, markdown
 -r, --repo <path>    Repository path (default: current directory)
+-o, --output <file>  Write JSON results to file
 -v, --verbose        Show detailed output
+--score              Include VibeScore (semantic-free metrics)
+--recommend          Include level recommendation
+--simple             Show simplified output (less verbose)
 -h, --help           Display help
 ```
 
+## Gamification
+
+vibe-check tracks your progress over time with XP, levels, streaks, and achievements.
+
+### Levels
+
+| Level | Name | XP Required |
+|-------|------|-------------|
+| 1 | Newbie | 0 |
+| 2 | Regular | 100 |
+| 3 | Committed | 300 |
+| 4 | Dedicated | 600 |
+| 5 | Expert | 1000 |
+| 6 | Master | 1500 |
+| 7 | Grandmaster | 2100 |
+| 8 | Guru | 2800 |
+| 9 | Sage | 3600 |
+| 10 | Legend | 4500 |
+
+### Achievements
+
+Unlock achievements by hitting milestones:
+
+- 🩸 **First Blood** - Run your first vibe-check
+- ⚔️ **Week Warrior** - Maintain a 7-day streak
+- 👑 **Monthly Master** - Maintain a 30-day streak
+- ✨ **Elite Vibes** - Achieve ELITE rating
+- 🏅 **Ninety Club** - Vibe Score of 90%+
+- 🧘 **Zen Master** - 50+ commits, 0 debug spirals
+- ...and 12 more, including 2 hidden achievements!
+
+### Profile Command
+
+View your stats, achievements, and progress:
+
+```bash
+# View your profile
+vibe-check profile
+
+# See all achievements
+vibe-check profile --achievements
+
+# Detailed statistics
+vibe-check profile --stats
+
+# JSON output
+vibe-check profile --json
+```
+
+### Save Results to JSON
+
+```bash
+# Write JSON to file while showing terminal output
+vibe-check --since "1 week ago" --score -o results.json
+
+# Combine with other formats
+vibe-check --format markdown -o results.json  # Terminal gets markdown, file gets JSON
+```
+
+## Git Hook
+
+Run vibe-check automatically before every push:
+
+```bash
+# Install the pre-push hook
+vibe-check init-hook
+
+# Or with blocking enabled (rejects push on LOW rating)
+vibe-check init-hook --block-low
+```
+
+### Hook Configuration
+
+Control behavior with environment variables:
+
+```bash
+# Block push on LOW rating (default: false)
+VIBE_CHECK_BLOCK_LOW=true git push
+
+# Show full output instead of simple (default: true)
+VIBE_CHECK_SIMPLE=false git push
+
+# Hide vibe score (default: true)
+VIBE_CHECK_SCORE=false git push
+```
+
+### Manual Installation
+
+If you prefer to install manually:
+
+```bash
+# Copy the hook to your repo
+curl -o .git/hooks/pre-push https://raw.githubusercontent.com/boshu2/vibe-check/main/hooks/pre-push
+chmod +x .git/hooks/pre-push
+```
+
+## GitHub Action
+
+Add automated vibe-check to your PRs:
+
+```yaml
+# .github/workflows/vibe-check.yml
+name: Vibe Check
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  vibe-check:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Run Vibe Check
+        uses: boshu2/vibe-check@v1
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+### Action Inputs
+
+| Input | Description | Default |
+|-------|-------------|---------|
+| `github-token` | GitHub token for PR comments | `${{ github.token }}` |
+| `since` | Start date for analysis | PR base commit |
+| `threshold` | Minimum rating to pass (elite, solid, needs-work) | none |
+| `include-score` | Include VibeScore | `true` |
+| `include-recommendation` | Include level recommendation | `true` |
+| `output-file` | Path to write JSON results | none |
+| `comment-on-pr` | Post results as PR comment | `true` |
+
+### Action Outputs
+
+| Output | Description |
+|--------|-------------|
+| `overall` | Overall rating (elite, solid, needs-work, struggling) |
+| `vibe-score` | Numeric score (0-100) |
+| `json` | Full JSON results |
+
+### Example: Fail PR if Below Threshold
+
+```yaml
+- uses: boshu2/vibe-check@v1
+  with:
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+    threshold: 'solid'  # Fails if below solid
+```
+
+### Example: Save Results to File
+
+```yaml
+- uses: boshu2/vibe-check@v1
+  with:
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+    output-file: 'vibe-check-results.json'
+
+- name: Upload results
+  uses: actions/upload-artifact@v4
+  with:
+    name: vibe-check-results
+    path: vibe-check-results.json
+```
+
 ## Requirements
 
-- Node.js >= 18.0.0
+- Node.js >= 20.0.0
 - Git repository with commit history
 - Conventional commits recommended (but not required)
 
+## Limitations & Caveats
+
+### What This Tool Does NOT Measure
+
+| Claim | Reality |
+|-------|---------|
+| Code quality | Measures commit patterns, not code correctness |
+| Actual productivity | Measures velocity signals, not shipped value |
+| AI effectiveness | Measures workflow patterns, not AI contribution |
+
+### Known Limitations
+
+1. **No ground truth validation**: The correlation between these metrics and actual productivity outcomes has not been independently validated.
+
+2. **Threshold sensitivity**: Magic numbers (5 min spiral threshold, 3-file churn) are based on practitioner intuition, not empirical studies.
+
+3. **Goodhart's Law risk**: Once you know the metrics, you may unconsciously optimize for them rather than actual outcomes.
+
+4. **Cold start**: New repositories have no calibration data. Default model weights are educated guesses.
+
+5. **Sample size**: The ML model requires 20+ calibration samples for meaningful learning. Results with fewer samples are unreliable.
+
+### When NOT to Use
+
+- As a performance review metric (easily gamed)
+- To compare across teams or developers (different baselines)
+- As the sole indicator of AI tool effectiveness
+- Without understanding what each metric actually measures
+
+### Recommended Use
+
+Use vibe-check as **one signal among many**:
+- Combine with code review feedback
+- Track alongside deployment success rates
+- Use for self-reflection, not external judgment
+- Treat as directional, not precise
+
 ## License
 
 MIT