@leanspec/ui 0.2.6-dev.20251125010539 → 0.2.6

package/.next/standalone/packages/ui/dist/standalone/specs/archived/031-gantt-ux-improvements/README.md

@@ -0,0 +1,230 @@
+---
+status: complete
+created: '2025-11-03'
+tags:
+  - ux
+  - visualization
+  - pm-tools
+priority: high
+completed: '2025-11-03'
+---
+
+# gantt-ux-improvements
+
+> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-03 · **Tags**: ux, visualization, pm-tools
+
+## Overview
+
+The current `lean-spec gantt` command has significant UX/UI issues that make it confusing and not very useful:
+
+**Current Problems:**
+
+1. **All bars look the same without due dates** - Every planned spec shows a 2-week bar starting from creation date, making it impossible to distinguish urgency or actual timelines
+2. **Bars start from creation date** - This clutters the past with already-created specs instead of focusing on future work
+3. **No visual priority** - All specs get equal visual weight regardless of priority
+4. **Redundant metadata** - Shows status emoji + status text + created date (which is already in the timeline)
+5. **Poor information density** - Takes 4 lines per spec but doesn't show enough useful info
+6. **No grouping** - All specs are flat, making it hard to see patterns or organize work
+7. **Today marker (○)** is often invisible when it overlaps with bars
+
+**Why Fix This:**
+Gantt charts are meant to show timeline planning and dependencies. The current implementation doesn't help users plan or prioritize work effectively.
+
+## Design
+
+### Option A: Simplified Timeline (Recommended)
+
+Focus on **future work** with **clear visual hierarchy**:
+
+```
+📅 Gantt Chart (4 weeks from Nov 3, 2025)
+
+Spec                                       Timeline
+                                           Nov 3   Nov 10  Nov 17  Nov 24  
+─────────────────────────────────────────  ────────────────────────────────
+                                           │ Today
+
+🔴 CRITICAL (0)
+
+🟠 HIGH (2)
+  ⚡ 002-complete-custom-frontmatter       ████████░░░░░░░░░░░░░░░░
+  📋 016-created-date-format-bug           (no due date set)
+
+🟡 MEDIUM (5)
+  📋 005-pattern-aware-list-grouping       (no due date set)
+  📋 012-init-pattern-selection            (no due date set)
+  📋 004-github-action                     (no due date set)
+  📋 006-vscode-extension                  (no due date set)
+  📋 008-spec-validation                   (no due date set)
+
+🟢 LOW (1)
+  📋 006-template-config-updates           (no due date set)
+
+Summary: 1 in-progress · 7 planned · 0 overdue
+💡 Tip: Add "due: YYYY-MM-DD" to frontmatter for timeline planning
+```
+
+**Key Changes:**
+- Group by priority (visual hierarchy)
+- Fixed-width columns: Spec (43 chars) + Timeline (32 chars)
+- Status emoji merged into spec name
+- Timeline bars only show if there's a due date
+- Timeline starts from today, not from creation dates
+- "(no due date set)" encourages adding due dates
+
+### Option B: Dependency-First View
+
+Focus on **critical path** and **blockers**:
+
+```
+📅 Gantt Chart - Dependency View
+
+Spec                                       Timeline
+─────────────────────────────────────────  ────────────────────────────────
+
+⚠️  BLOCKED (0 specs waiting on dependencies)
+
+⚡ IN PROGRESS (1)
+  ⚡ 002-complete-custom-frontmatter       ████████░░░░░░░░  started Nov 2
+     [HIGH]
+
+📋 READY TO START (7 specs with no blockers)
+  🟠 High Priority (2)
+    📋 016-created-date-format-bug
+  
+  🟡 Medium Priority (5)
+    📋 005-pattern-aware-list-grouping
+    📋 012-init-pattern-selection
+    📋 004-github-action
+    📋 006-vscode-extension
+    📋 008-spec-validation
+  
+  🟢 Low Priority (1)
+    📋 006-template-config-updates
+
+✅ COMPLETE (22) - use --show-complete to view
+```
+
+### Option C: Hybrid Approach (Table-Based)
+
+Combine timeline + priority + dependencies with **table alignment**:
+
+```
+📅 Gantt Chart (4 weeks from Nov 3, 2025)
+
+Spec                                       Timeline
+                                           Nov 3   Nov 10  Nov 17  Nov 24  
+─────────────────────────────────────────  ────────────────────────────────
+                                           │ Today
+
+🔴 CRITICAL (0)
+
+🟠 HIGH (2)
+  ⚡ 002-complete-custom-frontmatter       ████████░░░░░░░░░░░░░░░░
+  📋 016-created-date-format-bug           (no due date set)
+
+🟡 MEDIUM (5)
+  📋 005-pattern-aware-list-grouping       (no due date set)
+  📋 012-init-pattern-selection            (no due date set)
+  📋 004-github-action                     (no due date set)
+  📋 006-vscode-extension                  (no due date set)
+  📋 008-spec-validation                   (no due date set)
+
+🟢 LOW (1)
+  📋 006-template-config-updates           (no due date set)
+
+Summary: 1 in-progress · 7 planned · 0 overdue
+💡 Add "due: YYYY-MM-DD" to see timeline bars
+```
+
+## Recommendation: Option A + Option B Hybrid
+
+Implement **Option A** as the default view (priority-grouped timeline), and add **flags**:
+- `lean-spec gantt` - Priority-grouped with timelines (Option A)
+- `lean-spec gantt --deps` - Dependency-focused view (Option B)
+- `lean-spec gantt --compact` - Ultra-compact list view
+- `lean-spec gantt --traditional` - Classic gantt with all metadata (current style)
+
+## Plan
+
+- [ ] Decide on default view (recommend Option A)
+- [ ] **Define column width constants**
+  - Spec column: 43 characters (fixed)
+  - Timeline column: 32 characters (8 chars per week × 4 weeks default)
+  - Separator: 2 spaces between columns
+- [ ] **Implement table-based layout system**
+  - Create helper functions for column alignment
+  - Ensure spec names are truncated/padded to 43 chars
+  - Ensure timeline bars are exactly 32 chars (or weeks × 8)
+- [ ] Implement priority grouping with section headers
+- [ ] Merge status emoji into spec name (⚡ for in-progress, 📋 for planned, ✅ for complete)
+- [ ] Add column headers: "Spec" and "Timeline"
+- [ ] Add separator line matching column widths
+- [ ] Add calendar dates in Timeline column header (Nov 3, Nov 10, etc.)
+- [ ] Add "Today" marker aligned to current week
+- [ ] Change timeline bars to start from "today" instead of spec creation dates
+- [ ] Show "(no due date set)" for specs without due dates instead of fake bars
+- [ ] Add --deps flag for Option B (dependency view)
+- [ ] Add --compact flag for minimal view
+- [ ] Add --traditional flag for old style
+- [ ] Update tests to verify column alignment
+- [ ] Update documentation
+
+## Test
+
+- [ ] **Column alignment is perfect**
+  - Spec column exactly 43 chars wide (including status emoji and padding)
+  - Timeline column exactly 32 chars (8 per week)
+  - Column separator line matches column widths exactly
+  - Calendar dates align with timeline bars
+- [ ] Priority groups show clear visual hierarchy
+- [ ] Status emoji (⚡📋✅) appears inline with spec names
+- [ ] Specs without due dates show "(no due date set)" instead of bars
+- [ ] Timeline starts from today, not creation dates
+- [ ] "Today" marker aligns with current week boundary
+- [ ] --deps flag shows blocker-focused view
+- [ ] Works well with 5, 10, 50 specs
+- [ ] Long spec names truncate gracefully (with …)
+- [ ] Short spec names pad correctly
+- [ ] Alignment is consistent across all priority groups
+
+## Notes
+
+**Current Code Location:** `src/commands/gantt.ts`
+
+**Critical Implementation Rules:**
+
+1. **Column Width Constants** (must be enforced):
+   ```typescript
+   const SPEC_COLUMN_WIDTH = 43;  // Includes status emoji + 1 space + spec name
+   const TIMELINE_COLUMN_WIDTH = weeks * 8;  // 8 chars per week
+   const COLUMN_SEPARATOR = '  ';  // 2 spaces
+   ```
+
+2. **Spec Name Formatting**:
+   - Format: `{emoji} {spec-name}` (e.g., `⚡ 002-complete-custom-frontmatter`)
+   - Total width must be exactly 43 chars (pad with spaces or truncate with …)
+   - Emoji is 1 char, space is 1 char, name is remaining chars
+
+3. **Alignment Pattern** (same as `stats` and `timeline`):
+   ```
+   Header          Header
+   ───────────────  ────────────────────────────────
+   Content         Content
+   ```
+
+4. **Timeline Calculation**:
+   - Start date = today.startOf('week')
+   - Each week = 8 characters exactly
+   - Timeline bars use: ████ (filled), ░░░░ (empty), │ (today marker)
+
+5. **Priority Groups**:
+   - Always show all 4 priorities (CRITICAL, HIGH, MEDIUM, LOW)
+   - Show count in parentheses: `🟠 HIGH (2)`
+   - Indent specs under priority by 2 spaces
+
+**Key Issue:** The original design tried to show timeline bars for all specs even without due dates by creating fake 2-week estimates. This creates visual noise and doesn't help with planning.
+
+**Better Approach:** Embrace that most specs don't have due dates yet, and make the gantt chart encourage setting them while still being useful for high-level overview. Use "(no due date set)" placeholder text.
+
+**Alignment is Critical:** Following the same column-width discipline as `stats` and `timeline` ensures a consistent, professional CLI experience. All widths must be exact.

