@leanspec/ui 0.2.7-dev.20251126090633 → 0.2.7

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

@@ -0,0 +1,208 @@
+---
+status: complete
+created: '2025-11-04'
+completed: '2025-11-07'
+tags:
+  - ux
+  - visualization
+  - analytics
+  - launch
+  - v0.2.0
+priority: high
+created_at: '2025-11-04T00:00:00Z'
+updated_at: '2025-11-07T03:20:42.284Z'
+completed_at: '2025-11-07T00:00:00Z'
+transitions:
+  - status: complete
+    at: '2025-11-04T10:21:40.759Z'
+  - status: in-progress
+    at: '2025-11-06T06:55:31.151Z'
+  - status: complete
+    at: '2025-11-07T00:00:00Z'
+---
+
+# Unified Analytics & Velocity Tracking
+
+> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-04 · **Tags**: ux, visualization, analytics, launch, v0.2.0
+
+**Split into sub-specs for Context Economy** - See detailed sections below
+
+## Overview
+
+Consolidate analytics commands and add velocity tracking to measure SDD effectiveness.
+
+### What Was Built
+
+1. ✅ **Timestamp tracking** → `created_at`, `updated_at`, `completed_at`, `transitions` in frontmatter
+2. ✅ **Velocity metrics** → Cycle time, throughput, WIP tracking in `utils/velocity.ts`
+3. ✅ **Enhanced stats command** → Added `--velocity`, `--timeline`, `--full` flags
+4. ✅ **Board enhancements** → Integrated velocity summary into board view
+5. ❌ **Dashboard command** → Not implemented (functionality merged into enhanced `stats` and `board` instead)
+
+### Why Now?
+
+- v0.2.0 launch requires polished, cohesive UX
+- Analytics commands overlap in purpose (both show trends/metrics)
+- Need single entry point for "show me project health"
+- **Velocity is critical metric for SDD adoption** - proves if specs help or hinder
+
+### Before vs After
+
+**Before (v0.1.x):**
+```bash
+lean-spec stats      # Basic metrics only
+lean-spec timeline   # Separate timeline view
+lean-spec board      # Basic Kanban
+# No velocity tracking
+# No timestamp precision
+```
+
+**After (v0.2.0):**
+```bash
+# Enhanced Stats Command
+lean-spec stats              # Simplified view with insights
+lean-spec stats --timeline   # Add timeline section
+lean-spec stats --velocity   # Cycle time analysis
+lean-spec stats --full       # Everything combined
+
+# Enhanced Board Command  
+lean-spec board              # Now includes velocity summary
+
+# Timeline Command
+lean-spec timeline           # Still works (not deprecated)
+
+# Velocity tracking active
+# Precise timestamps in frontmatter
+```
+
+## Implemented Features
+
+### ✅ 1. Timestamp Tracking (Foundation)
+Precise timestamps alongside existing dates enable velocity metrics:
+- `created_at`, `updated_at`, `completed_at` (ISO 8601) - **IMPLEMENTED**
+- Optional `transitions` array for stage duration tracking - **IMPLEMENTED**
+- Backward compatible (infer from dates if missing) - **IMPLEMENTED**
+- Auto-enrichment on create/update operations - **IMPLEMENTED**
+
+### ✅ 2. Velocity Metrics
+Comprehensive velocity tracking implemented in `src/utils/velocity.ts`:
+- **Cycle Time**: Created → Completed (avg, median, P90) - **IMPLEMENTED**
+- **Lead Time**: Time in each status from transitions - **IMPLEMENTED**
+- **Throughput**: Specs/week with trend indicators - **IMPLEMENTED**
+- **WIP Tracking**: Current and historical WIP averages - **IMPLEMENTED**
+
+### ✅ 3. Enhanced Stats Command
+Completely redesigned stats command with multiple views:
+- `lean-spec stats` → New simplified view with insights (default) - **IMPLEMENTED**
+- `lean-spec stats --timeline` → Add timeline section - **IMPLEMENTED**
+- `lean-spec stats --velocity` → Show cycle time analysis - **IMPLEMENTED**
+- `lean-spec stats --full` → Everything combined (old analytics style) - **IMPLEMENTED**
+- Smart insights and completion tracking - **IMPLEMENTED**
+
+### ✅ 4. Board Command Enhancements
+Integrated velocity metrics into board view:
+- Shows velocity summary (cycle time, throughput, WIP) - **IMPLEMENTED**
+- Completion rate and project health - **IMPLEMENTED**
+
+### ❌ 5. Dashboard Command (Not Implemented)
+Decision: Instead of creating a separate dashboard command, the functionality was distributed:
+- Enhanced `stats` command provides comprehensive analytics
+- Enhanced `board` command shows velocity summary
+- This keeps the CLI simpler and more focused
+
+## Quick Reference
+
+### Command Comparison
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `lean-spec list` | Browse/search specs | Find specific spec, apply filters |
+| `lean-spec board` | Kanban workflow + velocity | Sprint planning, project health |
+| `lean-spec stats` | Comprehensive analytics | Deep metrics, velocity analysis |
+| `lean-spec timeline` | Historical trends | Activity over time |
+
+### Stats Output Examples
+
+**Simplified view (default):**
+```bash
+lean-spec stats
+# Shows: Overview, Status, Priority Focus, Needs Attention, Velocity Summary
+```
+
+**Velocity analysis:**
+```bash
+lean-spec stats --velocity
+# Shows: Cycle Time, Lead Time, Throughput, WIP metrics
+```
+
+**Full analytics:**
+```bash
+lean-spec stats --full
+# Shows: Everything combined (stats + timeline + velocity)
+```
+
+## Sub-Specs
+
+Detailed information split for Context Economy (<400 lines per file):
+
+- **[DESIGN.md](./DESIGN.md)** - Architecture, timestamp tracking, command structure
+- **[RATIONALE.md](./RATIONALE.md)** - Why velocity matters, design decisions, alternatives
+- **[IMPLEMENTATION.md](./IMPLEMENTATION.md)** - Step-by-step implementation plan with phases
+- **[TESTING.md](./TESTING.md)** - Comprehensive test strategy and success criteria
+- **[ACTUAL-IMPLEMENTATION.md](./ACTUAL-IMPLEMENTATION.md)** - Final implementation details and outcomes
+
+## Success Criteria (Achieved)
+
+**✅ User Experience:**
+- Stats command now provides clear project insights with simplified default view
+- Needs Attention section highlights critical issues
+- Velocity metrics prove SDD effectiveness
+- No breaking changes for existing users
+
+**✅ Technical:**
+- Fast render performance with single spec load
+- Backward compatible (old stats behavior available with `--full`)
+- Clean separation: velocity.ts, completion.ts, insights.ts utilities
+- Comprehensive test coverage
+
+**✅ Business:**
+- Velocity metrics demonstrate SDD value objectively
+- Enhanced board/stats commands improve v0.2.0 launch demo
+- Clear analytics for teams to track improvement
+
+## Dependencies
+
+None - standalone feature for v0.2.0
+
+## Implementation Notes
+
+### Why Velocity Metrics Matter
+
+**Velocity is SDD's feedback loop:**
+- Proves whether specs accelerate or slow development
+- Identifies workflow bottlenecks
+- Tracks team learning curve  
+- Makes SDD adoption measurable
+- Provides objective data for process improvement
+
+### Design Decisions
+
+**Why no separate dashboard command?**
+- Decided against `lean-spec` defaulting to dashboard (keeps help accessible)
+- Enhanced `stats` and `board` commands provide comprehensive views
+- Simpler CLI surface area (fewer commands to learn)
+- Functionality distributed where it makes most sense
+
+**Why keep timeline command?**
+- Originally planned for deprecation
+- Decided to keep it as dedicated historical view
+- No user confusion since stats/timeline serve different use cases
+- No breaking changes needed
+
+### Future Enhancements
+
+- Custom velocity targets via config
+- More granular lead time tracking (by spec type/priority)
+- Velocity trend predictions
+- Export capabilities (JSON, CSV)
+- Integration with CI/CD for automated tracking

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

