@boshu2/vibe-check 1.5.0 → 1.6.0

package/docs/VIBE-ECOSYSTEM.md

@@ -0,0 +1,406 @@
+# The Vibe-Coding Ecosystem
+
+**A complete guide to conscious AI-assisted development**
+
+---
+
+## What is Vibe-Coding?
+
+Vibe-coding is a methodology for AI-assisted software development that emphasizes:
+
+1. **Conscious calibration** - Knowing when to trust AI output and when to verify
+2. **Metric-driven feedback** - Measuring patterns, not productivity
+3. **Self-awareness** - Recognizing spirals before they consume hours
+4. **Progressive mastery** - Building trust through demonstrated accuracy
+
+The core insight: **AI assistance varies in reliability by task type.** Formatting code? Nearly 100% trustworthy. Designing authentication architecture? Maybe 20%. Vibe-coding gives you a framework to calibrate your verification effort appropriately.
+
+---
+
+## The Five Core Metrics
+
+| Metric | Question | Elite | Needs Work |
+|--------|----------|-------|------------|
+| **Trust Pass Rate** | What % of commits don't need immediate fixes? | >95% | <80% |
+| **Rework Ratio** | What % of commits are fixes vs. new work? | <30% | >50% |
+| **Debug Spiral Count** | How many fix-chain spirals detected? | 0 | 3+ |
+| **Debug Spiral Duration** | How long stuck in fix loops? | <15min | >45min |
+| **Flow Efficiency** | What % of time is productive building? | >90% | <70% |
+
+These metrics are **semantic-free** - they measure git patterns, not code content. This prevents gaming and ensures honest signal.
+
+---
+
+## Vibe Levels
+
+Before starting work, classify the task:
+
+| Level | Name | Trust AI | Verification | Example Tasks |
+|-------|------|----------|--------------|---------------|
+| **5** | Full Automation | 95% | Final only | Formatting, linting, boilerplate |
+| **4** | High Trust | 80% | Spot check | CRUD, simple features |
+| **3** | Balanced | 60% | Key outputs | Standard features, tests |
+| **2** | Careful | 40% | Every change | API integrations, complex logic |
+| **1** | Skeptical | 20% | Every line | Architecture, security, auth |
+| **0** | Manual | 0% | N/A | Novel research, exploration |
+
+**The insight:** Declaring a level upfront forces conscious calibration. After the session, compare actual metrics to expected - this builds intuition over time.
+
+---
+
+## vibe-check: The Tool
+
+`vibe-check` is a CLI tool that analyzes git history and provides immediate feedback on your coding patterns.
+
+### Installation
+
+```bash
+npm install -g @boshu2/vibe-check
+```
+
+Or run directly:
+
+```bash
+npx @boshu2/vibe-check
+```
+
+### Core Commands
+
+```bash
+# Basic analysis
+vibe-check --since "1 week ago"
+
+# Real-time monitoring
+vibe-check watch
+
+# Your profile (gamification)
+vibe-check profile
+
+# Start a tracked session
+vibe-check start --level 3
+```
+
+---
+
+## Feature Overview (v1.5.0)
+
+### 1. Metrics Engine
+
+The core analysis engine examines git history to compute:
+
+- **Trust Pass Rate**: Commits without immediate fix follow-ups
+- **Rework Ratio**: Proportion of fix/revert commits
+- **Debug Spirals**: Consecutive fix commits on same component
+- **VibeScore**: Weighted composite (0-100%)
+
+Output example:
+```
+VIBE-CHECK Nov 21 - Nov 28
+
+  Rating: ELITE
+  Trust: 94% ELITE
+  Rework: 18% ELITE
+  Spirals: 1 detected (12 min)
+
+  VibeScore: 87%
+```
+
+### 2. Watch Mode
+
+Real-time spiral detection while you work:
+
+```bash
+vibe-check watch
+```
+
+Monitors commits and alerts when patterns indicate a spiral forming:
+
+```
+  09:15 fix(auth) handle token refresh
+  09:18 fix(auth) add retry logic
+  09:22 fix(auth) increase timeout
+
+  SPIRAL DETECTED
+      Component: auth
+      Fixes: 3 commits, 7 min
+```
+
+### 3. Automatic Baseline Comparison
+
+After 5+ sessions, vibe-check learns your patterns and provides contextual feedback:
+
+```
+VS YOUR BASELINE
+
+  Trust:  92% (+7% vs avg 85%)
+  Rework: 18% (-4% vs avg 22%)
+
+  Better than your usual - nice flow!
+```
+
+### 4. Pattern Memory
+
+Tracks what triggers YOUR spirals over time:
+
+```bash
+vibe-check profile --patterns
+```
+
+```
+YOUR SPIRAL TRIGGERS
+
+  Component    Times   Pattern
+  auth         5       OAuth/token/refresh issues
+  database     3       Connection pooling
+  api          2       External API timeouts
+```
+
+### 5. Intervention Tracking
+
+Records what breaks your spirals:
+
+```
+WHAT WORKS FOR YOU
+
+  Take a break      4 times (avg 12 min)
+  Write test first  3 times
+  Read docs         2 times
+```
+
+---
+
+## Gamification System
+
+vibe-check includes a complete gamification layer to make improvement engaging:
+
+### XP & Levels
+
+```
+Level 1: Novice       (0-100 XP)      🌱
+Level 2: Apprentice   (100-300 XP)    🌿
+Level 3: Practitioner (300-600 XP)    🌳
+Level 4: Expert       (600-1000 XP)   🌲
+Level 5: Master       (1000-2000 XP)  🎋
+Level 6: Grandmaster  (2000-5000 XP)  🏔️
+```
+
+**Prestige tiers** (beyond Grandmaster):
+- Archmage (5000+ XP) 🔮
+- Sage (10000+ XP) 📿
+- Zenmester (20000+ XP) ☯️
+- Transcendent (40000+ XP) 🌟
+- Legendary (80000+ XP) 💫
+
+### Streaks
+
+Daily check-ins build streaks with visual progression:
+
+```
+🔥 5-day streak (1-5 days)
+🌟🌟 12-day streak (6-14 days)
+👑👑👑 18-day streak 🏆 (15+ days, Personal Best!)
+```
+
+Streak freezes protect against occasional missed days.
+
+### Weekly Challenges
+
+Auto-generated based on your weak metrics:
+
+```
+WEEKLY CHALLENGES
+
+🎯 Trust Gauntlet:  ████████░░  4/5 (90%+ trust in 5 sessions)
+🧘 Zen Mode:        ██████████  ✓ COMPLETE (+100 XP)
+🔥 Streak Builder:  ██░░░░░░░░  1/5 (extend streak by 5 days)
+```
+
+### Achievements (19 total)
+
+Categories:
+- **Consistency**: First Blood, Week Warrior, Streak Master
+- **Quality**: Elite Vibes, Trust Builder, Zen Master
+- **Volume**: Centurion, Marathon Coder
+- **Improvement**: Comeback Kid, On Fire
+- **Special**: Night Owl, Early Bird, Weekend Warrior
+
+### Rank Badges
+
+```
+🥉 Bronze    (10+ sessions)
+🥈 Silver    (50+ sessions)
+🥇 Gold      (100+ sessions)
+💎 Platinum  (14+ day streak)
+🔷 Diamond   (5000+ XP)
+```
+
+### Local Leaderboards & Hall of Fame
+
+Track your personal bests across all repos:
+
+```
+🏛️  HALL OF FAME
+
+🏆 Best Score: 96% (Nov 15, my-project)
+🔥 Longest Streak: 15 days
+⚡ Best Week: 847 XP
+📊 Most Commits: 127 (Nov 10, big-refactor)
+```
+
+---
+
+## Integration Points
+
+### Git Hook
+
+Automatic vibe-check on every push:
+
+```bash
+vibe-check init-hook           # Install hook
+vibe-check init-hook --block-low  # Block LOW pushes
+```
+
+### GitHub Action
+
+Automated PR feedback:
+
+```yaml
+name: Vibe Check
+on: [pull_request]
+
+jobs:
+  vibe-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: boshu2/vibe-check@v1
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+### JSON Output
+
+Machine-readable for dashboards/CI:
+
+```bash
+vibe-check --format json --output vibe-results.json
+```
+
+---
+
+## The Workflow
+
+### Daily Practice
+
+```
+Morning:
+1. vibe-check profile         # Check streak, challenges
+2. Plan tasks, estimate levels
+
+During work:
+3. vibe-check watch           # Real-time monitoring
+4. Notice spiral alerts, intervene early
+
+End of session:
+5. vibe-check --since "today" # Review session
+6. XP/achievements auto-update
+```
+
+### Session Workflow (Optional)
+
+For explicit tracking:
+
+```bash
+# Before: declare expectation
+vibe-check start --level 3
+
+# ... work ...
+
+# After: compare reality
+vibe-check --since "1 hour ago"
+```
+
+The tool will show whether your level classification was accurate.
+
+---
+
+## Philosophy
+
+### What vibe-check IS
+
+- A self-reflection tool
+- A pattern detector
+- A gamified improvement system
+- A calibration feedback loop
+
+### What vibe-check IS NOT
+
+- A productivity metric
+- A performance review tool
+- A surveillance system
+- A judgment of AI effectiveness
+
+**Use it for yourself, not for measuring others.**
+
+---
+
+## The Science
+
+vibe-check uses **semantic-free signals** - patterns in git history that indicate workflow health without reading code content. This approach:
+
+1. **Can't be gamed** - You can't fake commit timestamps
+2. **Respects privacy** - Never reads actual code
+3. **Is universal** - Works for any language/framework
+4. **Provides honest signal** - Measures behavior, not intention
+
+The VibeScore combines metrics using validated weights derived from empirical analysis of productive vs. struggling sessions.
+
+---
+
+## Future Roadmap
+
+| Phase | Status | Description |
+|-------|--------|-------------|
+| CLI Core | ✅ Complete | Metrics, scoring, analysis |
+| Gamification | ✅ Complete | XP, streaks, achievements, challenges |
+| Watch Mode | ✅ Complete | Real-time spiral detection |
+| GitHub Action | ✅ Complete | Automated PR feedback |
+| Pattern Memory | ✅ Complete | Track your spiral triggers |
+| Web Dashboard | 🔮 Planned | Visualizations, trends |
+| VS Code Extension | 🔮 Planned | Status bar, live alerts |
+| Team Features | 🔮 Planned | Opt-in leaderboards |
+
+---
+
+## Getting Started
+
+```bash
+# Install
+npm install -g @boshu2/vibe-check
+
+# Run your first check
+vibe-check --since "1 week ago"
+
+# See your profile
+vibe-check profile
+
+# Start watching
+vibe-check watch
+```
+
+---
+
+## Resources
+
+- **npm**: [@boshu2/vibe-check](https://www.npmjs.com/package/@boshu2/vibe-check)
+- **GitHub**: [boshu2/vibe-check](https://github.com/boshu2/vibe-check)
+- **Issues**: [Report bugs or request features](https://github.com/boshu2/vibe-check/issues)
+
+---
+
+*"The goal isn't perfect metrics. It's conscious awareness of your patterns."*
+
+**Version:** 1.5.0
+**Last Updated:** 2025-11-29

package/feature-list.json

@@ -141,6 +141,54 @@
       "description": "Near-miss psychology messaging (SO CLOSE motivational messages)",
       "passes": true,
       "completed_date": "2025-11-29"
+    },
+    {
+      "id": "VIBE-024",
+      "description": "Timeline command Phase 1 MVP (session detection, day grouping, terminal output)",
+      "passes": true,
+      "completed_date": "2025-11-30"
+    },
+    {
+      "id": "VIBE-025",
+      "description": "Timeline Phase 2: Flow state detection",
+      "passes": true,
+      "completed_date": "2025-11-30"
+    },
+    {
+      "id": "VIBE-026",
+      "description": "Timeline Phase 2: Post-delete sprint detection",
+      "passes": true,
+      "completed_date": "2025-11-30"
+    },
+    {
+      "id": "VIBE-027",
+      "description": "Timeline Phase 2: Thrashing detection",
+      "passes": true,
+      "completed_date": "2025-11-30"
+    },
+    {
+      "id": "VIBE-028",
+      "description": "Timeline recommendation engine with actionable insights",
+      "passes": true,
+      "completed_date": "2025-11-30"
+    },
+    {
+      "id": "VIBE-029",
+      "description": "Timeline Phase 3: Detour detection and late-night spirals",
+      "passes": true,
+      "completed_date": "2025-11-30"
+    },
+    {
+      "id": "VIBE-030",
+      "description": "Timeline Phase 4: Export formats (Markdown, HTML for sharing)",
+      "passes": true,
+      "completed_date": "2025-11-30"
+    },
+    {
+      "id": "VIBE-031",
+      "description": "Timeline persistence: Cache to .vibe-check/timeline.json with compounding insights",
+      "passes": true,
+      "completed_date": "2025-11-30"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boshu2/vibe-check",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Track git commit patterns during AI-assisted coding (experimental)",
   "main": "dist/cli.js",
   "bin": {
@@ -36,6 +36,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^4.0.14",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.0",
     "vitest": "^4.0.0"

package/vitest.config.ts

@@ -5,10 +5,6 @@ export default defineConfig({
     globals: true,
     environment: 'node',
     include: ['tests/**/*.test.ts'],
-    coverage: {
-      provider: 'v8',
-      include: ['src/**/*.ts'],
-      exclude: ['src/cli.ts'],
-    },
+    testTimeout: 30000, // Integration tests need more time
   },
 });

package/.vibe-check/calibration.json

@@ -1,38 +0,0 @@
-{
-  "samples": [
-    {
-      "timestamp": "2025-11-28T22:18:40.597Z",
-      "vibeScore": 0.83,
-      "declaredLevel": 4,
-      "outcome": "correct",
-      "features": [
-        0.95,
-        0.78,
-        0.53,
-        0.99
-      ],
-      "modelVersion": "2.0.0"
-    }
-  ],
-  "weights": [
-    0.3,
-    -0.5,
-    -0.4,
-    -0.4,
-    0.3,
-    0.8,
-    0.6,
-    0.3,
-    0.5
-  ],
-  "thresholds": [
-    -2,
-    -0.8,
-    0.4,
-    1.6,
-    2.8
-  ],
-  "ece": 0,
-  "lastUpdated": "2025-11-28T22:18:40.597Z",
-  "version": "2.0.0"
-}

package/.vibe-check/latest.json

@@ -1,114 +0,0 @@
-{
-  "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/.vibe-check/sessions.json

@@ -1,44 +0,0 @@
-{
-  "sessions": [
-    {
-      "id": "2025-11-29T15:25",
-      "startedAt": "2025-11-29T15:25:11.000Z",
-      "endedAt": "2025-11-29T20:46:56.000Z",
-      "commits": 29,
-      "trustPassRate": 100,
-      "reworkRatio": 14,
-      "spirals": 0
-    },
-    {
-      "id": "2025-11-28T17:09",
-      "startedAt": "2025-11-28T17:09:58.000Z",
-      "endedAt": "2025-11-28T18:56:36.000Z",
-      "commits": 7,
-      "trustPassRate": 100,
-      "reworkRatio": 14,
-      "spirals": 0
-    },
-    {
-      "id": "2025-11-29T21:01",
-      "startedAt": "2025-11-29T21:01:28.000Z",
-      "endedAt": "2025-11-29T21:45:06.000Z",
-      "commits": 3,
-      "trustPassRate": 100,
-      "reworkRatio": 0,
-      "spirals": 0,
-      "vibeScore": 0.93
-    },
-    {
-      "id": "2025-11-29T20:35",
-      "startedAt": "2025-11-29T20:35:11.000Z",
-      "endedAt": "2025-11-29T21:45:06.000Z",
-      "commits": 5,
-      "trustPassRate": 100,
-      "reworkRatio": 0,
-      "spirals": 0,
-      "vibeScore": 0.82
-    }
-  ],
-  "baseline": null,
-  "lastUpdated": "2025-11-29T22:12:35.462Z"
-}