@leanspec/ui 0.2.7-dev.20251128020042 → 0.2.8

package/.next/standalone/packages/ui/dist/standalone/specs/045-unified-dashboard/DESIGN.md

@@ -0,0 +1,382 @@
+# Design: Unified Analytics & Dashboard
+
+## Architecture
+
+### File Structure
+```
+src/commands/
+  ├── dashboard.ts       # NEW: Comprehensive overview
+  ├── stats.ts          # ENHANCED: Merge timeline logic
+  ├── list.ts           # KEEP: Detailed browsing
+  ├── board.ts          # KEEP: Kanban view
+  ├── gantt.ts          # KEEP: Timeline planning
+  ├── deps.ts           # KEEP: Dependencies
+  └── timeline.ts       # DEPRECATE → merge into stats.ts
+```
+
+### Code Reuse
+- Extract shared visualization helpers to `utils/vis.ts`:
+  - `createBar(count, max, width, char)` - reusable bar charts
+  - `formatMetric(label, value, color)` - consistent metric display
+  - `renderSection(title, content)` - section formatting
+- Dashboard composes high-level summaries from other commands
+- Stats command owns all analytics logic (including timeline)
+
+### Performance
+- Dashboard: Single `loadAllSpecs()` for all sections
+- Smart caching between dashboard and other commands
+- Lazy rendering (skip empty sections)
+- Target: < 300ms for 100 specs
+
+## Part 0: Timestamp Tracking (Foundation)
+
+### Problem
+Current tracking only stores dates (YYYY-MM-DD), not timestamps:
+- Can't calculate precise cycle times
+- Can't distinguish specs completed same day
+- Loses granularity for velocity analysis
+
+### Solution
+Add ISO 8601 timestamp fields alongside date fields
+
+### Frontmatter Schema Update
+```yaml
+---
+status: in-progress
+created: '2025-11-04'           # Keep for human readability
+created_at: '2025-11-04T14:30:00Z'  # NEW: Precise timestamp
+updated: '2025-11-04'           # Keep for human readability  
+updated_at: '2025-11-04T16:45:00Z'  # NEW: Precise timestamp
+completed_at: '2025-11-05T10:15:00Z'  # NEW: When status changed to complete
+
+# Status transition history (optional, for advanced velocity)
+transitions:
+  - status: planned
+    at: '2025-11-04T14:30:00Z'
+  - status: in-progress
+    at: '2025-11-04T15:00:00Z'
+  - status: complete
+    at: '2025-11-05T10:15:00Z'
+---
+```
+
+### Migration Strategy
+- Add new `*_at` fields alongside existing date fields
+- Auto-generate timestamps on spec creation/updates
+- Existing specs: infer timestamps from dates (use midnight UTC)
+- Keep date fields for backward compatibility
+- Make timestamps optional (graceful degradation)
+
+### Implementation
+```typescript
+// In frontmatter.ts
+export interface SpecFrontmatter {
+  // Existing date fields (keep for compatibility)
+  created: string;        // YYYY-MM-DD
+  updated?: string;       // YYYY-MM-DD
+  completed?: string;     // YYYY-MM-DD
+  
+  // NEW: Precise timestamps
+  created_at?: string;    // ISO 8601
+  updated_at?: string;    // ISO 8601
+  completed_at?: string;  // ISO 8601
+  
+  // NEW: Status transition history (optional)
+  transitions?: Array<{
+    status: SpecStatus;
+    at: string;  // ISO 8601
+  }>;
+}
+
+// Auto-generate timestamps on updates
+export function enrichWithTimestamps(
+  data: SpecFrontmatter, 
+  previousData?: SpecFrontmatter
+): void {
+  const now = new Date().toISOString();
+  
+  // Set created_at if missing
+  if (!data.created_at) {
+    data.created_at = data.created 
+      ? `${data.created}T00:00:00Z`  // Infer from date
+      : now;
+  }
+  
+  // Update updated_at on any change
+  if (previousData) {
+    data.updated_at = now;
+  }
+  
+  // Set completed_at when status changes to complete
+  if (data.status === 'complete' && 
+      previousData?.status !== 'complete' &&
+      !data.completed_at) {
+    data.completed_at = now;
+    data.completed = new Date().toISOString().split('T')[0];
+  }
+  
+  // Track transition (optional)
+  if (previousData && data.status !== previousData.status) {
+    if (!data.transitions) data.transitions = [];
+    data.transitions.push({
+      status: data.status,
+      at: now
+    });
+  }
+}
+```
+
+## Part 1: Unified Analytics Command
+
+### Command Structure
+Keep `lean-spec stats` (backward compatible), enhanced with velocity modes:
+
+```bash
+lean-spec stats              # Default: current stats (unchanged)
+lean-spec stats --timeline   # Add timeline section
+lean-spec stats --history    # Full historical view (current timeline command)
+lean-spec stats --velocity   # NEW: Cycle time & throughput analysis
+lean-spec stats --all        # Everything (stats + timeline + velocity)
+```
+
+### Velocity Section Output
+```
+📊 Velocity Metrics (Last 30 Days)
+
+Cycle Time (Created → Completed)
+  Average:  5.2 days  ████████░░░░░░░░░░  (target: 7 days)
+  Median:   4.0 days
+  P50-P95:  2-12 days
+
+Stage Duration
+  Planned:       2.1 days  ████░░░░░░░░░░░░░░░░
+  In-Progress:   3.5 days  ██████░░░░░░░░░░░░░░
+  
+Throughput
+  Last 7 days:   3 specs  ████████████░░░░░░░░  (up from 2)
+  Last 30 days: 12 specs  ████████████████████  (target: 10)
+  
+Work in Progress
+  Current WIP:   5 specs  (recommended: < 5)
+  Average WIP:   4.2 specs
+
+Velocity Trend
+  Week 1:  ████░░  2 specs
+  Week 2:  ████░░  2 specs  
+  Week 3:  ██████  3 specs  ↑ improving
+  Week 4:  ██████  3 specs
+```
+
+### Implementation Details
+- Calculate cycle time: `completed_at - created_at`
+- Track stage durations from transitions array
+- Show percentiles (P50, P90, P95) for cycle time distribution
+- Compare to targets (configurable in .lean-spec/config.json)
+- Show trends (last 4 weeks)
+
+## Part 2: Dashboard Command (NOT IMPLEMENTED)
+
+> **Decision**: Dashboard command was not implemented. Enhanced `stats` and `board` commands provide the needed functionality without adding CLI complexity.
+
+### Original Design (for reference):
+
+### Command
+`lean-spec` (no args) or `lean-spec dashboard`
+
+### Purpose
+Quick project health overview combining:
+- Summary metrics (from stats)
+- Key activity indicators (from timeline)  
+- Active work snapshot (from board)
+- Smart insights (what needs attention)
+
+### Dashboard Sections
+
+```
+╔══════════════════════════════════════════════════════════╗
+║  LeanSpec Dashboard · lean-spec                          ║
+╚══════════════════════════════════════════════════════════╝
+
+📊 Project Health
+  Total: 42 specs · 15 in-progress · 20 complete · 5 planned · 2 archived
+  Priority: 🔴 2 critical · 🟠 5 high · 🟡 10 medium · 🟢 3 low
+
+⚠️  Needs Attention
+  • 2 specs overdue (spec-001, spec-003)
+  • 3 critical priority specs still planned
+
+📈 Recent Activity (Last 14 Days)
+  Created:   ████████░░░░░░  8 specs
+  Completed: ████░░░░░░░░░░  4 specs
+  Velocity:  2.8 specs/week ↑ trending up
+  
+⏳ In Progress (5)
+  🔴 spec-042-mcp-error-handling     @alice  #bug #critical  (3d)
+  🟠 spec-045-unified-dashboard      @bob    #ux #launch     (2d)
+  🟡 spec-026-init-pattern           @alice  #feature       (8d ⚠️ long)
+  
+🏷️  Top Tags
+  launch (12) · feature (8) · bug (5) · docs (4)
+
+🚀 Velocity Summary
+  Avg Cycle Time:  5.2 days (target: 7d)
+  Throughput:      2.8 specs/week ↑
+  WIP:             5 specs (healthy)
+
+─────────────────────────────────────────────────────────────
+💡 Commands: lean-spec list | lean-spec board | lean-spec stats --velocity
+```
+
+### Smart Insights
+- Show overdue specs first
+- Highlight critical priority items
+- Show specs assigned to user (if `--assignee` or git config)
+- Suggest next actions
+
+### Display Options
+```bash
+lean-spec                      # Full dashboard
+lean-spec dashboard            # Explicit
+lean-spec --compact            # Minimal (just health + attention)
+lean-spec --expand-active      # Show all in-progress (not just top 5)
+lean-spec --json               # JSON for tooling
+```
+
+### vs. Individual Commands
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `lean-spec` | Quick overview | Daily standup, "what's happening?" |
+| `lean-spec list` | Browse/search specs | Find specific spec, apply filters |
+| `lean-spec board` | Kanban workflow | Sprint planning, status changes |
+| `lean-spec gantt` | Timeline planning | Schedule work, see deadlines |
+| `lean-spec stats` | Deep analytics | Metrics review, team performance |
+
+## Command Organization Philosophy
+
+### PM Commands (keep separate - distinct workflows)
+- `list` - Browse/search/filter specs
+- `board` - Kanban workflow (status changes)
+- `deps` - Dependency visualization
+- `gantt` - Timeline planning (schedule work)
+
+### Analytics Commands (consolidate - overlapping purpose)
+- `stats` - Current metrics + historical trends
+- `timeline` - Redundant with stats (merge in)
+
+### Dashboard (new - quick overview)
+- `lean-spec` - Glanceable project health
+- Entry point for daily use
+- Directs to PM commands for detail
+
+This organization makes sense because:
+- PM commands have distinct UX patterns (kanban, graph, gantt chart)
+- Analytics commands both show "numbers over time"
+- Dashboard is a meta-view (doesn't replace PM commands)
+
+## Why Merge Stats + Timeline?
+
+### Current Redundancy
+- Both load all specs
+- Both show date-based trends
+- Both have bar charts
+- Both support same filters
+- Both output similar visualizations
+
+### Differences
+- `stats` - emphasizes current state (status, priority, tags)
+- `timeline` - emphasizes historical change (created/completed over time)
+
+### Solution
+Make `stats` the comprehensive analytics command:
+- Default: current stats (backward compatible)
+- `--timeline`: add timeline section
+- `--history`: timeline-focused view
+
+## Smart Insights Algorithm
+
+"Needs Attention" section prioritizes:
+
+1. **Overdue & Critical** - highest urgency
+   ```typescript
+   spec.frontmatter.due < today &&
+   spec.frontmatter.status != 'complete' &&
+   spec.frontmatter.priority == 'critical'
+   ```
+
+2. **Overdue & In-Progress** - likely blockers
+   ```typescript
+   spec.frontmatter.due < today &&
+   spec.frontmatter.status == 'in-progress'
+   ```
+
+3. **Critical & Planned** - not started yet
+   ```typescript
+   spec.frontmatter.priority == 'critical' &&
+   spec.frontmatter.status == 'planned'
+   ```
+
+4. **Long-running In-Progress** - potential stalls
+   ```typescript
+   spec.frontmatter.status == 'in-progress' &&
+   daysSince(spec.frontmatter.updated) > 14
+   ```
+
+Show top 3-5 items max, then "and N more need attention"
+
+## Why `lean-spec` Should Default to Dashboard
+
+### Current behavior
+`lean-spec` shows help
+
+### Proposed
+`lean-spec` shows dashboard
+
+### Reasoning
+- Help still accessible via `lean-spec --help`
+- Dashboard is most frequently needed view
+- Matches modern CLI patterns (gh, git status at root)
+- Better new user experience (show, don't tell)
+- OpenSpec uses `openspec view` as primary command
+
+### User flow
+```bash
+cd my-project
+lean-spec                    # Quick overview (dashboard)
+# See something interesting...
+lean-spec list --tag bug     # Drill down
+lean-spec board              # Change status
+lean-spec                    # Check dashboard again
+```
+
+## Velocity Configuration
+
+Add to `.lean-spec/config.json`:
+
+```json
+{
+  "velocity": {
+    "enabled": true,
+    "targets": {
+      "cycle_time_days": 7,
+      "throughput_per_month": 10,
+      "max_wip": 5
+    },
+    "alerts": {
+      "long_running_days": 14,
+      "overdue_critical": true
+    },
+    "tracking": {
+      "use_timestamps": true,
+      "track_transitions": true
+    }
+  }
+}
+```
+
+### Defaults (if not configured)
+- Cycle time target: 7 days
+- Max WIP: 5 concurrent specs
+- Long-running threshold: 14 days
+- Timestamps: auto-enabled
+- Transitions: optional (off by default)

package/.next/standalone/packages/ui/dist/standalone/specs/045-unified-dashboard/IMPLEMENTATION.md

@@ -0,0 +1,144 @@
+# Implementation Plan: Unified Dashboard
+
+## Part 0: Timestamp Tracking (Week 1)
+
+Foundation for velocity metrics:
+
+- [ ] Update `SpecFrontmatter` interface with timestamp fields
+  - [ ] Add `created_at?: string` (ISO 8601)
+  - [ ] Add `updated_at?: string` (ISO 8601)
+  - [ ] Add `completed_at?: string` (ISO 8601)
+  - [ ] Add `transitions?: Array<{status, at}>` (optional)
+- [ ] Create `enrichWithTimestamps()` helper
+  - [ ] Auto-generate `created_at` on spec creation
+  - [ ] Update `updated_at` on any frontmatter change
+  - [ ] Set `completed_at` when status → complete
+  - [ ] Track status transitions (optional)
+- [ ] Update `create.ts` to set initial timestamps
+- [ ] Update `update.ts` to maintain timestamps
+- [ ] Migration: Infer timestamps from dates for existing specs
+- [ ] Add tests for timestamp generation logic
+
+## Part 1: Unified Analytics (Week 1-2)
+
+### Part A: Merge timeline into stats
+- [ ] Create `utils/vis.ts` with shared visualization helpers
+  - [ ] `createBar(count, max, width, char)` - reusable bar charts
+  - [ ] `formatMetric(label, value, color)` - metric formatting
+  - [ ] Date range helpers
+- [ ] Enhance `stats.ts` with timeline functionality
+  - [ ] Add `--timeline` flag (show timeline section after stats)
+  - [ ] Add `--history` flag (full timeline focus, like current timeline)
+  - [ ] Add `--velocity` flag (NEW: cycle time analysis)
+  - [ ] Add `--all` flag (everything combined)
+  - [ ] Keep default behavior (current stats only)
+- [ ] Extract bar chart logic from both commands to `utils/vis.ts`
+- [ ] Update tests for enhanced stats command
+- [ ] Mark `timeline.ts` as deprecated (but keep working)
+
+### Part B: Velocity Calculations
+- [ ] Create `utils/velocity.ts` with velocity analysis
+  - [ ] `calculateCycleTime(spec)` - created_at → completed_at
+  - [ ] `calculateStageDuration(spec, status)` - time in each status
+  - [ ] `calculateThroughput(specs, period)` - specs per week/month
+  - [ ] `calculateWIP(specs, date)` - active specs at point in time
+  - [ ] `calculatePercentiles(times, [50, 90, 95])` - distribution
+- [ ] Implement velocity section rendering
+  - [ ] Cycle time: avg, median, P50-P95
+  - [ ] Stage durations with bars
+  - [ ] Throughput with trend indicators
+  - [ ] WIP metrics
+  - [ ] Weekly velocity trend (last 4 weeks)
+- [ ] Add configurable targets in config.json
+  - [ ] `velocity.target_cycle_time: 7` (days)
+  - [ ] `velocity.target_throughput: 10` (specs/month)
+  - [ ] `velocity.max_wip: 5` (concurrent specs)
+
+### Part C: Testing
+- [ ] Test `lean-spec stats` (default behavior unchanged)
+- [ ] Test `lean-spec stats --timeline` (integrated view)
+- [ ] Test `lean-spec stats --history` (full timeline)
+- [ ] Test `lean-spec stats --velocity` (cycle time analysis)
+- [ ] Test `lean-spec stats --all` (comprehensive)
+- [ ] Test velocity calculations with mock data
+- [ ] Test graceful degradation (specs without timestamps)
+- [ ] Verify backward compatibility
+
+## Part 2: Dashboard Command (Week 2)
+
+### Part A: Core dashboard implementation
+- [ ] Create `src/commands/dashboard.ts`
+- [ ] Implement Summary section (project health)
+- [ ] Implement Needs Attention section (smart insights)
+- [ ] Implement Recent Activity section (14-day sparkline + velocity)
+- [ ] Implement In Progress section (top active specs with age)
+- [ ] Implement Quick Stats section (tags, assignees)
+- [ ] Implement Velocity Summary section (cycle time, throughput, WIP)
+- [ ] Add helpful footer with command hints
+
+### Part B: CLI integration
+- [ ] Make `lean-spec` (no args) default to dashboard
+- [ ] Add explicit `lean-spec dashboard` command
+- [ ] Support all filter options (--tag, --status, etc.)
+- [ ] Add display options (--compact, --expand-active)
+- [ ] Add JSON output mode (--json)
+
+### Part C: Smart insights
+- [ ] Detect overdue specs (due < today, status != complete)
+- [ ] Highlight critical priority specs
+- [ ] Show user's assigned work (from git config or --assignee)
+- [ ] Flag long-running in-progress specs (> 14 days)
+- [ ] Identify velocity bottlenecks (slow stages)
+- [ ] Suggest next actions based on state
+
+## Phase 3: Testing & Polish (Week 2-3)
+
+### Unit tests
+- [ ] Dashboard section rendering
+- [ ] Smart insights logic
+- [ ] Filter application
+- [ ] JSON output structure
+
+### Integration tests
+- [ ] Empty project (show helpful init message)
+- [ ] Small project (< 10 specs)
+- [ ] Medium project (10-50 specs)
+- [ ] Large project (100+ specs)
+- [ ] With all filter combinations
+- [ ] With display options
+
+### Visual regression
+- [ ] Compare dashboard output across sizes
+- [ ] Verify Unicode characters render correctly
+- [ ] Test color output (with/without color support)
+- [ ] Test terminal width handling
+
+## Phase 4: Documentation (Week 3)
+
+### README updates
+- [ ] Feature dashboard as primary command
+- [ ] Add dashboard screenshot/GIF
+- [ ] Update command reference table
+- [ ] Show dashboard → drill-down workflow
+
+### AGENTS.md updates
+- [ ] Update AI instructions to use dashboard first
+- [ ] Document `lean-spec stats --timeline` pattern
+- [ ] Update command examples
+
+### Help text
+- [ ] Update `lean-spec --help` to show dashboard first
+- [ ] Add examples to `lean-spec dashboard --help`
+- [ ] Update `lean-spec stats --help` with new flags
+
+## Phase 5: Migration & Deprecation (v0.3.0)
+
+### Add deprecation warnings
+- [ ] `lean-spec timeline` → "Use 'lean-spec stats --history' instead"
+- [ ] Show migration hints in output
+- [ ] Update CHANGELOG with deprecation notice
+
+### Remove in v0.4.0
+- [ ] Delete `src/commands/timeline.ts`
+- [ ] Remove from CLI registration
+- [ ] Archive any timeline-specific tests

package/.next/standalone/packages/ui/dist/standalone/specs/045-unified-dashboard/RATIONALE.md

@@ -0,0 +1,146 @@
+# Rationale: Why Velocity Tracking Matters for SDD
+
+## The SDD Adoption Challenge
+
+Teams wonder: "Does writing specs slow us down?"
+- Need data to prove SDD value, not just gut feel
+- Velocity metrics provide objective measurement
+- Makes SDD adoption measurable and defensible
+
+## What Velocity Reveals
+
+### 1. Cycle Time (Created → Completed)
+- **Shorter** = specs help clarify work faster
+- **Longer** = specs might be too detailed or not actionable
+- **Target**: < 7 days (configurable per team)
+
+### 2. Stage Duration (Time in each status)
+- **Long "Planned"** = analysis paralysis or unclear specs
+- **Long "In-Progress"** = implementation blockers or scope creep
+- **Helps identify process bottlenecks**
+
+### 3. Throughput (Specs completed per period)
+- **Increasing** = team getting better with SDD
+- **Stable** = sustainable pace
+- **Decreasing** = investigate blockers
+
+### 4. WIP Limits (Concurrent active specs)
+- **Too high (>5)** = context switching overhead
+- **Too low (<2)** = might not be using SDD effectively
+- **Kanban principle**: limit WIP to improve flow
+
+## Using Velocity to Improve
+
+- **Weekly review**: "Why did spec-X take 12 days?"
+- **Identify patterns**: Do certain types take longer?
+- **Adjust**: Simplify spec templates, add more detail, etc.
+- **Prove ROI**: "Our cycle time dropped 40% after adopting SDD"
+
+## Why Velocity is Critical for SDD
+
+Velocity is not just a metric—it's the feedback loop that makes SDD a learning system:
+
+1. **Proves whether specs accelerate or slow down development**
+2. **Identifies workflow bottlenecks** (long planned→in-progress, or in-progress→complete)
+3. **Tracks team learning curve with SDD over time**
+4. **Provides data for continuous improvement**
+5. **Makes SDD adoption measurable and defensible to stakeholders**
+
+## Timestamp vs Date Trade-offs
+
+| Approach | Pros | Cons |
+|----------|------|------|
+| **Date only** (current) | Simple, human-readable | Imprecise, can't distinguish same-day events |
+| **Timestamp** (proposed) | Precise, enables velocity metrics | More complex, harder to edit manually |
+| **Hybrid** (this spec) | Best of both: human dates + precise timestamps | Requires both fields, migration needed |
+
+### Decision: Hybrid Approach
+- Keep `created: YYYY-MM-DD` (human-readable, required)
+- Add `created_at: ISO8601` (precise, auto-generated)
+- Graceful degradation: velocity works with dates if timestamps missing
+- Migration: infer timestamps from dates for existing specs
+
+## Dashboard Design Inspiration
+
+### OpenSpec's Approach
+```typescript
+// OpenSpec view.ts structure
+- Summary (specs count, changes count, task progress)
+- Active Changes (with progress bars)
+- Completed Changes
+- Specifications (sorted by requirement count)
+- Footer (helpful hints)
+```
+
+### Our Adaptation
+```typescript
+// LeanSpec dashboard.ts structure
+- Project Health (total, status, priority)
+- Needs Attention (smart insights: overdue, critical)
+- Recent Activity (14-day sparkline)
+- In Progress (top 5 active specs)
+- Quick Stats (top tags, assignees)
+- Footer (command hints)
+```
+
+### Key Differences
+- We focus on "needs attention" (actionable)
+- We don't have "changes" concept (simpler)
+- We emphasize priority more (critical path)
+- We show assignee workload
+
+## Migration for Existing Users
+
+### v0.2.0 Release Notes
+```markdown
+## New: Dashboard Command
+
+Run `lean-spec` (no arguments) to see a comprehensive project overview!
+
+The dashboard combines summary stats, recent activity, and active work
+into a single glanceable view. Perfect for daily standup or checking
+project health.
+
+Individual commands (list, board, gantt, stats) remain unchanged.
+
+## Enhanced: Stats Command
+
+`lean-spec stats` now supports timeline views:
+- `lean-spec stats --timeline` - add 14-day activity
+- `lean-spec stats --history` - full historical view
+- `lean-spec stats` - current stats only (unchanged)
+
+The standalone `lean-spec timeline` command is deprecated and will be
+removed in v0.4.0. Use `lean-spec stats --history` instead.
+```
+
+## Alternatives Considered
+
+### Option A: Separate analytics command
+```bash
+lean-spec analytics           # New command
+lean-spec analytics --stats   # Current stats
+lean-spec analytics --timeline # Timeline view
+```
+- ✅ Clear namespace
+- ❌ More typing
+- ❌ Breaks backward compatibility
+
+### Option B: Enhance stats (This Spec)
+```bash
+lean-spec stats               # Current behavior (default)
+lean-spec stats --timeline    # Add timeline
+lean-spec stats --history     # Full timeline focus
+```
+- ✅ Backward compatible
+- ✅ Less typing
+- ✅ Intuitive progressive disclosure
+- ❌ Stats name doesn't perfectly fit timeline
+
+### Option C: Keep separate
+- ✅ No breaking changes
+- ❌ Redundant code
+- ❌ User confusion (which to use?)
+
+### Decision: Option B
+Best balance of compatibility and consolidation