@boshu2/vibe-check 1.7.0 → 1.8.0

package/README.md

@@ -1,265 +1,215 @@
-# vibe-check
+<p align="center">
+  <img src="https://raw.githubusercontent.com/boshu2/vibe-check/main/assets/logo.svg" alt="vibe-check" width="400">
+</p>
 
-[![npm version](https://img.shields.io/npm/v/@boshu2/vibe-check.svg)](https://www.npmjs.com/package/@boshu2/vibe-check)
-[![CI](https://github.com/boshu2/vibe-check/actions/workflows/ci.yml/badge.svg)](https://github.com/boshu2/vibe-check/actions/workflows/ci.yml)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+<p align="center">
+  <strong>Catch the debug spiral before it catches you.</strong>
+</p>
 
-![Vibe-Check Dashboard](docs/images/dashboard.png)
+<p align="center">
+  <a href="https://www.npmjs.com/package/@boshu2/vibe-check"><img src="https://img.shields.io/npm/v/@boshu2/vibe-check.svg?style=flat-square" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@boshu2/vibe-check"><img src="https://img.shields.io/npm/dm/@boshu2/vibe-check.svg?style=flat-square" alt="downloads"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="license"></a>
+</p>
 
-**Git-powered metrics for AI-assisted coding.** Catch debug spirals before they catch you.
+<p align="center">
+  Git-powered metrics for AI-assisted development.<br>
+  Detects the failure patterns from <a href="https://itrevolution.com/product/vibe-coding-book/"><em>Vibe Coding</em></a> (Gene Kim & Steve Yegge, 2025).
+</p>
+
+---
 
 ```bash
-npx @boshu2/vibe-check --since "2 hours ago"
+npx @boshu2/vibe-check
 ```
 
-```
-╭──────────────────────────────────────────────────────────────╮
-│  VIBE-CHECK                                    Nov 30, 2025  │
-├──────────────────────────────────────────────────────────────┤
-│                                                              │
-│  Rating: ELITE ✨                                            │
-│                                                              │
-│  Trust Pass Rate   ████████████████████  95%  ELITE          │
-│  Rework Ratio      ████░░░░░░░░░░░░░░░░  18%  ELITE          │
-│  Debug Spirals     None detected              ELITE          │
-│                                                              │
-│  You're in the zone. Ship it.                                │
-│                                                              │
-╰──────────────────────────────────────────────────────────────╯
-```
+<p align="center">
+  <img src="https://raw.githubusercontent.com/boshu2/vibe-check/main/assets/demo.gif" alt="vibe-check demo" width="600">
+</p>
 
 ---
 
-## Dashboard
+## The Problem
 
-```bash
-vibe-check dashboard
-```
+> "AI can destroy months of work in minutes." — Gene Kim & Steve Yegge
 
-Opens the dashboard above in your browser. Features:
-- 📊 Score trend charts with 7/30/90 day views
-- 🎯 AI-generated insights about your coding patterns
-- 🏆 Achievement tracking (19 achievements, 2 hidden)
-- 📈 Session history and ratings distribution
-- 🌙 GitHub dark theme
+AI-assisted coding creates a new failure mode: **the debug spiral**.
 
----
+You ask AI for a fix. It breaks something else. You ask for another fix. It breaks more. Three commits later, you've lost 30 minutes and made negative progress.
 
-## Install
+**vibe-check detects these spirals by analyzing your git history.**
 
-```bash
-npm install -g @boshu2/vibe-check
-```
+---
 
 ## Quick Start
 
 ```bash
 # Analyze recent work
-vibe-check --since "1 week ago"
+npx @boshu2/vibe-check --since "1 week ago"
 
 # Real-time spiral detection
-vibe-check watch
+npx @boshu2/vibe-check watch
 
 # Visual dashboard
-vibe-check dashboard
-
-# View your profile & achievements
-vibe-check profile
+npx @boshu2/vibe-check dashboard
 ```
 
 ---
 
-## Watch Mode
+## What It Measures
 
-Catch spirals **as they happen**, not after:
+| Metric | Question | Target |
+|--------|----------|--------|
+| **Trust Pass Rate** | Does the code stick? | >95% |
+| **Rework Ratio** | Building or debugging? | <30% |
+| **Debug Spirals** | Are you stuck? | 0 active |
 
-```bash
-vibe-check watch
-```
+### Detection Patterns
+
+| Pattern | Severity | What It Means |
+|---------|----------|---------------|
+| **Tests Passing Lie** | HIGH | AI claims tests pass, but they don't |
+| **Instruction Drift** | MEDIUM | AI gradually moves off-target |
+| **Debug Loop Spiral** | HIGH | 3+ fix commits on same component |
+| **Context Amnesia** | MEDIUM | Repeated fixes, forgotten solutions |
+
+---
+
+## Watch Mode
+
+Catches spirals **as they form** with personalized coaching:
 
 ```
 VIBE-CHECK WATCH MODE
-Monitoring: ~/projects/my-app
-────────────────────────────────────────────────────────
+────────────────────────────────────────────────
 
   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 over 7 minutes                   │
-  │                                                    │
-  │  💡 Consider:                                      │
-  │     • Step back and write a test                   │
-  │     • Check the docs or ask for help               │
-  │     • Take a 5-minute break                        │
-  └────────────────────────────────────────────────────┘
-
-────────────────────────────────────────────────────────
-```
-
----
+  ⚠️  SPIRAL FORMING
+      auth component, 3 fixes, 7 min
 
-## Gamification
+      Your history: 4 auth spirals, avg 18 min
+      What worked: wrote a test (3x), took a break (1x)
 
-Level up your coding with XP, streaks, and achievements:
+      → Write a test before your next fix attempt.
 
-```bash
-vibe-check profile
+────────────────────────────────────────────────
 ```
 
-```
-╭─────────────────────────────────────────────────────╮
-│                                                     │
-│   🏔️  Level 6 Grandmaster                          │
-│   ████████████████░░░░░░░░  2140 / 5000 XP         │
-│                                                     │
-│   🔥  12 day streak (longest: 14)                   │
-│   🏆  8/19 achievements unlocked                    │
-│                                                     │
-│   Recent Unlocks:                                   │
-│   ✨ Elite Vibes    🧘 Zen Master    📊 Regular     │
-│                                                     │
-╰─────────────────────────────────────────────────────╯
-```
-
-**19 achievements** including 2 hidden ones. Can you find them?
+Watch mode learns from your history and suggests what's worked before.
 
 ---
 
-## The Metrics
+## Install
 
-| 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 | 3+ |
+```bash
+npm install -g @boshu2/vibe-check
+```
+
+Or use directly with `npx`:
+
+```bash
+npx @boshu2/vibe-check --since "2 hours ago"
+```
 
 ---
 
-## Vibe Levels
+## Commands
 
-Declare your trust level before starting work:
+### Core Analysis
 
 ```bash
-vibe-check start --level 3
-# ... code ...
-vibe-check --since "1 hour ago"
+vibe-check                      # Analyze git history
+vibe-check watch                # Real-time spiral monitoring
+vibe-check dashboard            # Visual dashboard
+vibe-check timeline             # View coding journey
+vibe-check forensics            # Deep pattern analysis
 ```
 
-| Level | Name | Trust | Use For |
-|-------|------|-------|---------|
-| **5** | Full Auto | 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 |
+### Sessions
 
----
-
-## Git Hook
+```bash
+vibe-check start --level 3      # Quick session start
+vibe-check session start        # Interactive session start
+vibe-check session end          # End with metrics
+vibe-check session status       # Check active session
+```
 
-Auto-run before every push:
+### Profile & Insights
 
 ```bash
-vibe-check init-hook           # Install hook
-vibe-check init-hook --block-low  # Block LOW pushes
+vibe-check profile              # XP and achievements
+vibe-check insights             # Your spiral patterns
 ```
 
----
+### Tools
 
-## GitHub Action
-
-```yaml
-name: Vibe Check
-on: [pull_request]
-
-jobs:
-  vibe:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - uses: boshu2/vibe-check@v1
-        with:
-          github-token: ${{ secrets.GITHUB_TOKEN }}
+```bash
+vibe-check cache status         # Cache statistics
+vibe-check cache clear          # Clear cache
+vibe-check init-hook            # Install pre-push hook
+vibe-check pipeline             # Audit CI/CD safety
 ```
 
 ---
 
 ## Session Integration
 
-Integrate with Claude Code's `/session-start` and `/session-end` commands:
+Integrate with Claude Code or other AI dev tools:
 
 ```bash
-# At session start - capture baseline
+# Start session
 vibe-check session start --level 3
 
-# At session end - get metrics for claude-progress.json
+# End session - get JSON for logging
 vibe-check session end --format json
 ```
 
-Output includes failure pattern detection:
 ```json
 {
-  "metrics": { "trust_pass_rate": 92, "rework_ratio": 11, ... },
+  "metrics": { "trust_pass_rate": 92, "rework_ratio": 18 },
   "retro": {
     "failure_patterns_hit": [],
-    "failure_patterns_avoided": ["Debug Spiral", "Context Amnesia"],
-    "learnings": ["Test-first approach prevented spirals"]
+    "failure_patterns_avoided": ["Debug Spiral", "Context Amnesia"]
   }
 }
 ```
 
-Used by the [AgentOps session-management plugin](https://github.com/boshu2/agentops).
-
 ---
 
-## All Commands
+## The Ecosystem
 
-```
-vibe-check [options]           Analyze git history
-vibe-check watch               Real-time spiral detection
-vibe-check dashboard           Visual dashboard + insights
-vibe-check profile             XP, streaks, achievements
-vibe-check timeline            Coding journey visualization
-vibe-check start --level <n>   Declare vibe level (0-5)
-vibe-check session start       Capture baseline for session
-vibe-check session end         Get session metrics + patterns
-vibe-check session status      Show active session info
-vibe-check intervene           Record spiral intervention
-vibe-check learn               Extract learnings from patterns
-vibe-check lesson              Manage synthesized lessons
-vibe-check init-hook           Install git hook
-vibe-check cache               Manage local storage
-```
+vibe-check implements **Factor V (Measurement)** from [12-Factor AgentOps](https://github.com/boshu2/12-factor-agentops):
 
-**Options:**
-```
---since <date>       Start date ("1 week ago", "2024-01-01")
---until <date>       End date (default: now)
---score              Include VibeScore calculation
---simple             Compact output
---format <type>      terminal | json | markdown
---output <file>      Save JSON to file
---verbose            Detailed output
+```text
+BUILD              →     WORK          →     RUN
+12-Factor Agents        Vibe Coding         12-Factor AgentOps
+(HumanLayer)           (Gene & Steve)       (Operations)
+                                                  ↓
+                                             vibe-check
+                                            (Measurement)
 ```
 
+| Factor | What vibe-check Provides |
+|--------|-------------------------|
+| **IV: Validation Gates** | Pre-commit hooks, CI integration |
+| **V: Measurement** | Quantified feedback loop |
+| **VII: Smart Routing** | Spiral detection triggers intervention |
+| **XI: Fail-Safe Checks** | Pattern detection for all 12 failures |
+
 ---
 
 ## Philosophy
 
-**vibe-check is a mirror, not a judge.**
+vibe-check is a mirror, not a judge.
 
-Use it for self-reflection. Catch your own patterns. Improve your own flow.
+It answers one question: *are you building, or are you spiraling?*
 
-It's not a productivity metric. It's not for performance reviews. It's not measuring AI effectiveness.
+Use it for self-reflection. Catch your own patterns. Improve your own flow.
 
-It's just asking: *are you building, or are you spiraling?*
+It's not a productivity metric. It's not for performance reviews.
 
 ---
 
@@ -268,13 +218,16 @@ It's just asking: *are you building, or are you spiraling?*
 - Node.js >= 20.0.0
 - Git repository with commits
 
-## Docs
+---
+
+## Learn More
 
-- [Vibe-Coding Ecosystem](docs/VIBE-ECOSYSTEM.md) - Full methodology
-- [Architecture](docs/ARCHITECTURE.md) - Codebase structure
-- [Gamification](docs/GAMIFICATION.md) - XP & achievements deep dive
-- [Metrics Explained](docs/METRICS-EXPLAINED.md) - How it works
-- [Changelog](CHANGELOG.md) - Version history
+- [Vibe-Coding Ecosystem](docs/VIBE-ECOSYSTEM.md) — Full methodology, all features
+- [Vibe Coding Book](https://itrevolution.com/product/vibe-coding-book/) — Gene Kim & Steve Yegge (2025)
+- [12-Factor AgentOps](https://github.com/boshu2/12-factor-agentops) — Operational framework
+- [12-Factor Agents](https://github.com/humanlayer/12-factor-agents) — Engineering patterns (HumanLayer)
+
+---
 
 ## License
 
@@ -283,5 +236,5 @@ MIT
 ---
 
 <p align="center">
-  <i>Built for developers who vibe with AI</i>
+  <em>Built for developers who work with AI.</em>
 </p>

package/SECURITY.md

@@ -4,11 +4,12 @@
 
 | Version | Supported          |
 | ------- | ------------------ |
+| 1.7.x   | :white_check_mark: |
 | 1.x.x   | :white_check_mark: |
 
 ## Security Assessment
 
-**Last Review:** 2025-11-29
+**Last Review:** 2025-12-05
 **Risk Level:** LOW
 **Reviewer:** Automated + Manual
 
@@ -31,6 +32,8 @@ vibe-check is a local CLI tool that reads git history and writes statistics to l
 2. Calculates metrics from commit patterns
 3. Writes profile/calibration data to `.vibe-check/` directory
 4. Optionally installs a pre-push git hook
+5. Detects work sessions from commit timestamps (pure analysis)
+6. Analyzes patterns like debug spirals and vague commits (pure analysis)
 
 ### What vibe-check does NOT do
 
@@ -175,4 +178,5 @@ We aim to respond within 48 hours and will credit reporters in the fix announcem
 
 | Date | Version | Change |
 |------|---------|--------|
+| 2025-12-05 | 1.7.0 | Added forensics, sessions commands; updated threat model |
 | 2025-11-29 | 1.2.0 | Initial security review documented |

package/assets/logo-dark.svg

@@ -0,0 +1,47 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 100" fill="none">
+  <defs>
+    <linearGradient id="spiralGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#A78BFA"/>
+      <stop offset="100%" style="stop-color:#22D3EE"/>
+    </linearGradient>
+    <linearGradient id="checkGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#34D399"/>
+      <stop offset="100%" style="stop-color:#22D3EE"/>
+    </linearGradient>
+  </defs>
+
+  <!-- Spiral breaking into checkmark -->
+  <g transform="translate(10, 10)">
+    <!-- Spiral (left side, fading out) -->
+    <path d="M40 40
+             C40 25, 55 20, 60 35
+             C65 45, 50 55, 45 45
+             C42 38, 52 32, 55 40"
+          stroke="url(#spiralGrad)"
+          stroke-width="4"
+          stroke-linecap="round"
+          fill="none"
+          opacity="0.6"/>
+
+    <!-- Breaking point / transition -->
+    <circle cx="55" cy="40" r="3" fill="url(#spiralGrad)" opacity="0.4"/>
+
+    <!-- Checkmark (emerging from spiral) -->
+    <path d="M52 45 L62 55 L78 30"
+          stroke="url(#checkGrad)"
+          stroke-width="5"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          fill="none"/>
+  </g>
+
+  <!-- Text: vibe-check -->
+  <text x="100" y="62" font-family="system-ui, -apple-system, sans-serif" font-size="42" font-weight="600">
+    <tspan fill="#A78BFA">vibe</tspan><tspan fill="#94A3B8">-</tspan><tspan fill="#22D3EE">check</tspan>
+  </text>
+
+  <!-- Tagline -->
+  <text x="102" y="82" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#CBD5E1" letter-spacing="0.5">
+    catch the spiral before it catches you
+  </text>
+</svg>

package/assets/logo.svg

@@ -0,0 +1,47 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 100" fill="none">
+  <defs>
+    <linearGradient id="spiralGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#7C3AED"/>
+      <stop offset="100%" style="stop-color:#06B6D4"/>
+    </linearGradient>
+    <linearGradient id="checkGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#10B981"/>
+      <stop offset="100%" style="stop-color:#06B6D4"/>
+    </linearGradient>
+  </defs>
+
+  <!-- Spiral breaking into checkmark -->
+  <g transform="translate(10, 10)">
+    <!-- Spiral (left side, fading out) -->
+    <path d="M40 40
+             C40 25, 55 20, 60 35
+             C65 45, 50 55, 45 45
+             C42 38, 52 32, 55 40"
+          stroke="url(#spiralGrad)"
+          stroke-width="4"
+          stroke-linecap="round"
+          fill="none"
+          opacity="0.6"/>
+
+    <!-- Breaking point / transition -->
+    <circle cx="55" cy="40" r="3" fill="url(#spiralGrad)" opacity="0.4"/>
+
+    <!-- Checkmark (emerging from spiral) -->
+    <path d="M52 45 L62 55 L78 30"
+          stroke="url(#checkGrad)"
+          stroke-width="5"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          fill="none"/>
+  </g>
+
+  <!-- Text: vibe-check -->
+  <text x="100" y="62" font-family="system-ui, -apple-system, sans-serif" font-size="42" font-weight="600">
+    <tspan fill="#7C3AED">vibe</tspan><tspan fill="#64748B">-</tspan><tspan fill="#06B6D4">check</tspan>
+  </text>
+
+  <!-- Tagline -->
+  <text x="102" y="82" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#94A3B8" letter-spacing="0.5">
+    catch the spiral before it catches you
+  </text>
+</svg>

package/claude-progress.json

@@ -161,16 +161,15 @@
     }
   ],
   "current_state": {
-    "phase": "brainstorming",
-    "working_on": "Feature audit - cut/enhance/add analysis",
+    "phase": "completed",
+    "working_on": null,
     "blockers": [],
     "next_steps": [
-      "Decide: Cut learning system (10 files, ~1500 lines)?",
-      "Decide: Cut advanced gamification (challenges, leaderboards, badges)?",
-      "Decide: Add `vibe-check now` quick check?",
-      "Consider npm publish for v1.7.0"
+      "Run vibe-check on real projects to validate",
+      "Consider bumping version to 1.8.0",
+      "VIBE-047 DEFERRED: Era evolution tracking (scope creep risk - revisit after 045/046 proven)"
     ],
-    "resume_summary": "Session integration complete. Ran feature audit: 78 files is bloated, recommend cutting to ~35. Learning system (10 files) and advanced gamification (5 files) are over-engineered. Core value is analyze + watch + basic gamification."
+    "resume_summary": "VIBE-045 (forensics) and VIBE-046 (sessions) both implemented and tested. 41 new tracer tests, all 100 tests passing. Commands: vibe-check forensics, vibe-check sessions."
   },
   "sessions": [
     {
@@ -197,6 +196,28 @@
           "Learning system has zero adoption evidence - candidate for removal"
         ]
       }
+    },
+    {
+      "session_id": "2025-12-02-002",
+      "started": "2025-12-02T19:30:00Z",
+      "ended": "2025-12-02T21:00:00Z",
+      "vibe_level": 3,
+      "summary": "Major cleanup: cut 20 files (-3900 lines), published v1.7.0. Fixed all docs. Created actionable coaching plan (5 features).",
+      "commits": ["6c28204", "1526f6d", "fbe6a89", "e77a6c9", "8f77bda", "e4515e8", "5ec7758", "871a0c4"],
+      "features_completed": ["VIBE-033", "VIBE-034"],
+      "metrics": {
+        "trust_pass_rate": 100,
+        "rework_ratio": 0
+      },
+      "retro": {
+        "failure_patterns_hit": [],
+        "failure_patterns_avoided": ["Scope Creep", "Over-engineering"],
+        "learnings": [
+          "Cutting features feels good - 78→58 files, cleaner codebase",
+          "Documentation debt accumulates - must update docs after code changes",
+          "Plan before implement - actionable coaching plan guides next work"
+        ]
+      }
     }
   ],
   "sessions_continued": [

package/claude-progress.txt

@@ -3,6 +3,54 @@ Created: 2025-11-29
 
 ## Session Log
 
+--- 2025-12-02 21:00 - Major Cleanup & Actionable Coaching Plan ---
+
+VIBE LEVEL: 3 (Balanced, verify key outputs)
+
+COMPLETED:
+- Major codebase cleanup:
+  - Cut learning system (10 files, 1755 lines)
+  - Cut advanced gamification (7 files, 1215 lines)
+  - Removed learn, lesson, intervene commands
+  - 78 → 58 source files, -3900 lines total
+- Published v1.7.0 to npm
+- Fixed all documentation:
+  - Makefile, CLAUDE.md, README.md
+  - docs/GAMIFICATION.md (full rewrite)
+  - docs/ARCHITECTURE.md, docs/VIBE-ECOSYSTEM.md
+- Created actionable coaching plan:
+  - 5 new features (VIBE-040 to VIBE-044)
+  - Spiral history storage, personalized alerts
+  - ~300-400 lines, lean implementation
+
+COMMITS:
+- 6c28204 refactor: remove learning system and advanced gamification
+- 1526f6d chore: bump version to 1.7.0
+- fbe6a89 docs: remove references to deleted commands
+- e77a6c9 docs: update GAMIFICATION.md and ARCHITECTURE.md
+- 8f77bda docs: update VIBE-ECOSYSTEM.md and ARCHITECTURE.md
+- e4515e8 feat(dashboard): enhanced visual dashboard
+- 5ec7758 chore: add session bundles
+- 871a0c4 plan: actionable coaching enhancement
+
+ARTIFACTS:
+- .agents/bundles/actionable-coaching-plan-2025-12-02.md
+- feature-list.json updated with VIBE-040 to VIBE-044
+
+REMAINING:
+- VIBE-040: Spiral history storage (NDJSON)
+- VIBE-041: Auto-record spirals during analyze/session
+- VIBE-042: Personalized watch alerts
+- VIBE-043: Session end coaching
+- VIBE-044: Insights command
+
+NEXT SESSION SHOULD:
+- Start with VIBE-040: Create src/storage/spiral-history.ts
+- Implement NDJSON append/query functions
+- Then VIBE-041: Wire into analyze.ts and session.ts
+
+================================================================================
+
 --- 2025-12-02 - Automatic Learning Cadence Research & Planning ---
 
 VIBE LEVEL: 4 (Research/Planning, exploratory)