@@ -0,0 +1,182 @@
+# Testing Strategy: Unified Dashboard
+
+## Part 0: Timestamp Tracking Tests
+
+### Timestamp Generation
+- [ ] New spec gets `created_at` set automatically
+- [ ] `updated_at` updates on any frontmatter change
+- [ ] Status change to complete sets `completed_at`
+- [ ] Transitions array tracks status changes (if enabled)
+
+### Migration & Compatibility
+- [ ] Existing specs without timestamps still work
+- [ ] Timestamps inferred from dates (midnight UTC)
+- [ ] Date fields still required (backward compat)
+- [ ] Graceful degradation when timestamps missing
+
+### Edge Cases
+- [ ] Spec created and completed same day (timestamps differ)
+- [ ] Manual timestamp editing preserved
+- [ ] Timezone handling consistent (UTC)
+
+## Part 1: Enhanced Stats Command Tests
+
+### Backward Compatibility
+- [ ] `lean-spec stats` outputs same format as before (no breaking changes)
+- [ ] `lean-spec stats --json` matches existing JSON schema
+- [ ] All existing filter options work (--tag, --assignee, --priority)
+
+### New Timeline Integration
+- [ ] `lean-spec stats --timeline` adds timeline section after stats
+- [ ] `lean-spec stats --history` shows full historical view
+- [ ] `lean-spec stats --velocity` shows cycle time analysis
+- [ ] `lean-spec stats --all` combines everything
+- [ ] Timeline data matches previous `lean-spec timeline` output
+
+### Velocity Calculations
+- [ ] Cycle time accurate (created_at → completed_at)
+- [ ] Stage durations sum correctly
+- [ ] Throughput matches manual count
+- [ ] WIP calculation correct for any date
+- [ ] Percentiles (P50, P90, P95) accurate
+- [ ] Trend indicators (↑↓→) correct
+
+### Velocity Display
+- [ ] Shows average, median cycle time
+- [ ] Compares to configured targets
+- [ ] Stage durations visualized with bars
+- [ ] Throughput trends visible (last 4 weeks)
+- [ ] WIP stays within healthy range
+- [ ] Graceful when no completed specs yet
+
+### Edge Cases
+- [ ] Empty project shows helpful message
+- [ ] Project with no dates (no created/completed fields)
+- [ ] Filtered results still show timeline
+- [ ] Very large date ranges don't break layout
+
+## Part 2: Dashboard Command Tests
+
+### Project States
+
+#### Empty Project
+- [ ] Shows "No specs found" with init hint
+- [ ] No sections rendered (clean state)
+- [ ] Suggests `lean-spec init` to get started
+
+#### Small Project (< 10 specs)
+- [ ] All in-progress specs visible
+- [ ] Summary shows accurate counts
+- [ ] No truncation needed
+- [ ] All sections proportional
+
+#### Medium Project (10-50 specs)
+- [ ] Top 5 in-progress shown by default
+- [ ] `--expand-active` shows all
+- [ ] Top tags displayed (limit 5)
+- [ ] Timeline shows 14 days
+
+#### Large Project (100+ specs)
+- [ ] Summary remains concise
+- [ ] Smart prioritization in "Needs Attention"
+- [ ] Performance < 300ms
+- [ ] No visual clutter
+
+### Smart Insights Tests
+
+#### Overdue Detection
+- [ ] Specs with `due < today` and `status != complete` flagged
+- [ ] Shows count in "Needs Attention"
+- [ ] Lists spec names (limit 3, then "and N more")
+
+#### Critical Priority
+- [ ] Critical specs still planned highlighted
+- [ ] Critical in-progress shown prominently
+- [ ] Warning if critical overdue
+
+#### Long-Running Detection
+- [ ] In-progress > 14 days flagged with ⚠️
+- [ ] Age shown next to spec name (e.g., "8d")
+- [ ] Helps identify potential bottlenecks
+
+#### User Assignment
+- [ ] `--assignee alice` focuses on Alice's work
+- [ ] Git config detection works (if configured)
+- [ ] Shows user's active work first
+
+#### Velocity Bottlenecks
+- [ ] Identifies stages with longest average duration
+- [ ] Flags if WIP exceeds target
+- [ ] Warns if throughput declining
+
+### Filter Tests
+- [ ] `--tag feature` filters all sections consistently
+- [ ] `--status in-progress` shows only in-progress
+- [ ] `--priority high` shows only high priority
+- [ ] Multiple filters combine with AND logic
+- [ ] Filtered counts accurate in summary
+
+### Display Option Tests
+- [ ] `--compact` shows minimal view (health + attention only)
+- [ ] `--expand-active` reveals all in-progress specs
+- [ ] `--json` outputs valid, comprehensive JSON
+- [ ] Unknown options show helpful error
+
+### Integration Tests
+
+#### Command Flow
+- [ ] `lean-spec` defaults to dashboard
+- [ ] `lean-spec dashboard` explicitly shows dashboard
+- [ ] Dashboard → `lean-spec list` → dashboard (workflow)
+- [ ] Dashboard respects .lean-spec/config.json
+
+#### Cross-Command Consistency
+- [ ] Dashboard counts match `lean-spec list` counts
+- [ ] Dashboard stats match `lean-spec stats` output
+- [ ] Dashboard activity matches `lean-spec stats --timeline`
+
+### Visual Tests
+
+#### Layout
+- [ ] Sections align properly
+- [ ] Box drawing characters render correctly
+- [ ] Colors don't obscure information
+- [ ] Terminal width respected (no wrapping)
+
+#### Accessibility
+- [ ] Works without color (NO_COLOR env var)
+- [ ] Unicode fallback for non-supporting terminals
+- [ ] Screen reader compatible (semantic structure)
+
+### Performance Tests
+- [ ] 10 specs: < 100ms
+- [ ] 50 specs: < 200ms
+- [ ] 100 specs: < 300ms
+- [ ] 500 specs: < 1s
+- [ ] Single `loadAllSpecs()` call verified
+
+### Regression Tests
+- [ ] Existing commands unaffected (list, board, gantt, deps)
+- [ ] `lean-spec stats` backward compatible
+- [ ] JSON output schemas unchanged (where applicable)
+- [ ] All existing tests still pass
+
+## Success Criteria
+
+### User Experience
+- [ ] New user runs `lean-spec`, immediately understands project state
+- [ ] < 5 seconds to identify what needs attention
+- [ ] Existing users don't notice breaking changes
+- [ ] Smooth migration from timeline to stats --history
+
+### Technical
+- [ ] < 300ms render time for 100 specs
+- [ ] Single `loadAllSpecs()` call in dashboard
+- [ ] < 300 lines new code (reuse existing)
+- [ ] No regressions in existing commands
+
+### Business
+- [ ] Better demo-ability for v0.2.0 launch
+- [ ] Competitive with OpenSpec UX quality
+- [ ] Reduces support questions about "how to see X"
+- [ ] Positive beta tester feedback

