@leanspec/ui 0.2.7-dev.20251128020042 → 0.2.8

package/.next/standalone/packages/ui/dist/standalone/specs/archived/046-stats-dashboard-refactor/IMPLEMENTATION.md

@@ -0,0 +1,241 @@
+# Implementation Plan
+
+> Part of [046-stats-dashboard-refactor](./README.md)
+
+## Phase 1: Enhance Stats Command (Week 1)
+
+### Step 1.1: Enhance stats command
+- [ ] Merge all `analytics.ts` logic into `stats.ts`
+- [ ] Add default simplified output
+- [ ] Add `--full` flag (shows everything from old analytics)
+- [ ] Add `--velocity`, `--timeline` flags (focus modes)
+- [ ] Keep all existing analytics functionality
+
+### Step 1.2: Add smart insights
+- [ ] Create `utils/insights.ts` with insight generation
+- [ ] Integrate insights into default stats output
+- [ ] Add "Needs Attention" section
+- [ ] Test with various project states
+
+### Step 1.3: Remove analytics command
+- [ ] Delete `src/commands/analytics.ts` file
+- [ ] Remove from `src/commands/index.ts` exports
+- [ ] Remove from CLI registration in `cli.ts`
+- [ ] Update CHANGELOG with breaking change note
+
+### Step 1.4: Update documentation
+- [ ] Update README (remove analytics, show stats)
+- [ ] Update AGENTS.md (use stats, not analytics)
+- [ ] Update help text
+- [ ] Add migration note to CHANGELOG
+- [ ] Update help text
+- [ ] Mark `analytics` as deprecated in help
+
+## Phase 2: Enhance Board (Week 1-2)
+
+### Step 2.1: Add health calculations
+- [ ] Create `utils/health.ts` with health score logic
+- [ ] Implement simple completion calculation
+- [ ] Add critical issue detection
+- [ ] Add warning detection (long-running WIP)
+
+### Step 2.2: Update board command
+- [ ] Add health summary box at top
+- [ ] Include velocity snapshot
+- [ ] Add `--simple` flag (original view)
+- [ ] Add `--health-only` flag (just summary)
+- [ ] Ensure health box doesn't break existing layout
+
+### Step 2.3: Test board enhancements
+- [ ] Test with various project sizes
+- [ ] Verify health box renders correctly
+- [ ] Test with empty projects
+- [ ] Test with all-complete projects
+
+## Phase 3: Remove Dashboard (Week 2)
+
+### Step 3.1: Delete dashboard command
+- [ ] Delete `src/commands/dashboard.ts` file
+- [ ] Remove from `src/commands/index.ts` exports
+- [ ] Remove from CLI registration in `cli.ts`
+- [ ] Update CHANGELOG with breaking change note
+
+### Step 3.2: Update documentation
+- [ ] Remove dashboard from README
+- [ ] Update AGENTS.md (AI should use board, not dashboard)
+- [ ] Update help text
+- [ ] Add migration guide to CHANGELOG
+
+### Step 3.3: Verify removal
+- [ ] Ensure no references to dashboard remain
+- [ ] Update any tests that used dashboard
+- [ ] Clean up any dashboard-related utilities
+
+### Step 3.4: Plan removal
+- [ ] Schedule for v0.3.0
+- [ ] Add to CHANGELOG
+- [ ] Communicate in release notes
+
+## Phase 4: Testing (Week 2)
+
+### Unit tests
+- [ ] Test health score calculation (various priority mixes)
+- [ ] Test insight generation (all severity levels)
+- [ ] Test stats output modes (default, --full, --velocity)
+- [ ] Test board with/without health summary
+
+### Integration tests
+- [ ] Test command deprecation warnings
+- [ ] Test backward compatibility (analytics still works)
+- [ ] Test filter options work with new commands
+- [ ] Test JSON output formats
+
+### Visual regression
+- [ ] Compare new stats output (readable, not overwhelming)
+- [ ] Verify board health box layout
+- [ ] Test with various terminal widths
+- [ ] Test Unicode rendering
+
+### Documentation
+- [ ] Update README with new command examples
+- [ ] Add stats/board screenshots
+- [ ] Document all flags (--full, --simple, etc.)
+- [ ] Update AGENTS.md for AI usage
+
+### Migration guide
+- [ ] Add BREAKING CHANGES section to CHANGELOG
+- [ ] Document analytics → stats migration
+- [ ] Document dashboard → board migration
+- [ ] Provide command mapping table
+
+### Release
+- [ ] Update CHANGELOG with breaking changes
+- [ ] Tag as v0.2.0
+- [ ] Announce breaking changes clearly
+- [ ] Note: Pre-1.0, breaking changes acceptable
+
+## Implementation Details
+
+### Health Score Calculation
+
+Location: `src/utils/health.ts`
+
+```typescript
+export interface HealthMetrics {
+  score: number;           // 0-100
+  totalSpecs: number;
+  activeSpecs: number;
+  completeSpecs: number;
+  criticalIssues: string[];
+  warnings: string[];
+}
+
+export function calculateHealth(specs: SpecInfo[]): HealthMetrics {
+  // Simple: completion_rate = complete / total * 100
+  
+  let completeCount = 0;
+  let completeWeight = 0;
+  const criticalIssues: string[] = [];
+  const warnings: string[] = [];
+  
+  for (const spec of specs) {
+    const weight = priorityWeight(spec.frontmatter.priority);
+    totalWeight += weight;
+    
+    if (spec.frontmatter.status === 'complete') {
+      completeWeight += weight;
+    }
+    
+    // Detect critical issues
+    if (isCriticalOverdue(spec)) {
+      criticalIssues.push(spec.path);
+    }
+    if (isLongRunning(spec)) {
+      warnings.push(spec.path);
+    }
+  }
+  
+  return {
+    score: Math.round((completeWeight / totalWeight) * 100),
+    totalSpecs: specs.length,
+    activeSpecs: specs.filter(s => ['planned', 'in-progress'].includes(s.frontmatter.status)).length,
+    completeSpecs: specs.filter(s => s.frontmatter.status === 'complete').length,
+    criticalIssues,
+    warnings,
+  };
+}
+```
+
+### Smart Insights Algorithm
+
+Location: `src/utils/insights.ts`
+
+```typescript
+export interface Insight {
+  severity: 'critical' | 'warning' | 'info';
+  message: string;
+  specs: string[];
+}
+
+export function generateInsights(specs: SpecInfo[]): Insight[] {
+  const insights: Insight[] = [];
+  
+  // 1. Critical overdue
+  const criticalOverdue = specs.filter(s => 
+    s.frontmatter.priority === 'critical' &&
+    s.frontmatter.due && dayjs(s.frontmatter.due).isBefore(dayjs()) &&
+    s.frontmatter.status !== 'complete'
+  );
+  
+  if (criticalOverdue.length > 0) {
+    insights.push({
+      severity: 'critical',
+      message: `${criticalOverdue.length} critical specs overdue`,
+      specs: criticalOverdue.map(s => s.path),
+    });
+  }
+  
+  // 2. Long-running WIP
+  const longRunning = specs.filter(s =>
+    s.frontmatter.status === 'in-progress' &&
+    s.frontmatter.updated &&
+    dayjs().diff(dayjs(s.frontmatter.updated), 'day') > 7
+  );
+  
+  if (longRunning.length > 0) {
+    insights.push({
+      severity: 'warning',
+      message: `${longRunning.length} specs in-progress > 7 days`,
+      specs: longRunning.map(s => s.path),
+    });
+  }
+  
+  // 3. Critical not started
+  // ... more insight rules
+  
+  return insights.slice(0, 5); // Top 5 only
+}
+```
+
+### File Structure Changes
+
+**New structure:**
+```
+src/commands/
+  ├── stats.ts           # ENHANCED: Unified stats + velocity + insights
+  ├── board.ts           # ENHANCED: Kanban + health summary
+  └── ...                # analytics.ts and dashboard.ts DELETED
+
+src/utils/
+  ├── health.ts          # NEW: Health score calculation
+  ├── velocity.ts        # KEEP: Velocity metrics (used by stats)
+  ├── insights.ts        # NEW: Smart insights algorithm
+  └── spec-stats.ts      # KEEP: Basic counting/grouping
+```
+
+## Timeline
+
+- **Week 1**: Phase 1 (Stats enhancement) + Phase 2 (Board enhancement)
+- **Week 2**: Phase 3 (Dashboard removal) + Phase 4 (Testing + Release)
+
+Total: 2 weeks to v0.2.0 release

