@boshu2/vibe-check 1.2.0 → 1.3.1

package/.claude/settings.local.json

@@ -0,0 +1,6 @@
+{
+  "enabledMcpjsonServers": [
+    "context7"
+  ],
+  "enableAllProjectMcpServers": true
+}

package/README.md

@@ -1,58 +1,10 @@
 # vibe-check
 
-> ⚠️ **Experimental** - Metrics correlations with actual productivity outcomes have not been independently validated. Use as a directional signal, not ground truth.
+**Quick check: are you building or spiraling?**
 
-**Track patterns in your AI-assisted coding workflow.**
+Analyzes your git history to tell you if you're making progress or stuck in fix loops.
 
-## The Problem
-
-You're using AI to write code, but how do you know if it's actually helping?
-
-Are you shipping features faster, or just generating more commits? Building new features, or debugging AI mistakes? Moving forward, or stuck in fix-fix-fix loops?
-
-Without data, you're guessing.
-
-## The Insight
-
-vibe-check analyzes your git history and tells you:
-
-| What You'll Learn | Why It Matters |
-|-------------------|----------------|
-| **Trust Pass Rate** | Are you accepting AI code that works, or code that breaks immediately? |
-| **Debug Spirals** | Are you stuck in fix loops on the same component? |
-| **Rework Ratio** | What percentage of your work is building vs. cleaning up? |
-| **Pattern Detection** | What types of problems keep recurring? (auth, config, APIs...) |
-
-## Quick Demo
-
-```bash
-$ npx @boshu2/vibe-check --since "1 week ago"
-
-================================================================
-                    VIBE-CHECK RESULTS
-================================================================
-  Period: Nov 21 - Nov 28, 2025 (12.5h active)
-  Commits: 47 total (28 feat, 15 fix, 4 docs)
-
-  METRIC                      VALUE      RATING
-  --------------------------------------------------
-  Iteration Velocity          4.2/hr     HIGH
-  Rework Ratio                35%        MEDIUM
-  Trust Pass Rate             92%        HIGH
-  Debug Spiral Duration       18min      HIGH
-  Flow Efficiency             85%        HIGH
-
-  DEBUG SPIRALS (2 detected):
-  - auth: 4 commits, 25m (SECRETS_AUTH)
-  - api: 3 commits, 12m (API_MISMATCH)
-
-  OVERALL: HIGH
-================================================================
-```
-
-**What this tells you:** You're productive (4.2 commits/hour, 92% trust pass rate), but 35% of your work is fixing things—room to improve. OAuth caused a 25-minute spiral. Next time: validate auth flows with a tracer test before full implementation.
-
-## Installation
+## Install
 
 ```bash
 npm install -g @boshu2/vibe-check
@@ -64,182 +16,168 @@ Or run directly:
 npx @boshu2/vibe-check
 ```
 
-## Usage
+## Quick Start
 
 ```bash
-# Analyze current repository (all history)
-vibe-check
-
-# Analyze specific time period
+# Check your recent work
 vibe-check --since "1 week ago"
-vibe-check --since "2025-11-01"
 
-# Different output formats
-vibe-check --format json      # For CI/automation
-vibe-check --format markdown  # For reports
-
-# Analyze a different repo
-vibe-check --repo /path/to/repo
+# Watch mode - catch spirals in real-time
+vibe-check watch
 ```
 
-## The 5 Metrics
-
-| Metric | What It Measures | Elite | Good | Needs Work |
-|--------|------------------|-------|------|------------|
-| **Iteration Velocity** | Commits per hour | >5/hr | 3-5/hr | <3/hr |
-| **Rework Ratio** | % of commits that are fixes | <30% | 30-50% | >50% |
-| **Trust Pass Rate** | % of commits without immediate fix | >95% | 80-95% | <80% |
-| **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 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
-
-*Note: These ratings reflect commit patterns, not actual code quality or productivity.*
-
-## Debug Spiral Detection
+## Watch Mode (Real-Time Detection)
 
-When vibe-check detects 3+ consecutive fix commits on the same component, it flags a "debug spiral" and categorizes the pattern:
+Catch spirals as they happen, not after:
 
