@boshu2/vibe-check 1.0.1 → 1.1.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,52 @@ 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.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
+- Complete README rewrite with problem-first structure
+- Added "The Problem" and "The Insight" sections
+- Added practical "When to Run" guidance
+- Added prevention tips for debug spiral patterns
+
 ## [1.0.1] - 2025-11-28
 
 ### Added

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