@leanspec/ui 0.2.8 → 0.2.9-dev.20251205030455

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

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

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

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