-| Pattern | What It Means | Prevention |
-|---------|---------------|------------|
-| `SECRETS_AUTH` | Auth/OAuth/credentials issues | Validate auth flow before implementation |
-| `API_MISMATCH` | API version or schema problems | Check API docs, deploy minimal test first |
-| `VOLUME_CONFIG` | Mount/path/permission issues | Test volume config in isolation |
-| `SSL_TLS` | Certificate/HTTPS problems | Verify certs before deploying |
-| `IMAGE_REGISTRY` | Container pull/tag issues | Test image pull separately |
+```bash
+vibe-check watch
+```
 
-## When to Run
+```
+VIBE-CHECK WATCH MODE
+Monitoring /path/to/repo
+Polling every 5s - Ctrl+C to stop
+
+────────────────────────────────────────────────────────────
+  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
+
+      Consider:
+      • Step back and write a test
+      • Check the docs or ask for help
+      • Take a 5-minute break
+────────────────────────────────────────────────────────────
+```
 
-- **Before starting work**: Establish your baseline
-- **After a session**: Measure what just happened
-- **Weekly**: Track trends over time
-- **After frustrating sessions**: Identify what went wrong
+Options:
+- `--quiet` - Only show warnings, not all commits
+- `--interval <ms>` - Poll frequency (default: 5000ms)
 
-## CLI Options
+## Example Output
 
 ```
--V, --version        Output version number
---since <date>       Start date (e.g., "1 week ago", "2025-11-01")
---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 Nov 21 - Nov 28
 
-vibe-check tracks your progress over time with XP, levels, streaks, and achievements.
+  Rating: HIGH
+  Trust: 92% HIGH
+  Rework: 35% MEDIUM
 
-### Levels
+  Run without --simple for full details
+```
 
-| 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 |
+## Session Workflow
 
-### Achievements
+Declare your trust level before starting, then check if reality matched:
 
-Unlock achievements by hitting milestones:
+```bash
+# Before work: declare your expectation
+vibe-check start --level 3
 
-- 🩸 **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!
+# ... do your work ...
 
-### Profile Command
+# After work: compare reality vs expectation
+vibe-check --since "1 hour ago"
+```
 
-View your stats, achievements, and progress:
+Output:
 
-```bash
-# View your profile
-vibe-check profile
+```
+SESSION COMPLETE
 
-# See all achievements
-vibe-check profile --achievements
+  Declared: Level 3 - Balanced (60% trust)
+  Duration: 45 min, 12 commits
 
-# Detailed statistics
-vibe-check profile --stats
+  Trust Pass:  85% (expected >65%) ✓
+  Rework:      20% (expected <30%) ✓
 
-# JSON output
-vibe-check profile --json
+  ✓ Level 3 was appropriate for this work
 ```
 
-### Save Results to JSON
+### Vibe Levels
 
-```bash
-# Write JSON to file while showing terminal output
-vibe-check --since "1 week ago" --score -o results.json
+| Level | Name | Trust | When to Use |
+|-------|------|-------|-------------|
+| 5 | Full Automation | 95% | Formatting, linting |
+| 4 | High Trust | 80% | Boilerplate, CRUD |
+| 3 | Balanced | 60% | Features, tests |
+| 2 | Careful | 40% | Integrations, APIs |
+| 1 | Skeptical | 20% | Architecture, security |
+| 0 | Manual | 0% | Novel research |
 
-# Combine with other formats
-vibe-check --format markdown -o results.json  # Terminal gets markdown, file gets JSON
-```
+## The Core Metrics
+
+| Metric | What It Measures | Elite | Needs Work |
+|--------|------------------|-------|------------|
+| **Trust Pass Rate** | % commits without immediate fix | >95% | <80% |
+| **Rework Ratio** | % commits that are fixes | <30% | >50% |
+| **Debug Spiral** | Stuck in fix loops? | 0 detected | 3+ detected |
 
 ## Git Hook
 
-Run vibe-check automatically before every push:
+Run automatically before every push:
 
 ```bash
-# Install the pre-push hook
 vibe-check init-hook
+```
 
-# Or with blocking enabled (rejects push on LOW rating)
+Block pushes on LOW rating:
+
+```bash
 vibe-check init-hook --block-low
 ```
 
-### Hook Configuration
+## Gamification
 
-Control behavior with environment variables:
+Track progress with XP, streaks, and achievements:
 
 ```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