package/.next/standalone/packages/ui/dist/standalone/specs/archived/046-stats-dashboard-refactor/README.md

@@ -0,0 +1,139 @@
+---
+status: archived
+created: '2025-11-04'
+tags:
+  - ux
+  - refactor
+  - v0.2.0
+priority: high
+created_at: '2025-11-04T00:00:00Z'
+updated_at: '2025-11-11T04:26:08.942Z'
+transitions:
+  - status: in-progress
+    at: '2025-11-04T13:09:35.107Z'
+  - status: complete
+    at: '2025-11-04T13:10:54.267Z'
+  - status: archived
+    at: '2025-11-11T04:26:08.942Z'
+completed_at: '2025-11-04T13:10:54.267Z'
+completed: '2025-11-04'
+---
+
+# Stats & Dashboard Reorganization
+
+> **Status**: 📦 Archived · **Priority**: High · **Created**: 2025-11-04 · **Tags**: ux, refactor, v0.2.0
+
+**Split into sub-specs for Context Economy**
+
+## Overview
+
+Simplify and consolidate analytics/dashboard commands to create focused, PM-friendly overview tools.
+
+### The Problem
+
+Current command structure doesn't align with user needs:
+1. "Analytics" is too verbose - "Stats" is more concise
+2. Stats shows too much by default - Users need quick glance
+3. Smart insights are siloed - Should be unified  
+4. Board lacks context - Should show health metrics
+5. Dashboard is redundant - Overlaps with stats + board
+
+### Solution
+
+**Command Changes:**
+```bash
+# Before
+lean-spec analytics    # Too verbose
+lean-spec dashboard    # Separate command  
+lean-spec board        # Kanban only
+
+# After (v0.2.0)
+lean-spec stats             # Essential metrics (default)
+lean-spec stats --full      # Full analytics
+lean-spec board             # Kanban + health summary
+lean-spec board --simple    # Kanban only
+
+# REMOVED:
+lean-spec analytics    # → use `lean-spec stats`
+lean-spec dashboard    # → use `lean-spec board`
+```
+
+## Key Changes
+
+### 1. Rename analytics → stats
+- Shorter, more intuitive name
+- Matches common CLI patterns
+- Less intimidating for PMs
+
+### 2. Simplify default stats output
+- Focus on actionable insights
+- Health score at a glance
+- "Needs Attention" highlights issues
+- Prompt for `--full` if users want more
+
+### 3. Enhance board with health summary
+- Add health box at top of board
+- Show totals, completion %, alerts
+- Include velocity snapshot
+- Keep kanban columns below
+
+### 4. Remove dashboard command
+- Functionality merged into enhanced board
+- Reduces command sprawl
+- Simpler mental model
+
+## Sub-Specs
+
+Detailed information split for Context Economy:
+
+- **[DESIGN.md](./DESIGN.md)** - Full command redesign, architecture, health algorithms
+- **[IMPLEMENTATION.md](./IMPLEMENTATION.md)** - Step-by-step implementation details and execution plan
+- **[TESTING.md](./TESTING.md)** - Test strategy and validation criteria
+
+## Status
+
+✅ **COMPLETE** - All changes shipped in v0.2.0
+
+### Breaking Changes
+
+**v0.2.0 removes**:
+- `lean-spec analytics` → use `lean-spec stats`
+- `lean-spec dashboard` → use `lean-spec board`
+
+Migration path documented in CHANGELOG.
+
+### What Shipped
+
+**Phase 1: Rename analytics → stats** ✅
+- Merged analytics.ts into stats.ts
+- Removed analytics command
+- Updated all documentation
+
+**Phase 2: Simplify stats output** ✅
+- Default shows essential metrics only
+- `--full` flag for detailed view
+- Smart insights integrated
+
+**Phase 3: Enhance board** ✅
+- Health summary box at top
+- Velocity snapshot included
+- `--simple` flag for original view
+
+**Phase 4: Remove dashboard** ✅
+- Command deleted
+- Functionality available via board
+
+## Impact
+
+**Before:**
+- 4 overlapping commands (analytics, dashboard, stats, board)
+- Confusion about which to use
+- Too much detail by default
+
+**After:**
+- 2 focused commands (stats, board)
+- Clear use cases
+- PM-friendly defaults
+- Power users get `--full` flags
+
+This reorganization improved command clarity and reduced cognitive overhead for v0.2.0 launch.