package/.next/standalone/packages/ui/dist/standalone/specs/archived/032-console-log-chalk-security/README.md

@@ -0,0 +1,89 @@
+---
+status: complete
+created: '2025-11-03'
+tags:
+  - security
+  - refactor
+priority: high
+completed: '2025-11-03'
+---
+
+# console-log-chalk-security
+
+> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-03 · **Tags**: security, refactor
+
+**Project**: lean-spec  
+**Team**: Core Development
+
+## Overview
+
+**Security Issue**: Direct use of `console.log` with `chalk` throughout the codebase creates a potential security vulnerability. User-controlled input that flows through chalk formatting without proper sanitization could be exploited via terminal escape sequences or ANSI injection attacks.
+
+**Why now**: This is a security concern that should be addressed before wider adoption. The codebase has 40+ instances of `console.log` + `chalk` usage that need to be audited and potentially refactored.
+
+## Security Concerns
+
+1. **ANSI Injection**: Malicious spec names or metadata could inject terminal control sequences
+2. **Terminal Escape Abuse**: Unescaped user input could manipulate terminal behavior
+3. **Output Integrity**: Attackers could craft inputs that alter display or hide information
+
+**Attack Vector Example**:
+```
+lean-spec create "\x1b[0m\x1b[31mFAKE ERROR\x1b[0m"
+```
+
+## Design
+
+**Approach**: Create a safe output abstraction layer
+
+1. **Centralized Output Module** (`src/utils/safe-output.ts`):
+   - Sanitize all user-provided input before chalk formatting
+   - Strip ANSI sequences from untrusted strings
+   - Provide safe wrappers: `safeLog()`, `safeSuccess()`, `safeWarn()`, etc.
+
+2. **Input Sanitization**:
+   - Escape or strip terminal control characters
+   - Validate spec names, paths, and metadata
+   - Use allowlist approach for known-safe characters
+
+3. **Migration Strategy**:
+   - Replace direct `console.log(chalk...)` with safe wrappers
+   - Update `src/utils/ui.ts` to use sanitization
+   - Audit all instances found in grep results
+
+## Plan
+
+- [ ] Create `src/utils/safe-output.ts` with sanitization utilities
+- [ ] Implement `stripAnsi()` and `sanitizeUserInput()` functions
+- [ ] Add safe output wrappers (safeLog, safeSuccess, safeWarn, etc.)
+- [ ] Update `src/utils/ui.ts` to use safe wrappers internally
+- [ ] Migrate all console.log + chalk usage in commands:
+  - [ ] `src/commands/board.ts` (18 instances)
+  - [ ] `src/commands/search.ts` (8 instances)
+  - [ ] `src/commands/files.ts` (9 instances)
+  - [ ] `src/commands/deps.ts` (1 instance)
+  - [ ] `src/commands/update.ts` (2 instances)
+  - [ ] `src/utils/template-helpers.ts` (3 instances)
+- [ ] Add ESLint rule to prevent direct console.log + chalk usage
+- [ ] Add security documentation to README
+
+## Test
+
+- [ ] Unit tests for ANSI injection attempts
+- [ ] Test spec creation with malicious names containing escape sequences
+- [ ] Verify output sanitization doesn't break legitimate formatting
+- [ ] Test edge cases: unicode, emojis, special characters
+- [ ] Manual testing with terminal escape sequences
+- [ ] Verify no ANSI bleeding in error messages
+
+## Notes
+
+**Libraries to consider**:
+- `strip-ansi` - Well-maintained library for stripping ANSI codes
+- `ansi-regex` - For detection/validation
+
+**Files with console.log + chalk**:
+- 40+ instances found across 7 files
+- Most concentrated in `board.ts` (18), `search.ts` (8), `files.ts` (9)
+
+**Severity**: High - This affects all user-facing output and could be exploited in automated environments or CI/CD pipelines where lean-spec commands process untrusted input.

