@leanspec/ui 0.2.7-dev.20251126100750 → 0.2.7

package/.next/standalone/packages/ui/dist/standalone/specs/archived/038-flat-structure-migration/README.md

@@ -0,0 +1,276 @@
+---
+status: complete
+created: '2025-11-03'
+tags: [structure, migration, breaking-change, enhancement]
+priority: high
+---
+
+# Flat Structure Migration
+
+> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-03
+
+**Project**: lean-spec  
+**Team**: Core Development
+
+## Overview
+
+Migrate the default folder structure from date-based grouping (`{date}/{seq}-{name}/`) to a **flat structure with global numbering** (`{seq}-{name}/`). This simplifies the spec organization for most projects while maintaining date-based grouping as an optional pattern for those who need it.
+
+**Why now?**
+- Current date-based folders add unnecessary complexity for small/medium projects
+- Most users don't need date-based organization
+- **Flat structure with global numbering is simpler** to navigate and reference
+- Easier to reference specs by number alone (e.g., "spec 024" instead of "specs/20251103/024")
+- Other patterns (custom grouping) already available via config
+
+**Current structure**: `specs/20251103/024-flat-structure-migration/`  
+**Target structure**: `specs/024-flat-structure-migration/`
+
+**Key change**: Global unique sequence numbers (001, 002, 003...) across the entire project, not per-date folder.
+
+## Design
+
+### Configuration Changes
+
+**Default config becomes:**
+```json
+{
+  "structure": {
+    "pattern": "flat",
+    "prefix": "",  // No prefix by default - just global sequence numbers
+    "sequenceDigits": 3,
+    "defaultFile": "README.md"
+  }
+}
+```
+
+**Example folder structure:**
+```
+specs/
+├── 001-typescript-cli-migration/
+├── 002-template-system-redesign/
+├── 024-flat-structure-migration/
+├── 025-next-feature/
+└── archived/
+```
+
+**Migration paths:**
+1. **New projects** - Use flat structure by default
+2. **Existing projects** - Keep current structure, provide migration guide
+3. **Date grouping users** - Can opt-in via config:
+   ```json
+   {
+     "structure": {
+       "pattern": "custom",
+       "groupExtractor": "{YYYYMMDD}"
+     }
+   }
+   ```
+
+### Code Changes
+
+1. **Update `DEFAULT_CONFIG` in `src/config.ts`**:
+   - Change `pattern: 'flat'` (already correct)
+   - Remove `prefix: '{YYYYMMDD}-'` (set to empty string by default)
+
+2. **Update `lean-spec init`**:
+   - New projects get flat structure
+   - Remove date folder creation from init command
+
+3. **Update docs and templates**:
+   - README examples show flat structure
+   - AGENTS.md updated with new default
+   - Migration guide for existing projects
+
+4. **Spec loader compatibility**:
+   - Already supports both patterns (tested)
+   - No breaking changes to loader logic
+
+### Migration Guide for Existing Projects
+
+For users currently on date-based structure who want to migrate:
+
+**Option 1: Keep current structure** (recommended for active projects)
+```json
+// .lean-spec/config.json
+{
+  "structure": {
+    "pattern": "custom",
+    "groupExtractor": "{YYYYMMDD}"
+  }
+}
+```
+
+**Option 2: Migrate to flat**
+```bash
+# Flatten existing specs
+for dir in specs/*/; do
+  mv "$dir"*/ specs/
+done
+rmdir specs/202*
+
+# Update config to flat
+lean-spec init --pattern flat --force
+```
+
+## Plan
+
+- [x] Update `DEFAULT_CONFIG` in `src/config.ts` - remove date prefix
+- [x] Update `lean-spec init` to use flat structure by default
+- [x] Create migration guide document
+- [x] Update README.md with flat structure examples
+- [x] Update AGENTS.md with new default structure
+- [x] Update documentation website
+- [x] Update examples/configs to use flat structure
+- [x] Add migration notice to CHANGELOG.md
+- [x] Test new project creation
+- [x] Test existing project compatibility
+- [x] Verify spec loading works for both patterns
+- [x] ~~Migrate lean-spec's own specs to flat structure?~~ (Keep existing for backwards compat testing)
+
+## Test
+
+### New Projects
+- [x] `lean-spec init` creates `specs/` (no date folder)
+- [x] `lean-spec create test` creates `specs/001-test/`
+- [x] Next spec is `specs/002-another/`
+- [x] Sequence numbers are globally unique across entire project
+
+### Existing Projects
+- [x] Projects with date folders continue working
+- [x] Config with `custom` pattern and `{YYYYMMDD}` extractor works
+- [x] `lean-spec list`, `lean-spec stats`, etc. work with both structures
+
+### Migration
+- [x] Manual migration steps documented and tested
+- [x] Config update preserves custom fields
+- [x] No data loss during migration
+
+## Implementation Summary
+
+**Changes made:**
+1. ✅ Updated all template configs (minimal, standard, enterprise) to use `pattern: "flat"` with `prefix: ""`
+2. ✅ Created comprehensive migration guide at `docs/MIGRATION.md`
+3. ✅ Updated README.md with flat structure as default and migration note
+4. ✅ Updated AGENTS.md with folder structure section
+5. ✅ Updated CHANGELOG.md with v0.2.0 breaking change notice
+6. ✅ All tests pass (152 tests) including both flat and legacy structures
+
+**Key decisions:**
+- DEFAULT_CONFIG in `src/config.ts` was already correctly set to flat structure
+- Kept LeanSpec's own specs in date-based format for backwards compatibility testing
+- Legacy pattern `{date}/{seq}-{name}/` is auto-converted to custom pattern with date grouping
+- No code changes needed in init command - templates drive the structure
+
+**Test results:**
+```
+Test Files  7 passed (7)
+Tests  152 passed (152)
+```
+
+Both flat structure (new default) and date-based structure (legacy) work correctly.
+
+## Notes
+
+**Breaking change**: New projects will have different folder structure than examples in current docs. This is acceptable because:
+- Simpler default is better for onboarding
+- Date-based grouping still available via config
+- Migration path exists for those who want to switch
+
+**Backwards compatibility**: Existing projects continue working without changes. Spec loader already handles both patterns.
+
+**Timeline**: Can be implemented quickly since most infrastructure already exists (flat pattern support is already built-in).
+
+## Migration of LeanSpec Itself
+
+### Executed Migration Steps
+
+1. ✅ **Moved all specs from date folders to flat structure**
+   ```bash
+   # Moved 39 specs from specs/202*/*/ to specs/
+   # Removed empty date folders
+   ```
+
+2. ✅ **Renumbered all specs with globally unique sequences**
+   - Maintained chronological order based on `created` date
+   - Sequence 001-039 now globally unique across entire project
+   - Used Python script to safely renumber based on creation dates
+
+3. ✅ **Updated config to flat structure**
+   ```json
+   {
+     "structure": {
+       "pattern": "flat",
+       "prefix": "",
+       "sequenceDigits": 3
+     }
+   }
+   ```
+
+4. ✅ **Verified migration**
+   - `lean-spec check` - No conflicts detected
+   - `lean-spec list` - All 39 specs listed correctly
+   - `lean-spec stats` - Statistics working properly
+   - `pnpm test` - All 152 tests passing
+
+### Before Migration
+```
+specs/
+├── 20251031/
+│   ├── 001-typescript-cli-migration/
+│   ├── 002-template-system-redesign/
+│   └── 003-init-system-redesign/
+├── 20251101/
+│   ├── 001-existing-project-integration/
+│   └── ...
+└── 20251103/
+    ├── 024-flat-structure-migration/
+    └── ...
+```
+
+### After Migration
+```
+specs/
+├── 001-typescript-cli-migration/
+├── 002-template-system-redesign/
+├── 003-init-system-redesign/
+├── 004-existing-project-integration/
+├── ...
+├── 038-flat-structure-migration/
+└── 039-template-variable-sync/
+```
+
+**Benefits realized:**
+- ✅ Simpler navigation - no date folders
+- ✅ Easier references - just "spec 038" instead of "specs/20251103/024"
+- ✅ Globally unique numbering - no conflicts
+- ✅ All tools work perfectly with flat structure
+
+## Post-Migration Fix
+
+### Issue: `lean-spec list` Rendering Problem
+
+After migrating to flat structure, `lean-spec list` had a rendering issue where all specs were grouped under `📂 unknown/` instead of being displayed properly.
+
+**Root cause**: The `SpecListView` component was hardcoded to group specs by date pattern (`/^(\d{8})\//`), which doesn't work with flat structure paths like `001-feature-a/`.
+
+**Fix**: Updated `src/components/SpecListView.tsx` to be pattern-aware:
+- Detects if config uses date-based grouping (`pattern: 'custom'` with `{YYYY}` in `groupExtractor`)
+- **Flat structure**: Displays all specs in a simple list (no date grouping)
+- **Date-based structure**: Uses original date-grouped rendering
+
+**Changes**:
+1. Pass `config` to `SpecListView` component
+2. Split rendering into two views:
+   - `FlatView` - Simple list for flat structure
+   - `DateGroupedView` - Original date-grouped view for custom patterns
+3. Pattern detection logic chooses the appropriate view
+
+**Test results**:
+- ✅ Flat structure renders correctly (no `unknown/` grouping)
+- ✅ Date-based structure still works (backwards compatible)
+- ✅ All 152 tests passing
+
+**Files changed**:
+- `src/commands/list.ts` - Pass config to component
+- `src/components/SpecListView.tsx` - Pattern-aware rendering logic