package/.next/standalone/packages/ui/dist/standalone/specs/archived/046-stats-dashboard-refactor/TESTING.md

@@ -0,0 +1,328 @@
+# Testing Strategy
+
+> Part of [046-stats-dashboard-refactor](./README.md)
+
+## Stats Command Tests
+
+### Default output (simplified)
+- [ ] Shows only essential metrics (not overwhelming)
+- [ ] "Needs Attention" section highlights issues
+- [ ] Velocity summary shows 3 key metrics
+- [ ] Prompts user for `--full` if they want more
+- [ ] Renders in < 200ms for 50 specs
+
+### Full output
+- [ ] `lean-spec stats --full` shows all sections
+- [ ] Equivalent to old `lean-spec analytics` output
+- [ ] Stats + Timeline + Velocity all present
+- [ ] No information loss from analytics
+
+### Focus modes
+- [ ] `lean-spec stats --velocity` shows only velocity
+- [ ] `lean-spec stats --timeline` shows only timeline/activity
+- [ ] Filters work (--tag, --assignee)
+
+### Smart insights
+- [ ] Detects critical overdue specs
+- [ ] Flags long-running WIP (> 7 days)
+- [ ] Shows top 5 issues only
+- [ ] Empty when no issues (positive message)
+
+## Board Command Tests
+
+### Health summary
+- [ ] Shows at top of board output
+- [ ] Includes totals, health score, alerts, velocity
+- [ ] Doesn't break kanban columns layout
+- [ ] Box renders correctly (Unicode characters)
+
+### Health score accuracy
+- [ ] Simple completion rate (not weighted)
+- [ ] 0% when no specs complete
+- [ ] 100% when all complete
+- [ ] Reflects project health intuitively
+
+### Options
+- [ ] `lean-spec board` shows default view with health
+- [ ] `lean-spec board --simple` shows kanban only
+- [ ] `lean-spec board --health-only` shows health summary only
+- [ ] All filter options work (--tag, --assignee, --status)
+
+## Command Removal Tests
+
+### Analytics command
+- [ ] Command no longer exists
+- [ ] `lean-spec analytics` shows "unknown command" error
+- [ ] Error message suggests `lean-spec stats` instead
+- [ ] Help text doesn't mention analytics
+
+### Dashboard command
+- [ ] Command no longer exists
+- [ ] `lean-spec dashboard` shows "unknown command" error
+- [ ] Error message suggests `lean-spec board` instead
+- [ ] Help text doesn't mention dashboard
+
+## Breaking Changes (v0.2.0)
+
+### Expected behavior
+- [ ] `lean-spec analytics` fails with helpful error
+- [ ] `lean-spec dashboard` fails with helpful error
+- [ ] `lean-spec stats` works as replacement
+- [ ] `lean-spec board` works as replacement
+- [ ] JSON output formats compatible where applicable
+
+### Existing workflows
+- [ ] All `lean-spec analytics` scripts still work
+- [ ] JSON output format unchanged
+- [ ] Filter options unchanged
+- [ ] No breaking changes in v0.2.0
+
+## Performance Tests
+
+- [ ] `lean-spec stats` < 200ms for 50 specs
+- [ ] `lean-spec stats --full` < 500ms for 100 specs
+- [ ] `lean-spec board` < 300ms for 50 specs
+- [ ] Health calculation < 50ms
+- [ ] Insight generation < 50ms
+
+## Edge Cases
+
+- [ ] Empty project (helpful message)
+- [ ] No critical issues (positive message)
+- [ ] All specs complete (celebrate!)
+- [ ] Very long spec names don't break layout
+- [ ] Missing velocity data (graceful degradation)
+
+## Test Coverage Requirements
+
+### Unit Tests
+
+**Health Score Calculation:**
+```typescript
+describe('calculateHealth', () => {
+  it('returns 0% for no complete specs', () => {
+    const specs = [
+      createSpec({ status: 'planned' }),
+      createSpec({ status: 'in-progress' }),
+    ];
+    const health = calculateHealth(specs);
+    expect(health.score).toBe(0);
+  });
+
+  it('returns 100% for all complete specs', () => {
+    const specs = [
+      createSpec({ status: 'complete' }),
+      createSpec({ status: 'complete' }),
+    ];
+    const health = calculateHealth(specs);
+    expect(health.score).toBe(100);
+  });
+
+  it('calculates partial completion correctly', () => {
+    const specs = [
+      createSpec({ status: 'complete' }),
+      createSpec({ status: 'in-progress' }),
+      createSpec({ status: 'planned' }),
+    ];
+    const health = calculateHealth(specs);
+    expect(health.score).toBe(33); // 1/3 complete
+  });
+});
+```
+
+**Smart Insights:**
+```typescript
+describe('generateInsights', () => {
+  it('detects critical overdue specs', () => {
+    const specs = [
+      createSpec({ 
+        priority: 'critical', 
+        due: '2025-11-01', 
+        status: 'in-progress' 
+      }),
+    ];
+    const insights = generateInsights(specs);
+    expect(insights[0].severity).toBe('critical');
+    expect(insights[0].message).toContain('overdue');
+  });
+
+  it('detects long-running WIP', () => {
+    const specs = [
+      createSpec({ 
+        status: 'in-progress',
+        updated: '2025-10-20' // > 7 days ago
+      }),
+    ];
+    const insights = generateInsights(specs);
+    expect(insights[0].severity).toBe('warning');
+    expect(insights[0].message).toContain('in-progress > 7 days');
+  });
+
+  it('limits to top 5 insights', () => {
+    const specs = Array(10).fill(null).map(() => 
+      createSpec({ priority: 'critical', due: '2025-11-01', status: 'planned' })
+    );
+    const insights = generateInsights(specs);
+    expect(insights.length).toBeLessThanOrEqual(5);
+  });
+});
+```
+
+### Integration Tests
+
+**Stats Command:**
+```typescript
+describe('stats command', () => {
+  it('shows simplified output by default', async () => {
+    const output = await runCommand('lean-spec stats');
+    expect(output).toContain('📊 Spec Stats');
+    expect(output).toContain('Needs Attention');
+    expect(output).toContain('Use `lean-spec stats --full` for detailed analytics');
+  });
+
+  it('shows full output with --full flag', async () => {
+    const output = await runCommand('lean-spec stats --full');
+    expect(output).toContain('Status');
+    expect(output).toContain('Priority');
+    expect(output).toContain('Timeline');
+    expect(output).toContain('Velocity');
+  });
+
+  it('supports filter flags', async () => {
+    const output = await runCommand('lean-spec stats --tag=bug');
+    expect(output).toContain('Filtered');
+  });
+});
+```
+
+**Board Command:**
+```typescript
+describe('board command', () => {
+  it('shows health summary by default', async () => {
+    const output = await runCommand('lean-spec board');
+    expect(output).toContain('Project Health');
+    expect(output).toContain('health');
+    expect(output).toContain('Velocity');
+  });
+
+  it('hides health summary with --simple', async () => {
+    const output = await runCommand('lean-spec board --simple');
+    expect(output).not.toContain('Project Health');
+    expect(output).toContain('📅 Planned');
+  });
+
+  it('shows only health with --health-only', async () => {
+    const output = await runCommand('lean-spec board --health-only');
+    expect(output).toContain('Project Health');
+    expect(output).not.toContain('📅 Planned');
+  });
+});
+```
+
+## Success Criteria
+
+### User Experience
+- [ ] PMs can check project health in < 5 seconds (`lean-spec board`)
+- [ ] Quick stats check takes < 10 seconds (`lean-spec stats`)
+- [ ] Deep dive available when needed (`lean-spec stats --full`)
+- [ ] Clear error messages for removed commands
+
+### Technical
+- [ ] Breaking changes clearly documented in CHANGELOG
+- [ ] All tests pass
+- [ ] Performance < 300ms for typical projects
+- [ ] Clean codebase (no deprecated code)
+
+### Adoption
+- [ ] Beta testers prefer new commands
+- [ ] Positive feedback on simplified output
+- [ ] No confusion about command naming
+- [ ] Documentation clear and helpful
+
+## Visual Regression Tests
+
+### Stats Output Comparison
+
+**Before (analytics):**
+```
+Status:
+  Planned: 5
+  In Progress: 10
+  Complete: 20
+
+Priority:
+  Critical: 2
+  High: 8
+  Medium: 15
+  Low: 10
+
+Tags:
+  bug: 5
+  feature: 10
+  ... (long list)
+
+Timeline: (14-day chart)
+
+Velocity: (full breakdown)
+```
+
+**After (stats default):**
+```
+📊 Spec Stats
+
+📈 Overview
+  Total: 35 · Active: 15 · Complete: 20 · Health: 73% ✓
+
+⚠️  Needs Attention
+  • 2 critical overdue
+  • 5 specs WIP > 7 days
+
+🚀 Velocity: 5.2d avg, 2.8/wk ↑
+
+💡 Use `lean-spec stats --full` for detailed analytics
+```
+
+### Board Health Box Layout
+
+**Health Summary Box:**
+```
+╔══════════════════════════════════════════════════════════╗
+║  Project Health                                          ║
+║  42 total · 20 active · 15 complete · 73% health         ║
+║  ⚠️  2 critical overdue · 5 specs WIP > 7 days           ║
+║  🚀 Velocity: 5.2d avg cycle · 2.8/wk throughput         ║
+╚══════════════════════════════════════════════════════════╝
+```
+
+**Verify:**
+- [ ] Box characters render correctly
+- [ ] Content fits within box width
+- [ ] Emojis align properly
+- [ ] No layout breaks on narrow terminals
+- [ ] Graceful handling of long spec names
+
+## Performance Benchmarks
+
+| Command | Specs | Target | Measured |
+|---------|-------|--------|----------|
+| `lean-spec stats` | 50 | < 200ms | ___ms |
+| `lean-spec stats --full` | 100 | < 500ms | ___ms |
+| `lean-spec board` | 50 | < 300ms | ___ms |
+| Health calc | 100 | < 50ms | ___ms |
+| Insights gen | 100 | < 50ms | ___ms |
+
+## Test Automation
+
+**CI/CD Pipeline:**
+1. Run unit tests on every commit
+2. Run integration tests on PR
+3. Run performance tests on main branch
+4. Generate coverage report (target: > 80%)
+
+**Pre-release Checklist:**
+- [ ] All tests pass
+- [ ] Performance benchmarks met
+- [ ] Visual regression tests reviewed
+- [ ] Documentation updated
+- [ ] Migration guide ready
+- [ ] Beta testers feedback incorporated