package/.next/standalone/packages/ui/dist/standalone/specs/archived/033-mcp-server/README.md

@@ -0,0 +1,89 @@
+---
+status: complete
+created: '2025-11-03'
+tags:
+  - integration
+  - mcp
+  - ai
+priority: high
+completed: '2025-11-03'
+---
+
+# MCP Server Integration
+
+> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-03 · **Tags**: integration, mcp, ai
+
+**Project**: lean-spec  
+**Team**: Core Development
+
+## Overview
+
+Build a Model Context Protocol (MCP) server for LeanSpec that enables AI assistants (Claude Desktop, Cline, etc.) to interact with LeanSpec projects. This allows AI agents to read specs, create new ones, update status, search, and visualize project state—directly from their native environment.
+
+**Why now?** MCP is the emerging standard for AI-tool integration. Supporting it positions LeanSpec as AI-native and enables seamless workflows where agents can discover, understand, and contribute to specs without context switching.
+
+## Design
+
+**Architecture:**
+- TypeScript MCP server (`packages/mcp-server/`)
+- Implements MCP protocol for tools, prompts, and resources
+- Reuses existing CLI logic via shared core package
+
+**MCP Tools (exposed to AI):**
+- `lean-spec_list` - List specs with filtering
+- `lean-spec_search` - Full-text search across specs
+- `lean-spec_read` - Read full spec content
+- `lean-spec_create` - Create new spec
+- `lean-spec_update` - Update spec frontmatter/status
+- `lean-spec_stats` - Get project statistics
+- `lean-spec_board` - Get Kanban board view
+- `lean-spec_deps` - Show dependencies
+
+**MCP Resources (browsable by AI):**
+- `spec://<spec-name>` - Individual spec content
+- `board://kanban` - Current board state
+- `stats://overview` - Project statistics
+
+**MCP Prompts (quick actions for users):**
+- "Create feature spec" - Guided spec creation
+- "Update spec status" - Quick status changes
+- "Find related specs" - Dependency discovery
+
+**Configuration:**
+- Add to Claude Desktop config or any MCP-compatible client
+- Auto-discover project root from config file
+- Support multiple projects via config path parameter
+
+## Plan
+
+- [ ] Set up MCP server package structure
+- [ ] Implement MCP protocol handlers (tools, resources, prompts)
+- [ ] Wrap CLI commands as MCP tools
+- [ ] Add resource providers for browseable content
+- [ ] Create helpful prompt templates
+- [ ] Write setup instructions for Claude Desktop
+- [ ] Test with Claude Desktop and other MCP clients
+- [ ] Document in `docs/ai-integration/mcp-server.md`
+
+## Test
+
+- [ ] MCP server starts and responds to protocol handshake
+- [ ] All tools execute successfully and return valid data
+- [ ] Resources are browseable and return correct content
+- [ ] Prompts generate appropriate responses
+- [ ] Works with Claude Desktop in real project
+- [ ] Error handling for invalid project paths
+- [ ] Multiple projects can be configured simultaneously
+
+## Notes
+
+**MCP Protocol Reference:** https://modelcontextprotocol.io/
+
+**Related Work:**
+- VS Code extension (spec 006) - complementary UX for different context
+- PM integrations (planned) - MCP could expose sync status
+
+**Implementation Notes:**
+- Consider using `@modelcontextprotocol/sdk` for TypeScript
+- Keep server stateless; read from filesystem on each request
+- Reuse validation and config logic from core CLI