package/.next/standalone/packages/ui/dist/standalone/specs/archived/038-mcp-frontmatter-bug-fix/README.md

@@ -0,0 +1,122 @@
+---
+status: archived
+created: '2025-11-04'
+tags:
+  - bug
+  - mcp
+  - frontmatter
+priority: high
+completed: '2025-11-04'
+created_at: '2025-11-11T04:26:08.805Z'
+updated_at: '2025-11-11T04:26:08.805Z'
+transitions:
+  - status: archived
+    at: '2025-11-11T04:26:08.805Z'
+---
+
+# Fix MCP Server Frontmatter Parsing
+
+> **Status**: 📦 Archived · **Priority**: High · **Created**: 2025-11-04 · **Tags**: bug, mcp, frontmatter
+
+**Project**: lean-spec  
+**Team**: Core Development
+
+## Overview
+
+The MCP server's `specToData` function incorrectly accesses frontmatter properties directly on the `SpecInfo` object (e.g., `spec.status`) instead of through the `frontmatter` property (e.g., `spec.frontmatter.status`).
+
+**Impact:**
+- `lean-spec_board` command crashes with "Cannot read properties of undefined"
+- `lean-spec_stats` shows all specs with `undefined` status
+- All frontmatter fields (status, priority, tags, etc.) are not populated in MCP responses
+
+**Root cause:** `SpecInfo` type has structure:
+```typescript
+{
+  path: string;
+  name: string;
+  frontmatter: {
+    status: SpecStatus;
+    priority?: SpecPriority;
+    tags?: string[];
+    // ...
+  }
+}
+```
+
+But `specToData()` tries to access `spec.status` instead of `spec.frontmatter.status`.
+
+## Design
+
+**Fix approach:**
+Update `specToData()` function in `src/mcp-server.ts` to correctly access frontmatter properties:
+
+```typescript
+function specToData(spec: any): SpecData {
+  return {
+    name: spec.name,
+    path: spec.path,
+    status: spec.frontmatter.status,           // Fix: access via frontmatter
+    created: spec.frontmatter.created,         // Fix: access via frontmatter
+    title: spec.frontmatter.title,             // Fix: access via frontmatter
+    tags: spec.frontmatter.tags,               // Fix: access via frontmatter
+    priority: spec.frontmatter.priority,       // Fix: access via frontmatter
+    assignee: spec.frontmatter.assignee,       // Fix: access via frontmatter
+    description: spec.frontmatter.description, // Fix: access via frontmatter
+    customFields: spec.frontmatter.custom,     // Fix: access via frontmatter
+  };
+}
+```
+
+**Additional fixes needed:**
+- `getBoardData()` - accesses `spec.status` directly (line ~215)
+- `getStatsData()` - accesses `spec.status`, `spec.priority`, `spec.tags` directly (lines ~188-201)
+
+These need to use `spec.frontmatter.*` as well.
+
+## Plan
+
+- [x] Identify the bug through testing MCP commands
+- [x] Locate the root cause in `specToData()` function
+- [ ] Update `specToData()` to access `spec.frontmatter.*` properties
+- [ ] Fix `getBoardData()` to use `spec.frontmatter.status`
+- [ ] Fix `getStatsData()` to use `spec.frontmatter.*` fields
+- [ ] Add proper TypeScript typing to avoid this issue (use SpecInfo type)
+- [ ] Test all MCP commands (list, board, stats, search, read)
+- [ ] Add unit tests for `specToData()` transformation
+
+## Test
+
+Verify all MCP commands work correctly:
+
+- [ ] `lean-spec_list` returns specs with correct status/priority/tags
+- [ ] `lean-spec_board` successfully groups specs by status columns
+- [ ] `lean-spec_stats` shows correct counts by status/priority/tags
+- [ ] `lean-spec_search` includes proper metadata in results
+- [ ] `lean-spec_read` shows correct frontmatter in spec data
+- [ ] No "undefined" values in any MCP responses
+- [ ] Board command doesn't crash with undefined errors
+
+**Manual test:**
+```bash
+# Via MCP in VS Code
+- Call board tool → should show specs grouped by status
+- Call stats tool → should show counts > 0 for statuses
+- Call list tool → should show status field populated
+```
+
+## Notes
+
+**Discovery process:**
+1. Tested `lean-spec_board` → got "Cannot read properties of undefined (reading 'push')" error
+2. Tested `lean-spec_stats` → all 11 specs showed as `status: undefined`
+3. Tested `lean-spec_read` on spec 037 → spec file has `status: planned` in frontmatter
+4. Reviewed `mcp-server.ts` → found `specToData()` accessing wrong properties
+5. Checked `spec-loader.ts` → confirmed SpecInfo structure uses `frontmatter` sub-object
+
+**Files affected:**
+- `src/mcp-server.ts` - Main fix location (lines ~51, ~188-201, ~215)
+
+**Related:**
+- Spec 034: Copilot slash commands (uses MCP server)
+- MCP integration testing script: `test-mcp-integration.sh`

