@leanspec/ui 0.2.7 → 0.2.9-dev.20251205030455

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

@@ -1,241 +0,0 @@
-# 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

@@ -1,139 +0,0 @@
----
-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

@@ -1,328 +0,0 @@
-# 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