package/.next/standalone/packages/ui/dist/standalone/specs/archived/037-docs-overhaul/README.md

@@ -0,0 +1,166 @@
+---
+status: archived
+created: '2025-11-03'
+tags:
+  - docs
+  - maintenance
+  - clarity
+  - merged-into-051
+priority: low
+related:
+  - 043-official-launch-02
+created_at: '2025-11-03T00:00:00Z'
+updated_at: '2025-11-11T04:26:08.615Z'
+completed_at: '2025-11-07T07:00:40.261Z'
+completed: '2025-11-07'
+transitions:
+  - status: complete
+    at: '2025-11-07T07:00:40.261Z'
+  - status: archived
+    at: '2025-11-11T04:26:08.615Z'
+---
+
+# Documentation Overhaul & Simplification
+
+> **Status**: 📦 Archived · **Priority**: Low · **Created**: 2025-11-03 · **Tags**: docs, maintenance, clarity, merged-into-051
+
+**Project**: lean-spec  
+**Team**: Core Development
+
+## Overview
+
+Audit and simplify all LeanSpec documentation to eliminate unnecessary complexity, reduce redundancy, and ensure docs stay true to the "lean" philosophy. We may have accumulated overkill documentation that contradicts our core principle of clarity over documentation.
+
+**Why now?** As the project matures, docs naturally accumulate. Before we scale further, we need to ensure our documentation practices what we preach: minimal, clear, actionable—not exhaustive.
+
+## Design
+
+**Audit Scope:**
+- Main README.md
+- AGENTS.md (AI agent instructions)
+- CONTRIBUTING.md
+- Documentation website (`docs-site/docs/**`)
+- Inline code comments
+- Spec templates
+- Example specs
+
+**Assessment Criteria:**
+
+**Keep if:**
+- ✅ Answers "why" or "what" clearly
+- ✅ Needed for first-time users
+- ✅ Prevents common mistakes
+- ✅ Explains non-obvious design decisions
+
+**Cut if:**
+- ❌ Duplicates other docs
+- ❌ States the obvious (self-documenting code)
+- ❌ Over-explains simple concepts
+- ❌ Shows off rather than helps
+- ❌ Prescribes one "right way" unnecessarily
+- ❌ Hasn't been updated and is stale
+
+**Structure Review:**
+
+**README.md:**
+- Should get someone started in <5 min
+- Quick install, one example, link to docs
+- Cut: long philosophy sections, redundant examples
+
+**AGENTS.md:**
+- Keep focused on actionable instructions
+- Remove redundant context (they can read README)
+- Ensure examples are current
+
+**Documentation Website:**
+- Consolidate overlapping guides
+- Merge "Getting Started" with "Quick Start" if redundant
+- Reduce tutorial depth—link to specs as examples instead
+
+**Spec Templates:**
+- Already fairly lean, but review for cruft
+- Ensure comments are helpful, not prescriptive
+
+**Code Comments:**
+- Audit for unnecessary comments
+- Keep: "why" comments, non-obvious decisions
+- Remove: "what" comments that restate code
+
+## Plan
+
+**Status (2025-11-04):** Ready to start - part of Phase 2 for v0.2.0 launch
+
+- [ ] Audit README.md for redundancy and verbosity
+- [ ] Review AGENTS.md for outdated or unnecessary instructions
+- [ ] Check CONTRIBUTING.md for overkill guidelines
+- [ ] Audit docs-site structure for overlapping content
+- [ ] Review each doc page against assessment criteria
+- [ ] Consolidate or remove redundant guides
+- [ ] Simplify spec templates if needed
+- [ ] Scan codebase for unnecessary comments
+- [ ] Update examples to reflect current best practices
+- [ ] Test first-time user experience with simplified docs
+- [ ] Get feedback from fresh users (if possible)
+- [ ] Archive removed content for reference
+
+**Implementation Priority:**
+- 🔴 HIGH: README.md simplification (first impression matters)
+- 🔴 HIGH: AGENTS.md accuracy (AI integration is core feature)
+- 🟡 MEDIUM: Docs site consolidation
+- 🟢 LOW: Code comment cleanup
+
+**Related Work:**
+- Spec 043: Official Launch v0.2.0 - docs quality is critical for launch
+- Clear docs support adoption and reduce support burden
+
+## Test
+
+- [ ] New user can get started in <5 minutes from README
+- [ ] No duplicate information across docs
+- [ ] Every doc serves a clear purpose
+- [ ] Docs site navigation is intuitive
+- [ ] Spec templates are clear but not prescriptive
+- [ ] Code comments add value, not noise
+- [ ] Examples are current and accurate
+- [ ] No broken links after consolidation
+- [ ] Docs still cover critical use cases
+- [ ] The word count is notably reduced
+
+## Notes
+
+**Metrics to Track:**
+- Word count before/after
+- Number of doc pages before/after
+- Time to first successful spec creation (ideal: <5min)
+
+**LeanSpec Philosophy Check:**
+- "Clarity over documentation"
+- "If it doesn't add clarity, cut it"
+- "Minimal is the goal"
+
+**Risk:**
+- We might cut too much and confuse users
+- Mitigation: start with obvious redundancies, gather feedback
+
+**Related:**
+- Live specs showcase (spec 021) - could replace some documentation with examples
+- README improvement (spec 009) - previous work to build on
+
+**Examples of Potential Overkill:**
+- Multiple "Quick Start" sections across README and docs
+- Long philosophical explanations in every doc
+- Over-documented example projects
+- Exhaustive command references (when `--help` exists)
+- Multiple tutorials covering the same workflow
+
+**What Makes Good Lean Docs:**
+- Get user to "aha!" moment fast
+- One clear path for common tasks
+- Link to details rather than inline them
+- Trust users to explore
+- Show, don't tell (examples over prose)
+
+**Action Items Post-Overhaul:**
+- Add docs maintenance guidelines to CONTRIBUTING.md
+- Set up periodic review (quarterly?) to prevent accumulation
+- Consider docs page limit or word count budget