@boshu2/vibe-check 1.6.2 → 1.8.0

package/.agents/plans/git-forensics-enhancement-2025-12-05.md

@@ -0,0 +1,493 @@
+# vibe-check Enhancement Proposal
+
+**Package:** @boshu2/vibe-check v1.7.0
+**Purpose:** Add git forensics capabilities proven in release-engineering retrospective
+**Date:** December 5, 2025
+
+---
+
+## Summary
+
+Three proven algorithms from the release-engineering retrospective (475 commits, 60 days) should be integrated into vibe-check as new features:
+
+1. **Git Forensics** - Repository analysis with pattern detection
+2. **Session Detection** - Work session identification (90-min threshold)
+3. **Era Evolution** - Track transformation phases over time
+
+**Impact:** Transform vibe-check from real-time monitor → comprehensive retrospective tool
+
+---
+
+## Enhancement #1: Git Forensics Mode
+
+### Command
+```bash
+npx @boshu2/vibe-check forensics [--since DATE] [--format json|markdown]
+```
+
+### What It Does
+Analyzes git history to detect failure patterns and calculate quality metrics.
+
+### Outputs
+```json
+{
+  "analysis_period": "2025-10-04 to 2025-12-05",
+  "total_commits": 475,
+  "patterns_detected": {
+    "debug_spirals": {
+      "count": 14,
+      "duration_minutes": 58.7,
+      "dates": ["2025-10-04"],
+      "commits": ["7b07068", "bb685a2", ...]
+    },
+    "vague_commits": {
+      "count": 282,
+      "percentage": 59.4,
+      "threshold": 20,
+      "examples": ["ci", "v3", "blah", "take 2"]
+    },
+    "context_amnesia": {
+      "scopes": [
+        {"name": "ci", "visits": 10},
+        {"name": "automation", "visits": 9},
+        {"name": "pipelines", "visits": 8}
+      ]
+    }
+  },
+  "quality_metrics": {
+    "conventional_commits": 28.6,
+    "descriptive_quality": 30.7,
+    "vague_quality": 59.4
+  },
+  "recommendation": "sweep",
+  "sweep_targets": ["lib/common.sh", "harmonize.sh", "scaffold.sh"]
+}
+```
+
+### Implementation Algorithm
+
+```python
+# Pseudocode from release-engineering analysis
+def git_forensics(since_date):
+    # Extract commits
+    commits = git_log(format="%H|%h|%an|%ae|%ai|%at|%s", since=since_date)
+
+    # Parse each commit
+    parsed = []
+    for commit in commits:
+        hash, short, author, email, date_iso, timestamp, subject = commit.split('|')
+
+        # Detect patterns
+        is_take = re.match(r'^take [0-9]+$', subject)
+        is_vague = len(subject) < 20
+        is_conventional = re.match(r'^(feat|fix|docs|test|refactor|chore)', subject)
+
+        parsed.append({
+            'hash': short,
+            'subject': subject,
+            'is_take': is_take,
+            'is_vague': is_vague,
+            'is_conventional': is_conventional,
+            'timestamp': int(timestamp)
+        })
+
+    # Detect debug spirals
+    take_commits = [c for c in parsed if c['is_take']]
+    if len(take_commits) >= 3:
+        first = min(take_commits, key=lambda c: c['timestamp'])
+        last = max(take_commits, key=lambda c: c['timestamp'])
+        duration_min = (last['timestamp'] - first['timestamp']) / 60
+
+        patterns['debug_spirals'] = {
+            'count': len(take_commits),
+            'duration_minutes': duration_min
+        }
+
+    # Calculate quality metrics
+    total = len(parsed)
+    vague_count = len([c for c in parsed if c['is_vague']])
+    conventional_count = len([c for c in parsed if c['is_conventional']])
+
+    quality_metrics = {
+        'conventional_commits': 100 * conventional_count / total,
+        'vague_quality': 100 * vague_count / total
+    }
+
+    # Recommendation
+    if vague_count > total * 0.5 or len(take_commits) > 0:
+        recommendation = 'sweep'
+
+    return {
+        'patterns_detected': patterns,
+        'quality_metrics': quality_metrics,
+        'recommendation': recommendation
+    }
+```
+
+### Files to Create
+- `src/commands/forensics.js` - Main command
+- `src/analyzers/patterns.js` - Pattern detection
+- `src/analyzers/quality.js` - Quality metrics
+
+---
+
+## Enhancement #2: Session Detection
+
+### Command
+```bash
+npx @boshu2/vibe-check sessions [--threshold MINUTES] [--format json]
+```
+
+### What It Does
+Identifies work sessions from git history using configurable time gap threshold.
+
+### Output
+```json
+{
+  "total_sessions": 46,
+  "total_commits": 475,
+  "avg_commits_per_session": 10.3,
+  "avg_duration_minutes": 79.4,
+  "median_duration_minutes": 33.1,
+  "longest_session_minutes": 413.2,
+  "sessions": [
+    {
+      "session_id": 1,
+      "start_date": "2025-10-04 11:59:47",
+      "end_date": "2025-10-04 16:53:29",
+      "duration_minutes": 293.7,
+      "num_commits": 50,
+      "commits": ["c83fea9", "de59b1c", ...]
+    }
+  ]
+}
+```
+
+### Implementation Algorithm
+
+```python
+# Proven algorithm from release-engineering
+def detect_sessions(commits, gap_threshold=90):
+    """
+    Detect work sessions using time gap between commits.
+
+    Args:
+        commits: List of commits sorted by timestamp
+        gap_threshold: Minutes between commits to start new session (default: 90)
+
+    Returns:
+        List of sessions with metadata
+    """
+    SESSION_GAP = gap_threshold * 60  # Convert to seconds
+    sessions = []
+    current_session = []
+
+    for commit in sorted(commits, key=lambda c: c['timestamp']):
+        if not current_session:
+            current_session = [commit]
+        elif commit['timestamp'] - current_session[-1]['timestamp'] > SESSION_GAP:
+            # Gap exceeded, save current session and start new
+            sessions.append({
+                'start': current_session[0],
+                'end': current_session[-1],
+                'commits': current_session,
+                'duration_min': (current_session[-1]['timestamp'] - current_session[0]['timestamp']) / 60
+            })
+            current_session = [commit]
+        else:
+            current_session.append(commit)
+
+    # Don't forget last session
+    if current_session:
+        sessions.append({
+            'start': current_session[0],
+            'end': current_session[-1],
+            'commits': current_session,
+            'duration_min': (current_session[-1]['timestamp'] - current_session[0]['timestamp']) / 60
+        })
+
+    return sessions
+```
+
+### Use Cases
+- Productivity analysis (session duration trends)
+- Work pattern identification (when do you work best?)
+- Break analysis (gap between sessions)
+- Integration with time tracking tools
+
+### Files to Create
+- `src/commands/sessions.js` - Main command
+- `src/analyzers/sessions.js` - Session detection algorithm
+
+---
+
+## Enhancement #3: Era Evolution Tracking
+
+### Command
+```bash
+npx @boshu2/vibe-check evolution [--eras CONFIG] [--format json]
+```
+
+### What It Does
+Classifies commits into user-defined eras and tracks quality evolution over time.
+
+### Configuration
+```json
+{
+  "eras": [
+    {
+      "name": "genesis",
+      "start": "2025-10-04",
+      "end": "2025-10-05",
+      "description": "Initial chaos"
+    },
+    {
+      "name": "transformation",
+      "start": "2025-11-18",
+      "end": "2025-12-02",
+      "description": "Post-sweep discipline"
+    }
+  ]
+}
+```
+
+### Output
+```json
+{
+  "eras": [
+    {
+      "name": "genesis",
+      "commits": 154,
+      "sessions": 6,
+      "metrics": {
+        "conventional": 0.0,
+        "vague": 97.4,
+        "velocity": 10.79,
+        "rework_ratio": 6.5,
+        "debug_spirals": 14
+      }
+    },
+    {
+      "name": "transformation",
+      "commits": 63,
+      "sessions": 10,
+      "metrics": {
+        "conventional": 85.7,
+        "vague": 0.0,
+        "velocity": 6.97,
+        "rework_ratio": 25.4,
+        "debug_spirals": 0
+      }
+    }
+  ],
+  "transformation_summary": {
+    "conventional": "+85.7%",
+    "vague": "-97.4%",
+    "debug_spirals": "-14"
+  }
+}
+```
+
+### Implementation Algorithm
+
+```python
+# Era classification from release-engineering
+def classify_eras(commits, era_config):
+    """
+    Classify commits into eras and calculate per-era metrics.
+
+    Args:
+        commits: List of parsed commits
+        era_config: Era definitions with start/end dates
+
+    Returns:
+        Metrics grouped by era
+    """
+    commits_by_era = defaultdict(list)
+
+    for commit in commits:
+        commit_date = commit['date_iso'].split()[0]
+
+        # Find matching era
+        for era in era_config:
+            if era['start'] <= commit_date <= era['end']:
+                commits_by_era[era['name']].append(commit)
+                break
+
+    # Calculate metrics per era
+    results = []
+    for era_name, era_commits in commits_by_era.items():
+        total = len(era_commits)
+
+        metrics = {
+            'conventional': 100 * sum(1 for c in era_commits if c['is_conventional']) / total,
+            'vague': 100 * sum(1 for c in era_commits if c['is_vague']) / total,
+            'debug_spirals': sum(1 for c in era_commits if c['is_take'])
+        }
+
+        results.append({
+            'name': era_name,
+            'commits': total,
+            'metrics': metrics
+        })
+
+    return results
+```
+
+### Use Cases
+- Transformation stories (before/after)
+- Quarterly reviews (Q1, Q2, Q3, Q4)
+- Migration tracking (pre-refactor, during, post)
+- Team onboarding impact (before new dev, after)
+
+### Files to Create
+- `src/commands/evolution.js` - Main command
+- `src/analyzers/eras.js` - Era classification
+- `src/config/eras.schema.json` - Era config validation
+
+---
+
+## Integration Points
+
+### Current vibe-check Commands
+```bash
+vibe-check analyze       # Real-time metrics for current session
+vibe-check history       # Historical trend analysis
+```
+
+### New Commands (Proposed)
+```bash
+vibe-check forensics     # Git history pattern detection
+vibe-check sessions      # Work session analysis
+vibe-check evolution     # Era-based transformation tracking
+vibe-check sweep-check   # Quick check: is sweep needed?
+```
+
+### sweep-check Integration
+```bash
+npx @boshu2/vibe-check sweep-check
+
+# Combines forensics + pattern detection + recommendation
+# Output:
+⚠️ Sweep recommended
+Detected patterns:
+  - 12 vague commits (threshold: >5)
+  - 2 debug spirals
+  - Context amnesia: ci (10 visits), automation (9 visits)
+
+Targets for sweep:
+  - lib/common.sh (0% test coverage, 8 vague commits)
+  - harmonize.sh (no tests, spiral detected)
+
+Run: npx @boshu2/vibe-check sweep --target lib/common.sh
+```
+
+---
+
+## Implementation Priority
+
+### Phase 1: Core Forensics (MVP)
+- [ ] Git log parsing
+- [ ] Pattern detection (vague commits, debug spirals)
+- [ ] Basic quality metrics
+- [ ] JSON output
+- **Estimate:** 2-3 days
+
+### Phase 2: Sessions & Evolution
+- [ ] Session detection algorithm
+- [ ] Era classification
+- [ ] Comparative metrics
+- [ ] Markdown/Terminal output
+- **Estimate:** 2-3 days
+
+### Phase 3: Integration
+- [ ] sweep-check convenience command
+- [ ] Integration with existing analyze command
+- [ ] Historical storage
+- [ ] Dashboard visualization
+- **Estimate:** 2-3 days
+
+---
+
+## Testing Strategy
+
+### Unit Tests
+```javascript
+describe('forensics', () => {
+  it('detects debug spirals from take N pattern', () => {
+    const commits = [
+      { subject: 'take 2', timestamp: 1000 },
+      { subject: 'take 3', timestamp: 1300 },
+      { subject: 'take 4', timestamp: 1600 }
+    ];
+    const patterns = detectPatterns(commits);
+    expect(patterns.debug_spirals.count).toBe(3);
+    expect(patterns.debug_spirals.duration_minutes).toBe(10);
+  });
+
+  it('detects vague commits', () => {
+    const commits = [
+      { subject: 'ci' },
+      { subject: 'v3' },
+      { subject: 'feat: proper commit message' }
+    ];
+    const quality = calculateQuality(commits);
+    expect(quality.vague_percentage).toBe(66.7);
+  });
+});
+```
+
+### Integration Tests
+- Test against real repositories (release-engineering as reference)
+- Validate against known metrics (475 commits → 46 sessions)
+- Compare with manual analysis
+
+---
+
+## Reference Implementation
+
+All algorithms proven in:
+- **Repository:** release-engineering (475 commits analyzed)
+- **Files:** `/tmp/full_parse.py`, `/tmp/detect_sessions.py`, `/tmp/calc_vibe_metrics.py`
+- **Story:** `THE-RELEASE-ENGINEERING-STORY.md`
+
+**Results:**
+- Successfully detected 14 debug spirals
+- Calculated metrics across 5 eras
+- Identified 46 work sessions
+- Proved transformation: 97.4% vague → 0%
+
+---
+
+## Benefits
+
+**For Individual Developers:**
+- Understand your coding patterns
+- Identify when you're most productive
+- Catch failure patterns before they compound
+
+**For Teams:**
+- Track transformation progress
+- Identify training needs
+- Celebrate improvements with data
+
+**For Organizations:**
+- Prove ROI of process improvements
+- Benchmark across projects
+- Make data-driven decisions
+
+---
+
+## Next Steps
+
+1. **Validate approach** with vibe-check maintainers
+2. **Create GitHub issue** with this proposal
+3. **Implement Phase 1** (forensics MVP)
+4. **Get community feedback** on UX
+5. **Iterate** based on real-world usage
+
+---
+
+**Contact:** Boden Fuller (boden.fuller@gdit.com)
+**Reference:** release-engineering retrospective (Dec 5, 2025)
+**Tags:** `#vibe-check` `#git-forensics` `#enhancement-proposal`

