@leanspec/ui 0.2.7 → 0.2.9-dev.20251205030455

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

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

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

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