+vibe-check profile
 ```
 
-### Manual Installation
+```
+╭─────────────────────────────────────────────╮
+│           Your Vibe Profile                 │
+├─────────────────────────────────────────────┤
+│  🌲 Level 4 Expert                          │
+│  ████████████████░░░░  320/400 XP           │
+│                                             │
+│  🔥 Current Streak: 5 days                  │
+│  🏆 Achievements: 8/19 unlocked             │
+╰─────────────────────────────────────────────╯
+```
 
-If you prefer to install manually:
+## CLI Options
 
-```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
+```
+vibe-check [options]
+
+Options:
+  --since <date>       Start date (e.g., "1 week ago")
+  --until <date>       End date (default: now)
+  -f, --format <type>  Output: terminal, json, markdown
+  -r, --repo <path>    Repository path
+  -o, --output <file>  Write JSON to file
+  -s, --simple         Simplified output
+  --score              Include VibeScore
+  -v, --verbose        Verbose output
+
+Commands:
+  watch                Real-time spiral detection
+  start --level <n>    Start session with declared level (0-5)
+  profile              View your gamification profile
+  init-hook            Install pre-push git hook
 ```
 
 ## GitHub Action
 
-Add automated vibe-check to your PRs:
-
 ```yaml
-# .github/workflows/vibe-check.yml
 name: Vibe Check
-
 on:
   pull_request:
     branches: [main]
@@ -250,104 +188,28 @@ jobs:
     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 >= 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.
+- Git repository
 
-### When NOT to Use
+## What This Is (and Isn't)
 
-- 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
+**Is:** A quick feedback tool to catch debug spirals early
 
-### Recommended Use
+**Isn't:** A productivity metric, performance review tool, or AI effectiveness measure
 
-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
+Use it for self-reflection, not external judgment.
 
 ## License
 

package/SECURITY.md

@@ -0,0 +1,178 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.x.x   | :white_check_mark: |
+
+## Security Assessment
+
+**Last Review:** 2025-11-29
+**Risk Level:** LOW
+**Reviewer:** Automated + Manual
+
+### Summary
+
+vibe-check is a local CLI tool that reads git history and writes statistics to local files. It has a minimal attack surface:
+
+- No network requests (except GitHub Action for PR comments)
+- No sensitive data handling
+- No privilege escalation paths
+- Trusted, minimal dependencies
+
+---
+
+## Threat Model
+
+### What vibe-check does
+
+1. Reads git commit history via `simple-git`
+2. Calculates metrics from commit patterns
+3. Writes profile/calibration data to `.vibe-check/` directory
+4. Optionally installs a pre-push git hook
+
+### What vibe-check does NOT do
+
+- Make network requests
+- Handle authentication tokens (except GitHub Action)
+- Execute user-provided code
+- Access files outside the repository or `~/.vibe-check/`
+- Run with elevated privileges
+
+---
+
+## Known Security Considerations
+
+### 1. Shell Command Construction in Git Hook
+
+**Severity:** Low
+**Location:** `hooks/pre-push`, `src/commands/init-hook.ts`
+
+The pre-push hook uses `eval` to construct commands:
+
+```bash
+OUTPUT=$(eval "$VIBE_CMD $SINCE_FLAG" 2>&1)
+```
+
+**Risk:** Theoretical command injection if git commit dates contain shell metacharacters.
+
+**Mitigation:**
+- `SINCE_FLAG` is derived from `git log --format=%ci` output
+- Git date format is strictly controlled by git itself
+- Attacker would need to compromise git internals
+
+**Actual Risk:** Negligible in practice.
+
+### 2. File Path Handling
+
+**Severity:** Low
+**Location:** `src/calibration/storage.ts`, `src/gamification/profile.ts`
+
+The `--repo` flag accepts a path that's used for file operations.
+
+**Risk:** Path traversal if malicious path provided.
+
+**Mitigation:**
+- User controls the `--repo` flag (self-targeted attack)
+- Writes only to `.vibe-check/` subdirectory
+- Profile stored in user's home directory, not repo
+
+**Actual Risk:** None - users would only be affecting their own system.
+
+### 3. GitHub Action Input Handling
+
+**Severity:** Low
+**Location:** `action.yml`
+
+Action inputs are passed to shell commands.
+
+**Mitigation:**
+- GitHub sanitizes workflow inputs
+- Only collaborators can trigger PR workflows
+- Inputs validated by vibe-check CLI
+
+---
+
+## Dependencies
+
+All dependencies are widely-used, trusted packages:
+
+| Package | Purpose | Risk |
+|---------|---------|------|
+| simple-git | Git operations | Low - no shell execution |
+| commander | CLI framework | Low - argument parsing only |
+| chalk | Terminal colors | Low - output formatting only |
+| date-fns | Date formatting | Low - pure functions |
+| enquirer | CLI prompts | Low - user input handling |
+
+Run `npm audit` to check for known vulnerabilities.
+
+---
+
+## Security Best Practices for Users
+
+### Git Hook
+
+The pre-push hook executes on every `git push`. To review what it does:
+
+```bash
+cat .git/hooks/pre-push
+```
+
+To disable temporarily:
+
+```bash
+git push --no-verify
+```
+
+To remove:
+
+```bash
+rm .git/hooks/pre-push
+```
+
+### Profile Data
+
+Profile data is stored in `~/.vibe-check/profile.json`. This contains:
+- Session history (dates, scores, commits analyzed)
+- XP and achievement data
+- No sensitive information
+
+To clear your profile:
+
+```bash
+rm -rf ~/.vibe-check/
+```
+
+### Repository Data
+
+Calibration data is stored in `.vibe-check/` within each repository. Add to `.gitignore` if you don't want to commit it:
+
+```bash
+echo ".vibe-check/" >> .gitignore
+```
+
+---
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, please:
+
+1. **Do NOT** open a public issue
+2. Email the maintainer directly or use GitHub's private vulnerability reporting
+3. Include:
+   - Description of the vulnerability
+   - Steps to reproduce
+   - Potential impact
+   - Suggested fix (if any)
+
+We aim to respond within 48 hours and will credit reporters in the fix announcement.
+
+---
+
+## Changelog
+
+| Date | Version | Change |
+|------|---------|--------|
+| 2025-11-29 | 1.2.0 | Initial security review documented |

package/claude-progress.json

@@ -0,0 +1,44 @@
+{
+  "project": "vibe-check",
+  "created": "2025-11-29",
+  "version": "1.2.0",
+  "current_state": {
+    "working_on": null,
+    "blockers": [],
+    "next_steps": []
+  },
+  "stats": {
+    "test_files": 8,
+    "tests_passing": 108,
+    "npm_version": "1.2.0"
+  },
+  "sessions": [
+    {
+      "session_id": "2025-11-29-001",
+      "started": "2025-11-29T08:00:00Z",
+      "ended": "2025-11-29T09:30:00Z",
+      "vibe_level": 4,
+      "summary": "Implemented full gamification system: streaks, XP, 19 achievements, dashboard shell, profile command",
+      "commits": ["e132b83"],
+      "features_completed": ["VIBE-001", "VIBE-002", "VIBE-003"]
+    },
+    {
+      "session_id": "2025-11-29-002",
+      "started": "2025-11-29T12:00:00Z",
+      "ended": "2025-11-29T13:00:00Z",
+      "vibe_level": 3,
+      "summary": "GitHub Action, JSON output, --simple flag, 57 gamification tests, published v1.1.0",
+      "commits": ["70dbd6f", "9e06f71", "62c512a", "a2fb133", "c521144", "43bf561", "9fca764", "e4c9027"],
+      "features_completed": ["VIBE-004", "VIBE-005", "VIBE-007"]
+    },
+    {
+      "session_id": "2025-11-29-003",
+      "started": "2025-11-29T13:00:00Z",
+      "ended": "2025-11-29T13:45:00Z",
+      "vibe_level": 3,
+      "summary": "Pre-push git hook, security review, published v1.2.0",
+      "commits": ["f1d0843", "ad18702", "464a4ee", "9ae35d6"],
+      "features_completed": ["VIBE-006", "VIBE-008"]
+    }
+  ]
+}