package/.claude/skills/typescript-review.md

@@ -0,0 +1,152 @@
+# TypeScript Code Review Skill
+
+**Trigger:** User asks for TypeScript review, type safety audit, or TS best practices check.
+
+**Purpose:** Systematic TypeScript code review focusing on type safety, patterns, and idiomatic usage.
+
+---
+
+## Review Checklist
+
+### 1. Compiler Configuration (tsconfig.json)
+
+| Setting | Recommended | Why |
+|---------|-------------|-----|
+| `strict` | `true` | Enables all strict checks |
+| `noImplicitAny` | `true` (via strict) | No silent `any` types |
+| `strictNullChecks` | `true` (via strict) | Catch null/undefined errors |
+| `noUncheckedIndexedAccess` | `true` | Arrays return `T \| undefined` |
+| `exactOptionalPropertyTypes` | `true` | Distinguish `undefined` vs missing |
+| `noImplicitReturns` | `true` | All code paths must return |
+| `noFallthroughCasesInSwitch` | `true` | Prevent switch fallthrough bugs |
+
+### 2. Type Safety Issues
+
+**Critical (fix immediately):**
+- [ ] Explicit `any` types
+- [ ] Type assertions without validation (`as Type`)
+- [ ] Non-null assertions (`!`) without checks
+- [ ] `@ts-ignore` or `@ts-expect-error` comments
+- [ ] Missing return types on exported functions
+
+**Warning (improve when possible):**
+- [ ] Implicit `any` in callbacks
+- [ ] Overly broad types (`object`, `{}`, `Function`)
+- [ ] Missing generics where reuse is possible
+- [ ] Type assertions that could be type guards
+
+### 3. Type Design Patterns
+
+**Good patterns to look for:**
+```typescript
+// Discriminated unions
+type Result<T> =
+  | { success: true; data: T }
+  | { success: false; error: string };
+
+// Branded types for IDs
+type UserId = string & { readonly brand: unique symbol };
+
+// Const assertions for literals
+const STATUSES = ['pending', 'active', 'done'] as const;
+type Status = typeof STATUSES[number];
+
+// Type guards
+function isUser(obj: unknown): obj is User {
+  return typeof obj === 'object' && obj !== null && 'id' in obj;
+}
+```
+
+**Anti-patterns to flag:**
+```typescript
+// ❌ Stringly-typed
+function setStatus(status: string) { }
+
+// ✅ Union type
+function setStatus(status: 'pending' | 'active' | 'done') { }
+
+// ❌ Optional chaining hiding bugs
+const name = user?.profile?.name ?? 'Unknown';
+
+// ✅ Explicit null handling
+if (!user || !user.profile) {
+  throw new Error('User profile required');
+}
+const name = user.profile.name;
+```
+
+### 4. Interface vs Type
+
+| Use Interface | Use Type |
+|---------------|----------|
+| Object shapes | Unions, intersections |
+| Extendable contracts | Computed types |
+| Class implementations | Mapped types |
+| Public API | Internal aliases |
+
+### 5. Export Hygiene
+
+- [ ] Are internal types exported unnecessarily?
+- [ ] Is there a central `types.ts` for shared types?
+- [ ] Are re-exports organized (`index.ts` barrels)?
+
+---
+
+## Review Process
+
+1. **Check tsconfig.json** - Verify strict settings
+2. **Run `tsc --noEmit`** - Catch all compiler errors
+3. **Search for anti-patterns:**
+   ```bash
+   grep -r ": any" src/
+   grep -r "as " src/ | grep -v "import"
+   grep -r "@ts-ignore" src/
+   grep -r "!" src/ | grep -v "!=" | grep -v "!=="
+   ```
+4. **Review types.ts** - Check type design
+5. **Sample 3-5 files** - Deep review patterns
+
+---
+
+## Output Format
+
+```markdown
+## TypeScript Review: [Project Name]
+
+### Config Score: X/10
+[tsconfig.json findings]
+
+### Type Safety Score: X/10
+[Anti-pattern counts and examples]
+
+### Type Design Score: X/10
+[Pattern quality assessment]
+
+### Top Issues
+1. [Most critical issue]
+2. [Second issue]
+3. [Third issue]
+
+### Recommendations
+- [ ] [Actionable fix 1]
+- [ ] [Actionable fix 2]
+- [ ] [Actionable fix 3]
+```
+
+---
+
+## Quick Fixes
+
+```bash
+# Find all `any` types
+grep -rn ": any" src/
+
+# Find type assertions
+grep -rn " as [A-Z]" src/
+
+# Find non-null assertions
+grep -rn "\![^=]" src/
+
+# Run strict type check
+npx tsc --noEmit --strict
+```