package/.next/standalone/packages/ui/dist/standalone/specs/047-git-backfill-timestamps/README.md

@@ -0,0 +1,314 @@
+---
+status: complete
+created: '2025-11-04'
+tags:
+  - enhancement
+  - git
+  - timestamps
+  - analytics
+  - migration
+priority: medium
+related:
+  - 046-stats-dashboard-refactor
+  - 014-complete-custom-frontmatter
+created_at: '2025-11-04T22:58:23+08:00'
+updated_at: '2025-11-04T15:08:31.110Z'
+assignee: Marvin Zhang
+updated: '2025-11-04'
+completed_at: '2025-11-04T15:08:31.110Z'
+completed: '2025-11-04'
+transitions:
+  - status: complete
+    at: '2025-11-04T15:08:31.110Z'
+---
+
+# Backfill Timestamp Frontmatter from Git History
+
+> **Status**: ✅ Complete · **Priority**: Medium · **Created**: 2025-11-04 · **Tags**: enhancement, git, timestamps, analytics, migration
+> **Assignee**: Marvin Zhang · **Reviewer**: TBD
+
+**Project**: lean-spec  
+**Team**: Core Development
+
+## Overview
+
+Add a utility command to backfill created_at, updated_at, and completed_at timestamps for existing specs by analyzing their git commit history. This will enable velocity tracking and analytics for all historical specs.
+
+**Current State:**
+- ✅ Timestamp fields defined in frontmatter schema (`created_at`, `updated_at`, `completed_at`, `transitions`)
+- ✅ New specs automatically get timestamps via `enrichWithTimestamps()`
+- ❌ Existing specs lack timestamp data (only have date fields: `created`, `completed`)
+- ❌ No way to retroactively populate timestamps from git history
+
+**Why This Matters:**
+- **Analytics** - Can't calculate cycle times, lead times, or velocity metrics without timestamps
+- **Historical insight** - Valuable project data is already in git history, just not in frontmatter
+- **Completeness** - New specs get timestamps automatically, but old specs are left behind
+
+**Goals:**
+1. Extract first/last commit timestamps from git history for each spec
+2. Backfill `created_at`, `updated_at`, `completed_at` fields where missing
+3. Provide safe, idempotent command that doesn't overwrite existing timestamps
+4. Enable full velocity tracking across entire spec history
+
+## Design
+
+### Command Interface
+
+```bash
+# Backfill all specs (timestamps only)
+lean-spec backfill
+
+# Backfill with additional fields
+lean-spec backfill --assignee    # Add assignee from git author
+lean-spec backfill --transitions # Reconstruct full status history
+lean-spec backfill --all         # All available fields
+
+# Dry run (show what would be updated)
+lean-spec backfill --dry-run
+
+# Backfill specific spec(s)
+lean-spec backfill 014 046
+lean-spec backfill my-feature
+
+# Force overwrite existing values (rare case)
+lean-spec backfill --force
+```
+
+### Git Analysis Strategy
+
+For each spec's `README.md`:
+
+**Core timestamps (always backfilled):**
+
+1. **created_at** - Use timestamp from **first commit** that created the file
+   ```bash
+   git log --follow --format="%aI" --diff-filter=A -- specs/XXX-name/README.md | tail -1
+   ```
+
+2. **updated_at** - Use timestamp from **most recent commit**
+   ```bash
+   git log --format="%aI" -n 1 -- specs/XXX-name/README.md
+   ```
+
+3. **completed_at** - Heuristic based on git history:
+   - If `status: complete` in frontmatter, use timestamp of commit that changed status to complete
+   - Fallback: Use timestamp when `completed` date field was added
+   - If neither exists, leave `completed_at` empty
+
+**Optional fields (with flags):**
+
+4. **assignee** (via `--assignee` flag)
+   - Extract from first commit author: `git log --follow --format="%an" --diff-filter=A`
+   - Only sets if field is currently empty
+   - Use case: Attribute specs to their original authors
+
+5. **transitions[]** (via `--transitions` flag)
+   - Parse all commits that modified frontmatter `status:` field
+   - Build complete status change history: `planned → in-progress → complete`
+   - Uses `git log -p` to inspect frontmatter diffs
+   - Useful for: Cycle time analysis, understanding workflow patterns
+
+6. **updated** date field (automatically synced with `updated_at`)
+   - Convert `updated_at` timestamp to YYYY-MM-DD format
+   - Keeps date and timestamp fields in sync
+
+### Implementation Approach
+
+**New file**: `src/commands/backfill-timestamps.ts`
+
+```typescript
+interface BackfillResult {
+  specPath: string;
+  created_at?: string;
+  updated_at?: string;
+  completed_at?: string;
+  assignee?: string;
+  transitions?: StatusTransition[];
+  source: 'git' | 'existing' | 'skipped';
+  reason?: string;
+}
+
+async function backfillTimestamps(
+  options: {
+    dryRun?: boolean;
+    force?: boolean;
+    includeAssignee?: boolean;
+    includeTransitions?: boolean;
+    specs?: string[]; // specific specs to target
+  }
+): Promise<BackfillResult[]>
+```
+
+**Key functions:**
+
+1. `getFirstCommitTimestamp(specPath: string): Promise<string | null>`
+   - Uses `git log --follow --diff-filter=A` to find creation timestamp
+   
+2. `getLastCommitTimestamp(specPath: string): Promise<string | null>`
+   - Uses `git log -n 1` to find most recent modification
+   
+3. `getCompletionTimestamp(specPath: string): Promise<string | null>`
+   - Searches commit history for status change to `complete`
+   - Uses `git log -p` to inspect frontmatter changes
+
+4. `getFirstCommitAuthor(specPath: string): Promise<string | null>` (optional)
+   - Extracts author name from first commit
+   - Uses `git log --follow --format="%an" --diff-filter=A`
+
+5. `parseStatusTransitions(specPath: string): Promise<StatusTransition[]>` (optional)
+   - Parses all commits that modified `status:` field
+   - Reconstructs full transition history with timestamps
+   
+6. `applyBackfillUpdates(specPath: string, data: BackfillData, force: boolean)`
+   - Only updates missing fields (unless `--force`)
+   - Preserves existing timestamps
+   - Uses `updateFrontmatter()` from existing API
+
+### Safety Measures
+
+1. **Idempotent** - Running multiple times doesn't break anything
+2. **Non-destructive** - Never overwrites existing timestamps (unless `--force`)
+3. **Dry-run mode** - Preview changes before applying
+4. **Validation** - Verify git history exists before attempting backfill
+5. **Error handling** - Graceful failures for specs without git history
+
+### Edge Cases
+
+| Scenario | Behavior |
+|----------|----------|
+| Spec already has timestamps | Skip (unless `--force`) |
+| Spec not in git history | Skip with warning |
+| Git repo not available | Error with clear message |
+| Spec was renamed/moved | Use `--follow` to track history |
+| Multiple completion events | Use first transition to `complete` |
+| Assignee already set | Skip assignee (unless `--force`) |
+| Transitions already exist | Merge with git-derived history |
+| Multiple authors | Use first commit author for assignee |
+
+## Plan
+
+- [ ] Implement git timestamp extraction utilities
+  - [ ] `getFirstCommitTimestamp()` - file creation
+  - [ ] `getLastCommitTimestamp()` - last modification
+  - [ ] `getCompletionTimestamp()` - status change detection
+  - [ ] `getFirstCommitAuthor()` - spec author (optional)
+  - [ ] `parseStatusTransitions()` - full status history (optional)
+- [ ] Build backfill command with CLI interface
+  - [ ] Support `--dry-run` flag
+  - [ ] Support `--force` flag
+  - [ ] Support `--assignee` flag (optional backfill)
+  - [ ] Support `--transitions` flag (optional backfill)
+  - [ ] Support `--all` flag (all optional fields)
+  - [ ] Support targeting specific specs
+- [ ] Add safety validations
+  - [ ] Check git repo exists
+  - [ ] Verify spec file exists in git history
+  - [ ] Prevent overwrites unless forced
+- [ ] Integration with existing frontmatter system
+  - [ ] Use `updateFrontmatter()` API
+  - [ ] Preserve existing timestamp values
+  - [ ] Sync `updated` date field with `updated_at`
+- [ ] Add comprehensive tests
+  - [ ] Mock git commands
+  - [ ] Test dry-run mode
+  - [ ] Test idempotency
+  - [ ] Test optional flags (assignee, transitions)
+  - [ ] Test edge cases (no git history, renamed files)
+- [ ] Documentation
+  - [ ] Update CLI reference
+  - [ ] Add migration guide section
+  - [ ] Document timestamp semantics
+  - [ ] Document optional backfill fields
+
+## Test
+
+**Unit Tests:**
+- [ ] Git timestamp extraction works correctly
+- [ ] Dry-run doesn't modify files
+- [ ] Force flag overwrites existing values
+- [ ] Non-force preserves existing timestamps
+- [ ] Handles missing git history gracefully
+- [ ] Handles renamed/moved specs with `--follow`
+- [ ] Optional flags work correctly (assignee, transitions)
+
+**Integration Tests:**
+- [ ] Backfill command updates all specs in test repo
+- [ ] Can target specific specs by name or number
+- [ ] Progress output is clear and informative
+- [ ] Error messages are actionable
+
+**Manual Verification:**
+- [ ] Run on lean-spec's own specs (dogfooding)
+- [ ] Verify `lean-spec stats` shows velocity data after backfill
+- [ ] Check that re-running is safe (idempotent)
+
+**Expected Output (dry-run):**
+```
+Analyzing git history for 18 specs...
+
+046-stats-dashboard-refactor
+  created_at:   2025-11-04T12:57:25Z (git)
+  updated_at:   2025-11-04T14:18:46Z (git)
+  completed_at: 2025-11-04T13:10:54Z (existing)
+  assignee:     Marvin Zhang (git) [--assignee flag]
+  transitions:  3 status changes (git) [--transitions flag]
+
+014-complete-custom-frontmatter
+  created_at:   2025-11-02T05:11:37Z (git)
+  updated_at:   2025-11-04T07:39:49Z (git)
+  completed_at: 2025-11-04T07:39:49Z (git - inferred from status)
+  assignee:     (existing - alice)
+
+...
+
+Summary:
+  18 specs analyzed
+  16 would be updated (timestamps)
+  5 would get assignee (with --assignee)
+  12 would get transitions (with --transitions)
+  2 already have complete data
+  
+Run without --dry-run to apply changes.
+Run with --all to include optional fields.
+```
+
+## Notes
+
+### Why Not Store in Git Metadata Only?
+
+We could just query git history on-demand for analytics, but:
+- ❌ Performance: Git queries are slow for large repos
+- ❌ Portability: Specs lose metadata if moved outside git
+- ❌ Consistency: Frontmatter is source of truth for all metadata
+
+### Alternative: Git Hooks
+
+Could automatically update `updated_at` on commit via git hooks, but:
+- 👎 Requires setup in every repo
+- 👎 Doesn't help with existing specs
+- 👍 Could complement backfill for ongoing maintenance
+
+### Future Enhancements
+
+- **Automated backfill on `lean-spec init`** - Offer to backfill when initializing in existing project
+- **Watch mode** - Continuously sync timestamps from git (via git hooks or daemon)
+- **GitHub API integration** - Backfill `issue`, `pr`, `reviewer` from GitHub metadata
+- **Commit message parsing** - Extract additional metadata from commit messages
+- **Multi-author attribution** - Track all contributors, not just first author
+
+### Scope Boundaries
+
+**Out of scope for v1:**
+- ❌ GitHub API integration (issue/PR linking)
+- ❌ Reviewer inference (no clear git signal)
+- ❌ Epic/milestone extraction (requires external PM tools)
+
+**These could be separate features:**
+- `lean-spec sync-github` - Pull issue/PR metadata from GitHub
+- `lean-spec import-pm` - Import epic/milestone from Jira/ADO
+
+### Related Specs
+
+- **046-stats-dashboard-refactor** - Stats command will benefit from complete timestamp data
+- **014-complete-custom-frontmatter** - Timestamp fields are part of frontmatter schema