package/.next/standalone/packages/ui/dist/standalone/specs/archived/039-simplify-viewer-commands/README.md

@@ -0,0 +1,198 @@
+---
+status: archived
+created: '2025-11-04'
+tags:
+  - cli
+  - ux
+  - breaking-change
+  - simplification
+priority: high
+completed: '2025-11-04'
+created_at: '2025-11-11T04:26:08.824Z'
+updated_at: '2025-11-11T04:26:08.824Z'
+transitions:
+  - status: archived
+    at: '2025-11-11T04:26:08.824Z'
+---
+
+# Simplify Viewer Command Interface
+
+> **Status**: 📦 Archived · **Priority**: High · **Created**: 2025-11-04 · **Tags**: cli, ux, breaking-change, simplification
+
+**Project**: lean-spec  
+**Team**: Core Development
+
+## Overview
+
+We currently have 4 commands for viewing specs: `show`, `view`, `read`, and `open`. This causes confusion:
+- **`show` vs `view`**: Identical - `view` just calls `show`. Pure redundancy.
+- **`show` vs `read`**: Confusing names - people expect to "read" a spec, not "show" it
+- **`read`**: Named for scripting use case, but the name suggests human consumption
+
+**User confusion:**
+- "I want to read a spec - do I use `show`, `view`, or `read`?"
+- "Why are there three commands that all display spec content?"
+- "`read` sounds like what I want, but it gives me raw markdown?"
+
+This violates LeanSpec's principle of clarity over convention.
+
+## Design
+
+### Proposed Interface
+
+**Option A: Single command with flags (Recommended)**
+```bash
+lean-spec <spec>              # Default: formatted view (current "show")
+lean-spec <spec> --raw        # Raw markdown (current "read")  
+lean-spec <spec> --json       # JSON output (current "read --format=json")
+lean-spec <spec> --edit       # Open in editor (current "open")
+```
+
+**Benefits:**
+- One obvious way to view a spec
+- Flags make the variants clear
+- Matches user mental model: "view this spec, optionally with modifications"
+
+**Option B: Keep minimal commands**
+```bash
+lean-spec view <spec>         # Formatted (remove "show", keep only "view")
+lean-spec view <spec> --raw   # Raw markdown
+lean-spec view <spec> --json  # JSON output
+lean-spec open <spec>         # Edit (separate action, keep separate)
+```
+
+**Benefits:**
+- More explicit than positional arg
+- `view` vs `open` clearly distinguishes reading vs editing
+- Familiar CLI pattern (verb + noun)
+
+### Migration Strategy
+
+**Phase 1: Add new interface (non-breaking)**
+- Implement chosen option
+- Keep old commands as deprecated aliases
+- Show deprecation warnings
+
+**Phase 2: Documentation update**
+- Update all docs to show new commands
+- Add migration guide
+- Announce in changelog
+
+**Phase 3: Remove old commands (breaking)**
+- Remove in next major version
+- Clear error messages pointing to new commands
+
+### Implementation
+
+**Option A Implementation:**
+```typescript
+// Make spec-path optional, make it the default command
+program
+  .argument('[spec-path]', 'Spec to view')
+  .option('--raw', 'Output raw markdown (for piping/scripting)')
+  .option('--json', 'Output as JSON')
+  .option('--edit', 'Open in editor')
+  .option('--no-color', 'Disable colors')
+  .action(async (specPath?: string, options) => {
+    if (!specPath) {
+      // No spec provided - show help or list
+      program.help();
+      return;
+    }
+    
+    if (options.edit) {
+      await openCommand(specPath, options);
+    } else if (options.raw) {
+      await readCommand(specPath, { format: 'markdown' });
+    } else if (options.json) {
+      await readCommand(specPath, { format: 'json' });
+    } else {
+      await showCommand(specPath, options);
+    }
+  });
+
+// Deprecated commands with warnings
+program
+  .command('show <spec-path>')
+  .description('[DEPRECATED] Use: lean-spec <spec-path>')
+  .action(async (specPath: string) => {
+    console.warn(chalk.yellow('⚠️  "lean-spec show" is deprecated. Use: lean-spec <spec-path>'));
+    await showCommand(specPath);
+  });
+```
+
+**Option B Implementation:**
+```typescript
+program
+  .command('view <spec-path>')
+  .description('View spec content')
+  .option('--raw', 'Output raw markdown')
+  .option('--json', 'Output as JSON')
+  .option('--no-color', 'Disable colors')
+  .action(async (specPath: string, options) => {
+    if (options.json) {
+      await readCommand(specPath, { format: 'json' });
+    } else if (options.raw) {
+      await readCommand(specPath, { format: 'markdown' });
+    } else {
+      await showCommand(specPath, options);
+    }
+  });
+
+program
+  .command('open <spec-path>')
+  .description('Open spec in editor')
+  .option('--editor <editor>', 'Editor to use')
+  .action(async (specPath: string, options) => {
+    await openCommand(specPath, options);
+  });
+```
+
+## Plan
+
+- [x] Decide between Option A or B (chose B for clarity)
+- [x] Implement new interface
+- [x] Remove deprecated commands completely
+- [x] Update README examples
+- [x] Update AGENTS.md with new commands
+- [x] Update MCP server to align with CLI (lean-spec_read → lean-spec_view with flags)
+- [x] Update all tests
+- [x] Update docs site CLI reference
+- [ ] Add migration guide to CHANGELOG
+
+## Test
+
+- [x] `lean-spec view <spec>` displays formatted spec
+- [x] `lean-spec view <spec> --raw` outputs raw markdown (pipeable)
+- [x] `lean-spec view <spec> --json` outputs valid JSON
+- [x] `lean-spec open <spec>` opens in editor
+- [x] Old commands completely removed (breaking change)
+- [x] Help text is clear and unambiguous
+- [x] Error messages guide users to correct command
+- [x] All viewer tests pass (16/16)
+- [x] All command integration tests pass (30/30)
+- [x] TypeScript compilation succeeds with no errors
+
+## Notes
+
+**Why this matters:**
+- Every confusing command erodes trust in LeanSpec's "clarity over documentation" promise
+- New users shouldn't have to guess which of 3 similar commands to use
+- AI agents get confused by redundant commands too
+
+**Alternatives considered:**
+- Keep all commands: No, the confusion is the problem
+- Remove `view` and keep `show`: Better, but `show` still isn't intuitive
+- Just merge `show`/`view` and keep `read`: Doesn't solve the core naming confusion
+
+**Decision rationale for Option A:**
+- Matches `git show`, `docker ps`, etc - where default is formatted, flags modify
+- Clearest mental model: "I want to see spec X, optionally in a different format"
+- Fewest total commands = least cognitive load
+- Natural evolution: `lean-spec list` → `lean-spec <spec>` (browse → view)
+
+**Backward compatibility:**
+- ~~Deprecated commands in 0.2.x (with warnings)~~
+- **Breaking change**: Removed deprecated commands completely in 0.2.0
+- Clear migration path in docs
+- Users should update to: `lean-spec view <spec>` (with optional `--raw` or `--json` flags)