package/CHANGELOG.md

@@ -5,6 +5,59 @@ 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).
 
+## [Unreleased]
+
+## [1.8.0] - 2025-12-05
+
+### Added
+
+- **Git Forensics** - `vibe-check forensics` command for deep pattern analysis (VIBE-045)
+  - Detects debug spirals ("take N" patterns indicating fix-retry loops)
+  - Detects vague commits (<20 characters)
+  - Detects context amnesia (repeatedly revisiting same scope)
+  - Quality metrics: conventional commit %, descriptive commit %
+  - Recommendations: sweep, maintain, or celebrate
+- **Session Detection** - `vibe-check sessions` command for work session analysis (VIBE-046)
+  - Identifies sessions from commit timestamps (90-minute gap threshold)
+  - Session statistics: avg duration, commits per session, longest/shortest
+  - Proven algorithm from release-engineering retrospective
+- **Brand Assets** - Professional logo and visual identity
+  - SVG logo with spiral-to-checkmark concept
+  - Light and dark mode variants
+  - Tagline: "catch the spiral before it catches you"
+- **Actionable Coaching** - Personalized coaching based on your spiral history
+  - `vibe-check insights` - View your spiral patterns and what works for you
+  - Watch mode shows personalized alerts
+  - Session end shows coaching for spirals hit during the session
+  - All spirals auto-recorded to `~/.vibe-check/spiral-history.ndjson`
+
+### Changed
+
+- **README Redesign** - Modern visual flow inspired by top npm packages
+  - Centered hero section with logo and badges
+  - Progressive disclosure structure
+  - Cleaner section organization with horizontal rules
+  - Scannable tables instead of prose
+- **Security Policy Updated** - Added forensics and sessions to threat model
+
+## [1.7.0] - 2025-12-02
+
+### Added
+- **Session Integration** - New `vibe-check session` command suite for Claude Code integration
+  - `session start` - Capture baseline metrics at session start
+  - `session end` - Get session metrics with failure pattern detection
+  - `session status` - Show active session info
+  - JSON output compatible with `claude-progress.json` format
+  - Automatic failure pattern detection (Debug Spiral, Context Amnesia, Velocity Crash, Trust Erosion, Flow Disruption)
+  - Auto-generated learnings based on metrics and patterns
+  - Baseline comparison with last 7 days
+
+### Changed
+- Major cleanup: removed 20 files, -3900 lines of speculative features
+- Removed learning system (zero adoption evidence)
+- Removed advanced gamification (challenges, prestige, leaderboards)
+- Simplified to core value: metrics, coaching, insights
+
 ## [1.6.0] - 2025-11-30
 
 ### Added